مكتبة عميل Azure الذكاء الاصطناعي Document Intelligence ل JavaScript - الإصدار 5.0.0

مقالة
08/16/2023

Azure الذكاء الاصطناعي Document Intelligence هي خدمة سحابية تستخدم التعلم الآلي لتحليل النص والبيانات المنظمة من مستنداتك. يتضمن الميزات الرئيسية التالية:

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

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

ملاحظة

كانت خدمة Document Intelligence تعرف سابقا باسم "Azure Form Recognizer". هذه الخدمات واحدة ونفسها، وحزمة @azure/ai-form-recognizer JavaScript هي حزمة Azure SDK لخدمة Azure الذكاء الاصطناعي Document Intelligence. في وقت كتابة هذا التقرير، كانت إعادة تسمية Azure Form Recognizer إلى Azure الذكاء الاصطناعي Document Intelligence جارية، لذلك يمكن استخدام "Form Recognizer" و"Document Intelligence" بالتبادل في بعض الحالات.

تثبيت `@azure/ai-form-recognizer`الحزمة

قم بتثبيت مكتبة عميل Azure Document Intelligence ل JavaScript باستخدام npm:

npm install @azure/ai-form-recognizer

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

const { DocumentAnalysisClient } = require("@azure/ai-form-recognizer");
const { DefaultAzureCredential } = require("@azure/identity");

const fs = require("fs");

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com",
  credential
);

// Document Intelligence supports many different types of files.
const file = fs.createReadStream("path/to/file.jpg");
const poller = await client.beginAnalyzeDocument("<model ID>", file);

const { pages, tables, styles, keyValuePairs, entities, documents } = await poller.pollUntilDone();

البيئات المعتمدة حاليًا

إصدارات "LTS" من "Node.js".
آخر إصدارات Safari وChrome وEdge وFirefox.

راجع سياسة الدعم الخاصة بنا لمزيد من التفاصيل.

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

اشتراك Azure
مورد الخدمات المعرفية أو Form Recognizer. إذا كنت بحاجة إلى إنشاء المورد، يمكنك استخدام مدخل Microsoft Azure أو Azure CLI.

إنشاء مورد Form Recognizer

ملاحظة: في وقت كتابة هذا التقرير، لا يزال مدخل Microsoft Azure يشير إلى المورد كمورد "Form Recognizer". في المستقبل، قد يتم تحديث هذا إلى مورد "معلومات المستند". في الوقت الحالي، تستخدم الوثائق التالية اسم "Form Recognizer".

يدعم Document Intelligence كلا من الوصول متعدد الخدمات وخدمة واحدة. يمكنك إنشاء مورد الخدمات المعرفية إذا كنت تخطط للوصول إلى خدمات معرفية متعددة ضمن نقطة نهاية/مفتاح فردي. للوصول إلى 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

إذا كنت تستخدم Azure CLI، فاستبدل <your-resource-group-name> و <your-resource-name> بأسماء فريدة خاصة بك:

az cognitiveservices account create --kind FormRecognizer --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

إنشاء عميل ومصادقته

للتفاعل مع خدمة Document Intelligence، ستحتاج إلى تحديد أو DocumentAnalysisClientDocumentModelAdministrationClient، وإنشاء مثيل من هذا النوع. في الأمثلة التالية، سنستخدم DocumentAnalysisClient. لإنشاء مثيل عميل للوصول إلى واجهة برمجة تطبيقات ذكاء المستند، ستحتاج إلى endpoint مورد Form Recognizer الخاص بك و credential. يمكن للعملاء استخدام إما AzureKeyCredential مع مفتاح API لموردك أو TokenCredential الذي يستخدم Azure Active Directory RBAC لتخويل العميل.

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

az cognitiveservices account show --name <your-resource-name> --resource-group <your-resource-group-name> --query "properties.endpoint"

استخدام مفتاح API

استخدم مدخل Microsoft Azure للاستعراض وصولا إلى مورد Form Recognizer واسترداد مفتاح API، أو استخدم قصاصة برمجية Azure CLI أدناه:

