| ترحيل أداة التعرف على النموذج v3.0 معاينه

  • مقالة
  • قراءة خلال 8 دقائق

هام

يقدم نموذج التعرف على واجهة برمجة تطبيقات REST الإصدار 3.0 تغييرات قاطعة في طلب واجهة برمجة تطبيقات REST وتحليل استجابة JSON.

يقدم أداة التعرف على النموذج الإصدار 3.0 (المعاينة) العديد من الميزات والإمكانات الجديدة:

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

التغييرات التي تطرأ على نقاط نهاية واجهة برمجة تطبيقات REST

تجمع واجهة برمجة تطبيقات v3.0 REST بين عمليات التحليل لتحليل التخطيط والنماذج المعدة مسبقا والنماذج المخصصة في زوج واحد من العمليات عن طريق تعيين documentModels تحليل modelId التخطيط (التخطيط المبني مسبقا) والنماذج المعدة مسبقا.

طلب نشر

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-01-30-preview

طلب GET

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2022-01-30-preview

تحليل العملية

  • تظل حمولة الطلب ونمط المكالمة دون تغيير.
  • تحدد عملية التحليل مستند الإدخال والتكوينات الخاصة بالمحتوى، وتقوم بإرجاع عنوان URL لنتيجة التحليل عبر رأس Operation-Location في الاستجابة.
  • قم باستطلاع عنوان URL لتحليل النتائج هذا ، عبر طلب GET للتحقق من حالة عملية التحليل (الحد الأدنى للفاصل الزمني الموصى به بين الطلبات هو 1 ثانية).
  • عند النجاح، يتم تعيين الحالة إلى ناجح ويتم إرجاع analyzeResult في نص الاستجابة. في حالة مواجهة أخطاء، سيتم تعيين الحالة إلى فشل وسيتم إرجاع خطأ.
النموذج v2.1 الإصدار 3.0
بادئة طلب عنوان URL https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
🆕 وثيقة عامة غير متوفر /documentنماذج/مستند مسبق الصنع:تحليل
Layout /تخطيط/تحليل /documentنماذج/تخطيط مسبق الإنشاء:تحليل
مخصص /مخصص/{modelId}/تحليل /documentModels/{modelId}:تحليل
الفاتورة / معدة مسبقا / فاتورة / تحليل /documentنماذج/فاتورة مسبقة الصنع:تحليل
إيصال / مسبقة الصنع / استلام / تحليل /documentنماذج/استلام مسبق الصنع:تحليل
مستند المعرف /مسبق/idDocument/تحليل /documentModels/prebuilt-idDocument:تحليل
بطاقة العمل /مسبقة الصنع/بطاقة عمل/تحليل /documentنماذج/بطاقة عمل مسبقة الصنع:تحليل
دبليو-2 / بنيت مسبقا / ث - 2 / تحليل /documentنماذج/مبني مسبقا-w-2:تحليل

تحليل نص الطلب

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

لتحديد عنوان URL للويب يمكن الوصول إليه بشكل عام، قم بتعيين نوع المحتوى إلى التطبيق/json وأرسل نص JSON التالي:

{
  "urlSource": "{urlPath}"
}

ترميز Base64 مدعوم أيضا في نموذج التعرف v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

معلمات إضافية

المعلمات التي لا يزال يتم دعمها:

  • pages
  • locale

لم تعد المعلمات مدعومة:

  • تضمينالنصتفاصيل

تنسيق الاستجابة الجديد أكثر إحكاما ويتم إرجاع الإخراج الكامل دائما.

التغييرات في تحليل النتيجة

تمت إعادة هيكلة استجابة التحليل إلى نتائج المستوى الأعلى التالية لدعم العناصر متعددة الصفحات.

  • pages
  • tables
  • keyValuePairs
  • entities
  • styles
  • documents

ملاحظة

تتضمن تغييرات استجابة analyzeResult عددا من التغييرات مثل الانتقال لأعلى من خاصية الصفحات إلى خاصية الرافعة العلوية داخل analyzeResult.


{
// Basic analyze result metadata
"apiVersion": "2022-01-30-preview", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and bounding box coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"boundingBox": [ ... ], // Bounding box
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
], // List of extracted entities
"entities": [
{
"category": "DateTime", // Primary entity category
"subCategory": "Date", // Secondary entity category
"content": "11/15/2019", // Entity content
"boundingRegions": [ ... ], // Entity bounding regions
"spans": [ ... ], // Entity spans
"confidence": 0.99 // Extraction confidence
}, ...
], // List of extracted styles
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

