مشاركة عبر

مكتبة عميل Azure Form Recognizer ل Python - الإصدار 3.0.0

  • مقالة

Azure Cognitive Services Form Recognizer هي خدمة سحابية تستخدم التعلم الآلي للتعرف على بيانات النص والجدول من مستندات النموذج. يتضمن الوظائف الرئيسية التالية:

  • نماذج مخصصة - التعرف على قيم الحقول وبيانات الجدول من النماذج. يتم تدريب هذه النماذج مع بياناتك الخاصة، لذا فهي مصممة وفقاً لنماذجك.
  • واجهة برمجة تطبيقات المحتوى - التعرف على بنيات النص والجدول، جنبا إلى جنب مع إحداثيات مربع الإحاطة الخاصة بها، من المستندات. يتوافق مع واجهة برمجة تطبيقات تخطيط خدمة REST.
  • نموذج الإيصال الذي تم إنشاؤه مسبقا - التعرف على البيانات من إيصالات مبيعات الولايات المتحدة الأمريكية باستخدام نموذج تم إنشاؤه مسبقا.

التعليمات البرمجية | المصدر الحزمة (PyPI) | الوثائق | المرجعية لواجهة برمجة التطبيقاتوثائق | المنتج عينات

الشروع في العمل

المتطلبات الأساسية

تثبيت الحزمة

تثبيت مكتبة عميل Azure Form Recognizer ل Python - الإصدار 3.0.0 باستخدام pip:

pip install azure-ai-formrecognizer

ملاحظة: يدعم هذا الإصدار من مكتبة العميل الإصدار v2.0 من خدمة Form Recognizer

إنشاء مورد Form Recognizer

يدعم Form Recognizer كلا من الوصول متعدد الخدمات وخدمة واحدة. يمكنك إنشاء مورد الخدمات المعرفية إذا كنت تخطط للوصول إلى خدمات معرفية متعددة ضمن نقطة نهاية/مفتاح فردي. للوصول إلى Form Recognizer فقط، أنشئ مورد Form Recognizer.

يمكنك إنشاء المورد باستخدام

الخيار 1:مدخل Microsoft Azure

الخيار 2:Azure CLI. فيما يلي مثال على كيفية إنشاء مورد Form Recognizer باستخدام CLI:

# Create a new resource group to hold the form recognizer resource -
# if using an existing resource group, skip this step
az group create --name my-resource-group --location westus2

# Create form recognizer
az cognitiveservices account create \
    --name form-recognizer-resource \
    --resource-group my-resource-group \
    --kind FormRecognizer \
    --sku F0 \
    --location westus2 \
    --yes

مصادقة العميل

للتفاعل مع خدمة Form Recognizer، ستحتاج إلى إنشاء مثيل للعميل. نقطة النهايةوبيانات الاعتماد ضرورية لإنشاء مثيل لكائن العميل.

البحث عن نقطة النهاية

يمكنك العثور على نقطة النهاية لمورد Form Recognizer باستخدام مدخل Microsoft Azure أو Azure CLI:

# Get the endpoint for the form recognizer resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "endpoint"

الحصول على مفتاح API

يمكن العثور على مفتاح API في مدخل Microsoft Azure أو عن طريق تشغيل أمر Azure CLI التالي:

az cognitiveservices account keys list --name "resource-name" --resource-group "resource-group-name"

إنشاء العميل باستخدام AzureKeyCredential

لاستخدام مفتاح API كمعلمة credential ، قم بتمرير المفتاح كسلسلة إلى مثيل AzureKeyCredential.

from azure.core.credentials import AzureKeyCredential
from azure.ai.formrecognizer import FormRecognizerClient

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")
form_recognizer_client = FormRecognizerClient(endpoint, credential)

إنشاء العميل باستخدام بيانات اعتماد Azure Active Directory

AzureKeyCredential يتم استخدام المصادقة في الأمثلة الواردة في دليل البدء هذا، ولكن يمكنك أيضا المصادقة مع Azure Active Directory باستخدام مكتبة هوية azure . لاحظ أن نقاط النهاية الإقليمية لا تدعم مصادقة AAD. قم بإنشاء اسم مجال فرعي مخصص لموردك لاستخدام هذا النوع من المصادقة.

لاستخدام نوع DefaultAzureCredential الموضح أدناه، أو أنواع بيانات الاعتماد الأخرى المتوفرة مع Azure SDK، يرجى تثبيت الحزمة azure-identity :

pip install azure-identity

ستحتاج أيضا إلى تسجيل تطبيق AAD جديد ومنح حق الوصول إلى Form Recognizer عن طريق تعيين "Cognitive Services User" الدور إلى كيان الخدمة الخاص بك.

