مكتبة عميل REST ل Azure DocumentIntelligence (المعروف سابقا ب FormRecognizer) ل JavaScript - الإصدار 1.0.0-beta.2

استخراج المحتوى والتخطيط والبيانات المنظمة من المستندات.

يرجى الاعتماد بشكل كبير على مستندات عميل REST لاستخدام هذه المكتبة

ملاحظة: تمت إعادة تسمية Form Recognizer إلى Document Intelligence. يرجى التحقق من دليل الترحيل من @azure/ai-form-recognizer إلى @azure-rest/ai-document-intelligence.

الروابط الرئيسية:

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

يتم تعيين هذا الإصدار من مكتبة العميل افتراضيا على "2024-02-29-preview" إصدار الخدمة.

يوضح هذا الجدول العلاقة بين إصدارات SDK وإصدارات واجهة برمجة التطبيقات المدعومة للخدمة:

إصدار SDK	إصدار خدمة واجهة برمجة التطبيقات المدعومة
1.0.0-beta.2	معاينة 2024-02-29
1.0.0-beta.1	معاينة 2023-10-31

يرجى الاعتماد على المكتبة القديمة @azure/ai-form-recognizer من خلال إصدارات واجهة برمجة تطبيقات الخدمة الأقدم للنماذج المتوقفة، مثل "prebuilt-businessCard" و "prebuilt-document". لمزيد من المعلومات، راجع Changelog.

يصف الجدول أدناه علاقة كل عميل وإصدار (إصدارات) واجهة برمجة التطبيقات المدعومة الخاصة به:

إصدار واجهة برمجة تطبيقات الخدمة	العملاء المدعومون	الحزمة
معاينة 2024-02-29	DocumentIntelligenceClient	@azure-rest/ai-document-intelligence الإصدار 1.0.0-beta.2
معاينة 2023-10-31	DocumentIntelligenceClient	@azure-rest/ai-document-intelligence الإصدار 1.0.0-beta.1
2023-07-31	DocumentAnalysisClient و DocumentModelAdministrationClient	@azure/ai-form-recognizer الإصدار ^5.0.0
2022-08-01	DocumentAnalysisClient و DocumentModelAdministrationClient	@azure/ai-form-recognizer الإصدار ^4.0.0

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

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

• إصدارات "LTS" من "Node.js".

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

• يجب أن يكون لديك اشتراك Azure لاستخدام هذه الحزمة.

تثبيت @azure-rest/ai-document-intelligenceالحزمة

قم بتثبيت مكتبة عميل REST لعميل Azure DocumentIntelligence (المعروف سابقا بFormRecognizer) ل JavaScript باستخدام npm:

npm install @azure-rest/ai-document-intelligence

إنشاء ومصادقة DocumentIntelligenceClient

لاستخدام بيانات اعتماد الرمز المميز ل Azure Active Directory (AAD)، قم بتوفير مثيل لنوع بيانات الاعتماد المطلوب الذي تم الحصول عليه من مكتبة @azure/الهوية .

للمصادقة باستخدام AAD، يجب عليك أولا npm تثبيت @azure/identity

بعد الإعداد، يمكنك اختيار نوع بيانات الاعتماد التي @azure/identity تريد استخدامها. على سبيل المثال، يمكن استخدام DefaultAzureCredential لمصادقة العميل.

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

استخدام بيانات اعتماد الرمز المميز

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";

const client = DocumentIntelligence(
  process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"],
  new DefaultAzureCredential()
);

استخدام مفتاح واجهة برمجة التطبيقات

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";

const client = DocumentIntelligence(process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"], {
  key: process.env["DOCUMENT_INTELLIGENCE_API_KEY"],
});

نماذج المستندات

تحليل التخطيط الذي تم إنشاؤه مسبقا (urlSource)

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      urlSource:
        "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
    },
    queryParameters: { locale: "en-IN" },
  });

تحليل التخطيط الذي تم إنشاؤه مسبقا (base64Source)

import fs from "fs";
import path from "path";

const filePath = path.join(ASSET_PATH, "forms", "Invoice_1.pdf");
const base64Source = fs.readFileSync(filePath, { encoding: "base64" });
const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      base64Source,
    },
    queryParameters: { locale: "en-IN" },
  });

متابعة إنشاء الاستقصاء من الاستجابة الأولية

import {
  getLongRunningPoller,
  AnalyzeResultOperationOutput,
  isUnexpected,
} from "@azure-rest/ai-document-intelligence";

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const poller = await getLongRunningPoller(client, initialResponse);
const result = (await poller.pollUntilDone()).body as AnalyzeResultOperationOutput;
console.log(result);
// {
//   status: 'succeeded',
//   createdDateTime: '2023-11-10T13:31:31Z',
//   lastUpdatedDateTime: '2023-11-10T13:31:34Z',
//   analyzeResult: {
//     apiVersion: '2023-10-31-preview',
//     .
//     .
//     .
//     contentFormat: 'text'
//   }
// }

