ترحيل Document Intelligence v3.1

ينطبق هذا المحتوى على:v4.0 (معاينة)v3.1 (GA)v3.0 (GA)v2.1 (GA)

هام

يقدم Document Intelligence REST API v3.1 تغييرات فاصلة في طلب REST API وتحليل الاستجابة JSON.

الترحيل من إصدار واجهة برمجة التطبيقات لمعاينة الإصدار 3.1

يتم إهمال واجهات برمجة تطبيقات المعاينة بشكل دوري. إذا كنت تستخدم إصدار واجهة برمجة تطبيقات معاينة، فقم بتحديث التطبيق الخاص بك لاستهداف إصدار واجهة برمجة تطبيقات GA. للترحيل من إصدار واجهة برمجة التطبيقات 2023-02-28-preview إلى 2023-07-31 إصدار واجهة برمجة التطبيقات (GA) باستخدام SDK، قم بالتحديث إلى الإصدار الحالي من SDK الخاصة باللغة.

2023-07-31 تحتوي واجهة برمجة التطبيقات (GA) على بعض التحديثات والتغييرات من إصدار واجهة برمجة التطبيقات للمعاينة:

• تقتصر الميزات التي يتم تمكينها افتراضيا على الميزات الأساسية للنموذج المحدد مع فائدة تقليل زمن الانتقال وحجم الاستجابة. يمكن تمكين الميزات المضافة عبر قيم التعداد في features المعلمة.
• لم تعد بعض ميزات التخطيط من keyValuePairs التي تم إنشاؤها مسبقا وkeyValuePairs بخلاف prebuilt-{document,invoice} مدعومة.
• تعطيل الرموز الشريطية بشكل افتراضي للتخطيط مسبق الإنشاء والمقروء مسبقا واللغات للقراءة المسبقة وkeyValuePairs للفاتورة التي تم إنشاؤها مسبقا.
• تتم إزالة استخراج التعليق التوضيحي.
• تتم إزالة حقول الاستعلام والأسماء الشائعة لأزواج قيم المفاتيح.
• يتم دعم ملفات Office/HTML في نموذج للقراءة مسبقة الإنشاء، واستخراج الكلمات والفقرات دون مربعات إحاطة. لم تعد الصور المضمنة مدعومة. إذا تم طلب ميزات الوظيفة الإضافية لملفات Office/HTML، يتم إرجاع صفيف فارغ دون أخطاء.

ميزات التحليل

معرف النموذج	استخراج النص	الفقرات	أدوار الفقرة	علامات التحديد	الجداول‏‎	أزواج قيم المفاتيح	اللغات	الباركود	تحليل المستندات	الصيغ*	StyleFont*	OCR High Resolution*
prebuilt-read	√	√					O	O		O	O	O
prebuilt-layout	√	√	√	√	√		O	O		O	O	O
prebuilt-document	√	√	√	√	√	√	O	O		O	O	O
prebuilt-businessCard	√								√
prebuilt-idDocument	√						O	O	√	O	O	O
prebuilt-invoice	√			√	√	O	O	O	√	O	O	O
prebuilt-receipt	√						O	O	√	O	O	O
prebuilt-healthInsuranceCard.us	√						O	O	√	O	O	O
prebuilt-tax.us.w2	√			√			O	O	√	O	O	O
prebuilt-tax.us.1098	√			√			O	O	√	O	O	O
prebuilt-tax.us.1098E	√			√			O	O	√	O	O	O
prebuilt-tax.us.1098T	√			√			O	O	√	O	O	O
عقد مسبق الإنشاء	√	√	√	√			O	O	√	O	O	O
{ customModelName }	√	√	√	√	√		O	O	√	O	O	O

✓ - تمكين O - الصيغ الاختيارية / StyleFont / OCR عالية الدقة * - الميزات المتميزة تتحمل تكاليف إضافية

الترحيل من الإصدار 3.0

بالمقارنة مع الإصدار 3.0، يقدم Document Intelligence v3.1 العديد من الميزات والقدرات الجديدة:

• استخراج الرمز الشريطي .
• قدرات الوظيفة الإضافية بما في ذلك استخراج خصائص الدقة العالية والصيغة والخط.
• نموذج تصنيف مخصص لتقسيم المستند وتصنيفه.
• يدعم توسيع اللغة والحقول الجديدة في نموذج الفاتورة والإيصال.
• دعم نوع المستند الجديد في نموذج مستند المعرف.
• نموذج بطاقة التأمين الصحي الجديد الذي تم إنشاؤه مسبقا.
• يتم دعم ملفات Office/HTML في نموذج للقراءة مسبقة الإنشاء، واستخراج الكلمات والفقرات دون مربعات إحاطة. لم تعد الصور المضمنة مدعومة. إذا تم طلب ميزات الوظيفة الإضافية لملفات Office/HTML، يتم إرجاع صفيف فارغ دون أخطاء.
• انتهاء صلاحية النموذج لنماذج الاستخراج والتصنيف المخصصة - تعتمد نماذجنا المخصصة الجديدة على نموذج أساسي كبير نقوم بتحديثه بشكل دوري لتحسين الجودة. يتم تقديم تاريخ انتهاء الصلاحية لجميع النماذج المخصصة لتمكين إيقاف النماذج الأساسية المقابلة. بمجرد انتهاء صلاحية نموذج مخصص، تحتاج إلى إعادة تدريب النموذج باستخدام أحدث إصدار من واجهة برمجة التطبيقات (نموذج أساسي).

GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2023-09-24T12:54:35Z",
  "expirationDateTime": "2025-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}

• حصة بناء النموذج العصبي المخصصة - عدد النماذج العصبية التي يمكن لكل اشتراك بناءها لكل منطقة كل شهر محدود. نقوم بتوسيع النتيجة JSON لتضمين الحصة النسبية والمعلومات المستخدمة لمساعدتك على فهم الاستخدام الحالي كجزء من معلومات المورد التي تم إرجاعها بواسطة GET /info.

{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}

• يمكن لمعلمة استعلام اختيارية features لتحليل العمليات تمكين ميزات معينة اختياريا. يمكن أن تتحمل بعض الميزات المتميزة فوترة إضافية. راجع تحليل قائمة الميزات للحصول على التفاصيل.
• قم بتوسيع كائنات حقل العملة المستخرجة لإخراج حقل رمز عملة تمت تسويته عندما يكون ذلك ممكنا. حاليا، يمكن للحقل الحالي إرجاع المبلغ (على سبيل المثال، 123.45) و currencySymbol (على سبيل المثال$ ). تقوم هذه الميزة بتعيين رمز العملة إلى رمز ISO 4217 المتعارف عليه (على سبيل المثال، الدولار الأمريكي). يمكن للنموذج استخدام محتوى المستند العمومي اختياريا لإزالة الغموض عن رمز العملة أو استنتاجه.

