Клиентская библиотека Azure AI Document Intelligence для JavaScript — версия 5.1.0

Azure AI Document Intelligence — это облачная служба, которая использует машинное обучение для анализа текста и структурированных данных из документов. Он включает следующие основные функции:

• Макет — извлечение текста, структур таблиц и меток выбора, а также координат их ограничивающей области из документов.
• Документ — анализ сущностей, пар «ключ-значение», таблиц и меток выбора из документов с помощью общей предварительно созданной модели документа.
• Чтение — чтение информации о текстовых элементах, таких как слова страниц и строки, в дополнение к информации о языке текста.
• Предварительно созданные — анализируйте данные из определенных типов общих документов (таких как квитанции, счета, визитные карточки или документы, удостоверяющие личность) с помощью готовых моделей.
• Пользовательские — создание пользовательских моделей для извлечения текста, значений полей, меток выбора и табличных данных из документов. Пользовательские модели создаются на основе ваших собственных данных, поэтому они адаптированы к вашим документам.
• Классификаторы — создание пользовательских классификаторов для категоризации документов по предопределенным классам.

справочная документация по API исходного кода | пакета (NPM) | | документации по продуктам | примеры

Замечание

Служба Document Intelligence ранее была известна как "Azure Form Recognizer". Это одно и то же, и @azure/ai-form-recognizer пакет для JavaScript — это пакет Azure SDK для службы Azure AI Document Intelligence. На момент написания этой статьи Распознаватель документов Azure был переименован в Azure AI Document Intelligence, поэтому в некоторых случаях термины "Распознаватель документов" и "Аналитика документов" могут использоваться как взаимозаменяемые.

Установите пакет @azure/ai-form-recognizer.

Установите клиентскую библиотеку Azure Document Intelligence для JavaScript с помощью npm:

npm install @azure/ai-form-recognizer

Начало работы

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node: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 = createReadStream("path/to/file.jpg");
const poller = await client.beginAnalyzeDocument("<model ID>", file);

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

Поддерживаемые в настоящее время среды

• Версии Node.js LTS
• Последние версии Safari, Chrome, Edge и Firefox.

Чтобы получить дополнительные сведения, ознакомьтесь с нашей политикой поддержки.

Предпосылки

• Подписка Azure
• Ресурс Cognitive Services или Распознавателя документов. Если необходимо создать ресурс, можно использовать портал Azure или Azure CLI.

Создание ресурса Распознавателя форм

Примечание: На момент написания статьи портал Azure по-прежнему ссылается на ресурс как на ресурс "Распознавателя документов". В будущем он может быть обновлен до ресурса "Document Intelligence". На данный момент в следующей документации используется имя "Распознаватель документов".

Document Intelligence поддерживает как мультисервисный, так и односервисный доступ. Создайте ресурс Cognitive Services, если вы планируете получить доступ к нескольким службам Cognitive Services с помощью одной конечной точки или ключа. Для доступа только к Распознавателю документов создайте ресурс Распознавателя документов.

Создать ресурс можно с помощью

Вариант 1:Портал Azure

Вариант 2:Azure 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, вам нужно выбрать либо a DocumentAnalysisClient , DocumentModelAdministrationClientлибо , и создать экземпляр этого типа. В следующих примерах мы будем использовать DocumentAnalysisClient. Чтобы создать клиентский экземпляр для доступа к API Document Intelligence, вам потребуется endpoint ресурс Распознавателя документов и credential. Клиенты могут использовать либо AzureKeyCredential ключ API вашего ресурса, либо сервер, TokenCredential использующий Azure Active Directory RBAC для авторизации клиента.

Конечную точку для ресурса Распознавателя документов можно найти на портале Azure или с помощью приведенного ниже фрагмента кода Azure CLI :

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

Используйте ключ API

Используйте портал Azure для перехода к ресурсу Распознавателя документов и получения ключа API или используйте приведенный ниже фрагмент кода Azure CLI:

Примечание. Иногда ключ API называется ключом подписки или ключом API подписки.

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

После того, как у вас есть ключ API и конечная точка, вы можете использовать их следующим образом:

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

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

Использование Azure Active Directory

В большинстве примеров используется авторизация по ключу API, но вы также можете проверить подлинность клиента с помощью Azure Active Directory с помощью библиотеки Azure Identity. Чтобы использовать показанный ниже поставщик 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.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";

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

