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?

Los usuarios pueden transferir documentos de Cloud Storage a Document AI Warehouse. Allí, los usuarios pueden optar por procesarlos para tareas como búsquedas, 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 transferir 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:

  • Transferir 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"
  }
}

  • Transferir 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"
  }
}

    Se requiere processor_type para indicar que los archivos de entrada fueron procesados por Document AI. processor_type (OCR_PROCESSOR, INVOICE_PROCESSOR, FORM_PARSER_PROCESSOR) se puede encontrar en el campo Tipo en la API aquí.

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

    {
  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 de 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.

  • Transferir un tipo de documento sin procesar y activar el procesamiento con IA 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 del campo input_path se consideran un tipo de documento y se procesan con el mismo procesador de extracción.

  • Transferir varios tipos de documentos sin procesar y activar el procesamiento con IA 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 que correspondan a cada tipo de documento del resultado de la clasificación.

Configuración de la 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 transferidos cuando la canalización se activa en la misma carpeta de Cloud Storage más de una vez. Si los documentos de Cloud Storage contienen los metadatos status=ingested, que es una función de seguimiento de 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 proyectos que tienen ACL a nivel del documento habilitadas en Document AI Warehouse.

  • Usa la marca enable_document_text_extraction para que Document AI Warehouse extraiga texto de documentos sin procesar si los documentos contienen contenido. Esta marca es diferente del procesamiento con IA 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 transferidos. Todos los documentos transferidos se vincularán en la carpeta superior determinada.

  • Usa el campo cloud_function para personalizar aún más los campos del archivo proto del documento antes de que se transfiera a Document AI Warehouse. El valor 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 anula si se modifica o se agrega una clave a la respuesta. Se descartan las claves adicionales de la respuesta. Si el valor correspondiente no es válido, falla la transferencia de documentos.

    • 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 de 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 está completa, comprueba si se completó la LRO.

  • Para verificar el estado de cada documento en la canalización, consulta 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 por Document AI Warehouse: texto, archivos PDF, imágenes (archivos PDF escaneados, archivos TIFF, archivos JPEG), archivos de Microsoft Office (DOCX, PPTX, XSLX).

Propiedades de los documentos 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. Un valor de metadatos del documento de Cloud Storage se copiará automáticamente a la propiedad de documento de Document AI Warehouse correspondiente si su clave coincide con un nombre de propiedad en el esquema.

Ejecuta la canalización

Se requieren los diferentes parámetros 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 transferidos, ve a la web aplicación de Document AI Warehouse.