Detectar texto em arquivos

O serviço de reconhecimento óptico de caracteres (OCR) da Vertex AI no Google Distributed Cloud (GDC) com isolamento físico detecta e extrai texto de arquivos PDF e TIFF. É possível enviar arquivos locais em solicitações inline para o método de API BatchAnnotateFiles ou processar arquivos armazenados em buckets de forma assíncrona com o método de API AsyncBatchAnnotateFiles. O método de API BatchAnnotateFiles aceita uma única solicitação por chamada em lote.

Antes de começar

Para detectar texto em arquivos, entre em contato com o administrador do IAM do projeto para solicitar o papel de Desenvolvedor de OCR de IA (ai-ocr-developer) no namespace do projeto.

Para mais informações sobre esse papel, consulte Preparar permissões do IAM.

Antes de começar a usar a API OCR, é preciso ter um projeto com a API OCR ativada e as credenciais apropriadas. Também é possível instalar bibliotecas de cliente para ajudar você a fazer chamadas para a API. Para mais informações, consulte Configurar um projeto de reconhecimento de caracteres.

Detectar texto com solicitações inline

O método BatchAnnotateFiles detecta texto de um lote de arquivos PDF ou TIFF. Envie o arquivo em que você quer detectar texto diretamente como conteúdo na solicitação de API. O sistema retorna o texto detectado no formato JSON na resposta da API.

É preciso especificar valores para os campos no corpo JSON da solicitação de API. A tabela a seguir contém uma descrição dos campos do corpo da solicitação que você precisa fornecer ao usar o método de API BatchAnnotateFiles para suas solicitações de detecção de texto:

Campos do corpo da solicitação Descrição do campo
content Os arquivos com texto a ser detectado. Você fornece a representação Base64 (string ASCII) do conteúdo do arquivo binário.
mime_type O tipo de arquivo de origem. É preciso definir um dos seguintes valores:
  • application/pdf para arquivos PDF
  • image/tiff para arquivos TIFF
type O tipo de detecção de texto que você precisa do arquivo.

Especifique um dos dois recursos de anotação:
  • A TEXT_DETECTION detecta e extrai texto de qualquer arquivo. A resposta JSON inclui a string extraída, as palavras individuais e as caixas delimitadoras delas.
  • DOCUMENT_TEXT_DETECTION também extrai texto de um arquivo, mas o serviço otimiza a resposta para textos e documentos densos. O JSON inclui informações de página, bloco, parágrafo, palavra e quebra.
Para mais informações sobre esses recursos de anotação, consulte Recursos de reconhecimento óptico de caracteres.
language_hints Opcional. Lista de idiomas a serem usados para a detecção de texto.

O sistema interpreta um valor vazio para esse campo como detecção automática de idioma.

Não é necessário definir o campo language_hints para idiomas baseados no alfabeto latino.

Se você souber o idioma do texto no arquivo, definir uma dica vai melhorar os resultados.
pages Opcional. O número de páginas do arquivo a serem processadas para detecção de texto.

O número máximo de páginas que você pode especificar é cinco. Se você não especificar o número de páginas, o serviço vai processar as primeiras cinco páginas do arquivo.

Para informações sobre a representação JSON completa, consulte AnnotateFileRequest.

Fazer uma solicitação de API inline

Faça uma solicitação à API pré-treinada de OCR usando o método da API REST. Caso contrário, interaja com a API pré-treinada de OCR em um script Python para detectar texto em arquivos PDF ou TIFF.

Os exemplos a seguir mostram como detectar texto em um arquivo usando OCR:

REST

Siga estas etapas para detectar texto em arquivos usando o método da API REST:

  1. Salve o seguinte arquivo request.json para o corpo da solicitação:

    cat <<- EOF > request.json
{
  "requests": [
    {
      "input_config": {
        "content": "BASE64_ENCODED_FILE",
        "mime_type": "application/pdf"
      },
      "features": [
        {
          "type": "FEATURE_TYPE"
        }
      ],
      "image_context": {
        "language_hints": [
          "LANGUAGE_HINT"
        ]
      },
      "pages": []
    }
  ]
}
EOF

    Substitua:

    • BASE64_ENCODED_FILE: a representação Base64 (string ASCII) do conteúdo do arquivo binário. Essa string começa com caracteres semelhantes a /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
    • FEATURE_TYPE: o tipo de detecção de texto que você precisa do arquivo. Os valores permitidos são TEXT_DETECTION ou DOCUMENT_TEXT_DETECTION.
    • LANGUAGE_HINT: as tags de idioma BCP 47 a serem usadas como dicas de idioma para detecção de texto, como en-t-i0-handwrit. Esse campo é opcional, e o sistema interpreta um valor vazio como detecção automática de idioma.

  2. Receba um token de autenticação.

  3. Faça a solicitação:

    curl

    curl -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "x-goog-user-project: projects/PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  https://ENDPOINT/v1/files:annotate

    Substitua:

    PowerShell

    $headers = @{
  "Authorization" = "Bearer TOKEN"
  "x-goog-user-project" = "projects/PROJECT_ID"
}

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://ENDPOINT/v1/files:annotate" | Select-Object -Expand Content

    Substitua:

