Detete texto em ficheiros

O serviço de reconhecimento ótico de carateres (OCR) do Vertex AI no Google Distributed Cloud (GDC) isolado deteta texto em ficheiros PDF e TIFF através dos dois métodos de API seguintes:

Esta página mostra como detetar texto em ficheiros através da API OCR na Distributed Cloud.

Antes de começar

Antes de poder começar a usar a API OCR, tem de ter um projeto com a API OCR ativada e as credenciais adequadas. Também pode instalar bibliotecas cliente para ajudar a fazer chamadas para a API. Para mais informações, consulte o artigo Configure um projeto de reconhecimento de carateres.

Detete texto com pedidos inline

O método BatchAnnotateFiles deteta texto a partir de um lote de ficheiros PDF ou TIFF. Envia o ficheiro a partir do qual quer detetar texto diretamente como conteúdo no pedido da API. O sistema devolve o texto detetado resultante no formato JSON na resposta da API.

Tem de especificar valores para os campos no corpo JSON do seu pedido API. A tabela seguinte contém uma descrição dos campos do corpo do pedido que tem de fornecer quando usa o método da API BatchAnnotateFiles para os seus pedidos de deteção de texto:

Campos do corpo do pedido Descrição do campo
content Os ficheiros com texto a detetar. Fornece a representação Base64 (string ASCII) do conteúdo do ficheiro binário.
mime_type O tipo de ficheiro de origem. Tem de defini-lo para um dos seguintes valores:
  • application/pdf para ficheiros PDF
  • image/tiff para ficheiros TIFF
type O tipo de deteção de texto de que precisa no ficheiro.

Especifique uma das duas funcionalidades de anotação:
  • TEXT_DETECTION deteta e extrai texto de qualquer ficheiro. A resposta JSON inclui a string extraída, as palavras individuais e as respetivas caixas delimitadoras.
  • DOCUMENT_TEXT_DETECTION também extrai texto de um ficheiro, mas o serviço otimiza a resposta para texto e documentos densos. O JSON inclui informações sobre páginas, blocos, parágrafos, palavras e quebras.
Para mais informações sobre estas funcionalidades de anotação, consulte o artigo Funcionalidades de reconhecimento ótico de carateres.
language_hints Opcional. Lista de idiomas a usar para a deteção de texto.

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

Não tem de definir o campo language_hints para idiomas baseados no alfabeto latino.

Se souber o idioma do texto no ficheiro, a definição de uma sugestão melhora os resultados.
pages Opcional. O número de páginas do ficheiro a processar para deteção de texto.

O número máximo de páginas que pode especificar é cinco. Se não especificar o número de páginas, o serviço processa as primeiras cinco páginas do ficheiro.

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

Faça um pedido de API inline

Faça um pedido à API pré-preparada de OCR através do método da API REST. Em alternativa, interaja com a API pré-preparada de OCR a partir de um script Python para detetar texto em ficheiros PDF ou TIFF.

Os exemplos seguintes mostram como detetar texto num ficheiro através de OCR:

REST

Siga estes passos para detetar texto em ficheiros através do método da API REST:

  1. Guarde o seguinte ficheiro request.json para o corpo do pedido:

    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_1",
          "LANGUAGE_HINT_2",
          ...
        ]
      },
      "pages": []
    }
  ]
}
EOF

    Substitua o seguinte:

    • BASE64_ENCODED_FILE: a representação Base64 (string ASCII) do conteúdo do seu ficheiro binário. Esta string começa com carateres semelhantes a /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
    • FEATURE_TYPE: o tipo de deteção de texto de que precisa no ficheiro. Os valores permitidos são TEXT_DETECTION ou DOCUMENT_TEXT_DETECTION.
    • LANGUAGE_HINT: as etiquetas de idioma BCP 47 a usar como sugestões de idioma para a deteção de texto, como en-t-i0-handwrit. Este campo é opcional e o sistema interpreta um valor vazio como deteção automática do idioma.

  2. Obtenha um token de autenticação.

  3. Faça o pedido:

    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 o seguinte:

    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 "ENDPOINT/v1/files:annotate" | Select-Object -Expand Content

    Substitua o seguinte:

