Pipeline di importazione di Cloud Storage

Questo documento descrive cosa fa la pipeline di importazione di Cloud Storage e come eseguirla.

Che cosa fa la pipeline di importazione di Cloud Storage?

I tuoi utenti possono trasferire documenti da Cloud Storage a Document AI Warehouse. Qui gli utenti possono scegliere di farli elaborare per attività come la ricerca, i flussi di lavoro di gestione dei documenti o semplicemente per testare gli output di Document AI.

Perché utilizzare questa pipeline?

Se è necessario importare molti documenti (con o senza elaborazione), questa pipeline fornisce un flusso di lavoro affidabile. Inoltre, aiuta gli utenti ad accelerare i tempi di onboarding dei clienti di Document AI Warehouse per proof of concept o carichi di lavoro di produzione.

Funzionalità della pipeline

In generale, la pipeline di importazione di Cloud Storage supporta le seguenti azioni:

  • Importa i documenti non elaborati in 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"
  }
}

  • Importa i documenti elaborati da Document AI in 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"
  }
}

    Il processor_type è obbligatorio per indicare che i file di input sono stati elaborati da Document AI. processor_type (OCR_PROCESSOR, INVOICE_PROCESSOR, FORM_PARSER_PROCESSOR) si trova nel campo Digita API qui.

  • Inserisci i documenti elaborati da Document AI e i documenti non elaborati corrispondenti nella stessa richiesta.

    {
  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 posizione input_path deve contenere i documenti elaborati da Document AI. La pipeline trova i documenti non elaborati corrispondenti per ogni documento elaborato da Doc AI nel percorso URI.

  • Inserisci un tipo di documento non elaborato e attiva l'elaborazione di Document AI nella 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"
  }
}

    Il campo extract_processor_infos deve contenere un solo processore di estrazione. Tutti i documenti nel campo input_path sono considerati un unico tipo di documento ed elaborati dallo stesso processore di estrazione.

  • Inserisci più tipi di documenti non elaborati e attiva l'elaborazione di Document AI nella 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"
  }
}

    Il campo split_classify_processor_info classifica i documenti in base al tipo. Il campo extract_processor_infos (trasmesso come array) deve contenere diversi processori di estrazione corrispondenti a ogni tipo di documento del risultato della classificazione.

Configurazione dell'importazione

La pipeline di importazione di Cloud Storage supporta personalizzazioni facoltative durante l'importazione dei documenti, come descritto dalle seguenti opzioni:

  • Utilizza il flag skip_ingested_documents per ignorare i documenti inseriti quando la pipeline viene attivata più di una volta nella stessa cartella Cloud Storage. Se i documenti in Cloud Storage contengono i metadati status=ingested, una funzionalità di monitoraggio dello stato della pipeline, i documenti non vengono reingestiti se questo flag è abilitato.

  • Utilizza il flag document_acl_policy per fornire un'ulteriore policy ACL a livello di documento durante la creazione dei documenti. Questo flag è per i progetti in cui sono abilitate le ACL a livello di documento in Document AI Warehouse.

  • Utilizza il flag enable_document_text_extraction per fare in modo che Document AI Warehouse estragga il testo dai documenti non elaborati se contengono contenuti. Questo flag è diverso dall'elaborazione di Document AI e l'estrazione di documenti supporta solo i seguenti tipi di file di documenti in Document AI Warehouse.

    • RAW_DOCUMENT_FILE_TYPE_TEXT
    • RAW_DOCUMENT_FILE_TYPE_DOCX

  • Utilizza il campo folder per specificare la cartella di destinazione dei documenti importati. Tutti i documenti importati verranno collegati alla cartella principale specificata.

  • Utilizza il campo cloud_function per personalizzare ulteriormente i campi nel file proto del documento prima che venga inviato a Document AI Warehouse. Il valore cloud_function deve essere un URL valido accessibile all'account di servizio Document AI Warehouse. Ogni chiamata deve terminare entro 5 minuti. Le richieste e le risposte sono in formato JSON. Potresti trovare queste chiavi nel payload della richiesta:

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

    Le chiavi del payload di risposta vengono inserite in Document AI Warehouse come parte del proto. Il valore originale viene sovrascritto se una chiave viene modificata o aggiunta alla risposta. Le chiavi aggiuntive nella risposta vengono eliminate. Se il valore corrispondente non è valido, l'importazione del documento non riesce.

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

  • Personalizzazione della pipeline di importazione utilizzando 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"
    }
  }
}

Monitoraggio dello stato

Il monitoraggio dello stato mostra l'avanzamento dei risultati dell'importazione nell'intera pipeline e in ogni documento.

  • Puoi verificare se la pipeline è stata completata controllando se l'operazione LRO è stata eseguita.

  • Puoi controllare lo stato di ogni documento nella pipeline visualizzando i metadati di Cloud Storage. Cloud Storage crea le seguenti coppie chiave-valore in ogni documento.

    • Chiave: status; valore: status=queued o status=processed o status=ingested o status=failed.
    • Chiave: error; Valore: the error message.

Tipi di documenti supportati

I tipi di documenti supportati nella pipeline sono gli stessi di Document AI Warehouse: testo, PDF, immagini (PDF scansionati, file TIFF, file JPEG), file Microsoft Office (DOCX, PPTX, XSLX).

Proprietà del documento dai metadati di Cloud Storage

Puoi utilizzare i metadati di Cloud Storage nella pipeline per creare proprietà personalizzate in Document AI Warehouse. Se la chiave corrisponde a un nome di proprietà nello schema, un valore dei metadati del documento Cloud Storage verrà copiato automaticamente nella proprietà del documento Document AI Warehouse corrispondente.

esegui la pipeline.

I diversi parametri sono necessari per attivare funzionalità diverse nella pipeline di importazione di Cloud Storage. Per ulteriori informazioni, consulta Metodo: projects.locations.runPipeline.

La parte seguente fornisce due esempi per attivare la pipeline di importazione di Cloud Storage.

  • Esegui la pipeline di importazione di Cloud Storage senza i processori 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"
            }
        }
}'

  • Esegui la pipeline di importazione di Cloud Storage con i processori 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"
            }
        }
}'

Questo comando restituisce il nome di una risorsa per un'operazione a lunga esecuzione. Con questo nome risorsa, puoi monitorare l'avanzamento della pipeline seguendo il passaggio successivo.

Ottieni il risultato dell'operazione a lunga esecuzione

REST

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

Passaggi successivi

Per controllare i documenti inseriti, vai all'applicazione web di Document AI Warehouse.