Национальные облака

Подключитесь к альтернативным облачным средам Azure (например, Azure для Китая или Azure для государственных организаций), указав соответствующий audience параметр при создании клиента. Используйте перечисление, KnownFormRecognizerAudience чтобы выбрать правильное значение для вашей среды.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient, KnownFormRecognizerAudience } from "@azure/ai-form-recognizer";

const credential = new DefaultAzureCredential();
const client = new DocumentAnalysisClient(
  "https://<resource name>.cognitiveservices.azure.com", // endpoint
  credential,
  {
    audience: KnownFormRecognizerAudience.AzureGovernment,
  }
);

Если вы не укажете этот параметр, audience то по умолчанию он подходит для Публичного облака Azure (https://cognitiveservices.azure.com).

Основные понятия

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 сборки модели, можно найти ниже, в разделе «Пример сборки модели».

Длительные операции

Длительные операции (LRO) — это операции, которые состоят из первоначального запроса, отправляемого в службу для запуска операции, за которым следует опрос результата через определенный интервал, чтобы определить, завершена ли операция и завершилась ли она неудачей или успешной. В конечном счете, LRO либо завершится ошибкой из-за ошибки, либо приведет к результату.

В Azure AI Document Intelligence операции по созданию моделей (включая копирование и составление моделей), а также операции анализа и извлечения данных являются LRO. Клиенты SDK предоставляют асинхронные begin<operation-name> методы, возвращающие Promise<PollerLike> объекты. Объект PollerLike представляет собой операцию, которая выполняется асинхронно в инфраструктуре службы, и программа может ожидать завершения операции, вызывая и ожидая pollUntilDone метода на поллере, возвращенном из метода begin<operation-name> . Примеры фрагментов кода приведены для иллюстрации использования длительных операций в следующем разделе.

Примеры

В следующем разделе представлено несколько фрагментов кода JavaScript, иллюстрирующих распространенные шаблоны, используемые в клиентских библиотеках Document Intelligence.

• Анализ документа с идентификатором модели
• Использование готовых моделей документов
• Используйте предварительно собранный «макет»
• Используйте предварительно созданный «документ»
• Используйте предварительно созданную команду "read"
• Построение модели
• Управление моделями

Анализ документа с идентификатором модели

Метод beginAnalyzeDocument может извлекать поля и табличные данные из документов. Для анализа может использоваться либо пользовательская модель, обученная на ваших собственных данных, либо предварительно созданная модель, предоставленная сервисом (см. раздел Использование предварительно созданных моделей ниже). Пользовательская модель адаптирована к вашим собственным документам, поэтому ее следует использовать только с документами той же структуры, что и один из типов документов в модели (их может быть несколько, например, в составной модели).

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";

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

const modelId = "<model id>";
const path = "<path to a document>";
const readStream = createReadStream(path);

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 content '${field.content}' 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}"`);
  }
}

Анализ документа по URL-адресу

В качестве альтернативы предоставлению удобочитаемого потока вместо этого метода можно предоставить beginAnalyzeDocumentFromUrl общедоступный URL-адрес. «Общедоступный» означает, что источники URL-адресов должны быть доступны из инфраструктуры службы (другими словами, частный URL-адрес интрасети или URL-адреса, использующие секреты на основе заголовков или сертификатов, не будут работать, поскольку служба Document Intelligence должна иметь доступ к URL-адресу). Однако сам URL-адрес может закодировать секрет, например URL-адрес BLOB-объекта службы хранилища Azure, который содержит маркер SAS в параметрах запроса.

Использование готовых моделей документов

Метод beginAnalyzeDocument также поддерживает извлечение полей из определенных типов общих документов, таких как квитанции, счета-фактуры, визитные карточки, документы, удостоверяющие личность, и т. д., с помощью предварительно созданных моделей, предоставляемых службой Document Intelligence. Предварительно созданные модели могут быть предоставлены либо в виде строк идентификаторов моделей (так же, как и пользовательские модели документов — см. раздел о других предварительно созданных моделях ниже), так и с помощью DocumentModel объекта. При использовании DocumentModel, Document Intelligence SDK для JavaScript предоставляет гораздо более строгий тип TypeScript для результирующих извлеченных документов на основе схемы модели, и он будет преобразован для использования соглашений об именовании JavaScript.