بمجرد الانتهاء، قم بتعيين قيم معرف العميل ومعرف المستأجر وسر العميل لتطبيق AAD كمتغيرات بيئة: AZURE_CLIENT_ID، ، AZURE_TENANT_IDAZURE_CLIENT_SECRET.

from azure.identity import DefaultAzureCredential
from azure.ai.formrecognizer import FormRecognizerClient
credential = DefaultAzureCredential()

form_recognizer_client = FormRecognizerClient(
    endpoint="https://<my-custom-subdomain>.cognitiveservices.azure.com/",
    credential=credential
)

المفاهيم الرئيسية

FormRecognizerClient

FormRecognizerClientيوفر عمليات لـ:

  • التعرف على حقول النماذج والمحتوى باستخدام نماذج مخصصة مدربة للتعرف على النماذج المخصصة. يتم إرجاع هذه القيم في مجموعة من RecognizedForm كائن.
  • التعرف على الحقول المشتركة من إيصالات الولايات المتحدة، باستخدام نموذج إيصال مدرب مسبقا. يتم إرجاع هذه الحقول وبيانات التعريف في مجموعة من العناصر RecognizedForm .
  • التعرف على محتوى النموذج، بما في ذلك الجداول والأسطر والكلمات، دون الحاجة إلى التدريب على نموذج. يتم إرجاع محتوى النموذج هذا في مجموعة كائنات FormPage.

يتم توفير نماذج القصاصات البرمجية لتوضيح استخدام نماذج FormRecognizerClient هنا.

FormTrainingClient

FormTrainingClientيوفر عمليات لـ:

  • تدريب نماذج مخصصة بدون تسميات للتعرف على جميع الحقول والقيم الموجودة في النماذج المخصصة. CustomFormModel يتم إرجاع يشير إلى أنواع النماذج التي سيتعرف عليها النموذج، والحقول التي سيتم استخراجها لكل نوع نموذج. راجع وثائق الخدمة للحصول على شرح أكثر تفصيلا.
  • تدريب النماذج المخصصة باستخدام التسميات للتعرف على حقول وقيم محددة تحددها عن طريق تسمية النماذج المخصصة. يتم إرجاع CustomFormModel للإشارة إلى الحقول التي يستخرجها النموذج، إضافة إلى الدقة المقدرة لكل حقل. راجع وثائق الخدمة للحصول على شرح أكثر تفصيلا.
  • إدارة النماذج التي تم إنشاؤها في حسابك.
  • نسخ طراز مخصص من مورد Form Recognizer إلى مورد آخر.

يرجى ملاحظة أنه يمكن أيضا تدريب النماذج باستخدام واجهة مستخدم رسومية مثل أداة تسمية Form Recognizer.

يتم توفير نماذج القصاصات البرمجية لتوضيح استخدام نموذج FormTrainingClient هنا.

عمليات Long-Running

العمليات طويلة الأمد هي عمليات تتكون من طلب أولي تم إرساله إلى الخدمة لبدء عملية، متبوعة باستطلاع الخدمة على فترات لتحديد ما إذا كانت العملية قد اكتملت أو فشلت، وما إذا كانت قد نجحت، للحصول على النتيجة.

يتم تصميم الأساليب التي تدرب النماذج أو تتعرف على القيم من النماذج أو نماذج النسخ على أنها عمليات طويلة الأمد. يعرض العميل أسلوبا begin_<method-name> يقوم بإرجاع LROPoller أو AsyncLROPoller. يجب أن ينتظر المتصلون حتى تكتمل العملية عن طريق استدعاء result() كائن الاستقصاء الذي تم إرجاعه من begin_<method-name> الأسلوب . يتم توفير نماذج القصاصات البرمجية لتوضيح استخدام العمليات طويلة الأمد أدناه.

أمثلة

يوفر القسم التالي العديد من القصاصات البرمجية التي تغطي بعض مهام Form Recognizer الأكثر شيوعا، بما في ذلك:

التعرف على النماذج باستخدام نموذج مخصص

التعرف على أزواج الاسم/القيمة وبيانات الجدول من النماذج. يتم تدريب هذه النماذج مع بياناتك الخاصة، لذا فهي مصممة وفقاً لنماذجك. للحصول على أفضل النتائج، يجب أن تتعرف فقط على النماذج من نفس نوع النموذج الذي تم تدريب النموذج المخصص عليه.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)
model_id = "<your custom model id>"

with open("<path to your form>", "rb") as fd:
    form = fd.read()

poller = form_recognizer_client.begin_recognize_custom_forms(model_id=model_id, form=form)
result = poller.result()