Python

Siga estas etapas para usar o serviço de OCR de um script Python para detectar texto em um arquivo:

  1. Instale a versão mais recente da biblioteca de cliente do OCR.

  2. Defina as variáveis de ambiente necessárias em um script Python.

  3. Autentique sua solicitação de API.

  4. Adicione o seguinte código ao script Python que você criou:

    from google.cloud import vision
import google.auth
from google.auth.transport import requests
from google.api_core.client_options import ClientOptions

audience = "https://ENDPOINT:443"
api_endpoint="ENDPOINT:443"

def vision_client(creds):
  opts = ClientOptions(api_endpoint=api_endpoint)
  return vision.ImageAnnotatorClient(credentials=creds, client_options=opts)

def main():
  creds = None
  try:
    creds, project_id = google.auth.default()
    creds = creds.with_gdch_audience(audience)
    req = requests.Request()
    creds.refresh(req)
  except Exception as e:
    print("Caught exception" + str(e))
    raise e
  return creds

def vision_func(creds):
  vc = vision_client(creds)
  input_config = {"content": "BASE64_ENCODED_FILE"}
  features = [{"type_": vision.Feature.Type.FEATURE_TYPE}]
  # Each requests element corresponds to a single file. To annotate more
  # files, create a request element for each file and add it to
  # the array of requests
  req = {"input_config": input_config, "features": features}

  metadata = [("x-goog-user-project", "projects/PROJECT_ID")]

  resp = vc.annotate_file(req,metadata=metadata)

  print(resp)

if __name__=="__main__":
  creds = main()
  vision_func(creds)

    Substitua:

    • ENDPOINT: o endpoint de OCR que você usa para sua organização. Para mais informações, confira o status e os endpoints do serviço.
    • BASE64_ENCODED_FILE: a representação Base64 (string ASCII) do conteúdo do arquivo. Essa string começa com caracteres semelhantes a /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
    • FEATURE_TYPE: o tipo de detecção de texto que você precisa do arquivo. Os valores permitidos são TEXT_DETECTION ou DOCUMENT_TEXT_DETECTION.
    • PROJECT_ID: o ID do projeto.

  5. Salve o script em Python.

  6. Execute o script Python para detectar texto no arquivo:

    python SCRIPT_NAME

    Substitua SCRIPT_NAME pelo nome que você deu ao script do Python, como vision.py.

Detectar texto com solicitações off-line

O método AsyncBatchAnnotateFiles detecta texto de um lote de arquivos PDF ou TIFF realizando uma solicitação off-line (assíncrona). Os arquivos podem conter várias páginas e várias imagens por página. Os arquivos de origem precisam estar em um bucket de armazenamento do projeto na nuvem do Distributed Cloud. O sistema salva o texto detectado resultante no formato JSON em um bucket de armazenamento.

O serviço de OCR inicia o processamento off-line e retorna o ID do processo de longa duração que realiza a detecção de texto no arquivo. Use o ID retornado para acompanhar o status do processamento off-line. Se houver muitas operações em andamento, o processamento off-line pode não começar imediatamente.

É preciso especificar valores para os campos no corpo JSON da solicitação de API. A tabela a seguir contém uma descrição dos campos do corpo da solicitação que você precisa fornecer ao usar o método de API AsyncBatchAnnotateFiles para suas solicitações de detecção de texto:

Campos do corpo da solicitação Descrição do campo
gcs_source.uri O caminho do URI para um arquivo de origem válido (PDF ou TIFF) em um bucket de armazenamento do seu projeto do Distributed Cloud.

Esse arquivo contém o texto que você quer detectar.

O usuário ou a conta de serviço solicitante precisa ter, pelo menos, privilégios de leitura para o arquivo.
mime_type O tipo de arquivo de origem. É preciso definir um dos seguintes valores:
  • application/pdf para arquivos PDF
  • image/tiff para arquivos TIFF
type O tipo de detecção de texto que você precisa do arquivo.

