Pipeline de ingestão do Cloud Storage

Este documento descreve o que o pipeline de ingestão do Cloud Storage faz e como executar o pipeline.

O que o pipeline de ingestão do Cloud Storage faz?

Seus usuários podem transferir documentos do Cloud Storage para o Document AI Warehouse. Lá, os usuários podem optar por processar os dados para tarefas como pesquisa, fluxos de trabalho de gerenciamento de documentos ou simplesmente testar as saídas da Document AI.

Por que usar esse pipeline?

Se muitos documentos precisarem ser ingeridos (com ou sem processamento), esse pipeline fornece um fluxo de trabalho confiável. Ele também ajuda os usuários a acelerar o tempo de integração dos clientes do Document AI Warehouse para provas de conceito ou cargas de trabalho de produção.

Recursos do pipeline

Em geral, o pipeline de ingestão do Cloud Storage é compatível com as seguintes ações:

  • Ingerir documentos brutos no 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"
  }
}

  • Ingerir documentos processados pela Document AI no 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"
  }
}

    O processor_type é necessário para indicar que os arquivos de entrada foram processados pela Document AI. processor_type (OCR_PROCESSOR, INVOICE_PROCESSOR, FORM_PARSER_PROCESSOR) pode ser encontrado no campo Digite na API aqui.

  • Ingerir documentos processados pela Document AI e documentos brutos correspondentes na mesma solicitação.

    {
  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"
  }
}

    O local input_path precisa conter documentos processados pela Document AI. O pipeline encontra os documentos brutos correspondentes para cada documento processado pela Doc AI no caminho do URI.

  • Ingerir um tipo de documento bruto e acionar o processamento da Document AI no pipeline.

    {
  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"
  }
}

    O campo extract_processor_infos precisa conter apenas um processador de extração. Todos os documentos no campo input_path são considerados um tipo de documento e processados pelo mesmo processador de extração.

  • Ingerir vários tipos de documentos brutos e acionar o processamento da Document AI no pipeline.

    {
  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"
  }
}

    O campo split_classify_processor_info classifica os documentos por tipo. O campo extract_processor_infos (transmitido como uma matriz) precisa conter diferentes processadores de extração correspondentes a cada tipo de documento do resultado da classificação.

Configuração de ingestão

O pipeline de ingestão do Cloud Storage oferece suporte a personalizações opcionais durante a ingestão de documentos, conforme descrito nas opções a seguir:

  • Use a flag skip_ingested_documents para ignorar documentos ingeridos quando o pipeline for acionado na mesma pasta do Cloud Storage mais de uma vez. Se os documentos no Cloud Storage contiverem os metadados status=ingested, que é um recurso de rastreamento de status do pipeline, eles não serão ingeridos novamente se essa flag estiver ativada.

  • Use a flag document_acl_policy para fornecer uma política de ACL no nível do documento adicional durante a criação de documentos. Esta flag é para projetos que têm ACLs no nível do documento ativadas no Document AI Warehouse.

  • Use a flag enable_document_text_extraction para que o Document AI Warehouse extraia texto de documentos brutos se eles tiverem conteúdo. Essa flag é diferente do processamento da Document AI, e a extração de documentos só é compatível com os seguintes tipos de arquivos no Document AI Warehouse.

    • RAW_DOCUMENT_FILE_TYPE_TEXT
    • RAW_DOCUMENT_FILE_TYPE_DOCX

  • Use o campo folder para especificar a pasta de destino dos documentos ingeridos. Todos os documentos ingeridos serão vinculados à pasta principal especificada.

  • Use o campo cloud_function para personalizar ainda mais os campos no arquivo proto do documento antes que ele seja enviado para o Document AI Warehouse. O valor cloud_function precisa ser um URL válido acessível à conta de serviço do Document AI Warehouse. Cada chamada precisa terminar em até 5 minutos. As solicitações e respostas estão no formato JSON. Você pode encontrar estas chaves no payload da solicitação:

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

    As chaves do payload de resposta são ingeridas no Document AI Warehouse como parte do proto. O valor original é substituído se uma chave for modificada ou adicionada à resposta. As chaves extras na resposta são descartadas. Se o valor correspondente for inválido, a ingestão de documentos vai falhar.

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

  • Personalização do pipeline de ingestão usando 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"
    }
  }
}

Acompanhamento de status

O acompanhamento de status mostra o progresso dos resultados da ingestão em todo o pipeline e em cada documento.

  • Para verificar se o pipeline foi concluído, confira se a LRO foi concluída.

  • Para verificar o status de cada documento no pipeline, consulte os metadados do Cloud Storage. O Cloud Storage cria os seguintes pares de chave-valor em cada documento.

    • Chave: status; Valor: status=queued ou status=processed ou status=ingested ou status=failed.
    • Chave: error; Valor: the error message.

Tipos de documentos aceitos

Os tipos de documentos aceitos no pipeline são os mesmos do Document AI Warehouse: texto, PDFs, imagens (PDFs digitalizados, arquivos TIFF e JPEG), arquivos do Microsoft Office (DOCX, PPTX e XSLX).

Propriedades do documento dos metadados do Cloud Storage

É possível usar os metadados do Cloud Storage no pipeline para criar propriedades personalizadas no Document AI Warehouse. Um valor de metadados do documento do Cloud Storage será copiado automaticamente para a propriedade correspondente do documento do Document AI Warehouse se a chave dele corresponder a um nome de propriedade no esquema.

Executar o pipeline

Os diferentes parâmetros são necessários para acionar funcionalidades diferentes no pipeline de ingestão do Cloud Storage. Consulte Método: projects.locations.runPipeline para mais informações.

A parte a seguir fornece dois exemplos para acionar o pipeline de ingestão do Cloud Storage.

  • Execute o pipeline de ingestão do Cloud Storage sem processadores da 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"
            }
        }
}'

  • Executar o pipeline de ingestão do Cloud Storage com processadores da 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"
            }
        }
}'

Esse comando retorna um nome de recurso para uma operação de longa duração. Com esse nome de recurso, é possível acompanhar o progresso do pipeline seguindo a próxima etapa.

Receber o resultado de uma operação de longa duração

REST

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

Próximas etapas

Para verificar os documentos ingeridos, acesse o aplicativo da Web da Document AI Warehouse.