1. نظرة عامة
ما هي خدمة Document AI؟
Document AI API هو حلّ لفهم المستندات يستند إلى بيانات غير منظَّمة، مثل المستندات والرسائل الإلكترونية وما إلى ذلك، ويسهّل فهم البيانات وتحليلها واستخدامها. توفّر واجهة برمجة التطبيقات بنية من خلال تصنيف المحتوى واستخراج الكيانات والبحث المتقدّم وغير ذلك.
في هذا البرنامج التعليمي، ستركز على استخدام Document AI API مع Node.js. يوضّح البرنامج التعليمي كيفية تحليل نموذج بسيط لجمع المعلومات الطبية.
ما ستتعلمه
- كيفية تفعيل Document AI API
- كيفية مصادقة طلبات البيانات من واجهة برمجة التطبيقات
- كيفية تثبيت مكتبة البرامج لنظام التشغيل Node.js
- كيفية تحليل البيانات من نموذج تم مسحه ضوئيًا
المتطلبات
استطلاع الرأي
كيف ستستخدم هذا البرنامج التعليمي؟
كيف تقيّم تجربتك مع Node.js؟
ما هو تقييمك لتجربة استخدام خدمات Google Cloud؟
2. الإعداد والمتطلبات
إعداد البيئة بالسرعة التي تناسبك
- سجِّل الدخول إلى Cloud Console وأنشِئ مشروعًا جديدًا أو أعِد استخدام مشروع حالي. (إذا لم يكن لديك حساب على Gmail أو G Suite، عليك إنشاء حساب).
تذكَّر رقم تعريف المشروع، وهو اسم فريد في جميع مشاريع Google Cloud. (الاسم أعلاه مستخدَم حاليًا ولن يكون متاحًا لك، نأسف لذلك). يجب تقديم هذا المعرّف لاحقًا كـ PROJECT_ID.
- بعد ذلك، عليك تفعيل الفوترة في Cloud Console من أجل استخدام موارد Google Cloud.
احرص على اتّباع أي تعليمات في قسم "التنظيف". ينصحك القسم بكيفية إيقاف الموارد حتى لا تتكبّد تكاليف فوترة بعد هذا البرنامج التعليمي. يمكن لمستخدمي Google Cloud الجدد الاستفادة من برنامج الفترة التجريبية المجانية بقيمة 300 دولار أمريكي.
بدء Cloud Shell
مع أنّ Google Cloud يتيح لك تشغيل Google Cloud عن بُعد من الكمبيوتر المحمول، يستخدم برنامج التدريب العملي هذا Google Cloud Shell، وهي بيئة سطر أوامر تعمل في السحابة الإلكترونية.
تفعيل Cloud Shell
- من Cloud Console، انقر على تفعيل Cloud Shell
.
إذا لم يسبق لك بدء Cloud Shell، ستظهر لك شاشة وسيطة (الجزء السفلي غير المرئي من الصفحة) توضّح ماهيته. في هذه الحالة، انقر على متابعة (ولن تظهر لك مرة أخرى). في ما يلي الشكل الذي ستظهر به هذه الشاشة لمرة واحدة:
يستغرق توفير Cloud Shell والاتصال به بضع لحظات فقط.
توفّر لك Cloud Shell إمكانية الوصول إلى جهاز افتراضي مستضاف على السحابة الإلكترونية من خلال سطر الأوامر. يتضمّن الجهاز الافتراضي جميع أدوات التطوير التي تحتاج إليها. توفّر هذه الخدمة دليلًا رئيسيًا دائمًا بسعة 5 غيغابايت وتعمل في Google Cloud، ما يؤدي إلى تحسين أداء الشبكة والمصادقة بشكل كبير. يمكن إنجاز معظم العمل في هذا الدرس التطبيقي حول الترميز، إن لم يكن كله، باستخدام متصفّح أو جهاز 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، يجب تفعيل واجهة برمجة التطبيقات. افتح Cloud Console في المتصفّح.
- انقر على قائمة التنقّل ☰ > واجهات برمجة التطبيقات والخدمات > المكتبة.
- ابحث عن "Document AI API"، ثم انقر على تفعيل لاستخدام واجهة برمجة التطبيقات في مشروعك على Google Cloud.
4. إنشاء معالج واختباره
يجب أولاً إنشاء مثيل لمعالج Form Parser لاستخدامه في "منصة AI Platform" لهذا البرنامج التعليمي.
- في وحدة التحكّم، انتقِل إلى نظرة عامة على منصة Document AI
- انقر على إنشاء معالج واختَر محلّل النماذج
- حدِّد اسم المعالج واختَر منطقتك من القائمة.
- انقر على إنشاء لإنشاء المعالج.
- انسخ رقم تعريف المعالج. يجب استخدام هذا المعرّف في الرمز البرمجي لاحقًا.
(اختياري) يمكنك اختبار المعالج في وحدة التحكّم عن طريق تحميل مستند. انقر على تحميل مستند واختَر نموذجًا لتحليله. يمكنك تنزيل نموذج الطلب هذا واستخدامه إذا لم يكن لديك نموذج آخر متاح للاستخدام.
يجب أن تبدو مخرجاتك على هذا النحو: 
5- مصادقة طلبات البيانات من واجهة برمجة التطبيقات
لإرسال طلبات إلى Document AI API، يجب استخدام حساب خدمة. حساب الخدمة هو حساب يخص مشروعك، وتستخدمه مكتبة Google Client Node.js لتقديم طلبات إلى واجهة برمجة التطبيقات. وكما هو الحال مع أي حساب مستخدم آخر، يتم تمثيل حساب الخدمة بعنوان بريد إلكتروني. في هذا القسم، ستستخدم Cloud SDK لإنشاء حساب خدمة، ثم ستنشئ بيانات الاعتماد اللازمة للمصادقة كحساب خدمة.
أولاً، اضبط متغيّر بيئة باستخدام PROJECT_ID الذي ستستخدمه طوال هذا الدرس التطبيقي حول الترميز:
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. إجراء طلب مستند عملية متزامن
في هذه الخطوة، يمكنك إجراء طلب مستند معالجة باستخدام نقطة النهاية المتزامنة. لمعالجة كميات كبيرة من المستندات في الوقت نفسه، يمكنك أيضًا استخدام واجهة برمجة التطبيقات غير المتزامنة. ولمزيد من المعلومات عن استخدام واجهات برمجة التطبيقات Form Parser، يمكنك الاطّلاع على الدليل هنا.
أنشئ ملف 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 Console، انتقِل إلى صفحة إدارة الموارد.
- في قائمة المشاريع، اختَر مشروعك ثم انقر على "حذف".
- في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على "إيقاف" لحذف المشروع.
مزيد من المعلومات
- مستقبل المستندات - قائمة تشغيل على YouTube
- مستندات Document AI
- مرجع مكتبة عميل Document AI لنظام التشغيل Node.js
- نماذج Document AI Node.js