Pipeline d'ingestion Cloud Storage

Ce document décrit le fonctionnement du pipeline d'ingestion Cloud Storage et explique comment l'exécuter.

Que fait le pipeline d'ingestion Cloud Storage ?

Vos utilisateurs peuvent transférer des documents de Cloud Storage vers Document AI Warehouse. Les utilisateurs peuvent choisir de les faire traiter pour des tâches telles que la recherche, les workflows de gestion de documents ou simplement pour tester les résultats de Document AI.

Pourquoi utiliser ce pipeline ?

Si de nombreux documents doivent être ingérés (avec ou sans traitement), ce pipeline fournit un workflow fiable. Il aide également les utilisateurs à accélérer l'intégration des clients Document AI Warehouse pour les démonstrations de faisabilité ou les charges de travail de production.

Fonctionnalités du pipeline

En général, le pipeline d'ingestion Cloud Storage est compatible avec les actions suivantes :

  • Ingérez des documents bruts dans 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"
  }
}

  • Ingérez les documents traités par Document AI dans 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"
  }
}

    Le processor_type est obligatoire pour indiquer que les fichiers d'entrée ont été traités par Document AI. processor_type (OCR_PROCESSOR, INVOICE_PROCESSOR, FORM_PARSER_PROCESSOR) se trouve dans le champ Type in API (Saisir l'API) ici.

  • Ingérez les documents traités par Document AI et les documents bruts correspondants dans la même requête.

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

    L'emplacement input_path doit contenir des documents traités par Document AI. Le pipeline trouve les documents bruts correspondants pour chaque document traité par Document AI sous ce chemin d'URI.

  • Ingérez un type de document brut et déclenchez le traitement Document AI dans le 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"
  }
}

    Le champ extract_processor_infos ne doit contenir qu'un seul processeur d'extraction. Tous les documents du champ input_path sont considérés comme un seul type de document et sont traités par le même processeur d'extraction.

  • Ingérez plusieurs types de documents bruts et déclenchez le traitement Document AI dans le 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"
  }
}

    Le champ split_classify_processor_info classe les documents par type. Le champ extract_processor_infos (transmis sous forme de tableau) doit contenir différents processeurs d'extraction correspondant à chaque type de document du résultat de la classification.

Configuration de l'ingestion

Le pipeline d'ingestion Cloud Storage accepte les personnalisations facultatives lors de l'ingestion de documents, comme décrit par les options suivantes :

  • Utilisez l'indicateur skip_ingested_documents pour ignorer les documents ingérés lorsque le pipeline est déclenché plusieurs fois sur le même dossier Cloud Storage. Si les documents dans Cloud Storage contiennent les métadonnées status=ingested, qui sont une fonctionnalité de suivi de l'état du pipeline, ils ne sont pas réingérés si cet indicateur est activé.

  • Utilisez le flag document_acl_policy pour fournir une stratégie LCA supplémentaire au niveau du document lors de la création de documents. Ce signalement concerne les projets pour lesquels les LCA au niveau du document sont activées dans Document AI Warehouse.

  • Utilisez l'indicateur enable_document_text_extraction pour que Document AI Warehouse extraie le texte des documents bruts s'ils contiennent du contenu. Cet indicateur est différent du traitement Document AI et de l'extraction de documents. Il n'est compatible qu'avec les types de fichiers de documents suivants dans Document AI Warehouse.

    • RAW_DOCUMENT_FILE_TYPE_TEXT
    • RAW_DOCUMENT_FILE_TYPE_DOCX

  • Utilisez le champ folder pour spécifier le dossier cible des documents ingérés. Tous les documents ingérés seront associés au dossier parent indiqué.

  • Utilisez le champ cloud_function pour personnaliser davantage les champs du fichier proto du document avant qu'il ne soit envoyé à Document AI Warehouse. La valeur cloud_function doit être une URL valide accessible au compte de service Document AI Warehouse. Chaque appel doit se terminer dans les cinq minutes. Les requêtes et les réponses sont au format JSON. Vous trouverez peut-être ces clés dans le corps de la requête :

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

    Les clés de la charge utile de la réponse sont ingérées dans Document AI Warehouse dans le cadre du fichier proto. La valeur d'origine est écrasée si une clé est modifiée ou ajoutée à la réponse. Les clés supplémentaires de la réponse sont ignorées. Si la valeur correspondante n'est pas valide, l'ingestion du document échoue.

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

  • Personnalisez le pipeline d'ingestion à l'aide de 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"
    }
  }
}

Suivi de l'état

Le suivi de l'état indique la progression des résultats de l'ingestion pour l'ensemble du pipeline et pour chaque document.

  • Pour vérifier si le pipeline est terminé, vérifiez si l'opération LRO est terminée.

  • Vous pouvez vérifier l'état de chaque document du pipeline en consultant les métadonnées Cloud Storage. Cloud Storage crée les paires clé/valeur suivantes sur chaque document.

    • Clé : status ; Valeur : status=queued, status=processed, status=ingested ou status=failed.
    • Clé : error ; Valeur : the error message.

Types de documents acceptés

Les types de documents acceptés dans le pipeline sont les mêmes que ceux acceptés dans Document AI Warehouse : texte, PDF, images (PDF scannés, fichiers TIFF, fichiers JPEG), fichiers Microsoft Office (DOCX, PPTX, XLSX).

Propriétés des documents à partir des métadonnées Cloud Storage

Vous pouvez utiliser les métadonnées Cloud Storage dans le pipeline pour créer des propriétés personnalisées dans Document AI Warehouse. Une valeur de métadonnées du document Cloud Storage sera automatiquement copiée dans la propriété correspondante du document Document AI Warehouse si sa clé correspond à un nom de propriété dans le schéma.

Exécuter le pipeline

Les différents paramètres sont nécessaires pour déclencher différentes fonctionnalités dans le pipeline d'ingestion Cloud Storage. Pour en savoir plus, consultez Méthode : projects.locations.runPipeline.

La partie suivante fournit deux exemples pour déclencher le pipeline d'ingestion Cloud Storage.

  • Exécutez le pipeline d'ingestion Cloud Storage sans processeurs 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"
            }
        }
}'

  • Exécutez le pipeline d'ingestion Cloud Storage avec des processeurs 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"
            }
        }
}'

Cette commande renvoie un nom de ressource pour une opération de longue durée. Avec ce nom de ressource, vous pouvez suivre la progression du pipeline en passant à l'étape suivante.

Obtenir le résultat d'une opération de longue durée

REST

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

Étapes suivantes

Pour vérifier les documents ingérés, accédez à l'application Web de Document AI Warehouse.