Canalización de transferencia de Cloud Storage

En este documento, se describe qué hace la canalización de transferencia de Cloud Storage y cómo ejecutarla.

¿Qué hace la canalización de transferencia de Cloud Storage?

Tus usuarios pueden transferir documentos de Cloud Storage a Document AI Warehouse. Allí, los usuarios pueden optar por que se procesen para tareas como la búsqueda, los flujos de trabajo de administración de documentos o simplemente probar los resultados de Document AI.

¿Por qué usar esta canalización?

Si se deben ingerir muchos documentos (con o sin procesamiento), esta canalización proporciona un flujo de trabajo confiable. También ayuda a los usuarios a acelerar el tiempo de incorporación de los clientes de Document AI Warehouse para pruebas de concepto o cargas de trabajo de producción.

Funciones de la canalización

En general, la canalización de transferencia de Cloud Storage admite las siguientes acciones:

  • Transfiere documentos sin procesar a Document AI Warehouse.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
  }
}

  • Transfiere los documentos procesados por Document AI a Document AI Warehouse.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    processor_type: "PROCESS_TYPE"
  }
}

    El processor_type es obligatorio para indicar que Document AI procesó los archivos de entrada. processor_type (OCR_PROCESSOR, INVOICE_PROCESSOR, FORM_PARSER_PROCESSOR) se puede encontrar en el campo Escribe en la API aquí.

  • Ingiere en la misma solicitud los documentos procesados por Document AI y los documentos sin procesar correspondientes.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    processor_type: "PROCESS_TYPE"
  }
}

    La ubicación input_path debe contener documentos procesados por Document AI. La canalización encuentra los documentos sin procesar correspondientes para cada documento procesado por Doc AI en esa ruta de URI.

  • Ingiere un tipo de documento sin procesar y activa el procesamiento de Document AI en la canalización.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_with_doc_ai_processors_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    extract_processor_infos: {
      processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
      schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
    },
    processor_results_folder_path: "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME"
  }
}

    El campo extract_processor_infos debe contener solo un procesador de extracción. Todos los documentos incluidos en el campo input_path se consideran un tipo de documento y se procesan con el mismo procesador de extracción.

  • Ingiere varios tipos de documentos sin procesar y activa el procesamiento de Document AI en la canalización.

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_with_doc_ai_processors_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    split_classify_processor_info: {
      processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID"
    },
    extract_processor_infos: [
      {
        processor_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
        document_type: "DOCUMENT_TYPE",
        schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
      }
    ],
    processor_results_folder_path: "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME"
  }
}

    El campo split_classify_processor_info clasifica los documentos por tipo. El campo extract_processor_infos (que se pasa como un array) debe contener diferentes procesadores de extracción correspondientes a cada tipo de documento del resultado de la clasificación.

Configuración de transferencia

La canalización de transferencia de Cloud Storage admite personalizaciones opcionales durante la transferencia de documentos, como se describe en las siguientes opciones:

  • Usa la marca skip_ingested_documents para omitir los documentos ingeridos cuando la canalización se activa en la misma carpeta de Cloud Storage más de una vez. Si los documentos en Cloud Storage contienen los metadatos status=ingested, que son una función de seguimiento del estado de la canalización, los documentos no se vuelven a transferir si esta marca está habilitada.

  • Usa la marca document_acl_policy para proporcionar una política de LCA adicional a nivel del documento durante la creación de documentos. Esta marca es para los proyectos que tienen habilitadas las LCA a nivel del documento en Document AI Warehouse.

  • Usa la marca enable_document_text_extraction para que Document AI Warehouse extraiga texto de documentos sin procesar si estos contienen contenido. Esta marca es diferente del procesamiento de Document AI, y la extracción de documentos solo admite los siguientes tipos de archivos de documentos en Document AI Warehouse.

    • RAW_DOCUMENT_FILE_TYPE_TEXT
    • RAW_DOCUMENT_FILE_TYPE_DOCX

  • Usa el campo folder para especificar la carpeta de destino de los documentos ingeridos. Todos los documentos incorporados se vincularán en la carpeta principal proporcionada.

  • Usa el campo cloud_function para personalizar aún más los campos en el archivo .proto del documento antes de que se envíe a Document AI Warehouse. El valor de cloud_function debe ser una URL válida a la que pueda acceder la cuenta de servicio de Document AI Warehouse. Cada llamada debe finalizar en un plazo de 5 minutos. Las solicitudes y respuestas están en formato JSON. Es posible que encuentres estas claves en la carga útil de la solicitud:

    • display_name
    • properties
    • plain_text o cloud_ai_document.text
    • reference_id
    • document_schema_name
    • raw_document_path
    • raw_document_file_type

    Las claves de la carga útil de la respuesta se transfieren a Document AI Warehouse como parte del .proto. El valor original se reemplaza si se modifica o agrega una clave a la respuesta. Se descartan las claves adicionales en la respuesta. Si el valor correspondiente no es válido, falla la transferencia del documento.

    • display_name
    • properties
    • plain_text o cloud_ai_document.text
    • reference_id
    • document_acl_policy
    • folder

  • Personalización de la canalización de transferencia con pipeline_config

    {
  name: "projects/PROJECT_NUMBER/locations/LOCATION_ID",
  gcs_ingest_pipeline: {
    input_path: "gs://BUCKET_NAME/FOLDER_NAME",
    schema_name: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
    skip_ingested_documents: "true",
    pipeline_config: {
      enable_document_text_extraction: "true"
      folder: "projects/PROJECT_NUMBER/locations/LOCATION_ID/documents/FOLDER_DOCUMENT_ID",
      cloud_function: "https://REGION-PROJECT_ID.cloudfunctions.net/CLOUD_FUNCTION_NAME"
    }
  }
}