ملاحظه: في بعض الأحيان يشار إلى مفتاح واجهة برمجة التطبيقات باسم "مفتاح الاشتراك" أو "مفتاح واجهة برمجة تطبيقات الاشتراك".

az cognitiveservices account keys list --resource-group <your-resource-group-name> --name <your-resource-name>

بمجرد أن يكون لديك مفتاح واجهة برمجة التطبيقات ونقطة النهاية، يمكنك استخدامه على النحو التالي:

const { DocumentAnalysisClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");

const client = new DocumentAnalysisClient("<endpoint>", new AzureKeyCredential("<API key>"));

استخدام Azure Active Directory

يتم استخدام تخويل مفتاح واجهة برمجة التطبيقات في معظم الأمثلة، ولكن يمكنك أيضا مصادقة العميل باستخدام Azure Active Directory باستخدام مكتبة هوية Azure. لاستخدام موفر DefaultAzureCredential الموضح أدناه أو موفري بيانات الاعتماد الآخرين المقدمين مع Azure SDK، يرجى تثبيت الحزمة @azure/identity :

npm install @azure/identity

للمصادقة باستخدام كيان خدمة، ستحتاج أيضا إلى تسجيل تطبيق AAD ومنح حق الوصول إلى الخدمة عن طريق تعيين "Cognitive Services User" الدور إلى كيان الخدمة (ملاحظة: لن تمنح الأدوار الأخرى مثل "Owner" الأذونات الضرورية، بل تكفي فقط "Cognitive Services User" لتشغيل الأمثلة ونموذج التعليمات البرمجية).

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

const { DocumentAnalysisClient } = require("@azure/ai-form-recognizer");
const { DefaultAzureCredential } = require("@azure/identity");

const client = new DocumentAnalysisClient("<endpoint>", new DefaultAzureCredential());

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

`DocumentAnalysisClient`

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

beginAnalyzeDocument، الذي يستخرج البيانات من دفق ملف مستند الإدخال باستخدام نموذج مخصص أو تم إنشاؤه مسبقا تم منحه بواسطة معرف النموذج الخاص به. للحصول على معلومات حول النماذج التي تم إنشاؤها مسبقا المدعومة في جميع الموارد ومعرفات/مخرجات النموذج الخاصة بها، يرجى الاطلاع على وثائق الخدمة للنماذج.
beginAnalyzeDocumentFromUrl، الذي يؤدي نفس وظيفة beginAnalyzeDocument، ولكنه يرسل عنوان URL يمكن الوصول إليه بشكل عام لملف بدلا من دفق ملف.

`DocumentModelAdministrationClient`

DocumentModelAdministrationClient يوفر عمليات لإدارة (إنشاء النماذج وقراءتها وإدراجها وحذفها) في المورد:

beginBuildDocumentModel يبدأ عملية لإنشاء نموذج مستند جديد من مجموعة بيانات التدريب الخاصة بك. يمكن للنموذج الذي تم إنشاؤه استخراج الحقول وفقا لمخطط مخصص. من المتوقع أن تكون بيانات التدريب موجودة في حاوية تخزين Azure ويتم تنظيمها وفقا لاصطلاح معين. راجع وثائق الخدمة حول إنشاء مجموعة بيانات تدريب للحصول على شرح أكثر تفصيلا لتطبيق التسميات على مجموعة بيانات التدريب.
beginComposeDocumentModel يبدأ عملية لإنشاء نماذج متعددة في نموذج واحد. عند استخدامه للتعرف على النموذج المخصص، سيقوم النموذج المكون الجديد أولا بإجراء تصنيف لمستندات الإدخال لتحديد أي من نماذجه الفرعية هو الأنسب.
beginCopyModelTo بدء عملية لنسخ نموذج مخصص من مورد إلى آخر (أو حتى إلى نفس المورد). يتطلب من CopyAuthorization المورد الهدف، والذي يمكن إنشاؤه باستخدام getCopyAuthorization الأسلوب .
getResourceDetails يسترد معلومات حول حدود المورد، مثل عدد النماذج المخصصة والحد الأقصى لعدد النماذج التي يمكن أن يدعمها المورد.
getDocumentModel، listDocumentModels، وتمكين deleteDocumentModel إدارة النماذج في المورد.
getOperation وتمكين listOperations عرض حالة عمليات إنشاء النموذج، حتى تلك العمليات المستمرة أو التي فشلت. يتم الاحتفاظ بالعملية لمدة 24 ساعة.

يرجى ملاحظة أنه يمكن أيضا إنشاء النماذج باستخدام واجهة المستخدم الرسومية لخدمة Document Intelligence: Document Intelligence Studio.

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

عمليات طويلة الأمد

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

في Azure الذكاء الاصطناعي Document Intelligence، تكون العمليات التي تنشئ نماذج (بما في ذلك نسخ النماذج وتكوينها) بالإضافة إلى عمليات التحليل/استخراج البيانات هي LROs. يوفر عملاء SDK أساليب غير begin<operation-name> متزامنة ترجع Promise<PollerLike> العناصر. PollerLike يمثل الكائن العملية، التي تعمل بشكل غير متزامن على البنية الأساسية للخدمة، ويمكن لبرنامج انتظار اكتمال العملية عن طريق استدعاء الأسلوب على الاستقصاء الذي تم إرجاعه من begin<operation-name> الأسلوب وانتظارهpollUntilDone. يتم توفير نماذج القصاصات البرمجية لتوضيح استخدام العمليات طويلة الأمد في القسم التالي.

أمثلة

يوفر القسم التالي العديد من القصاصات البرمجية JavaScript التي توضح الأنماط الشائعة المستخدمة في مكتبات عميل Document Intelligence.

تحليل مستند باستخدام معرف نموذج
استخدام نماذج المستندات التي تم إنشاؤها مسبقا
استخدام "التخطيط" الذي تم إنشاؤه مسبقا
استخدام "المستند" الذي تم إنشاؤه مسبقا
استخدام "القراءة" التي تم إنشاؤها مسبقا
إنشاء نموذج
إدارة النماذج

تحليل مستند باستخدام معرف نموذج

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

const { DocumentAnalysisClient, AzureKeyCredential } = require("@azure/ai-form-recognizer");

const fs = require("fs");

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const modelId = "<model id>";
  const path = "<path to a document>";

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));
  const poller = await client.beginAnalyzeDocument(modelId, readStream, {
    onProgress: ({ status }) => {
      console.log(`status: ${status}`);
    },
  });

  // There are more fields than just these three
  const { documents, pages, tables } = await poller.pollUntilDone();

  console.log("Documents:");
  for (const document of documents || []) {
    console.log(`Type: ${document.docType}`);
    console.log("Fields:");
    for (const [name, field] of Object.entries(document.fields)) {
      console.log(
        `Field ${name} has value '${field.value}' with a confidence score of ${field.confidence}`
      );
    }
  }
  console.log("Pages:");
  for (const page of pages || []) {
    console.log(`Page number: ${page.pageNumber} (${page.width}x${page.height} ${page.unit})`);
  }

  console.log("Tables:");
  for (const table of tables || []) {
    console.log(`- Table (${table.columnCount}x${table.rowCount})`);
    for (const cell of table.cells) {
      console.log(`  - cell (${cell.rowIndex},${cell.columnIndex}) "${cell.content}"`);
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

تحليل مستند من عنوان URL

كبديل لتوفير دفق قابل للقراءة، يمكن توفير عنوان URL يمكن الوصول إليه بشكل عام بدلا من ذلك باستخدام beginAnalyzeDocumentFromUrl الأسلوب . تعني كلمة "يمكن الوصول إليها بشكل عام" أنه يجب الوصول إلى مصادر URL من البنية الأساسية للخدمة (بمعنى آخر، لن يعمل عنوان URL خاص للشبكة الداخلية أو عناوين URL التي تستخدم البيانات السرية المستندة إلى العنوان أو الشهادة، حيث يجب أن تكون خدمة معلومات المستند قادرة على الوصول إلى عنوان URL). ومع ذلك، يمكن أن يقوم عنوان URL نفسه بترميز سر، مثل عنوان URL لكائن ثنائي كبير الحجم لتخزين Azure الذي يحتوي على رمز SAS المميز في معلمات الاستعلام.

استخدام نماذج المستندات التي تم إنشاؤها مسبقا

beginAnalyzeDocument يدعم الأسلوب أيضا استخراج الحقول من أنواع معينة من المستندات الشائعة مثل الإيصالات والفواتير وبطاقات العمل ومستندات الهوية والمزيد باستخدام النماذج التي تم إنشاؤها مسبقا والتي توفرها خدمة معلومات المستند. يمكن توفير النماذج التي تم إنشاؤها مسبقا إما كسلاسل معرف النموذج (مثل نماذج المستندات المخصصة - راجع قسم النماذج الأخرى التي تم إنشاؤها مسبقا أدناه) أو باستخدام كائن DocumentModel . عند استخدام DocumentModel، يوفر Document Intelligence SDK ل JavaScript نوع TypeScript أقوى بكثير للمستندات المستخرجة الناتجة استنادا إلى مخطط النموذج، وسيتم تحويله لاستخدام اصطلاحات تسمية JavaScript.

يمكن العثور على أمثلة DocumentModel على كائنات لإصدار واجهة برمجة تطبيقات الخدمة الحالي (2022-08-31) في prebuilt دليل العينات. في المثال التالي، سنستخدم PrebuiltReceiptModel من الملف [prebuilt-receipt.ts] في هذا الدليل.

نظرا لأن الفائدة الرئيسية للتحليل DocumentModelالمستند إلى هي قيود نوع TypeScript الأقوى، تتم كتابة النموذج التالي في TypeScript باستخدام بناء جملة وحدة ECMAScript:

import { DocumentAnalysisClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

// Copy the file from the above-linked sample directory so that it can be imported in this module
import { PrebuiltReceiptModel } from "./prebuilt/prebuilt-receipt";

import fs from "fs";

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const path = "<path to your receipt document>"; // pdf/jpeg/png/tiff formats

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));

  // The PrebuiltReceiptModel `DocumentModel` instance encodes both the model ID and a stronger return type for the operation
  const poller = await client.beginAnalyzeDocument(PrebuiltReceiptModel, readStream, {
    onProgress: ({ status }) => {
      console.log(`status: ${status}`);
    },
  });

  const {
    documents: [receiptDocument],
  } = await poller.pollUntilDone();

  // The fields of the document constitute the extracted receipt data.
  const receipt = receiptDocument.fields;

  if (receipt === undefined) {
    throw new Error("Expected at least one receipt in analysis result.");
  }

  console.log(`Receipt data (${receiptDocument.docType})`);
  console.log("  Merchant Name:", receipt.merchantName?.value);

  // The items of the receipt are an example of a `DocumentArrayValue`
  if (receipt.items !== undefined) {
    console.log("Items:");
    for (const { properties: item } of receipt.items.values) {
      console.log("- Description:", item.description?.value);
      console.log("  Total Price:", item.totalPrice?.value);
    }
  }

  console.log("  Total:", receipt.total?.value);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

بدلا من ذلك، كما ذكر أعلاه، بدلا من استخدام PrebuiltReceiptModel، الذي ينتج نوع إرجاع أقوى، يمكن استخدام معرف نموذج الإيصال الذي تم إنشاؤه مسبقا ("إيصال مسبق الإنشاء")، ولكن لن يتم كتابة حقول المستند بقوة في TypeScript، وستكون أسماء الحقول بشكل عام في "PascalCase" بدلا من "camelCase".

نماذج أخرى تم إنشاؤها مسبقا

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

الإيصالات، باستخدام PrebuiltReceiptModel (كما هو موضح أعلاه) أو معرف "prebuilt-receipt"نموذج الإيصال الذي تم إنشاؤه مسبقا .
بطاقات العمل، باستخدام PrebuiltBusinessCardModel أو معرف "prebuilt-businessCard"النموذج الخاص به.
الفواتير، باستخدام PrebuiltInvoiceModel أو معرف "prebuilt-invoice"النموذج الخاص به .
وثائق الهوية (مثل تراخيص القيادة وجوازات السفر)، باستخدام PrebuiltIdDocumentModel أو معرف "prebuilt-idDocument"النموذج الخاص به.
نماذج ضريبة W2 (الولايات المتحدة)، باستخدام PrebuiltTaxUsW2Model أو معرف "prebuilt-tax.us.w2"النموذج الخاص به.
بطاقات التأمين الصحي (الولايات المتحدة)، باستخدام [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] أو معرف "prebuilt-healthInsuranceCard.us"النموذج الخاص به.

ينتج documents كل نموذج من النماذج التي تم إنشاؤها مسبقا أعلاه (مثيلات مستخرجة من مخطط حقل النموذج). هناك أيضا ثلاثة نماذج تم إنشاؤها مسبقا لا تحتوي على مخططات حقول وبالتالي لا تنتج documents. وهي كالتالي:

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

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

يمكن أيضا الوصول إلى حقول جميع النماذج التي تم إنشاؤها مسبقا برمجيا باستخدام getDocumentModel الأسلوب (بواسطة معرفات النموذج الخاصة بها) DocumentModelAdministrationClient وفحص docTypes الحقل في النتيجة.

استخدام "التخطيط" الذي تم إنشاؤه مسبقا

يستخرج "prebuilt-layout" النموذج فقط العناصر الأساسية للمستند، مثل الصفحات، (التي تتكون من كلمات/أسطر نصية وعلامات تحديد) والجداول وأنماط النص المرئي جنبا إلى جنب مع المناطق المحيطة بها وتمتد ضمن المحتوى النصي لمستندات الإدخال. نحن نقدم مثيلا مكتوبا DocumentModel بقوة يسمى PrebuiltLayoutModel يستدعي هذا النموذج، أو كما هو الحال دائما، يمكن استخدام معرف "prebuilt-layout" النموذج الخاص به مباشرة.

import { DocumentAnalysisClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

// Copy the above-linked `DocumentModel` file so that it may be imported in this module.
import { PrebuiltLayoutModel } from "./prebuilt/prebuilt-layout";

import fs from "fs";

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const path = "<path to a document>"; // pdf/jpeg/png/tiff formats

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));
  const poller = await client.beginAnalyzeDocument(PrebuiltLayoutModel, readStream);
  const { pages, tables } = await poller.pollUntilDone();

  for (const page of pages || []) {
    console.log(`- Page ${page.pageNumber}: (${page.width}x${page.height} ${page.unit})`);
  }

  for (const table of tables || []) {
    console.log(`- Table (${table.columnCount}x${table.rowCount})`);
    for (const cell of table.cells) {
      console.log(`  cell [${cell.rowIndex},${cell.columnIndex}] "${cell.content}"`);
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

استخدام "المستند" الذي تم إنشاؤه مسبقا

يستخرج "prebuilt-document" النموذج معلومات حول أزواج قيم المفاتيح (الاقترانات الموجهة بين عناصر الصفحة، مثل الحقول المسماة) بالإضافة إلى الخصائص التي تنتجها طريقة استخراج التخطيط. يوفر نموذج المستندات (العام) هذا الذي تم إنشاؤه مسبقا وظائف مماثلة للنماذج المخصصة المدربة دون معلومات التسمية في التكرارات السابقة لخدمة ذكاء المستند، ولكن يتم توفيره الآن كنموذج تم إنشاؤه مسبقا يعمل مع مجموعة واسعة من المستندات. نحن نقدم مثيلا مكتوبا DocumentModel بقوة يسمى PrebuiltDocumentModel يستدعي هذا النموذج، أو كما هو الحال دائما، يمكن استخدام معرف "prebuilt-document" النموذج الخاص به مباشرة.

import { DocumentAnalysisClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

// Copy the above-linked `DocumentModel` file so that it may be imported in this module.
import { PrebuiltDocumentModel } from "./prebuilt/prebuilt-document";

import fs from "fs";

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const path = "<path to a document>"; // pdf/jpeg/png/tiff formats

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));
  const poller = await client.beginAnalyzeDocument(PrebuiltDocumentModel, readStream);

  // `pages`, `tables` and `styles` are also available as in the "layout" example above, but for the sake of this
  // example we won't show them here.
  const { keyValuePairs } = await poller.pollUntilDone();

  if (!keyValuePairs || keyValuePairs.length <= 0) {
    console.log("No key-value pairs were extracted from the document.");
  } else {
    console.log("Key-Value Pairs:");
    for (const { key, value, confidence } of keyValuePairs) {
      console.log("- Key  :", `"${key.content}"`);
      console.log("  Value:", `"${value?.content ?? "<undefined>"}" (${confidence})`);
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

استخدام "القراءة" التي تم إنشاؤها مسبقا

يستخرج "prebuilt-read" النموذج المعلومات النصية في مستند مثل الكلمات والفقرات ويحلل اللغة ونمط الكتابة (على سبيل المثال، الكتابة بخط اليد مقابل typeset) لهذا النص. نحن نقدم مثيلا مكتوبا DocumentModel بقوة يسمى PrebuiltReadModel يستدعي هذا النموذج، أو كما هو الحال دائما، يمكن استخدام معرف "prebuilt-read" النموذج الخاص به مباشرة.

import { DocumentAnalysisClient, AzureKeyCredential } from "@azure/ai-form-recognizer";

// Copy the above-linked `DocumentModel` file so that it may be imported in this module.
import { PrebuiltReadModel } from "./prebuilt/prebuilt-read";

// See the samples directory for a definition of this helper function.
import { getTextOfSpans } from "./utils";

import fs from "fs";

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const path = "<path to a document>"; // pdf/jpeg/png/tiff formats

  const readStream = fs.createReadStream(path);

  const client = new DocumentAnalysisClient(endpoint, new AzureKeyCredential(apiKey));
  const poller = await client.beginAnalyzeDocument(PrebuiltReadModel, readStream);

  // The "prebuilt-read" model (`beginReadDocument` method) only extracts information about the textual content of the
  // document, such as page text elements, text styles, and information about the language of the text.
  const { content, pages, languages } = await poller.pollUntilDone();

  if (!pages || pages.length <= 0) {
    console.log("No pages were extracted from the document.");
  } else {
    console.log("Pages:");
    for (const page of pages) {
      console.log("- Page", page.pageNumber, `(unit: ${page.unit})`);
      console.log(`  ${page.width}x${page.height}, angle: ${page.angle}`);
      console.log(
        `  ${page.lines && page.lines.length} lines, ${page.words && page.words.length} words`
      );

      if (page.lines && page.lines.length > 0) {
        console.log("  Lines:");

        for (const line of page.lines) {
          console.log(`  - "${line.content}"`);
        }
      }
    }
  }

  if (!languages || languages.length <= 0) {
    console.log("No language spans were extracted from the document.");
  } else {
    console.log("Languages:");
    for (const languageEntry of languages) {
      console.log(
        `- Found language: ${languageEntry.locale} (confidence: ${languageEntry.confidence})`
      );

      for (const text of getTextOfSpans(content, languageEntry.spans)) {
        const escapedText = text.replace(/\r?\n/g, "\\n").replace(/"/g, '\\"');
        console.log(`  - "${escapedText}"`);
      }
    }
  }
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

تصنيف مستند

تدعم خدمة Document Intelligence مصنفات المستندات المخصصة التي يمكنها تصنيف المستندات إلى مجموعة من الفئات المعرفة مسبقا استنادا إلى مجموعة بيانات التدريب. يمكن تصنيف المستندات باستخدام مصنف مخصص باستخدام beginClassifyDocument أسلوب DocumentAnalysisClient. كما هو الحال beginAnalyzeDocument أعلاه، يقبل هذا الأسلوب ملفا أو دفقا يحتوي على المستند المراد تصنيفه، ولديه beginClassifyDocumentFromUrl نظير يقبل عنوان URL يمكن الوصول إليه بشكل عام إلى مستند بدلا من ذلك.

يوضح النموذج التالي كيفية تصنيف مستند باستخدام مصنف مخصص:

const { AzureKeyCredential, DocumentAnalysisClient } = require("@azure/ai-form-recognizer");

async function main() {
  const endpoint = "<endpoint>";
  const credential = new AzureKeyCredential("<api key>");

  const documentUrl =
    "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/main/sdk/formrecognizer/ai-form-recognizer/assets/invoice/Invoice_1.pdf";

  const client = new DocumentAnalysisClient(endpoint, credential);

  const poller = await client.beginClassifyDocumentFromUrl("<classifier id>", documentUrl);

  const result = await poller.pollUntilDone();

  if (result.documents === undefined || result.documents.length === 0) {
    throw new Error("Failed to extract any documents.");
  }

  for (const document of result.documents) {
    console.log(
      `Extracted a document with type '${document.docType}' on page ${document.boundingRegions?.[0].pageNumber} (confidence: ${document.confidence})`
    );
  }
}

main().catch((error) => {
  console.error("An error occurred:", error);
  process.exit(1);
});

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

إنشاء نموذج

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

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

على سبيل المثال، ينشئ البرنامج التالي نموذج مستند مخصص باستخدام عنوان URL مشفر بواسطة SAS إلى حاوية Azure Storage موجودة مسبقا:

const {
  DocumentModelAdministrationClient,
  AzureKeyCredential,
} = require("@azure/ai-form-recognizer");

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const containerSasUrl = "<SAS url to the blob container storing training documents>";

  const client = new DocumentModelAdministrationClient(endpoint, new AzureKeyCredential(apiKey));

  // You must provide the model ID. It can be any text that does not start with "prebuilt-".
  // For example, you could provide a randomly generated GUID using the "uuid" package.
  // The second parameter is the SAS-encoded URL to an Azure Storage container with the training documents.
  // The third parameter is the build mode: one of "template" (the only mode prior to 4.0.0-beta.3) or "neural".
  // See https://aka.ms/azsdk/formrecognizer/buildmode for more information about build modes.
  const poller = await client.beginBuildDocumentModel("<model ID>", containerSasUrl, "template", {
    // The model description is optional and can be any text.
    description: "This is my new model!",
    onProgress: ({ status }) => {
      console.log(`operation status: ${status}`);
    },
  });
  const model = await poller.pollUntilDone();

  console.log("Model ID:", model.modelId);
  console.log("Description:", model.description);
  console.log("Created:", model.createdOn);

  // A model may contain several document types, which describe the possible object structures of fields extracted using
  // this model

  console.log("Document Types:");
  for (const [docType, { description, fieldSchema: schema }] of Object.entries(
    model.docTypes ?? {}
  )) {
    console.log(`- Name: "${docType}"`);
    console.log(`  Description: "${description}"`);

    // For simplicity, this example will only show top-level field names
    console.log("  Fields:");

    for (const [fieldName, fieldSchema] of Object.entries(schema)) {
      console.log(`  - "${fieldName}" (${fieldSchema.type})`);
      console.log(`    ${fieldSchema.description ?? "<no description>"}`);
    }
  }
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

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

إدارة النماذج

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

const {
  DocumentModelAdministrationClient,
  AzureKeyCredential,
} = require("@azure/ai-form-recognizer");

async function main() {
  const endpoint = "<cognitive services endpoint>";
  const apiKey = "<api key>";
  const client = new DocumentModelAdministrationClient(endpoint, new AzureKeyCredential(apiKey));

  // Produces an async iterable that supports paging (`PagedAsyncIterableIterator`). The `listDocumentModels` method will only
  // iterate over model summaries, which do not include detailed schema information. Schema information is only returned
  // from `getDocumentModel` as part of the full model information.
  const models = client.listDocumentModels();
  let i = 1;
  for await (const summary of models) {
    console.log(`Model ${i++}:`, summary);
  }

  // The iterable is paged, and the application can control the flow of paging if needed
  i = 1;
  for await (const page of client.listDocumentModels().byPage()) {
    for (const summary of page) {
      console.log(`Model ${i++}`, summary);
    }
  }

  // We can also get a full ModelInfo by ID. Here we only show the basic information. See the documentation and the
  // `getDocumentModel` sample program for information about the `docTypes` field, which contains the model's document type
  // schemas.
  const model = await client.getDocumentModel("<model ID>");
  console.log("ID", model.modelId);
  console.log("Created:", model.createdOn);
  console.log("Description: ", model.description ?? "<none>");

  // A model can also be deleted by its model ID. Once it is deleted, it CANNOT be recovered.
  const modelIdToDelete = "<model ID that should be deleted forever>";
  await client.deleteDocumentModel(modelIdToDelete);
}

main().catch((err) => {
  console.error("The sample encountered an error:", err);
});

تتوفر أساليب listDocumentClassifiers مماثلة و getDocumentClassifier لإدراج والحصول على معلومات حول المصنفات المخصصة بالإضافة إلى deleteDocumentClassifier حذف المصنفات المخصصة.

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

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

قد يساعد تمكين التسجيل في الكشف عن معلومات مفيدة حول حالات الفشل. للاطلاع على سجل لطلبات HTTP واستجاباته، قم بتعيين AZURE_LOG_LEVELمتغير البيئة إلى info. بدلًا من ذلك، يمكن تمكين التسجيل في وقت التشغيل عن طريق الاتصال setLogLevelبـ @azure/logger:

const { setLogLevel } = require("@azure/logger");

setLogLevel("info");

للحصول على إرشادات أكثر تفصيلا حول كيفية تمكين السجلات، يمكنك إلقاء نظرة على مستندات حزمة @azure/المسجل.

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

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

المساهمة

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

مرات الظهور

Share via

مكتبة عميل Azure الذكاء الاصطناعي Document Intelligence ل JavaScript - الإصدار 5.0.0

ملاحظة

تثبيت `@azure/ai-form-recognizer`الحزمة

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

البيئات المعتمدة حاليًا

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

إنشاء مورد Form Recognizer

إنشاء عميل ومصادقته

استخدام مفتاح API

استخدام Azure Active Directory

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

`DocumentAnalysisClient`

`DocumentModelAdministrationClient`

عمليات طويلة الأمد

أمثلة

تحليل مستند باستخدام معرف نموذج

تحليل مستند من عنوان URL

استخدام نماذج المستندات التي تم إنشاؤها مسبقا

نماذج أخرى تم إنشاؤها مسبقا

استخدام "التخطيط" الذي تم إنشاؤه مسبقا

استخدام "المستند" الذي تم إنشاؤه مسبقا

استخدام "القراءة" التي تم إنشاؤها مسبقا

تصنيف مستند

إنشاء نموذج

إدارة النماذج

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

تسجيل الدخول

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

المساهمة

الملاحظات

الموارد الإضافية

Share via

مكتبة عميل Azure الذكاء الاصطناعي Document Intelligence ل JavaScript - الإصدار 5.0.0

ملاحظة

تثبيت @azure/ai-form-recognizerالحزمة

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

البيئات المعتمدة حاليًا

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

إنشاء مورد Form Recognizer

إنشاء عميل ومصادقته

استخدام مفتاح API

استخدام Azure Active Directory

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

DocumentAnalysisClient

DocumentModelAdministrationClient

عمليات طويلة الأمد

أمثلة

تحليل مستند باستخدام معرف نموذج

تحليل مستند من عنوان URL

استخدام نماذج المستندات التي تم إنشاؤها مسبقا

نماذج أخرى تم إنشاؤها مسبقا

استخدام "التخطيط" الذي تم إنشاؤه مسبقا

استخدام "المستند" الذي تم إنشاؤه مسبقا

استخدام "القراءة" التي تم إنشاؤها مسبقا

تصنيف مستند

إنشاء نموذج

إدارة النماذج

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

تسجيل الدخول

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

المساهمة

الملاحظات

الموارد الإضافية

تثبيت `@azure/ai-form-recognizer`الحزمة

`DocumentAnalysisClient`

`DocumentModelAdministrationClient`