تنسيق محتوى Markdown

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

تتبع الخدمة مواصفات GFM (GitHub Flavored Markdown) لتنسيق Markdown. يقدم أيضا خاصية contentFormat جديدة بقيمة "نص" أو "markdown" للإشارة إلى تنسيق محتوى النتيجة.

import DocumentIntelligence from "@azure-rest/ai-document-intelligence";
const client = DocumentIntelligence(process.env["DOCUMENT_INTELLIGENCE_ENDPOINT"], {
  key: process.env["DOCUMENT_INTELLIGENCE_API_KEY"],
});

const initialResponse = await client
  .path("/documentModels/{modelId}:analyze", "prebuilt-layout")
  .post({
    contentType: "application/json",
    body: {
      urlSource:
        "https://raw.githubusercontent.com/Azure/azure-sdk-for-js/6704eff082aaaf2d97c1371a28461f512f8d748a/sdk/formrecognizer/ai-form-recognizer/assets/forms/Invoice_1.pdf",
    },
    queryParameters: { outputContentFormat: "markdown" }, // <-- new query parameter
  });

حقول الاستعلام

عند تحديد علامة الميزة هذه، ستقوم الخدمة باستخراج قيم الحقول المحددة عبر معلمة استعلام queryFields لتكملة أي حقول موجودة يحددها النموذج على أنها احتياطية.

await client.path("/documentModels/{modelId}:analyze", "prebuilt-layout").post({
  contentType: "application/json",
  body: { urlSource: "..." },
  queryParameters: {
    features: ["queryFields"],
    queryFields: ["NumberOfGuests", "StoreNumber"],
  }, // <-- new query parameter
});

خيارات التقسيم

في إصدارات واجهة برمجة التطبيقات السابقة التي تدعمها المكتبة القديمة @azure/ai-form-recognizer ، حاولت عملية تقسيم المستندات وتصنيفها ("/documentClassifiers/{classifierId}:analyze") دائما تقسيم ملف الإدخال إلى مستندات متعددة.

لتمكين مجموعة أوسع من السيناريوهات، تقدم الخدمة معلمة استعلام "مقسمة" مع إصدار الخدمة الجديد "2023-10-31-preview". تُعتبر القيم التالية مدعومة:

• split: "auto"

  اسمح للخدمة بتحديد مكان التقسيم.

• split: "none"

  يتم التعامل مع الملف بأكمله كمستند واحد. لم يتم إجراء أي تقسيم.

• split: "perPage"

  يتم التعامل مع كل صفحة كمستند منفصل. يتم الاحتفاظ بكل صفحة فارغة كمستند خاص بها.

مصنفات المستندات #Build

import {
  DocumentClassifierBuildOperationDetailsOutput,
  getLongRunningPoller,
  isUnexpected,
} from "@azure-rest/ai-document-intelligence";

const containerSasUrl = (): string =>
  process.env["DOCUMENT_INTELLIGENCE_TRAINING_CONTAINER_SAS_URL"];
const initialResponse = await client.path("/documentClassifiers:build").post({
  body: {
    classifierId: `customClassifier${getRandomNumber()}`,
    description: "Custom classifier description",
    docTypes: {
      foo: {
        azureBlobSource: {
          containerUrl: containerSasUrl(),
        },
      },
      bar: {
        azureBlobSource: {
          containerUrl: containerSasUrl(),
        },
      },
    },
  },
});

if (isUnexpected(initialResponse)) {
  throw initialResponse.body.error;
}
const poller = await getLongRunningPoller(client, initialResponse);
const response = (await poller.pollUntilDone())
  .body as DocumentClassifierBuildOperationDetailsOutput;
console.log(response);
//  {
//    operationId: '31466834048_f3ee629e-73fb-48ab-993b-1d55d73ca460',
//    kind: 'documentClassifierBuild',
//    status: 'succeeded',
//    .
//    .
//    result: {
//      classifierId: 'customClassifier10978',
//      createdDateTime: '2023-11-09T12:45:56Z',
//      .
//      .
//      description: 'Custom classifier description'
//    },
//    apiVersion: '2023-10-31-preview'
//  }

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

const response = await client.path("/info").get();
if (isUnexpected(response)) {
  throw response.body.error;
}
console.log(response.body.customDocumentModels.limit);
// 20000

سرد نماذج المستندات

import { paginate } from "@azure-rest/ai-document-intelligence";
const response = await client.path("/documentModels").get();
if (isUnexpected(response)) {
  throw response.body.error;
}

const modelsInAccount: string[] = [];
for await (const model of paginate(client, response)) {
  console.log(model.modelId);
}

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

تسجيل الدخول

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

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

setLogLevel("info");

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