Seguimiento de estado

El seguimiento del estado muestra el progreso de los resultados de la transferencia en toda la canalización y en cada documento.

  • Para verificar si la canalización se completó, comprueba si se completó el LRO.

  • Puedes verificar el estado de cada documento en la canalización si consultas los metadatos de Cloud Storage. Cloud Storage crea los siguientes pares clave-valor en cada documento.

    • Clave: status; Valor: status=queued, status=processed, status=ingested o status=failed
    • Clave: error; valor: the error message.

Tipos de documentos admitidos

Los tipos de documentos admitidos en la canalización son los mismos que los tipos de documentos admitidos en Document AI Warehouse: texto, PDFs, imágenes (PDFs escaneados, archivos TIFF, archivos JPEG) y archivos de Microsoft Office (DOCX, PPTX, XLSX).

Propiedades del documento a partir de los metadatos de Cloud Storage

Puedes usar los metadatos de Cloud Storage en la canalización para crear propiedades personalizadas en Document AI Warehouse. Si la clave coincide con el nombre de una propiedad en el esquema, se copiará automáticamente un valor de metadatos del documento de Cloud Storage a la propiedad correspondiente del documento de Document AI Warehouse.

Ejecuta la canalización

Los diferentes parámetros son necesarios para activar diferentes funcionalidades en la canalización de transferencia de Cloud Storage. Consulta Método: projects.locations.runPipeline para obtener más información.

En la siguiente parte, se proporcionan dos ejemplos para activar la canalización de transferencia de Cloud Storage.

  • Ejecuta la canalización de transferencia de Cloud Storage sin procesadores de Document AI.

    REST

    curl --location --request POST 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID:runPipeline' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${AUTH_TOKEN}" \
--data '{
        "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID",
        "gcs_ingest_pipeline": {
            "input_path": "gs://BUCKET_NAME/FOLDER_NAME/",
"schema_name": "projects/PROJECT_NUMBER/locations/
LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID",
            "skip_ingested_documents": "true"
        },
        "request_metadata": {
            "user_info": {
                "id": "user:USER EMAIL ADDRESS"
            }
        }
}'

  • Ejecuta la canalización de transferencia de Cloud Storage con procesadores de Document AI.

    REST

    curl --location --request POST 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION_ID:runPipeline' \
--header 'Content-Type: application/json' \
--header "Authorization: Bearer ${AUTH_TOKEN}" \
--data '{
        "name": "projects/PROJECT_NUMBER/locations/LOCATION_ID",
        "gcs_ingest_with_doc_ai_processors_pipeline": {
            "input_path": "gs://BUCKET_NAME/FOLDER_NAME/",
            "split_classify_processor_info": {
              "processor_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID"
            },
            "extract_processor_infos": [
              {
                "processor_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/processors/PROCESSOR_ID",
                "document_type": "DOCUMENT_TYPE",
                "schema_name": "projects/PROJECT_NUMBER/locations/LOCATION_ID/documentSchemas/DOCUMENT_SCHEMA_ID"
              }
            ],
            "processor_results_folder_path": "gs://OUTPUT_BUCKET_NAME/OUTPUT_BUCKET_FOLDER_NAME/"
            "skip_ingested_documents": "true"
        },
        "request_metadata": {
            "user_info": {
                "id": "user:USER EMAIL ADDRESS"
            }
        }
}'

Este comando devuelve un nombre de recurso para una operación de larga duración. Con este nombre de recurso, puedes hacer un seguimiento del progreso de la canalización siguiendo el siguiente paso.

Obtén el resultado de la operación de larga duración

REST

curl --location --request GET 'https://contentwarehouse.googleapis.com/v1/projects/PROJECT_NUMBER/locations/LOCATION/operations/OPERATION' \
--header "Authorization: Bearer ${AUTH_TOKEN}"

Próximos pasos

Para verificar los documentos que se incorporaron, ve a la aplicación web de Document AI Warehouse.