Примеры DocumentModel объектов для текущей версии API службы (2022-08-31) можно найти в каталоге samplesprebuilt. В следующем примере мы будем использовать PrebuiltReceiptModel файл from the [prebuilt-receipt.ts] в этом каталоге.

Поскольку основным преимуществом DocumentModelанализа на основе -based является более строгое ограничение типов TypeScript, следующий пример написан на TypeScript с использованием синтаксиса модуля ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltReceiptModel } from "../samples-dev/prebuilt/prebuilt-receipt.js";

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

const path = "<path to a document>";
const readStream = createReadStream(path);

// 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);

В качестве альтернативы, как упоминалось выше, вместо использования PrebuiltReceiptModel, который создает более строгий тип возврата, можно использовать идентификатор модели предварительно созданного чека ("prebuilt-receipt"), но поля документа не будут строго типизированы в TypeScript, а имена полей обычно будут в "PascalCase", а не в "camelCase".

Другие готовые модели

Вы не ограничены в квитанциях! Есть несколько готовых моделей на выбор, и еще больше на подходе. Каждая предварительно созданная модель имеет свой набор поддерживаемых полей:

• Квитанции, используя PrebuiltReceiptModel (как указано выше) или предварительно созданный идентификатор "prebuilt-receipt"модели чека.
• Визитные карточки, с помощью PrebuiltBusinessCardModel или их ID "prebuilt-businessCard"модели.
• Счета-фактуры, используя PrebuiltInvoiceModel или идентификатор "prebuilt-invoice"модели.
• Документы, удостоверяющие личность (такие как водительские права и паспорта), использование PrebuiltIdDocumentModel или идентификатор "prebuilt-idDocument"модели.
• W2 Tax Forms (Соединенные Штаты), с использованием 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" модели может использоваться напрямую.

Поскольку основным преимуществом DocumentModelанализа на основе -based является более строгое ограничение типов TypeScript, следующий пример написан на TypeScript с использованием синтаксиса модуля ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltLayoutModel } from "../samples-dev/prebuilt/prebuilt-layout.js";

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

const path = "<path to a document>";
const readStream = createReadStream(path);

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}"`);
  }
}

Используйте предварительно созданный «документ»

Модель "prebuilt-document" извлекает сведения о парах "ключ-значение" (направленных связях между элементами страницы, такими как помеченные поля) в дополнение к свойствам, созданным методом извлечения макета. Эта предварительно созданная (общая) модель документа предоставляет функциональные возможности, аналогичные пользовательским моделям, обученным без сведений о метках в предыдущих итерациях службы Document Intelligence, но теперь она предоставляется в виде предварительно созданной модели, которая работает с широким спектром документов. Мы предоставляем строго типизированный DocumentModel экземпляр с именем PrebuiltDocumentModel , который вызывает эту модель, или, как всегда, идентификатор "prebuilt-document" модели может использоваться напрямую.

Поскольку основным преимуществом DocumentModelанализа на основе -based является более строгое ограничение типов TypeScript, следующий пример написан на TypeScript с использованием синтаксиса модуля ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltDocumentModel } from "../samples-dev/prebuilt/prebuilt-document.js";

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

const path = "<path to a document>";
const readStream = createReadStream(path);

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})`);
  }
}

Используйте предварительно созданную команду "read"

Модель "prebuilt-read" извлекает текстовую информацию из документа, такую как слова и абзацы, и анализирует язык и стиль письма (например, рукописный или печатный) этого текста. Мы предоставляем строго типизированный DocumentModel экземпляр с именем PrebuiltReadModel , который вызывает эту модель, или, как всегда, идентификатор "prebuilt-read" модели может использоваться напрямую.

Поскольку основным преимуществом DocumentModelанализа на основе -based является более строгое ограничение типов TypeScript, следующий пример написан на TypeScript с использованием синтаксиса модуля ECMAScript:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";
import { createReadStream } from "node:fs";
import { PrebuiltReadModel } from "../samples-dev/prebuilt/prebuilt-read.js";

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

const path = "<path to a document>";
const readStream = createReadStream(path);

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}"`);
    }
  }
}