Python

Siga estes passos para usar o serviço de OCR a partir de um script Python para detetar texto num ficheiro:

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

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

  3. Autentique o seu pedido de API.

  4. Adicione o seguinte código ao script Python que 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)
    print("Got token: ")
    print(creds.token)
  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 o seguinte:

    • ENDPOINT: o ponto final de OCR que usa para a sua organização. Para mais informações, veja o estado do serviço e os pontos finais.
    • BASE64_ENCODED_FILE: a representação Base64 (string ASCII) do conteúdo do ficheiro. Esta string começa com carateres semelhantes a /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
    • FEATURE_TYPE: o tipo de deteção de texto de que precisa no ficheiro. Os valores permitidos são TEXT_DETECTION ou DOCUMENT_TEXT_DETECTION.
    • PROJECT_ID: o ID do seu projeto.

  5. Guarde o script Python.

  6. Execute o script Python para detetar texto no ficheiro:

    python SCRIPT_NAME

    Substitua SCRIPT_NAME pelo nome que deu ao seu script Python, como vision.py.

Detete texto com pedidos offline

O método AsyncBatchAnnotateFiles deteta texto a partir de um lote de ficheiros PDF ou TIFF através de um pedido offline (assíncrono). Os ficheiros podem conter várias páginas e várias imagens por página. Os ficheiros de origem têm de estar num contentor de armazenamento do seu projeto do Distributed Cloud. O sistema guarda o texto detetado resultante num contentor de armazenamento no formato JSON.

O serviço de OCR inicia o processamento offline e devolve o ID do processo de longa duração que realiza a deteção de texto no ficheiro. Pode usar o ID devolvido para acompanhar o estado do processamento offline. Se existirem demasiadas operações em curso, o processamento offline pode não ser iniciado imediatamente.

Tem de especificar valores para os campos no corpo JSON do seu pedido API. A tabela seguinte contém uma descrição dos campos do corpo do pedido que tem de fornecer quando usa o método da API AsyncBatchAnnotateFiles para os seus pedidos de deteção de texto:

Campos do corpo do pedido Descrição do campo
gcs_source.uri O caminho URI para um ficheiro de origem válido (PDF ou TIFF) num contentor de armazenamento do seu projeto do Distributed Cloud.

Este ficheiro contém o texto que quer detetar.

O utilizador ou a conta de serviço que faz o pedido tem de ter, pelo menos, privilégios de leitura para o ficheiro.
mime_type O tipo de ficheiro de origem. Tem de defini-lo para um dos seguintes valores:
  • application/pdf para ficheiros PDF
  • image/tiff para ficheiros TIFF
type O tipo de deteção de texto de que precisa no ficheiro.

Especifique uma das duas funcionalidades de anotação:
  • TEXT_DETECTION deteta e extrai texto de qualquer ficheiro. A resposta JSON inclui a string extraída, as palavras individuais e as respetivas caixas delimitadoras.
  • DOCUMENT_TEXT_DETECTION também extrai texto de um ficheiro, mas o serviço otimiza a resposta para texto e documentos densos. O JSON inclui informações sobre páginas, blocos, parágrafos, palavras e quebras.
Para mais informações sobre estas funcionalidades de anotação, consulte o artigo Funcionalidades de reconhecimento ótico de carateres.
gcs_destination.uri O caminho do URI para um contentor de armazenamento do seu projeto do Distributed Cloud para guardar os ficheiros de saída.

Esta localização é onde quer armazenar os resultados da deteção.

O utilizador ou a conta de serviço que faz o pedido tem de ter autorização de escrita no contentor.

Armazene o ficheiro de origem num contentor de armazenamento

Antes de enviar um pedido, tem de garantir que a conta de serviço de OCR tem autorizações de leitura para o seu contentor de entrada e autorizações de escrita para o seu contentor de saída.

Os contentores de entrada e saída podem ser diferentes e estar em espaços de nomes de projetos diferentes. Recomendamos que use os mesmos contentores de entrada e saída para evitar erros, como o armazenamento dos resultados em contentores erróneos.