Especifique um dos dois recursos de anotação:
  • A TEXT_DETECTION detecta e extrai texto de qualquer arquivo. A resposta JSON inclui a string extraída, as palavras individuais e as caixas delimitadoras delas.
  • DOCUMENT_TEXT_DETECTION também extrai texto de um arquivo, mas o serviço otimiza a resposta para textos e documentos densos. O JSON inclui informações de página, bloco, parágrafo, palavra e quebra.
Para mais informações sobre esses recursos de anotação, consulte Recursos de reconhecimento óptico de caracteres.
gcs_destination.uri O caminho do URI para um bucket de armazenamento do projeto do Distributed Cloud em que os arquivos de saída serão salvos.

Esse local é onde você quer armazenar os resultados da detecção.

O usuário ou a conta de serviço que faz a solicitação precisa ter permissão de gravação no bucket.

Armazenar o arquivo de origem em um bucket de armazenamento

Antes de enviar uma solicitação, verifique se a conta de serviço do OCR tem permissões de leitura para o bucket de entrada e permissões de gravação para o bucket de saída.

Os buckets de entrada e saída podem ser diferentes e estar em namespaces de projeto distintos. Recomendamos usar os mesmos buckets de entrada e saída para evitar erros, como armazenar os resultados em buckets incorretos.

Siga estas etapas para armazenar o arquivo em que você quer detectar texto em um bucket de armazenamento:

  1. Configure a CLI gdcloud para o armazenamento de objetos.

  2. Crie um bucket de armazenamento no namespace do projeto.Use uma classe de armazenamento Standard.

    É possível criar o bucket de armazenamento implantando um recurso Bucket no namespace do projeto:

    apiVersion: object.gdc.goog/v1
kind: Bucket
metadata:
  name: ocr-async-bucket
  namespace: PROJECT_NAMESPACE
spec:
  description: bucket for async ocr
  storageClass: Standard
  bucketPolicy:
    lockingPolicy:
      defaultObjectRetentionDays: 90

  3. Conceda as permissões read e write no bucket à conta de serviço (g-vai-ocr-sie-sa) usada pelo serviço de OCR.

    Siga estas etapas para criar o papel e a vinculação de papel usando recursos personalizados:

    1. Crie o papel implantando um recurso Role no namespace do projeto:

        apiVersion: rbac.authorization.k8s.io/v1
  kind: Role
  metadata:
    name: ocr-async-reader-writer
    namespace: PROJECT_NAMESPACE
  rules:
    -
      apiGroups:
        - object.gdc.goog
      resources:
        - buckets
      verbs:
        - read-object
        - write-object

    2. Crie a vinculação de papel implantando um recurso RoleBinding no namespace do projeto:

        apiVersion: rbac.authorization.k8s.io/v1
  kind: RoleBinding

  metadata:
    name: ocr-async-reader-writer-rolebinding
    namespace: PROJECT_NAMESPACE
  roleRef:
    apiGroup: rbac.authorization.k8s.io
    kind: Role
    name: ocr-async-reader-writer
  subjects:
    -
      kind: ServiceAccount
      name: g-vai-ocr-sie-sa
      namespace: g-vai-ocr-sie

  4. Faça upload do arquivo para o bucket de armazenamento que você criou. Para mais informações, consulte Fazer upload e download de objetos de armazenamento em projetos.

Fazer uma solicitação de API off-line

Faça uma solicitação à API pré-treinada de OCR usando o método da API REST. Caso contrário, interaja com a API pré-treinada de OCR em um script Python para detectar texto em arquivos PDF ou TIFF.

Os exemplos a seguir mostram como detectar texto em um arquivo usando OCR:

REST

Siga estas etapas para detectar texto em arquivos usando o método da API REST:

  1. Salve o seguinte arquivo request.json para o corpo da solicitação:

    cat <<- EOF > request.json
{
  "parent": "PROJECT_ID",
  "requests":[
    {
      "input_config": {
        "gcs_source": {
          "uri": "SOURCE_FILE"
        },
        "mime_type": "application/pdf"
      },
      "features": [
        {
          "type": "FEATURE_TYPE"
        }
      ],
      "output_config": {
        "gcs_destination": {
          "uri": "DESTINATION_BUCKET"
        }
      }
    }
  ]
}
EOF

    Substitua:

    • PROJECT_ID: o ID do projeto.
    • SOURCE_FILE: o caminho do URI para um arquivo de origem válido (PDF ou TIFF) em um bucket de armazenamento do seu projeto na nuvem do Distributed Cloud.
    • FEATURE_TYPE: o tipo de detecção de texto que você precisa do arquivo. Os valores permitidos são TEXT_DETECTION ou DOCUMENT_TEXT_DETECTION.
    • DESTINATION_BUCKET: o caminho do URI para um bucket de armazenamento do seu projeto na nuvem do Distributed Cloud em que os arquivos de saída serão salvos.

  2. Receba um token de autenticação.

  3. Faça a solicitação:

    curl

    curl -X POST \
  -H "Authorization: Bearer TOKEN" \
  -H "x-goog-user-project: projects/PROJECT_ID" \
  -H "Content-Type: application/json; charset=utf-8" \
  -d @request.json \
  https://ENDPOINT/v1/files:asyncBatchAnnotate

    Substitua:

    PowerShell

    $headers = @{
  "Authorization" = "Bearer TOKEN"
  "x-goog-user-project" = "projects/PROJECT_ID"
}