بناء نموذج أو تدريبه

يحتوي كائن النموذج على ثلاثة تحديثات في واجهة برمجة التطبيقات الجديدة

  • modelId هي الآن خاصية يمكن تعيينها على نموذج لاسم بشري قابل للقراءة.
  • تمت إعادة تسميةmodelName إلى description
  • buildMode هو برويرتي جديد مع قيم template لنماذج النماذج المخصصة أو neural لنماذج المستندات المخصصة.

build يتم استدعاء العملية لتدريب نموذج. تظل حمولة الطلب ونمط المكالمة دون تغيير. تحدد عملية الإنشاء مجموعة بيانات النموذج والتدريب ، وتقوم بإرجاع النتيجة عبر رأس Operation-Location في الاستجابة. استقصاء عنوان URL لعملية النموذج هذا ، عبر طلب GET للتحقق من حالة عملية الإنشاء (الحد الأدنى للفاصل الزمني الموصى به بين الطلبات هو 1 ثانية). على عكس الإصدار 2.1 ، فإن عنوان URL هذا ليس موقع المورد الخاص بالنموذج. بدلا من ذلك، يمكن إنشاء عنوان URL للنموذج من modelId المحدد، ويتم استرداده أيضا من الخاصية resourceLocation في الاستجابة. عند النجاح، يتم تعيين الحالة إلى succeeded والنتيجة تحتوي على معلومات النموذج المخصصة. في حالة مواجهة أخطاء، يتم تعيين الحالة إلى failed ويتم إرجاع الخطأ.

التعليمة البرمجية التالية هي نموذج طلب إنشاء باستخدام رمز SAS. لاحظ الشرطة المائلة الزائدة عند تعيين البادئة أو مسار المجلد.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-01-30-preview

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

التغييرات في إنشاء النموذج

يقتصر تكوين النموذج الآن على مستوى واحد من التعشيش. تتوافق النماذج المكونة الآن مع النماذج المخصصة مع إضافة modelId وخصائص description .

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-01-30-preview
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

التغييرات في نموذج النسخ

يبقى نمط الاستدعاء لنموذج النسخ دون تغيير:

  • تفويض عملية النسخ باستخدام استدعاء authorizeCopyالمورد المستهدف . الآن طلب POST.
  • إرسال التفويض إلى المورد المصدر لنسخ استدعاء النموذج copy-to
  • استقصاء العملية التي تم إرجاعها للتحقق من صحة العملية التي تم إكمالها بنجاح

التغييرات الوحيدة على وظيفة نموذج النسخ هي:

  • إجراء HTTP على authorizeCopy هو الآن طلب POST.
  • وتحتوي حمولة الإذن على جميع المعلومات اللازمة لتقديم طلب النسخة.

تفويض النسخة

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-01-30-preview
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

استخدم نص الاستجابة من إجراء التفويض لإنشاء طلب النسخة.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copy-to?api-version=2022-01-30-preview
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

التغييرات في نماذج القوائم

تم توسيع نماذج القائمة لإرجاع النماذج المعدة مسبقا والمخصصة الآن. تبدأ جميع أسماء النماذج المعدة مسبقا ب prebuilt-. يتم إرجاع النماذج ذات الحالة الناجحة فقط. لسرد النماذج التي فشلت أو قيد التقدم، راجع قائمة العمليات.

نموذج طلب نماذج القوائم

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-01-30-preview

تغيير للحصول على نموذج

نظرا لأن نموذج get يتضمن الآن نماذج مسبقة الإنشاء ، فإن عملية get ترجع قاموسا docTypes . يتم وصف كل نوع مستند باسمه ووصفه الاختياري ومخطط الحقل والثقة الاختيارية في الحقل. يصف مخطط الحقل قائمة الحقول التي يحتمل إرجاعها مع نوع المستند.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-01-30-preview

عملية الحصول على معلومات جديدة

ترجع info العملية على الخدمة عدد الطرز المخصص والحد الأقصى للطراز المخصص.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-01-30-preview

استجابة العينة

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

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

في دليل الترحيل هذا، تعلمت كيفية ترقية تطبيق "التعرف على النماذج" الحالي لاستخدام واجهات برمجة التطبيقات v3.0. استمر في استخدام واجهة برمجة التطبيقات 2.1 لجميع ميزات GA واستخدم واجهة برمجة التطبيقات 3.0 لأي من ميزات المعاينة.