Share via

Клиентская библиотека Аналитики документов Azure ИИ для JavaScript версии 5.0.0

  • Статья

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

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

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

Примечание

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

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

Установите клиентскую библиотеку Аналитики документов Azure для 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();

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

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

Предварительные требования

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

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

Аналитика документов поддерживает доступ как с несколькими службами, так и с одной службой. Создайте ресурс 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>

Создание и проверка подлинности клиента

Чтобы взаимодействовать со службой аналитики документов, необходимо выбрать DocumentAnalysisClient или DocumentModelAdministrationClient, а затем создать экземпляр этого типа. В следующих примерах мы будем использовать DocumentAnalysisClient. Чтобы создать экземпляр клиента для доступа к API аналитики документов, вам потребуется 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 и конечную точку, их можно использовать следующим образом:

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

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

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

Авторизация ключа API используется в большинстве примеров, но вы также можете проверить подлинность клиента в 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 Studio.

Примеры фрагментов кода, иллюстрирующие использование DocumentModelAdministrationClient для создания модели, можно найти ниже в разделе примеров "Создание модели".

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

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

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

Примеры

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

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

Метод 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-адрес BLOB-объекта службы хранилища Azure, который содержит маркер SAS в параметрах запроса.

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

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

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

Так как преимущество DocumentModelmain анализа на основе является более строгим ограничением типов 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. К ним относятся:

Сведения о полях всех этих моделей см. в документации службы по доступным предварительно созданным моделям.

Доступ к полям всех предварительно созданных моделей также можно получить программным способом с помощью getDocumentModel метода (по идентификаторам моделей) и DocumentModelAdministrationClient проверки docTypes поля в результате.

Использование предварительно созданного макета

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

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

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" модели можно использовать напрямую.

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

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

Использование предварительно созданного "read"

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

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

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

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

Служба аналитики документов поддерживает пользовательские классификаторы документов, которые могут классифицировать документы в набор предопределенных категорий на основе обучающего набора данных. Документы можно классифицировать с помощью пользовательского классификатора с 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, в котором хранятся обучающие документы. Инфраструктура службы аналитики документов считывает файлы в контейнере и создает модель на основе их содержимого. Дополнительные сведения о создании и структуре контейнера обучающих данных см. в документации по созданию модели в службе аналитики документов.

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

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

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 и средства ведения журнала.

Дальнейшие действия

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

Участие

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

Просмотры