1. סקירה כללית
מה זה Document AI?
Document AI API הוא פתרון להבנת מסמכים שלוקח נתונים לא מובנים, כמו מסמכים, אימיילים ועוד, ומקל על הבנה, ניתוח וצריכה של הנתונים. ה-API מספק מבנה באמצעות סיווג תוכן, חילוץ ישויות, חיפוש מתקדם ועוד.
במדריך הזה תלמדו איך להשתמש ב-Document AI API עם Node.js. המדריך מדגים איך לנתח טופס איסוף רפואי פשוט.
מה תלמדו
- איך מפעילים את Document AI API
- איך לאמת בקשות API
- איך להתקין את ספריית הלקוח ל-Node.js
- איך לנתח נתונים מטופס שנסרק
מה צריך להכין
סקר
איך תשתמשו במדריך הזה?
איזה דירוג מגיע לחוויה שלך עם Node.js?
איזה דירוג מגיע לדעתך לחוויית השימוש שלך בשירותי Google Cloud?
2. הגדרה ודרישות
הגדרת סביבה בקצב עצמאי
- נכנסים למסוף Cloud ויוצרים פרויקט חדש או עושים שימוש חוזר בפרויקט קיים. (אם עדיין אין לכם חשבון Gmail או G Suite, עליכם ליצור חשבון).
חשוב לזכור את מזהה הפרויקט – שם ייחודי בכל הפרויקטים ב-Google Cloud. (השם שלך כבר תפוס ולא יעבוד, לצערי!). חובה לספק את המזהה הזה בהמשך בתור PROJECT_ID.
- בשלב הבא צריך להפעיל את החיוב במסוף Cloud כדי להשתמש במשאבים של Google Cloud.
חשוב לבצע את כל ההוראות בקטע 'ניקוי' . הקטע מסביר איך להשבית את המשאבים כדי שלא תצברו חיובים מעבר למדריך הזה. משתמשים חדשים ב-Google Cloud זכאים להשתתף בתוכנית תקופת ניסיון בחינם בשווי 1,200 ש"ח.
הפעלת Cloud Shell
אפשר לתפעל את Google Cloud מרחוק מהמחשב הנייד ב-Google Cloud, אבל ה-Codelab הזה משתמש ב-Google Cloud Shell, סביבת שורת הפקודה שפועלת ב-Cloud.
הפעלת Cloud Shell
- במסוף Cloud, לוחצים על Activate Cloud Shell
.
אם לא השתמשתם ב-Cloud Shell בעבר, יוצג לכם מסך ביניים (בחלק הנגלל) שמתאר מהו. במקרה כזה, לוחצים על המשך (וזה לא יקרה שוב). כך נראה המסך החד-פעמי:
ההקצאה וההתחברות ל-Cloud Shell נמשכת כמה דקות.
פלטפורמת Cloud Shell נותנת לכם גישה למסוף למכונה וירטואלית שמתארחת בענן. המכונה הווירטואלית כוללת את כל כלי הפיתוח הדרושים לך. יש בה ספריית בית בנפח מתמיד של 5GB והיא פועלת ב-Google Cloud, מה שמשפר משמעותית את ביצועי הרשת והאימות. אם לא את כולן, ניתן לבצע חלק גדול מהעבודה ב-Codelab הזה באמצעות דפדפן או Chromebook.
אחרי ההתחברות ל-Cloud Shell, אתם אמורים לראות שכבר בוצע אימות ושהפרויקט כבר מוגדר למזהה הפרויקט שלכם.
- מריצים את הפקודה הבאה ב-Cloud Shell כדי לוודא שהאימות בוצע:
gcloud auth list
פלט הפקודה
Credentialed Accounts
ACTIVE ACCOUNT
* <my_account>@<my_domain.com>
To set the active account, run:
$ gcloud config set account `ACCOUNT`
gcloud config list project
פלט הפקודה
[core] project = <PROJECT_ID>
אם היא לא נמצאת שם, תוכלו להגדיר אותה באמצעות הפקודה הבאה:
gcloud config set project <PROJECT_ID>
פלט הפקודה
Updated property [core/project].
3. הפעלת Cloud Document AI API
לפני שמתחילים להשתמש ב-Document AI, צריך להפעיל את ה-API. פותחים את מסוף Cloud בדפדפן.
- לוחצים על תפריט הניווט myactivity > ממשקי API שירותים > ספרייה.
- מחפשים את Document AI API, לוחצים על Enable כדי להשתמש ב-API בפרויקט ב-Google Cloud.
4. יצירה ובדיקה של מעבד
קודם כל צריך ליצור מכונה של מעבד טפסים לניתוח טפסים כדי להשתמש ב-Document AI Platform עבור המדריך הזה.
- במסוף, עוברים אל Document AI Platform Overview
- לוחצים על יצירת מעבד מידע ובוחרים באפשרות מנתח טפסים
- מציינים שם מעבד ובוחרים את האזור שלכם מהרשימה.
- לוחצים על יצירה כדי ליצור את המעבד.
- מעתיקים את מזהה המעבד. חובה להשתמש בה בקוד מאוחר יותר.
(אופציונלי) אפשר לבדוק את המעבד במסוף על ידי העלאת מסמך. לוחצים על העלאת מסמך ובוחרים טופס לניתוח. אם אין לך טופס זמין לשימוש, אפשר להוריד את הטופס לדוגמה ולהשתמש בו.
הפלט שלכם אמור להיראות כך: 
5. אימות בקשות API
כדי לשלוח בקשות ל-Document AI API, עליך להשתמש בחשבון שירות. חשבון שירות שייך לפרויקט שלכם, ומשמש את ספריית Node.js של לקוח Google כדי לשלוח בקשות API. כמו כל חשבון משתמש אחר, חשבון שירות מיוצג על ידי כתובת אימייל. בקטע הזה משתמשים ב-Cloud SDK כדי ליצור חשבון שירות, ולאחר מכן יוצרים פרטי כניסה שנדרשים לאימות כחשבון השירות.
קודם כול צריך להגדיר משתנה סביבה עם PROJECT_ID, שבו תשתמשו ב-Codelab הזה:
export GOOGLE_CLOUD_PROJECT=$(gcloud config get-value core/project)
בשלב הבא, יוצרים חשבון שירות חדש כדי לגשת ל-Document AI API באמצעות:
gcloud iam service-accounts create my-docai-sa \
--display-name "my-docai-service-account"
בשלב הבא, יוצרים את פרטי הכניסה שבהם הקוד של Node.js משתמש כדי להתחבר בתור חשבון השירות החדש. יוצרים את פרטי הכניסה האלה ושומרים אותם כקובץ JSON ~/key.json. באמצעות הפקודה הבאה:
gcloud iam service-accounts keys create ~/key.json \
--iam-account my-docai-sa@${GOOGLE_CLOUD_PROJECT}.iam.gserviceaccount.com
לסיום, מגדירים את משתנה הסביבה GOOGLE_APPLICATION_CREDENTIALS, שבו הספרייה תשתמש כדי למצוא את פרטי הכניסה שלכם. מידע נוסף על אימות הטופס זמין במדריך. מגדירים את משתנה הסביבה לנתיב המלא של קובץ ה-JSON של פרטי הכניסה שיצרתם באמצעות:
export GOOGLE_APPLICATION_CREDENTIALS="/path/to/key.json"
6. הורדת הטופס לדוגמה
יש לנו טופס לדוגמה שמאוחסן בקטגוריית הדוגמאות הציבורית של Google Cloud Storage. משתמשים בפקודה הבאה כדי להוריד אותו לספריית העבודה.
gsutil cp gs://cloud-samples-data/documentai/form.pdf .
מוודאים שהקובץ הורד ל-cloudshell באמצעות הפקודה הבאה:
ls -ltr form.pdf
7. התקנה של ספריית הלקוח
בשלב הבא צריך להגדיר את הקוד בספריית העבודה.
אתחול חבילת Node.js חדשה:
npm init
מתקינים את ספריית הלקוח של Document AI:
npm install @google-cloud/documentai
8. הגשת בקשה למסמך של תהליך סינכרוני
בשלב הזה, מבצעים קריאה למסמך של התהליך באמצעות נקודת הקצה הסנכרנת. אם רוצים לעבד כמויות גדולות של מסמכים בו-זמנית, אפשר גם להשתמש ב-API האסינכרוני. מידע נוסף על השימוש בממשקי ה-API של מנתח הטפסים זמין במדריך הזה.
יוצרים קובץ index.js ומדביקים את הקוד הבא. ממלאים את המשתנים הרלוונטיים בפרטי המעבד.
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;
});
מריצים את הקוד עכשיו, והטקסט הבא אמור להופיע במסוף.
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
בשלבים הבאים אפשר לחלץ נתונים מובְנים שניתן לאחסן בקלות רבה יותר במסדי נתונים או להשתמש בהם באפליקציות אחרות.
9. חילוץ צמדי מפתח/ערך של טופס
עכשיו אפשר לחלץ את צמדי המפתח-ערך מהטופס ואת ציוני הסמך התואמים שלהם. אובייקט התשובה Document מכיל רשימת דפים ממסמך הקלט. כל אובייקט page מכיל רשימה של שדות טופס ואת המיקומים שלהם בטקסט.
הקוד הבא חוזר על עצמו בכל דף ומחלץ כל מפתח, ערך וציון ודאות.
מוסיפים את הפונקציה הבאה לקוד.
/**
* 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;
}
צריך להוסיף קריאה לפונקציה extractFormData() מתוך הפונקציה הראשית ולהדפיס את האובייקט שמתקבל כטבלה.
/**
* 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);
}
עכשיו מריצים את הקוד. אם אתם משתמשים במסמך לדוגמה שלנו, הפלט הבא אמור להופיע:
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. מעולה!
מזל טוב, השתמשת בהצלחה ב-Document AI API כדי לחלץ נתונים מטופס בכתב יד. מומלץ לנסות תמונות אחרות של טפסים.
הסרת המשאבים
כדי להימנע מצבירת חיובים בחשבון Google Cloud על המשאבים שבהם השתמשתם במדריך הזה:
- במסוף Cloud, עוברים לדף Manage resources.
- ברשימת הפרויקטים, בוחרים את הפרויקט הרלוונטי ולוחצים על 'מחיקה'.
- כדי למחוק את הפרויקט, כותבים את מזהה הפרויקט בתיבת הדו-שיח ולוחצים על Shut down.
מידע נוסף
- עתיד המסמכים – פלייליסט ב-YouTube
- מסמכי תיעוד מבוססי-AI של מסמכים
- חומר עזר בנושא ספריית הלקוח של Document AI Node.js
- דוגמאות של Document AI Node.js