{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

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

الترحيل من الإصدار 2.1 أو v2.0

Document Intelligence v3.1 هو أحدث إصدار من التوفر العام مع أغنى الميزات ومعظم اللغات وتغطية أنواع المستندات وجودة النموذج المحسنة. راجع نظرة عامة على النموذج للميزات والقدرات المتوفرة في الإصدار 3.1.

بدءا من الإصدار 3.0، تتم إعادة تصميم واجهة برمجة تطبيقات REST لذكاء المستند لتحسين إمكانية الاستخدام. في هذا القسم، تعرف على الاختلافات بين Document Intelligence v2.0 وv2.1 وv3.1 وكيفية الانتقال إلى الإصدار الأحدث من واجهة برمجة التطبيقات.

تنبيه

• يتضمن إصدار REST API 2023-07-31 تغييرا فاصلا في استجابة تحليل واجهة برمجة تطبيقات REST JSON.
• تتم إعادة تسمية العقار boundingBox إلى polygon في كل حالة.

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

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

طلب نشر

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31

طلب GET

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31

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

• تظل حمولة الطلب ونمط الاستدعاء دون تغيير.
• تحدد عملية Analyze مستند الإدخال والتكوينات الخاصة بالمحتوى، وتعيد عنوان URL لنتيجة التحليل عبر عنوان موقع التشغيل في الاستجابة.
• قم باستطلاع عنوان URL لنتيجة التحليل هذا، عبر طلب GET للتحقق من حالة عملية التحليل (الحد الأدنى الموصى به للفاصل الزمني بين الطلبات هو 1 ثانية).
• عند النجاح، يتم تعيين الحالة للنجاح ويتم إرجاع تحليل النتيجة في نص الاستجابة. إذا تمت مصادفة أخطاء، يتم تعيين الحالة إلى failed، ويتم إرجاع خطأ.

النموذج	v2.0	v2.1	الإصدار 3.1
بادئة عنوان URL للطلب	https://{your-form-recognizer-endpoint}/formrecognizer/v2.0	https://{your-form-recognizer-endpoint}/formrecognizer/v2.1	https://{your-form-recognizer-endpoint}/formrecognizer
المستند العام	‏‫غير متوفر‬	‏‫غير متوفر‬	/documentModels/prebuilt-document:analyze
تخطيط	/layout/analysis	/layout/analysis	/documentModels/prebuilt-layout:analyze
مخصص	/custom/models/{modelId}/analyze	/custom/{modelId}/analyze	/documentModels/{modelId}:analyze
فاتورة	‏‫غير متوفر‬	/ما قبل الإنشاء/الفاتورة/التحليل	/documentModels/prebuilt-invoice:analyze
استلام	/prebuilt/receipt/analyze	/prebuilt/receipt/analyze	/documentModels/prebuilt-receipt:analyze
مستند المعرف	‏‫غير متوفر‬	/prebuilt/idDocument/analyze	/documentModels/prebuilt-idDocument:analyze
بطاقة العمل	‏‫غير متوفر‬	/prebuilt/businessCard/analyze	/documentModels/prebuilt-businessCard:analyze
W-2	‏‫غير متوفر‬	‏‫غير متوفر‬	/documentModels/prebuilt-tax.us.w2:analyze
بطاقة التأمين الصحي	‏‫غير متوفر‬	‏‫غير متوفر‬	/documentModels/prebuilt-healthInsuranceCard.us:analyze
‏‏عقد	‏‫غير متوفر‬	‏‫غير متوفر‬	/documentModels/prebuilt-contract:analyze

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

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

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

{
  "urlSource": "{urlPath}"
}

يتم دعم ترميز Base 64 أيضا في Document Intelligence v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

معلمات مدعومة بالإضافة إلى ذلك

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

• pages: قم فحسب بتحليل مجموعة فرعية محددة من الصفحات في المستند. قائمة بأرقام الصفحات المفهرسة من الرقم 1 للتحليل. على سبيل المثال، "1-3,5,7-9"
• locale: تلميح محلي للتعرف على النص وتحليل المستندات. يمكن أن تحتوي القيمة على رمز اللغة فقط (على سبيل المثال en، أو fr) أو علامة لغة BCP 47 (على سبيل المثال، "en-US").

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

• includeTextDetails

يعد تنسيق الاستجابة الجديد أكثر ضغطًا، ويتم دائمًا إرجاع الناتج الكامل.

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

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

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

إشعار

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

{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // 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 polygon 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": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"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
}, ...
],
"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 للنموذج من معرف النموذج المحدد، والذي يتم استرداده أيضًا من خاصية موقع المورد في الاستجابة. عند النجاح، يتم تعيين الحالة إلى succeeded وتحتوي النتيجة على معلومات النموذج المخصص. في حالة حدوث أخطاء، تعيّن الحالة إلى failed ويُرجع الخطأ.

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

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "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-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

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

يظل نمط الاتصال لنموذج النسخ دون تغيير:

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

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

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

تفويض النسخة

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

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

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "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-08-31

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

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

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

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

تقوم عملية info للخدمة بإرجاع عدد النماذج المخصصة وحدود النماذج المخصصة.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

نموذج الاستجابة

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

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

• مراجعة واجهة برمجة تطبيقات REST الجديدة
• ما المقصود ب Document Intelligence؟
• التشغيل السريع لذكاء المستند