Siga estes passos para armazenar o ficheiro a partir do qual quer detetar texto num contentor de armazenamento:

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

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

    Pode criar o contentor de armazenamento implementando um recurso Bucket no espaço de nomes 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 autorizações read e write no contentor à conta de serviço (g-vai-ocr-sie-sa) usada pelo serviço de OCR.

    Pode seguir estes passos para criar a função e a associação de funções através de recursos personalizados:

    1. Crie a função implementando um recurso Role no espaço de nomes 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 associação de funções implementando um recurso RoleBinding no espaço de nomes 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. Carregue o ficheiro para o contentor de armazenamento que criou. Para mais informações, consulte o artigo Carregue e transfira objetos de armazenamento em projetos.

Faça um pedido de API offline

Faça um pedido à API pré-preparada de OCR através do método da API REST. Em alternativa, interaja com a API pré-preparada de OCR a partir de um script Python para detetar texto em ficheiros PDF ou TIFF.

Os exemplos seguintes mostram como detetar texto num ficheiro através de OCR:

REST

Siga estes passos para detetar texto em ficheiros através do método da API REST:

  1. Guarde o seguinte ficheiro request.json para o corpo do pedido:

    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 o seguinte:

    • PROJECT_ID: o ID do seu projeto.
    • SOURCE_FILE: o caminho do URI para um ficheiro de origem válido (PDF ou TIFF) num contentor de armazenamento do seu projeto do Distributed Cloud.
    • FEATURE_TYPE: o tipo de deteção de texto de que precisa no ficheiro. Os valores permitidos são TEXT_DETECTION ou DOCUMENT_TEXT_DETECTION.
    • DESTINATION_BUCKET: o caminho do URI para um contentor de armazenamento do seu projeto do Distributed Cloud para guardar os ficheiros de saída.

  2. Obtenha um token de autenticação.

  3. Faça o pedido:

    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 o seguinte:

    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 "ENDPOINT/v1/files:asyncBatchAnnotate" | Select-Object -Expand Content

    Substitua o seguinte:

Python

Siga estes passos para usar o serviço de OCR a partir de um script Python para detetar texto num ficheiro:

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

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

  3. Autentique o seu pedido de API.

  4. Adicione o seguinte código ao script Python que 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_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_BUKET}}
  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)
    print("Got token: ")
    print(creds.token)
  except Exception as e:
    print("Caught exception" + str(e))
    raise e
  return creds

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

    Substitua o seguinte:

    • ENDPOINT: o ponto final de OCR que usa para a sua organização. Para mais informações, veja o estado do serviço e os pontos finais.
    • FEATURE_TYPE: o tipo de deteção de texto de que precisa no ficheiro. Os valores permitidos são TEXT_DETECTION ou DOCUMENT_TEXT_DETECTION.
    • SOURCE_FILE: o caminho do URI para um ficheiro de origem válido (PDF ou TIFF) num contentor de armazenamento do seu projeto do Distributed Cloud.
    • DESTINATION_BUCKET: o caminho do URI para um contentor de armazenamento do seu projeto do Distributed Cloud para guardar os ficheiros de saída.
    • PROJECT_ID: o ID do seu projeto.

  5. Guarde o script Python.

  6. Execute o script Python para detetar texto no ficheiro:

    python SCRIPT_NAME

    Substitua SCRIPT_NAME pelo nome que deu ao seu script Python, como vision.py.

Pode usar o nome da operação devolvido pelo método AsyncBatchAnnotateFiles para verificar o estado da operação.

Obtenha o estado da operação

O método get devolve o estado mais recente de uma operação de execução prolongada, como o pedido offline de deteção de texto. Use este método para verificar o estado da operação, como no exemplo seguinte:

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

Substitua OPERATION_NAME pelo nome da operação que o método AsyncBatchAnnotateFiles devolveu quando fez o pedido offline.

Apresentar operações

O método list devolve uma lista das operações que correspondem a um filtro especificado no pedido. O método pode devolver operações de um projeto específico. Para chamar o método list, especifique o ID do projeto e o ponto final da OCR, como no exemplo seguinte:

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