for recognized_form in result:
    print("Form type: {}".format(recognized_form.form_type))
    for name, field in recognized_form.fields.items():
        print("Field '{}' has label '{}' with value '{}' and a confidence score of {}".format(
            name,
            field.label_data.text if field.label_data else name,
            field.value,
            field.confidence
        ))

بدلا من ذلك، يمكن أيضا استخدام عنوان URL للنموذج للتعرف على النماذج begin_recognize_custom_forms_from_url المخصصة باستخدام الأسلوب . توجد الأساليب _from_url لجميع أساليب التعرف.

form_url = "<url_of_the_form>"
poller = form_recognizer_client.begin_recognize_custom_forms_from_url(model_id=model_id, form_url=form_url)
result = poller.result()

التعرف على المحتوى

التعرف على بنيات النص والجدول، جنبا إلى جنب مع إحداثيات مربع الإحاطة الخاصة بها، من المستندات.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)

with open("<path to your form>", "rb") as fd:
    form = fd.read()

poller = form_recognizer_client.begin_recognize_content(form)
page = poller.result()

table = page[0].tables[0] # page 1, table 1
print("Table found on page {}:".format(table.page_number))
for cell in table.cells:
    print("Cell text: {}".format(cell.text))
    print("Location: {}".format(cell.bounding_box))
    print("Confidence score: {}\n".format(cell.confidence))

التعرف على الإيصالات

التعرف على البيانات من إيصالات مبيعات الولايات المتحدة الأمريكية باستخدام نموذج تم إنشاؤه مسبقا. يمكن العثور على حقول الإيصالات التي تعرفت عليها الخدمة هنا.

from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_recognizer_client = FormRecognizerClient(endpoint, credential)

with open("<path to your receipt>", "rb") as fd:
    receipt = fd.read()

poller = form_recognizer_client.begin_recognize_receipts(receipt)
result = poller.result()

for receipt in result:
    for name, field in receipt.fields.items():
        if name == "Items":
            print("Receipt Items:")
            for idx, items in enumerate(field.value):
                print("...Item #{}".format(idx+1))
                for item_name, item in items.value.items():
                    print("......{}: {} has confidence {}".format(item_name, item.value, item.confidence))
        else:
            print("{}: {} has confidence {}".format(name, field.value, field.confidence))

تدريب نموذج

تدريب نموذج مخصص على نوع النموذج الخاص بك. يمكن استخدام النموذج الناتج للتعرف على القيم من أنواع النماذج التي تم تدريبه عليها. قم بتوفير عنوان URL ل SAS للحاوية لحاوية Azure Storage Blob حيث تقوم بتخزين مستندات التدريب. إذا كانت ملفات التدريب ضمن مجلد فرعي في الحاوية، فاستخدم وسيطة الكلمة الأساسية للبادئة لتحديد المجلد الذي يجب تدريبه ضمنه.

يمكن العثور على مزيد من التفاصيل حول إعداد حاوية وبنية الملف المطلوبة في وثائق الخدمة.

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_training_client = FormTrainingClient(endpoint, credential)

container_sas_url = "<container-sas-url>"  # training documents uploaded to blob storage
poller = form_training_client.begin_training(
    container_sas_url, use_training_labels=False
)
model = poller.result()

# Custom model information
print("Model ID: {}".format(model.model_id))
print("Status: {}".format(model.status))
print("Training started on: {}".format(model.training_started_on))
print("Training completed on: {}".format(model.training_completed_on))

print("\nRecognized fields:")
for submodel in model.submodels:
    print(
        "The submodel with form type '{}' has recognized the following fields: {}".format(
            submodel.form_type,
            ", ".join(
                [
                    field.label if field.label else name
                    for name, field in submodel.fields.items()
                ]
            ),
        )
    )

# Training result information
for doc in model.training_documents:
    print("Document name: {}".format(doc.name))
    print("Document status: {}".format(doc.status))
    print("Document page count: {}".format(doc.page_count))
    print("Document errors: {}".format(doc.errors))

إدارة النماذج الخاصة بك

إدارة النماذج المخصصة المرفقة بحسابك.

from azure.ai.formrecognizer import FormTrainingClient
from azure.core.credentials import AzureKeyCredential
from azure.core.exceptions import ResourceNotFoundError

endpoint = "https://<region>.api.cognitive.microsoft.com/"
credential = AzureKeyCredential("<api_key>")

form_training_client = FormTrainingClient(endpoint, credential)

account_properties = form_training_client.get_account_properties()
print("Our account has {} custom models, and we can have at most {} custom models".format(
    account_properties.custom_model_count, account_properties.custom_model_limit
))

