Elabora i documenti con la funzione ML.PROCESS_DOCUMENT
Questo documento descrive come utilizzare la
funzione ML.PROCESS_DOCUMENT
con un
modello remoto
per estrarre insight utili dai documenti in una
tabella di oggetti.
Località supportate
Devi creare il modello remoto utilizzato in questa procedura nella US o EU multiregione. Devi eseguire la funzione ML.PROCESS_DOCUMENT nella stessa regione del modello remoto.
Ruoli obbligatori
Per creare un modello remoto ed elaborare i documenti, devi disporre dei seguenti ruoli Identity and Access Management (IAM) a livello di progetto:
- Crea un processore di documenti: Document AI Editor
(
roles/documentai.editor) - Creare e utilizzare set di dati, tabelle e modelli BigQuery:
BigQuery Data Editor (
roles/bigquery.dataEditor) Crea, delega e utilizza le connessioni BigQuery: BigQuery Connections Admin (
roles/bigquery.connectionsAdmin)Se non hai configurato una connessione predefinita, puoi crearne e impostarne una durante l'esecuzione dell'istruzione
CREATE MODEL. Per farlo, devi disporre del ruolo Amministratore BigQuery (roles/bigquery.admin) nel tuo progetto. Per saperne di più, consulta Configura la connessione predefinita.Concedi le autorizzazioni al account di servizio della connessione: Project IAM Admin (
roles/resourcemanager.projectIamAdmin)Creare job BigQuery: BigQuery Job User (
roles/bigquery.jobUser)
Questi ruoli predefiniti contengono le autorizzazioni necessarie per eseguire le attività descritte in questo documento. Per vedere quali sono esattamente le autorizzazioni richieste, espandi la sezione Autorizzazioni obbligatorie:
Autorizzazioni obbligatorie
- Crea un set di dati:
bigquery.datasets.create - Crea, delega e utilizza una connessione:
bigquery.connections.* - Imposta le autorizzazioni del account di servizio:
resourcemanager.projects.getIamPolicyeresourcemanager.projects.setIamPolicy - Crea un modello ed esegui l'inferenza:
bigquery.jobs.createbigquery.models.createbigquery.models.getDatabigquery.models.updateDatabigquery.models.updateMetadata
- Crea una tabella di oggetti:
bigquery.tables.createebigquery.tables.update - Crea un processore di documenti:
documentai.processors.createdocumentai.processors.updatedocumentai.processors.delete
Potresti anche ottenere queste autorizzazioni con ruoli personalizzati o altri ruoli predefiniti.
Prima di iniziare
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator role
(
roles/resourcemanager.projectCreator), which contains theresourcemanager.projects.createpermission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
Enable the BigQuery, BigQuery Connection API, and Document AI APIs, if any are not already enabled.
Roles required to enable APIs
To enable APIs, you need the
serviceusage.services.enablepermission. If you created the project, then you likely already have this permission through the Owner role (roles/owner). Otherwise, you can get this permission through the Service Usage Admin role (roles/serviceusage.serviceUsageAdmin). Learn how to grant roles.
Crea un processore
Crea un processore in Document AI per elaborare i documenti. Il processore deve essere di un tipo supportato.
Crea un set di dati
Devi creare il set di dati, la connessione e il processore di documenti nella stessa regione.
Crea un set di dati BigQuery per contenere le tue risorse:
Console
Nella console Google Cloud , vai alla pagina BigQuery.
Nel riquadro a sinistra, fai clic su Spazio di esplorazione:

Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.
Nel riquadro Explorer, fai clic sul nome del progetto.
Fai clic su Visualizza azioni > Crea set di dati.
Nella pagina Crea set di dati, segui questi passaggi:
In ID set di dati, digita un nome per il set di dati.
Per Tipo di località, seleziona Regione o Multi-regione.
- Se hai selezionato Regione, seleziona una località dall'elenco Regione.
- Se hai selezionato Multiregione, seleziona Stati Uniti o Europa dall'elenco Multiregione.
Fai clic su Crea set di dati.
bq
Crea una connessione
Crea una connessione alle risorse Cloud e ottieni il account di servizio della connessione. Crea la connessione nella stessa località del set di dati creato nel passaggio precedente.
Puoi saltare questo passaggio se hai configurato una connessione predefinita o se hai il ruolo Amministratore BigQuery.
Seleziona una delle seguenti opzioni:Console
Vai alla pagina BigQuery.
Nel riquadro a sinistra, fai clic su Explorer:

Se non vedi il riquadro a sinistra, fai clic su Espandi riquadro sinistro per aprirlo.
Nel riquadro Explorer, espandi il nome del progetto, quindi fai clic su Connessioni.
Nella pagina Connessioni, fai clic su Crea connessione.
In Tipo di connessione, scegli Modelli remoti di Vertex AI, funzioni remote, BigLake e Spanner (risorsa Cloud).
Nel campo ID connessione, inserisci un nome per la connessione.
In Tipo di località, seleziona una località per la connessione. La connessione deve essere collocata insieme alle altre risorse, ad esempio i set di dati.
Fai clic su Crea connessione.
Fai clic su Vai alla connessione.
Nel riquadro Informazioni sulla connessione, copia l'ID account di servizio da utilizzare in un passaggio successivo.
SQL
Utilizza l'istruzione CREATE CONNECTION:
Nella console Google Cloud , vai alla pagina BigQuery.
Nell'editor di query, inserisci la seguente istruzione:
CREATE CONNECTION [IF NOT EXISTS] `CONNECTION_NAME` OPTIONS ( connection_type = "CLOUD_RESOURCE", friendly_name = "FRIENDLY_NAME", description = "DESCRIPTION" );
Sostituisci quanto segue:
-
CONNECTION_NAME: il nome della connessione nel formatoPROJECT_ID.LOCATION.CONNECTION_ID,LOCATION.CONNECTION_IDoCONNECTION_ID. Se il progetto o la località vengono omessi, vengono dedotti dal progetto e dalla località in cui viene eseguita l'istruzione. -
FRIENDLY_NAME(facoltativo): un nome descrittivo per la connessione. -
DESCRIPTION(facoltativo): una descrizione della connessione.
-
Fai clic su Esegui.
Per saperne di più su come eseguire le query, consulta Esegui una query interattiva.
bq
In un ambiente a riga di comando, crea una connessione:
bq mk --connection --location=REGION --project_id=PROJECT_ID \ --connection_type=CLOUD_RESOURCE CONNECTION_ID
Il parametro
--project_idsostituisce il progetto predefinito.Sostituisci quanto segue:
REGION: la tua regione di connessionePROJECT_ID: il tuo ID progetto Google CloudCONNECTION_ID: un ID per la tua connessione
Quando crei una risorsa di connessione, BigQuery crea un account di servizio di sistema univoco e lo associa alla connessione.
Risoluzione dei problemi: se ricevi il seguente errore di connessione, aggiorna Google Cloud SDK:
Flags parsing error: flag --connection_type=CLOUD_RESOURCE: value should be one of...
Recupera e copia l'ID del account di servizio da utilizzare in un passaggio successivo:
bq show --connection PROJECT_ID.REGION.CONNECTION_ID
L'output è simile al seguente:
name properties 1234.REGION.CONNECTION_ID {"serviceAccountId": "connection-1234-9u56h9@gcp-sa-bigquery-condel."}
Python
Prima di provare questo esempio, segui le istruzioni di configurazione di Python nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Python.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Node.js
Prima di provare questo esempio, segui le istruzioni di configurazione di Node.js nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Node.js.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Java
Prima di provare questo esempio, segui le istruzioni di configurazione di Java nella guida rapida di BigQuery per l'utilizzo delle librerie client. Per saperne di più, consulta la documentazione di riferimento dell'API BigQuery Java.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
Terraform
Utilizza la risorsa google_bigquery_connection.
Per eseguire l'autenticazione in BigQuery, configura le Credenziali predefinite dell'applicazione. Per saperne di più, vedi Configura l'autenticazione per le librerie client.
L'esempio seguente crea una connessione alle risorse Cloud denominata
my_cloud_resource_connection nella regione US:
Per applicare la configurazione Terraform in un progetto Google Cloud , completa i passaggi descritti nelle sezioni seguenti.
Prepara Cloud Shell
- Avvia Cloud Shell.
-
Imposta il progetto Google Cloud predefinito in cui vuoi applicare le configurazioni Terraform.
Devi eseguire questo comando una sola volta per progetto e puoi eseguirlo in qualsiasi directory.
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
Le variabili di ambiente vengono sostituite se imposti valori espliciti nel file di configurazione Terraform.
Prepara la directory
Ogni file di configurazione Terraform deve avere la propria directory (chiamata anche modulo principale).
-
In Cloud Shell, crea una directory e un nuovo file al suo interno. Il nome file deve avere l'estensione
.tf, ad esempiomain.tf. In questo tutorial, il file è denominatomain.tf.mkdir DIRECTORY && cd DIRECTORY && touch main.tf
-
Se stai seguendo un tutorial, puoi copiare il codice campione in ogni sezione o passaggio.
Copia il codice campione nel file
main.tfappena creato.Facoltativamente, copia il codice da GitHub. Questa opzione è consigliata quando lo snippet Terraform fa parte di una soluzione end-to-end.
- Esamina e modifica i parametri di esempio da applicare al tuo ambiente.
- Salva le modifiche.
-
Inizializza Terraform. Devi eseguire questa operazione una sola volta per directory.
terraform init
Facoltativamente, per utilizzare l'ultima versione del provider Google, includi l'opzione
-upgrade:terraform init -upgrade
Applica le modifiche
-
Esamina la configurazione e verifica che le risorse che Terraform creerà o aggiornerà corrispondano alle tue aspettative:
terraform plan
Apporta le correzioni necessarie alla configurazione.
-
Applica la configurazione Terraform eseguendo il comando seguente e inserendo
yesal prompt:terraform apply
Attendi che Terraform visualizzi il messaggio "Apply complete!".
- Apri il tuo progetto Google Cloud per visualizzare i risultati. Nella console Google Cloud , vai alle risorse nell'interfaccia utente per assicurarti che Terraform le abbia create o aggiornate.
Concedi l'accesso al service account
Seleziona una delle seguenti opzioni:
Console
Vai alla pagina IAM e amministrazione.
Fai clic su Concedi l'accesso.
Viene visualizzata la finestra di dialogo Aggiungi entità.
Nel campo Nuove entità, inserisci l'ID del account di servizio che hai copiato in precedenza.
Nel campo Seleziona un ruolo, seleziona Document AI e poi Visualizzatore Document AI.
Fai clic su Aggiungi un altro ruolo.
Nel campo Seleziona un ruolo, seleziona Cloud Storage e poi Visualizzatore oggetti Storage.
Fai clic su Salva.
gcloud
Utilizza il
comando gcloud projects add-iam-policy-binding:
gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/documentai.viewer' --condition=None gcloud projects add-iam-policy-binding 'PROJECT_NUMBER' --member='serviceAccount:MEMBER' --role='roles/storage.objectViewer' --condition=None
Sostituisci quanto segue:
PROJECT_NUMBER: il numero del progetto.MEMBER: l'ID del account di servizio che hai copiato in precedenza.
La mancata concessione dell'autorizzazione genera un errore Permission denied.
crea un modello
Crea un modello remoto con un REMOTE_SERVICE_TYPE di CLOUD_AI_DOCUMENT_V1:
CREATE OR REPLACE MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME` REMOTE WITH CONNECTION {DEFAULT | `PROJECT_ID.REGION.CONNECTION_ID`} OPTIONS ( REMOTE_SERVICE_TYPE = 'CLOUD_AI_DOCUMENT_V1', DOCUMENT_PROCESSOR = 'PROCESSOR_ID' );
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto.DATASET_ID: l'ID del set di dati che conterrà il modello.MODEL_NAME: il nome del modello.REGION: la regione utilizzata dalla connessione.CONNECTION_ID: l'ID connessione, ad esempiomyconnection.Quando visualizzi i dettagli della connessione nella console Google Cloud , l'ID connessione è il valore nell'ultima sezione dell'ID connessione completo mostrato in ID connessione, ad esempio
projects/myproject/locations/connection_location/connections/myconnection.PROCESSOR_ID: l'ID del processore di documenti. Per trovare questo valore, visualizza i dettagli del processore, quindi guarda la riga ID nella sezione Informazioni di base.
Per visualizzare le colonne di output del modello, fai clic su Vai al modello nel risultato della query dopo la creazione del modello. Le colonne di output sono mostrate nella sezione Etichette della scheda Schema.
Crea una tabella di oggetti
Crea una tabella di oggetti su un insieme di documenti in Cloud Storage. I documenti nella tabella degli oggetti devono essere di un tipo supportato.
Elabora documenti
Elabora tutti i documenti con ML.PROCESS_DOCUMENT:
SELECT * FROM ML.PROCESS_DOCUMENT( MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`, TABLE `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME` [, PROCESS_OPTIONS => ( JSON 'PROCESS_OPTIONS')] );
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto.DATASET_ID: l'ID del set di dati che contiene il modello.MODEL_NAME: il nome del modello.OBJECT_TABLE_NAME: il nome della tabella degli oggetti che contiene gli URI dei documenti da elaborare.PROCESS_OPTIONS: la configurazione JSON che specifica come elaborare i documenti. Ad esempio, puoi utilizzarlo per specificare la suddivisione in blocchi dei documenti per l'analizzatore del layout
In alternativa, elabora alcuni documenti con ML.PROCESS_DOCUMENT:
SELECT * FROM ML.PROCESS_DOCUMENT( MODEL `PROJECT_ID.DATASET_ID.MODEL_NAME`, (SELECT * FROM `PROJECT_ID.DATASET_ID.OBJECT_TABLE_NAME` WHERE FILTERS LIMIT NUM_DOCUMENTS ) [, PROCESS_OPTIONS => ( JSON 'PROCESS_OPTIONS')] );
Sostituisci quanto segue:
PROJECT_ID: il tuo ID progetto.DATASET_ID: l'ID del set di dati che contiene il modello.MODEL_NAME: il nome del modello.OBJECT_TABLE_NAME: il nome della tabella degli oggetti che contiene gli URI dei documenti da elaborare.FILTERS: condizioni per filtrare i documenti che vuoi elaborare nelle colonne della tabella degli oggetti.NUM_DOCUMENTS: il numero massimo di documenti che vuoi elaborare.PROCESS_OPTIONS: la configurazione JSON che definisce la configurazione, ad esempio la configurazione di suddivisione in blocchi per il parser di layout
Esempi
Esempio 1
L'esempio seguente utilizza il parser delle spese per elaborare i documenti rappresentati dalla tabella documents:
SELECT * FROM ML.PROCESS_DOCUMENT( MODEL `myproject.mydataset.expense_parser`, TABLE `myproject.mydataset.documents` );
Questa query restituisce i report sulle spese analizzati, tra cui la valuta, l'importo totale, la data della ricevuta e le voci dei report sulle spese. La colonna ml_process_document_result contiene l'output non elaborato dell'analizzatore sintattico delle spese, mentre la colonna ml_process_document_status contiene gli eventuali errori restituiti dall'elaborazione dei documenti.
Esempio 2
L'esempio seguente mostra come filtrare la tabella degli oggetti per scegliere i documenti da elaborare e poi scrivere i risultati in una nuova tabella:
CREATE TABLE `myproject.mydataset.expense_details` AS SELECT uri, content_type, receipt_date, purchase_time, total_amount, currency FROM ML.PROCESS_DOCUMENT( MODEL `myproject.mydataset.expense_parser`, (SELECT * FROM `myproject.mydataset.expense_reports` WHERE uri LIKE '%restaurant%'));
Passaggi successivi
- Per saperne di più sull'inferenza del modello in BigQuery ML, consulta Panoramica dell'inferenza del modello.
- Per saperne di più sull'utilizzo delle API Cloud AI per eseguire attività AI, consulta Panoramica delle applicazioni AI.
- Per saperne di più sulle istruzioni e sulle funzioni SQL supportate per i modelli di AI generativa, consulta User journey end-to-end per i modelli di AI generativa.