Detecta texto en archivos

El servicio de reconocimiento óptico de caracteres (OCR) de Vertex AI en Google Distributed Cloud (GDC) aislado detecta y extrae texto de archivos PDF y TIFF. Puedes enviar archivos locales en solicitudes intercaladas al método de la API de BatchAnnotateFiles o procesar archivos almacenados en buckets de forma asíncrona con el método de la API de AsyncBatchAnnotateFiles. El método de la API de BatchAnnotateFiles admite una sola solicitud por llamada por lotes.

Antes de comenzar

Para detectar texto en archivos, comunícate con tu administrador de proyectos de IAM y solicita el rol de desarrollador de OCR de IA (ai-ocr-developer) en el espacio de nombres de tu proyecto.

Para obtener más información sobre este rol, consulta Prepara los permisos de IAM.

Antes de comenzar a usar la API de OCR, debes tener un proyecto con esta API habilitada y las credenciales adecuadas. También puedes instalar bibliotecas cliente para ayudarte a realizar llamadas a la API. Para obtener más información, consulta Configura un proyecto de reconocimiento de caracteres.

Detecta texto con solicitudes intercaladas

El método BatchAnnotateFiles detecta texto de un lote de archivos PDF o TIFF. Envías el archivo del que deseas detectar texto directamente como contenido en la solicitud a la API. El sistema devuelve el texto detectado resultante en formato JSON en la respuesta de la API.

Debes especificar valores para los campos en el cuerpo JSON de tu solicitud a la API. En la siguiente tabla, se incluye una descripción de los campos del cuerpo de la solicitud que debes proporcionar cuando usas el método de la API de BatchAnnotateFiles para tus solicitudes de detección de texto:

Campos del cuerpo de la solicitud Descripción del campo
content Son los archivos con texto que se detectará. Proporcionas la representación en Base64 (cadena ASCII) del contenido de tu archivo binario.
mime_type Es el tipo de archivo de origen. Debes establecerlo en uno de los siguientes valores:
  • application/pdf para archivos PDF
  • image/tiff para archivos TIFF
type El tipo de detección de texto que necesitas del archivo.

Especifica una de las dos funciones de anotación:
  • TEXT_DETECTION detecta y extrae el texto de cualquier archivo. La respuesta JSON incluye la cadena extraída, las palabras individuales y sus cuadros delimitadores.
  • DOCUMENT_TEXT_DETECTION también extrae el texto de un archivo, pero el servicio optimiza la respuesta para textos y documentos densos. El archivo JSON incluye información de la página, el bloque, el párrafo, la palabra y la división.
Para obtener más información sobre estas funciones de anotación, consulta Funciones de reconocimiento óptico de caracteres.
language_hints Es opcional. Es la lista de idiomas que se usarán para la detección de texto.

El sistema interpreta un valor vacío para este campo como detección automática de idioma.

No es necesario que configures el campo language_hints para los idiomas que se basan en el alfabeto latino.

Si conoces el idioma del texto del archivo, configurar una sugerencia mejora los resultados.
pages Es opcional. Es la cantidad de páginas del archivo que se procesarán para la detección de texto.

La cantidad máxima de páginas que puedes especificar es cinco. Si no especificas la cantidad de páginas, el servicio procesará las primeras cinco páginas del archivo.

Para obtener información sobre la representación JSON completa, consulta AnnotateFileRequest.

Realiza una solicitud a la API intercalada

Realiza una solicitud a la API de OCR previamente entrenada con el método de la API de REST. De lo contrario, interactúa con la API previamente entrenada de OCR desde una secuencia de comandos de Python para detectar texto de archivos PDF o TIFF.

En los siguientes ejemplos, se muestra cómo detectar texto en un archivo con OCR:

REST

Sigue estos pasos para detectar texto en archivos con el método de la API de REST:

  1. Guarda el siguiente archivo request.json para el cuerpo de la solicitud:

    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

    Reemplaza lo siguiente:

    • BASE64_ENCODED_FILE: Es la representación en Base64 (cadena ASCII) del contenido del archivo binario. Esta cadena comienza con caracteres que se parecen a /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
    • FEATURE_TYPE: Es el tipo de detección de texto que necesitas del archivo. Los valores permitidos son TEXT_DETECTION o DOCUMENT_TEXT_DETECTION.
    • LANGUAGE_HINT: Son las etiquetas de idioma BCP 47 que se usarán como sugerencias de idioma para la detección de texto, como en-t-i0-handwrit. Este campo es opcional y el sistema interpreta un valor vacío como detección automática de idioma.

  2. Obtén un token de autenticación.

  3. Realiza la solicitud:

    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

    Reemplaza lo siguiente:

    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

    Reemplaza lo siguiente:

Python

Sigue estos pasos para usar el servicio de OCR desde una secuencia de comandos de Python y detectar texto en un archivo:

  1. Instala la versión más reciente de la biblioteca cliente de OCR.

  2. Establece las variables de entorno necesarias en una secuencia de comandos de Python.

  3. Autentica tu solicitud a la API.

  4. Agrega el siguiente código a la secuencia de comandos de Python que creaste:

    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)

    Reemplaza lo siguiente:

    • ENDPOINT: Es el extremo de OCR que usas para tu organización. Para obtener más información, consulta el estado y los extremos del servicio.
    • BASE64_ENCODED_FILE: Es la representación en Base64 (cadena ASCII) del contenido de tu archivo. Esta cadena comienza con caracteres que se parecen a /9j/4QAYRXhpZgAA...9tAVx/zDQDlGxn//2Q==.
    • FEATURE_TYPE: Es el tipo de detección de texto que necesitas del archivo. Los valores permitidos son TEXT_DETECTION o DOCUMENT_TEXT_DETECTION.
    • PROJECT_ID: Es el ID del proyecto.

  5. Guarda la secuencia de comandos de Python.

  6. Ejecuta la secuencia de comandos de Python para detectar texto en el archivo:

    python SCRIPT_NAME

    Reemplaza SCRIPT_NAME por el nombre que le diste a tu secuencia de comandos de Python, como vision.py.

Detecta texto con solicitudes sin conexión

El método AsyncBatchAnnotateFiles detecta texto de un lote de archivos PDF o TIFF con una solicitud sin conexión (asíncrona). Los archivos pueden contener varias páginas y varias imágenes por página. Los archivos de origen deben estar en un bucket de almacenamiento de tu proyecto de Distributed Cloud. El sistema guarda el texto detectado resultante en formato JSON en un bucket de almacenamiento.

El servicio de OCR inicia el procesamiento sin conexión y devuelve el ID del proceso de larga duración que realiza la detección de texto en el archivo. Puedes usar el ID que se muestra para hacer un seguimiento del estado del procesamiento sin conexión. Si hay demasiadas operaciones en curso, es posible que el procesamiento sin conexión no se inicie de inmediato.

Debes especificar valores para los campos en el cuerpo JSON de tu solicitud a la API. En la siguiente tabla, se incluye una descripción de los campos del cuerpo de la solicitud que debes proporcionar cuando usas el método de la API de AsyncBatchAnnotateFiles para tus solicitudes de detección de texto:

Campos del cuerpo de la solicitud Descripción del campo
gcs_source.uri La ruta de acceso del URI a un archivo de origen válido (PDF o TIFF) en un bucket de almacenamiento de tu proyecto de Distributed Cloud.

Este archivo contiene el texto que deseas detectar.

La cuenta de servicio o el usuario que realiza la solicitud debe tener, como mínimo, privilegios de lectura en el archivo.
mime_type Es el tipo de archivo de origen. Debes establecerlo en uno de los siguientes valores:
  • application/pdf para archivos PDF
  • image/tiff para archivos TIFF
type El tipo de detección de texto que necesitas del archivo.

Especifica una de las dos funciones de anotación:
  • TEXT_DETECTION detecta y extrae el texto de cualquier archivo. La respuesta JSON incluye la cadena extraída, las palabras individuales y sus cuadros delimitadores.
  • DOCUMENT_TEXT_DETECTION también extrae el texto de un archivo, pero el servicio optimiza la respuesta para textos y documentos densos. El archivo JSON incluye información de la página, el bloque, el párrafo, la palabra y la división.
Para obtener más información sobre estas funciones de anotación, consulta Funciones de reconocimiento óptico de caracteres.
gcs_destination.uri Es la ruta de acceso del URI a un bucket de almacenamiento de tu proyecto de Distributed Cloud en el que se guardarán los archivos de salida.

Esta ubicación es donde deseas almacenar los resultados de la detección.

La cuenta de servicio o el usuario que realiza la solicitud debe tener permiso de escritura en el bucket.

Almacena el archivo de origen en un bucket de almacenamiento

Antes de enviar una solicitud, debes asegurarte de que la cuenta de servicio de OCR tenga permisos de lectura para el bucket de entrada y permisos de escritura para el bucket de salida.

Los buckets de entrada y salida pueden ser diferentes y estar en espacios de nombres de proyectos distintos. Te recomendamos que uses los mismos buckets de entrada y salida para evitar errores, como almacenar los resultados en buckets incorrectos.

