1. Panoramica
Che cos'è Document AI?
L'API Document AI è una soluzione di comprensione dei documenti che prende dati non strutturati, come documenti, email e così via, e li rende più facili da comprendere, analizzare e utilizzare. L'API fornisce una struttura tramite la classificazione dei contenuti, l'estrazione di entità, la ricerca avanzata e altro ancora.
In questo tutorial ti concentrerai sull'utilizzo dell'API Document AI con Node.js. Il tutorial mostra come analizzare un semplice modulo di anamnesi medica.
Cosa imparerai a fare
- Come abilitare l'API Document AI
- Come autenticare le richieste API
- Come installare la libreria client per Node.js
- Come analizzare i dati di un modulo scansionato
Che cosa ti serve
Sondaggio
Come utilizzerai questo tutorial?
Come valuteresti la tua esperienza con Node.js?
Come valuti la tua esperienza di utilizzo dei servizi Google Cloud?
2. Configurazione e requisiti
Configurazione dell'ambiente autonomo
- Accedi alla console Cloud e crea un nuovo progetto o riutilizzane uno esistente. Se non hai già un account Gmail o G Suite, devi crearne uno.
Ricorda l'ID progetto, un nome univoco tra tutti i progetti Google Cloud. Il nome riportato sopra è già stato utilizzato e non funzionerà per te. Ci dispiace. Devi fornire questo ID in un secondo momento come PROJECT_ID.
- Successivamente, devi abilitare la fatturazione in Cloud Console per utilizzare le risorse Google Cloud.
Assicurati di seguire le istruzioni riportate nella sezione "Pulizia". La sezione ti consiglia come arrestare le risorse in modo che non vengano addebitati costi di fatturazione al termine di questo tutorial. I nuovi utenti di Google Cloud possono beneficiare del programma prova senza costi di 300$.
Avvia Cloud Shell
Anche se puoi gestire Google Cloud da remoto dal tuo laptop, questo codelab utilizza Google Cloud Shell, un ambiente a riga di comando in esecuzione nel cloud.
Attiva Cloud Shell
- Nella console Cloud, fai clic su Attiva Cloud Shell
.
Se non hai mai avviato Cloud Shell, viene visualizzata una schermata intermedia (sotto la piega) che ne descrive le funzionalità. In questo caso, fai clic su Continua (e non comparirà più). Ecco come si presenta la schermata intermedia:
Bastano pochi istanti per eseguire il provisioning e connettersi a Cloud Shell.
Cloud Shell fornisce l'accesso tramite terminale a una macchina virtuale ospitata nel cloud. La macchina virtuale include tutti gli strumenti per sviluppatori di cui avrai bisogno. Offre una home directory permanente da 5 GB e viene eseguita in Google Cloud, migliorando notevolmente le prestazioni e l'autenticazione della rete. Gran parte del lavoro per questo codelab, se non tutto, può essere svolto semplicemente con un browser o con Chromebook.
Una volta eseguita la connessione a Cloud Shell, dovresti vedere che il tuo account è già autenticato e il progetto è già impostato sul tuo ID progetto.
- Esegui questo comando in Cloud Shell per verificare che l'account sia autenticato:
gcloud auth list
Output comando
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
gcloud config list project
Output comando
[core] project = <PROJECT_ID>
In caso contrario, puoi impostarlo con questo comando:
gcloud config set project <PROJECT_ID>
Output comando
Updated property [core/project].
3. Abilita l'API Cloud Document AI
Prima di poter iniziare a utilizzare Document AI, devi abilitare l'API. Apri Cloud Console nel browser.
- Fai clic sul menu di navigazione ☰ > API e servizi > Libreria.
- Cerca "API Document AI", quindi fai clic su Abilita per utilizzare l'API nel tuo progetto Google Cloud.
4. Creare e testare un processore
Per questo tutorial, devi prima creare un'istanza del processore Form Parser da utilizzare in Document AI Platform.
- Nella console, vai alla panoramica della piattaforma Document AI.
- Fai clic su Crea processore e seleziona Analizzatore sintattico di moduli
- Specifica un nome del processore e seleziona la tua regione dall'elenco.
- Fai clic su Crea per creare il processore.
- Copia l'ID processore. Lo dovrai utilizzare nel tuo codice in un secondo momento.
(Facoltativo) Puoi testare il processore nella console caricando un documento. Fai clic su Carica documento e seleziona un modulo da analizzare. Puoi scaricare e utilizzare questo modulo di esempio se non ne hai uno a disposizione.
L'output dovrebbe avere il seguente aspetto: 
5. Autenticare le richieste API
Per effettuare richieste all'API Document AI, devi utilizzare un service account. Un service account appartiene al tuo progetto e viene utilizzato dalla libreria Google Client Node.js per effettuare richieste API. Come qualsiasi altro account utente, un service account è rappresentato da un indirizzo email. In questa sezione utilizzerai Cloud SDK per creare un service account e poi creare le credenziali necessarie per l'autenticazione come service account.
Innanzitutto, imposta una variabile di ambiente con il tuo PROJECT_ID che utilizzerai durante questo codelab:
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value core/project)
Successivamente, crea un nuovo service account per accedere all'API Document AI utilizzando:
gcloud iam service-accounts create my-docai-sa \
--display-name "my-docai-service-account"
Successivamente, crea le credenziali che il codice Node.js utilizza per accedere al nuovo service account. Utilizza il seguente comando per creare le credenziali e salvarle in un file JSON denominato "~/key.json":
gcloud iam service-accounts keys create ~/key.json \
--iam-account my-docai-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com
Infine, imposta la variabile di ambiente GOOGLE_APPLICATION_CREDENTIALS, che viene utilizzata dalla libreria per trovare le tue credenziali. Per saperne di più su questa autenticazione basata su moduli, consulta la guida. Il valore della variabile di ambiente deve essere il percorso completo del file JSON delle credenziali che hai creato, utilizzando:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
6. Scarica il modulo di esempio
Abbiamo un modulo di esempio da utilizzare memorizzato nel nostro bucket di esempi di Google Cloud Storage pubblico. Utilizza il seguente comando per scaricarlo nella directory di lavoro.
gsutil cp gs://cloud-samples-data/documentai/form.pdf .
Verifica che il file sia stato scaricato in Cloud Shell utilizzando il comando riportato di seguito:
ls -ltr form.pdf
7. Installa la libreria client
Poi configura il codice nella directory di lavoro.
Inizializza un nuovo pacchetto Node.js:
npm init
Installa la libreria client Document AI:
npm install @google-cloud/documentai
8. Eseguire una richiesta di documento di processo sincrono
In questo passaggio, effettui una chiamata al documento di processo utilizzando l'endpoint sincrono. Per elaborare grandi quantità di documenti contemporaneamente, puoi anche utilizzare l'API asincrona. Per scoprire di più sull'utilizzo delle API Form Parser, leggi la guida qui.
Crea un file index.js e incolla il seguente codice. Compila le variabili applicabili con le informazioni del tuo responsabile del trattamento.
const { DocumentProcessorServiceClient } = require('@google-cloud/documentai').v1;
const fs = require('fs');
/**
* Runs the sample document through Document AI to get key/value pairs and
* confidence scores.
*/
async function processDocument(projectId, location, processorId, filePath, mimeType) {
// Instantiates a client
const documentaiClient = new DocumentProcessorServiceClient();
// The full resource name of the processor, e.g.:
// projects/project-id/locations/location/processor/processor-id
// You must create new processors in the Cloud Console first
const resourceName = documentaiClient.processorPath(projectId, location, processorId);
// Read the file into memory.
const imageFile = fs.readFileSync(filePath);
// Convert the image data to a Buffer and base64 encode it.
const encodedImage = Buffer.from(imageFile).toString('base64');
// Load Binary Data into Document AI RawDocument Object
const rawDocument = {
content: encodedImage,
mimeType: mimeType,
};
// Configure ProcessRequest Object
const request = {
name: resourceName,
rawDocument: rawDocument
};
// Use the Document AI client to process the sample form
const [result] = await documentaiClient.processDocument(request);
return result.document;
}
/**
* Run the codelab.
*/
async function main() {
const projectId = 'YOUR_PROJECT_ID';
const location = 'YOUR_PROJECT_LOCATION'; // Format is 'us' or 'eu'
const processorId = 'YOUR_PROCESSOR_ID'; // Should be a Hexadecimal string
// Supported File Types
// https://cloud.google.com/document-ai/docs/processors-list#processor_form-parser
filePath = 'form.pdf'; // The local file in your current working directory
mimeType = 'application/pdf';
const document = await processDocument(projectId, location, processorId, filePath, mimeType);
console.log("Document Processing Complete");
// Print the document text as one big string
console.log(`Text: ${document.text}`);
}
main(...process.argv.slice(2)).catch(err => {
console.error(err);
process.exitCode = 1;
});
Esegui il codice ora e dovresti vedere il seguente testo stampato nella console.
Text: FakeDoc M.D. HEALTH INTAKE FORM Please fill out the questionnaire carefully. The information you provide will be used to complete your health profile and will be kept confidential. Name: Date: Sally Walker DOB: 09/04/1986 Address: 24 Barney Lane City: Towalo State: NJ Zip: 07082 Email: Sally, waller@cmail.com Phone #: (906) 917-3486 Gender: Marital Status: Single Occupation: Software Engineer Referred By: None Emergency Contact: Eva Walker Emergency Contact Phone: (906) 334-8926 Describe your medical concerns (symptoms, diagnoses, etc): Runny nose, mucas in throat, weakness, aches, chills, tired Are you currently taking any medication? (If yes, please describe): Vyvanse (25mg) daily for attention
Nei passaggi successivi, estrai i dati strutturati che possono essere archiviati più facilmente nei database o utilizzati in altre applicazioni.
9. Estrai le coppie chiave/valore del modulo
Ora puoi estrarre le coppie chiave-valore dal modulo e i relativi punteggi di confidenza. L'oggetto di risposta Document contiene un elenco di pagine del documento di input. Ogni oggetto page contiene un elenco di campi del modulo e le relative posizioni nel testo.
Il seguente codice scorre ogni pagina ed estrae ogni chiave, valore e punteggio di confidenza.
Aggiungi la seguente funzione al tuo codice.
/**
* Extract form data and confidence from processed document.
*/
function extractFormData(document) {
// Extract shards from the text field
function getText(textAnchor, document) {
if (!textAnchor.textSegments || textAnchor.textSegments.length === 0) {
return '';
}
// First shard in document doesn't have startIndex property
const startIndex = textAnchor.textSegments[0].startIndex || 0;
const endIndex = textAnchor.textSegments[0].endIndex;
return document.text.substring(startIndex, endIndex);
}
var formData = [];
const pages = document.pages;
pages.forEach((page) => {
const formFields = page.formFields;
formFields.forEach((field) => {
// Get the extracted field names and remove extra space from text
const fieldName = getText(field.fieldName.textAnchor, document);
// Confidence - How "sure" the API is that the text is correct
const nameConfidence = field.fieldName.confidence.toFixed(4);
const fieldValue = getText(field.fieldValue.textAnchor, document);
const valueConfidence = field.fieldValue.confidence.toFixed(4);
formData.push({
fieldName: fieldName,
fieldValue: fieldValue,
nameConfidence: nameConfidence,
valueConfidence: valueConfidence
});
});
});
return formData;
}
Aggiungi una chiamata alla funzione extractFormData() dall'interno della funzione principale e stampa l'oggetto risultante come tabella.
/**
* Run the codelab.
*/
async function main() {
const projectId = 'YOUR_PROJECT_ID';
const location = 'YOUR_PROJECT_LOCATION'; // Format is 'us' or 'eu'
const processorId = 'YOUR_PROCESSOR_ID'; // Should be a Hexadecimal string
// Supported File Types
// https://cloud.google.com/document-ai/docs/processors-list#processor_form-parser
filePath = 'form.pdf'; // The local file in your current working directory
mimeType = 'application/pdf';
const document = await processDocument(projectId, location, processorId, filePath, mimeType);
const formData = extractFormData(document);
console.log('\nThe following form key/value pairs were detected:');
console.table(formData);
}
Ora esegui il codice. Se utilizzi il nostro documento di esempio, dovresti vedere il seguente output:
The following form key/value pairs were detected: ┌─────────┬────────────────────────────────────────────────────────────────┬──────────────────────────────────────────────────────────────────┬────────────────┬─────────────────┐ │ (index) │ fieldName │ fieldValue │ nameConfidence │ valueConfidence │ ├─────────┼────────────────────────────────────────────────────────────────┼──────────────────────────────────────────────────────────────────┼────────────────┼─────────────────┤ │ 0 │ 'Marital Status: ' │ 'Single ' │ '1.0000' │ '1.0000' │ │ 1 │ 'DOB: ' │ '09/04/1986\n' │ '0.9999' │ '0.9999' │ │ 2 │ 'City: ' │ 'Towalo ' │ '0.9996' │ '0.9996' │ │ 3 │ 'Address: ' │ '24 Barney Lane ' │ '0.9994' │ '0.9994' │ │ 4 │ 'Referred By: ' │ 'None\n' │ '0.9968' │ '0.9968' │ │ 5 │ 'Phone #: ' │ '(906) 917-3486\n' │ '0.9961' │ '0.9961' │ │ 6 │ 'State: ' │ 'NJ ' │ '0.9960' │ '0.9960' │ │ 7 │ 'Emergency Contact Phone: ' │ '(906) 334-8926\n' │ '0.9925' │ '0.9925' │ │ 8 │ 'Name:\n' │ 'Sally\nWalker\n' │ '0.9922' │ '0.9922' │ │ 9 │ 'Occupation: ' │ 'Software Engineer\n' │ '0.9914' │ '0.9914' │ │ 10 │ 'Zip: ' │ '07082\n' │ '0.9904' │ '0.9904' │ │ 11 │ 'Email: ' │ 'Sally, waller@cmail.com ' │ '0.9681' │ '0.9681' │ │ 12 │ 'Emergency Contact: ' │ 'Eva Walker ' │ '0.9430' │ '0.9430' │ │ 13 │ 'Describe your medical concerns (symptoms, diagnoses, etc):\n' │ 'Runny nose, mucas in throat, weakness,\naches, chills, tired\n' │ '0.7817' │ '0.7817' │ └─────────┴────────────────────────────────────────────────────────────────┴──────────────────────────────────────────────────────────────────┴────────────────┴─────────────────┘
10. Complimenti!
Congratulazioni, hai utilizzato correttamente l'API Document AI per estrarre dati da un modulo scritto a mano. Ti invitiamo a sperimentare con altre immagini del modulo.
Esegui la pulizia
Per evitare che al tuo account Google Cloud vengano addebitati costi relativi alle risorse utilizzate in questo tutorial:
- In Cloud Console, vai alla pagina Gestisci risorse.
- Nell'elenco dei progetti, seleziona il tuo progetto e poi fai clic su Elimina.
- Nella finestra di dialogo, digita l'ID progetto, quindi fai clic su Chiudi per eliminare il progetto.
Scopri di più
- The Future of Documents - YouTube Playlist
- Documentazione di Document AI
- Riferimento della libreria client Node.js di Document AI
- Esempi Node.js di Document AI