Invoke-WebRequest `
  -Method POST `
  -Headers $headers `
  -ContentType "application/json; charset=utf-8" `
  -InFile request.json `
  -Uri "https://ENDPOINT/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content

    Substitua:

Python

Siga estas etapas para usar o serviço de OCR de um script Python para detectar texto em um arquivo:

  1. Instale a versão mais recente da biblioteca de cliente do OCR.

  2. Defina as variáveis de ambiente necessárias em um script Python.

  3. Autentique sua solicitação de API.

  4. Adicione o seguinte código ao script Python que você criou:

    from google.cloud import vision
import google.auth
from google.auth.transport import requests
from google.api_core.client_options import ClientOptions

audience = "https://ENDPOINT:443"
api_endpoint="ENDPOINT:443"

def vision_client(creds):
  opts = ClientOptions(api_endpoint=api_endpoint)
  return vision.ImageAnnotatorClient(credentials=creds, client_options=opts)

def vision_func_async(creds):
  vc = vision_client(creds)
  features = [{"type_": vision.Feature.Type.FEATURE_TYPE}]
  input_config = {"gcs_source":{"uri":"SOURCE_FILE"},"mime_type": "application/pdf"}
  output_config = {"gcs_destination": {"uri": "DESTINATION_BUCKET"}}
  req = {"input_config": input_config, "output_config": output_config, "features":features}
  reqs = {"requests":[req],"parent":"PROJECT_ID"}

  metadata = [("x-goog-user-project", "projects/PROJECT_ID")]

  operation = vc.async_batch_annotate_files(request=reqs, metadata=metadata)
  lro = operation.operation
  resp = operation.result()

def main():
  creds = None
  try:
    creds, project_id = google.auth.default()
    creds = creds.with_gdch_audience(audience)
    req = requests.Request()
    creds.refresh(req)
  except Exception as e:
    print("Caught exception" + str(e))
    raise e
  return creds

if __name__=="__main__":
  creds = main()
  vision_func_async(creds)

    Substitua:

    • ENDPOINT: o endpoint de OCR que você usa para sua organização. Para mais informações, confira o status e os endpoints do serviço.
    • FEATURE_TYPE: o tipo de detecção de texto que você precisa do arquivo. Os valores permitidos são TEXT_DETECTION ou DOCUMENT_TEXT_DETECTION.
    • SOURCE_FILE: o caminho do URI para um arquivo de origem válido (PDF ou TIFF) em um bucket de armazenamento do seu projeto na nuvem do Distributed Cloud.
    • DESTINATION_BUCKET: o caminho do URI para um bucket de armazenamento do seu projeto na nuvem do Distributed Cloud em que os arquivos de saída serão salvos.
    • PROJECT_ID: o ID do projeto.

  5. Salve o script em Python.

  6. Execute o script Python para detectar texto no arquivo:

    python SCRIPT_NAME

    Substitua SCRIPT_NAME pelo nome que você deu ao script do Python, como vision.py.

Use o nome da operação retornado pelo método AsyncBatchAnnotateFiles para verificar o status da operação.

Ver o status da operação

O método get retorna o estado mais recente de uma operação de longa duração, como a solicitação off-line para detecção de texto. Use esse método para verificar o status da operação, como no exemplo a seguir:

curl -X GET "http://ENDPOINT/v1/OPERATION_NAME"

Substitua OPERATION_NAME pelo nome da operação que o método AsyncBatchAnnotateFiles retornou quando você fez a solicitação off-line.

Listar operações

O método list retorna uma lista das operações que correspondem a um filtro especificado na solicitação. O método pode retornar operações de um projeto específico. Para chamar o método list, especifique o ID do projeto e o endpoint de OCR, como no exemplo a seguir:

curl -X GET "http://ENDPOINT/v1/PROJECT_ID?page_size=10"