1. مقدمة
في هذا الدرس التطبيقي حول الترميز، ستتعرّف على كيفية استخدام أداة "محلّل النماذج" في Document AI لتحليل نموذج مكتوب بخط اليد باستخدام لغة Python.
سنستخدم نموذجًا بسيطًا لجمع المعلومات الطبية كمثال، ولكن يمكن استخدام هذا الإجراء مع أي نموذج عام متوافق مع DocAI.
المتطلبات الأساسية
يستند هذا الدرس التطبيقي حول الترميز إلى المحتوى المقدَّم في دروس تطبيقية أخرى حول Document AI.
ننصحك بإكمال Codelabs التالية قبل المتابعة.
ما ستتعلمه
- كيفية تحليل البيانات واستخراجها من نموذج تم مسحه ضوئيًا باستخدام أداة تحليل النماذج في Document AI
المتطلبات
استطلاع الرأي
كيف ستستخدم هذا البرنامج التعليمي؟
كيف تقيّم تجربتك مع Python؟
ما هو تقييمك لتجربة استخدام خدمات Google Cloud؟
2. الإعداد والمتطلبات
يفترض هذا الدرس العملي أنك أكملت خطوات إعداد Document AI المُدرَجة في درس Document AI OCR العملي.
يُرجى إكمال الخطوات التالية قبل المتابعة:
عليك أيضًا تثبيت Pandas، وهي مكتبة مفتوحة المصدر لتحليل البيانات في Python.
pip3 install --upgrade pandas
3- إنشاء معالج Form Parser
يجب أولاً إنشاء مثيل لمعالج Form Parser لاستخدامه في "منصة Document AI" لهذا البرنامج التعليمي.
- في وحدة التحكّم، انتقِل إلى نظرة عامة على منصة Document AI
- انقر على إنشاء معالج واختَر محلّل النماذج
- حدِّد اسم المعالج واختَر منطقتك من القائمة.
- انقر على إنشاء لإنشاء المعالج.
- انسخ رقم تعريف المعالج. يجب استخدام هذا المعرّف في الرمز البرمجي لاحقًا.
أداة اختبار المعالجة في Cloud Console
يمكنك تجربة المعالج في وحدة التحكّم من خلال تحميل مستند. انقر على تحميل مستند واختَر نموذجًا لتحليله. يمكنك تنزيل نموذج الطلب هذا واستخدامه إذا لم يكن لديك نموذج آخر متاح للاستخدام.
يجب أن تبدو مخرجاتك على هذا النحو: 
4. تنزيل نموذج الطلب
لدينا مستند نموذجي يحتوي على نموذج بسيط لجمع المعلومات الطبية.
يمكنك تنزيل ملف PDF باستخدام الرابط التالي. بعد ذلك، حمِّله إلى مثيل Cloud Shell.
بدلاً من ذلك، يمكنك تنزيله من حزمة Google Cloud Storage العامة باستخدام gsutil.
gsutil cp gs://cloud-samples-data/documentai/codelabs/form-parser/intake-form.pdf .
تأكَّد من تنزيل الملف إلى Cloud Shell باستخدام الأمر التالي:
ls -ltr intake-form.pdf
5- استخراج أزواج المفتاح/القيمة من النماذج
في هذه الخطوة، ستستخدم واجهة برمجة التطبيقات الخاصة بالمعالجة على الإنترنت لاستدعاء أداة معالجة محلّل النماذج التي أنشأتها سابقًا. بعد ذلك، ستستخرج أزواج المفاتيح والقيم الواردة في المستند.
تُستخدَم المعالجة على الإنترنت لإرسال مستند واحد وانتظار الردّ. يمكنك أيضًا استخدام المعالجة الدفعية إذا أردت إرسال ملفات متعددة أو إذا كان حجم الملف يتجاوز الحدّ الأقصى لعدد الصفحات في المعالجة على الإنترنت. يمكنك مراجعة كيفية إجراء ذلك في الدرس التطبيقي حول الترميز الخاص بالتعرّف الضوئي على الحروف.
إنّ الرمز البرمجي لتقديم طلب معالجة هو نفسه لكل نوع من أنواع المعالِجات باستثناء معرّف المعالِج.
يحتوي عنصر الاستجابة Document على قائمة بالصفحات من المستند المُدخَل.
يحتوي كل عنصر page على قائمة بحقول النموذج ومواقعها في النص.
تكرّر الرمز التالي كل صفحة وتستخرج كل مفتاح وقيمة ونقاط ثقة. هذه بيانات منظَّمة يمكن تخزينها بسهولة أكبر في قواعد البيانات أو استخدامها في تطبيقات أخرى.
أنشئ ملفًا باسم form_parser.py واستخدِم الرمز البرمجي أدناه.
form_parser.py
import pandas as pd
from google.cloud import documentai_v1 as documentai
def online_process(
project_id: str,
location: str,
processor_id: str,
file_path: str,
mime_type: str,
) -> documentai.Document:
"""
Processes a document using the Document AI Online Processing API.
"""
opts = {"api_endpoint": f"{location}-documentai.googleapis.com"}
# Instantiates a client
documentai_client = documentai.DocumentProcessorServiceClient(client_options=opts)
# 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
resource_name = documentai_client.processor_path(project_id, location, processor_id)
# Read the file into memory
with open(file_path, "rb") as image:
image_content = image.read()
# Load Binary Data into Document AI RawDocument Object
raw_document = documentai.RawDocument(
content=image_content, mime_type=mime_type
)
# Configure the process request
request = documentai.ProcessRequest(
name=resource_name, raw_document=raw_document
)
# Use the Document AI client to process the sample form
result = documentai_client.process_document(request=request)
return result.document
def trim_text(text: str):
"""
Remove extra space characters from text (blank, newline, tab, etc.)
"""
return text.strip().replace("\n", " ")
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "YOUR_PROJECT_LOCATION" # Format is 'us' or 'eu'
PROCESSOR_ID = "FORM_PARSER_ID" # Create processor in Cloud Console
# The local file in your current working directory
FILE_PATH = "intake-form.pdf"
# Refer to https://cloud.google.com/document-ai/docs/processors-list
# for supported file types
MIME_TYPE = "application/pdf"
document = online_process(
project_id=PROJECT_ID,
location=LOCATION,
processor_id=PROCESSOR_ID,
file_path=FILE_PATH,
mime_type=MIME_TYPE,
)
names = []
name_confidence = []
values = []
value_confidence = []
for page in document.pages:
for field in page.form_fields:
# Get the extracted field names
names.append(trim_text(field.field_name.text_anchor.content))
# Confidence - How "sure" the Model is that the text is correct
name_confidence.append(field.field_name.confidence)
values.append(trim_text(field.field_value.text_anchor.content))
value_confidence.append(field.field_value.confidence)
# Create a Pandas Dataframe to print the values in tabular format.
df = pd.DataFrame(
{
"Field Name": names,
"Field Name Confidence": name_confidence,
"Field Value": values,
"Field Value Confidence": value_confidence,
}
)
print(df)
نفِّذ الرمز الآن، ومن المفترض أن يظهر النص الذي تم استخراجه وطباعته في وحدة التحكّم.
من المفترض أن يظهر لك الناتج التالي في حال استخدام مستندنا النموذجي:
$ python3 form_parser.py
Field Name Field Name Confidence Field Value Field Value Confidence
0 Phone #: 0.999982 (906) 917-3486 0.999982
1 Emergency Contact: 0.999972 Eva Walker 0.999972
2 Marital Status: 0.999951 Single 0.999951
3 Gender: 0.999933 F 0.999933
4 Occupation: 0.999914 Software Engineer 0.999914
5 Referred By: 0.999862 None 0.999862
6 Date: 0.999858 9/14/19 0.999858
7 DOB: 0.999716 09/04/1986 0.999716
8 Address: 0.999147 24 Barney Lane 0.999147
9 City: 0.997718 Towaco 0.997718
10 Name: 0.997345 Sally Walker 0.997345
11 State: 0.996944 NJ 0.996944
...
6. تحليل الجداول
يمكن أيضًا لأداة "محلّل النماذج" استخراج البيانات من الجداول داخل المستندات. في هذه الخطوة، سننزّل مستندًا جديدًا ونستخرج البيانات من الجدول. بما أنّنا نحمّل البيانات إلى Pandas، يمكن إخراج هذه البيانات إلى ملف CSV والعديد من التنسيقات الأخرى من خلال طلب إجراء واحد.
تنزيل نموذج يحتوي على جداول
لدينا مستند نموذجي يحتوي على نموذج وجدول.
يمكنك تنزيل ملف PDF باستخدام الرابط التالي. بعد ذلك، حمِّله إلى مثيل Cloud Shell.
بدلاً من ذلك، يمكنك تنزيله من حزمة Google Cloud Storage العامة باستخدام gsutil.
gsutil cp gs://cloud-samples-data/documentai/codelabs/form-parser/form_with_tables.pdf .
تأكَّد من تنزيل الملف إلى Cloud Shell باستخدام الأمر التالي:
ls -ltr form_with_tables.pdf
استخراج بيانات الجدول
إنّ طلب المعالجة لبيانات الجدول هو نفسه تمامًا كما هو الحال بالنسبة إلى استخراج أزواج المفتاح والقيمة. ويكمن الاختلاف في الحقول التي نستخرج البيانات منها في الردّ. يتم تخزين بيانات الجدول في الحقل pages[].tables[].
يستخرج هذا المثال معلومات من صفوف عناوين الجدول وصفوف النص الأساسي لكل جدول وصفحة، ثم يطبع الجدول ويحفظه كملف CSV.
أنشئ ملفًا باسم table_parsing.py واستخدِم الرمز البرمجي أدناه.
table_parsing.py
# type: ignore[1]
"""
Uses Document AI online processing to call a form parser processor
Extracts the tables and data in the document.
"""
from os.path import splitext
from typing import List, Sequence
import pandas as pd
from google.cloud import documentai
def online_process(
project_id: str,
location: str,
processor_id: str,
file_path: str,
mime_type: str,
) -> documentai.Document:
"""
Processes a document using the Document AI Online Processing API.
"""
opts = {"api_endpoint": f"{location}-documentai.googleapis.com"}
# Instantiates a client
documentai_client = documentai.DocumentProcessorServiceClient(client_options=opts)
# 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
resource_name = documentai_client.processor_path(project_id, location, processor_id)
# Read the file into memory
with open(file_path, "rb") as image:
image_content = image.read()
# Load Binary Data into Document AI RawDocument Object
raw_document = documentai.RawDocument(
content=image_content, mime_type=mime_type
)
# Configure the process request
request = documentai.ProcessRequest(
name=resource_name, raw_document=raw_document
)
# Use the Document AI client to process the sample form
result = documentai_client.process_document(request=request)
return result.document
def get_table_data(
rows: Sequence[documentai.Document.Page.Table.TableRow], text: str
) -> List[List[str]]:
"""
Get Text data from table rows
"""
all_values: List[List[str]] = []
for row in rows:
current_row_values: List[str] = []
for cell in row.cells:
current_row_values.append(
text_anchor_to_text(cell.layout.text_anchor, text)
)
all_values.append(current_row_values)
return all_values
def text_anchor_to_text(text_anchor: documentai.Document.TextAnchor, text: str) -> str:
"""
Document AI identifies table data by their offsets in the entirety of the
document's text. This function converts offsets to a string.
"""
response = ""
# If a text segment spans several lines, it will
# be stored in different text segments.
for segment in text_anchor.text_segments:
start_index = int(segment.start_index)
end_index = int(segment.end_index)
response += text[start_index:end_index]
return response.strip().replace("\n", " ")
PROJECT_ID = "YOUR_PROJECT_ID"
LOCATION = "YOUR_PROJECT_LOCATION" # Format is 'us' or 'eu'
PROCESSOR_ID = "FORM_PARSER_ID" # Create processor before running sample
# The local file in your current working directory
FILE_PATH = "form_with_tables.pdf"
# Refer to https://cloud.google.com/document-ai/docs/file-types
# for supported file types
MIME_TYPE = "application/pdf"
document = online_process(
project_id=PROJECT_ID,
location=LOCATION,
processor_id=PROCESSOR_ID,
file_path=FILE_PATH,
mime_type=MIME_TYPE,
)
header_row_values: List[List[str]] = []
body_row_values: List[List[str]] = []
# Input Filename without extension
output_file_prefix = splitext(FILE_PATH)[0]
for page in document.pages:
for index, table in enumerate(page.tables):
header_row_values = get_table_data(table.header_rows, document.text)
body_row_values = get_table_data(table.body_rows, document.text)
# Create a Pandas Dataframe to print the values in tabular format.
df = pd.DataFrame(
data=body_row_values,
columns=pd.MultiIndex.from_arrays(header_row_values),
)
print(f"Page {page.page_number} - Table {index}")
print(df)
# Save each table as a CSV file
output_filename = f"{output_file_prefix}_pg{page.page_number}_tb{index}.csv"
df.to_csv(output_filename, index=False)
نفِّذ الرمز الآن، ومن المفترض أن يظهر النص الذي تم استخراجه وطباعته في وحدة التحكّم.
من المفترض أن يظهر لك الناتج التالي في حال استخدام مستندنا النموذجي:
$ python3 table_parsing.py
Page 1 - Table 0
Item Description
0 Item 1 Description 1
1 Item 2 Description 2
2 Item 3 Description 3
Page 1 - Table 1
Form Number: 12345678
0 Form Date: 2020/10/01
1 Name: First Last
2 Address: 123 Fake St
يجب أن يتضمّن الدليل الذي تنفّذ الرمز منه ملفَي CSV جديدَين.
$ ls form_with_tables_pg1_tb0.csv form_with_tables_pg1_tb1.csv table_parsing.py
7. تهانينا
تهانينا، لقد استخدمت Document AI API بنجاح لاستخراج البيانات من نموذج مكتوب بخط اليد. ننصحك بتجربة مستندات نماذج أخرى.
تنظيف
لتجنُّب تحمّل رسوم في حسابك على Google Cloud مقابل الموارد المستخدَمة في هذا البرنامج التعليمي، اتّبِع الخطوات التالية:
- في Cloud Console، انتقِل إلى صفحة إدارة الموارد.
- في قائمة المشاريع، اختَر مشروعك ثم انقر على "حذف".
- في مربّع الحوار، اكتب رقم تعريف المشروع، ثم انقر على "إيقاف" لحذف المشروع.
مزيد من المعلومات
يمكنك مواصلة التعرّف على Document AI من خلال تجربة Codelabs التالية.
- المعالِجات المتخصّصة باستخدام Document AI (Python)
- إدارة معالِجات Document AI باستخدام Python
- Document AI: Human in the Loop
المراجع
الترخيص
يخضع هذا العمل لترخيص المشاع الإبداعي مع نسب العمل إلى مؤلفه 2.0 Generic License.