# Here we get a paged list of all of our custom models
custom_models = form_training_client.list_custom_models()
print("We have models with the following ids: {}".format(
    ", ".join([m.model_id for m in custom_models])
))

# Replace with the custom model ID from the "Train a model" sample
model_id = "<model_id from the Train a Model sample>"

custom_model = form_training_client.get_custom_model(model_id=model_id)
print("Model ID: {}".format(custom_model.model_id))
print("Status: {}".format(custom_model.status))
print("Training started on: {}".format(custom_model.training_started_on))
print("Training completed on: {}".format(custom_model.training_completed_on))

# Finally, we will delete this model by ID
form_training_client.delete_model(model_id=custom_model.model_id)

try:
    form_training_client.get_custom_model(model_id=custom_model.model_id)
except ResourceNotFoundError:
    print("Successfully deleted model with id {}".format(custom_model.model_id))

استكشاف الأخطاء وإصلاحها

عام

ستقوم مكتبة عميل Form Recognizer برفع الاستثناءات المحددة في Azure Core.

تسجيل الدخول

تستخدم هذه المكتبة مكتبة التسجيل القياسية للتسجيل. يتم تسجيل المعلومات الأساسية حول جلسات HTTP (عناوين URL والعناوين وما إلى ذلك) على مستوى INFO.

يمكن تمكين تسجيل مستوى DEBUG مفصلة بما في ذلك الهيئات طلب /استجابة ورؤوس غير منقحة على عميل مع logging_enable وسيطة الكلمة الأساسية:

import sys
import logging
from azure.ai.formrecognizer import FormRecognizerClient
from azure.core.credentials import AzureKeyCredential

# Create a logger for the 'azure' SDK
logger = logging.getLogger('azure')
logger.setLevel(logging.DEBUG)

# Configure a console output
handler = logging.StreamHandler(stream=sys.stdout)
logger.addHandler(handler)

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")

# This client will log detailed information about its HTTP sessions, at DEBUG level
form_recognizer_client = FormRecognizerClient(endpoint, credential, logging_enable=True)

وبالمثل، logging_enable يمكن تمكين تسجيل مفصل لعملية واحدة، حتى عندما لا يتم تمكين للعميل:

poller = form_recognizer_client.begin_recognize_receipts(receipt, logging_enable=True)

التكوين الاختياري

يمكن تمرير وسيطات الكلمات الأساسية الاختيارية على مستوى العميل وكل عملية. تصف الوثائق المرجعية azure-core التكوينات المتوفرة لإعادة المحاولة والتسجيل وبروتوكولات النقل والمزيد.

الخطوات التالية

يوفر القسم التالي العديد من القصاصات البرمجية التي توضح الأنماط الشائعة المستخدمة في واجهة برمجة تطبيقات Form Recognizer Python.

المزيد من نماذج التعليمات البرمجية

تعرض نماذج التعليمات البرمجية هذه عمليات السيناريو الشائعة مع مكتبة عميل Azure Form Recognizer.

APIs غير المتزامنة

تتضمن هذه المكتبة أيضا واجهة برمجة تطبيقات غير متزامنة كاملة مدعومة على Python 3.5+. لاستخدامه، يجب أولا تثبيت نقل غير متزامن، مثل aiohttp. يتم العثور على عملاء غير متزامنين azure.ai.formrecognizer.aio ضمن مساحة الاسم.

وثائق إضافية

للحصول على وثائق أكثر شمولا حول Azure Cognitive Services Form Recognizer، راجع وثائق Form Recognizer على docs.microsoft.com.

المساهمة

هذا المشروع يرحب بالمساهمات والاقتراحات. معظم المساهمات تتطلب منك الموافقة على اتفاقية ترخيص المساهم (CLA) التي تعلن أن لديك الحق في منحنا حق استخدام مساهمتك. للحصول على التفاصيل، تفضل بزيارة cla.microsoft.com.

عند إرسال طلب سحب، سيحدد روبوت CLA-bot تلقائيًا ما إذا كنت بحاجة إلى تقديم CLA وتزيين العلاقات العامة بشكل مناسب (على سبيل المثال، التسمية أو التعليق). ما عليك سوى اتباع التعليمات التي يقدمها الروبوت. ستحتاج فقط إلى القيام بذلك مرة واحدة عبر جميع عمليات إعادة الشراء باستخدام CLA الخاص بنا.

اعتمد هذا المشروع مدونة السلوك من المصادر المفتوحة من Microsoft. لمزيد من المعلومات، راجع الأسئلة المتداولة حول قواعد السلوك أو الاتصال opencode@microsoft.com بأي أسئلة أو تعليقات إضافية.