function* getTextOfSpans(content, spans) {
  for (const span of spans) {
    yield content.slice(span.offset, span.offset + span.length);
  }
}

Классификация документа

Служба Document Intelligence поддерживает пользовательские классификаторы документов, которые могут классифицировать документы по набору предопределенных категорий на основе набора обучающих данных. Документы могут быть классифицированы с помощью пользовательского классификатора beginClassifyDocument с помощью метода DocumentAnalysisClient. Как и выше beginAnalyzeDocument , этот метод принимает файл или поток, содержащий классифицируемый документ, и у него есть аналог, beginClassifyDocumentFromUrl который принимает общедоступный URL-адрес документа.

В следующем примере показано, как классифицировать документ с помощью пользовательского классификатора:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentAnalysisClient } from "@azure/ai-form-recognizer";

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

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

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

const result = await poller.pollUntilDone();

if (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})`,
  );
}

Сведения о подготовке пользовательского классификатора см. в разделе о обучении классификатора в конце следующего раздела.

Создание модели

SDK также поддерживает создание моделей с помощью DocumentModelAdministrationClient класса. При построении модели на основе помеченных обучающих данных создается новая модель, которая обучается на собственных документах, и результирующая модель сможет распознавать значения из структур этих документов. Операция сборки модели принимает URL-адрес в кодировке SAS для контейнера BLOB-объектов службы хранилища Azure, в котором хранятся обучающие документы. Инфраструктура сервиса Document Intelligence прочитает файлы в контейнере и создаст модель на основе их содержимого. Подробнее о том, как создать и структурировать контейнер обучающих данных, см. в документации службы Document Intelligence по построению модели.

Хотя мы предоставляем эти методы для создания программных моделей, команда службы Document Intelligence создала интерактивное веб-приложение Document Intelligence Studio, которое позволяет создавать модели и управлять ими в Интернете.

Например, следующая программа создает пользовательскую модель документа с использованием URL-адреса в кодировке SAS для уже существующего контейнера службы хранилища Azure:

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";

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

const containerSasUrl = "<SAS url to the blob container storing training documents>";

// 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>"}`);
  }
}

Пользовательские классификаторы строятся аналогичным образом с использованием метода, beginBuildDocumentClassifier а не beginBuildDocumentModel. Дополнительные сведения о создании пользовательского классификатора см. в примере сборки , так как входные обучающие данные предоставляются в несколько ином формате. Сведения о создании обучающего набора данных для пользовательского классификатора см. в документации по службе Document Intelligence.

Manage models in the repository (Управление моделями в репозитории)

DocumentModelAdministrationClient Также предоставляет несколько методов для доступа к моделям и их перечисления. В следующем примере показано, как выполнить итерацию по моделям в ресурсе (сюда входят как пользовательские модели в ресурсе, так и предварительно созданные модели, общие для всех ресурсов), получить модель по идентификатору и удалить модель.

import { DefaultAzureCredential } from "@azure/identity";
import { DocumentModelAdministrationClient } from "@azure/ai-form-recognizer";

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

// 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);

Аналогичные методы listDocumentClassifiers доступны и getDocumentClassifier для перечисления и получения информации о пользовательских классификаторах, а также deleteDocumentClassifier для удаления пользовательских классификаторов.

Устранение неполадок

Сведения об устранении неполадок см. в руководстве по устранению неполадок .

Лесозаготовка

Включение ведения журнала может помочь выявить полезные сведения о сбоях. Чтобы просмотреть журнал HTTP-запросов и ответов, задайте для переменной среды AZURE_LOG_LEVEL значение info. В альтернативном порядке, логирование можно включить во время выполнения, вызвав setLogLevel в @azure/logger:

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

Дополнительные инструкции по включению журналов см. в документации по пакету @azure/loger.

Дальнейшие шаги

Пожалуйста, взгляните на каталог примеров для получения подробных примеров кода, которые показывают, как использовать эту библиотеку, включая несколько функций и методов, которые не показаны в разделе "Примеры" выше, такие как копирование и составление моделей, перечисление операций управления моделями и удаление моделей.

Вклад

Если вы хотите внести свой вклад в эту библиотеку, ознакомьтесь с руководством по вкладу, чтобы узнать больше о том, как создавать и тестировать код.