Sigue estos pasos para almacenar el archivo del que deseas detectar texto en un bucket de almacenamiento:

  1. Configura la CLI de gdcloud para el almacenamiento de objetos.

  2. Crea un bucket de almacenamiento en el espacio de nombres de tu proyecto.Usa una clase de almacenamiento Standard.

    Puedes crear el bucket de almacenamiento implementando un recurso Bucket en el espacio de nombres del proyecto:

    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. Otorga permisos read y write en el bucket a la cuenta de servicio (g-vai-ocr-sie-sa) que usa el servicio de OCR.

    Puedes seguir estos pasos para crear el rol y la vinculación de rol con recursos personalizados:

    1. Crea el rol implementando un recurso Role en el espacio de nombres del proyecto:

        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. Crea la vinculación de rol implementando un recurso RoleBinding en el espacio de nombres del proyecto:

        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. Sube tu archivo al bucket de almacenamiento que creaste. Para obtener más información, consulta Sube y descarga objetos de almacenamiento en proyectos.

Realiza una solicitud a la API sin conexión

Realiza una solicitud a la API de OCR previamente entrenada con el método de la API de REST. De lo contrario, interactúa con la API previamente entrenada de OCR desde una secuencia de comandos de Python para detectar texto de archivos PDF o TIFF.

En los siguientes ejemplos, se muestra cómo detectar texto en un archivo con OCR:

REST

Sigue estos pasos para detectar texto en archivos con el método de la API de REST:

  1. Guarda el siguiente archivo request.json para el cuerpo de la solicitud:

    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

    Reemplaza lo siguiente:

    • PROJECT_ID: Es el ID del proyecto.
    • SOURCE_FILE: Es la ruta del URI a un archivo de origen válido (PDF o TIFF) en un bucket de almacenamiento de tu proyecto de Distributed Cloud.
    • FEATURE_TYPE: Es el tipo de detección de texto que necesitas del archivo. Los valores permitidos son TEXT_DETECTION o DOCUMENT_TEXT_DETECTION.
    • DESTINATION_BUCKET: Es la ruta de acceso del URI a un bucket de almacenamiento de tu proyecto de Distributed Cloud en el que se guardarán los archivos de salida.

  2. Obtén un token de autenticación.

  3. Realiza la solicitud:

    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

    Reemplaza lo siguiente:

    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

    Reemplaza lo siguiente:

Python

Sigue estos pasos para usar el servicio de OCR desde una secuencia de comandos de Python y detectar texto en un archivo:

  1. Instala la versión más reciente de la biblioteca cliente de OCR.

  2. Establece las variables de entorno necesarias en una secuencia de comandos de Python.

  3. Autentica tu solicitud a la API.

  4. Agrega el siguiente código a la secuencia de comandos de Python que creaste:

    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)

    Reemplaza lo siguiente:

    • ENDPOINT: Es el extremo de OCR que usas para tu organización. Para obtener más información, consulta el estado y los extremos del servicio.
    • FEATURE_TYPE: Es el tipo de detección de texto que necesitas del archivo. Los valores permitidos son TEXT_DETECTION o DOCUMENT_TEXT_DETECTION.
    • SOURCE_FILE: Es la ruta del URI a un archivo de origen válido (PDF o TIFF) en un bucket de almacenamiento de tu proyecto de Distributed Cloud.
    • DESTINATION_BUCKET: Es la ruta de acceso del URI a un bucket de almacenamiento de tu proyecto de Distributed Cloud en el que se guardarán los archivos de salida.
    • PROJECT_ID: Es el ID del proyecto.

  5. Guarda la secuencia de comandos de Python.

  6. Ejecuta la secuencia de comandos de Python para detectar texto en el archivo:

    python SCRIPT_NAME

    Reemplaza SCRIPT_NAME por el nombre que le diste a tu secuencia de comandos de Python, como vision.py.

Puedes usar el nombre de la operación que devolvió el método AsyncBatchAnnotateFiles para verificar el estado de la operación.

Obtén el estado de la operación

El método get devuelve el estado más reciente de una operación de larga duración, como la solicitud sin conexión para la detección de texto. Usa este método para verificar el estado de la operación, como en el siguiente ejemplo:

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

Reemplaza OPERATION_NAME por el nombre de la operación que devolvió el método AsyncBatchAnnotateFiles cuando realizaste la solicitud sin conexión.

Mostrar lista de operaciones

El método list devuelve una lista de las operaciones que coinciden con un filtro especificado en la solicitud. El método puede devolver operaciones de un proyecto específico. Para llamar al método list, especifica el ID del proyecto y el extremo de OCR, como en el siguiente ejemplo:

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