你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

适用于 JavaScript 的 Azure AI 文档智能客户端库 - 版本 5.0.0

项目
08/16/2023

Azure AI 文档智能是一项云服务，它使用机器学习来分析文档中的文本和结构化数据。它包括以下main功能：

布局 - 从文档中提取文本、表结构和选择标记及其边界区域坐标。
文档 - 使用常规预生成文档模型分析文档中的实体、键值对、表和选择标记。
读取 - 除了文本语言信息外，还读取有关文本元素的信息，例如页面字词和行。
预生成 - 使用预生成模型) 分析某些类型的常见文档的数据， (如收据、发票、名片或标识文档。
自定义 - 生成自定义模型以从文档中提取文本、字段值、选择标记和表数据。自定义模型是使用你自己的数据构建的，因此它们是针对你的文档定制的。
分类器 - 生成自定义分类器，以将文档分类为预定义类。

注意

文档智能服务以前称为“Azure 表单识别器”。这些服务是同一个服务，适用于 JavaScript 的@azure/ai-form-recognizer包是 Azure AI 文档智能服务的 Azure SDK 包。在撰写本文时，Azure 表单识别器重命名为 Azure AI 文档智能正在进行中，因此在某些情况下，“表单识别器”和“文档智能”可以互换使用。

安装 `@azure/ai-form-recognizer` 包

使用安装适用于 JavaScript 的 npmAzure 文档智能客户端库：

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 订阅
认知服务或表单识别器资源。如果需要创建资源，可以使用 Azure 门户或 Azure CLI。

创建表单识别器资源

注意：在撰写本文时，Azure 门户仍将资源称为“表单识别器”资源。将来，可能会将其更新为“文档智能”资源。目前，以下文档使用“表单识别器”名称。

文档智能支持多服务和单服务访问。如果计划通过一个终结点/密钥访问多个认知服务，请创建认知服务资源。若要仅访问表单识别器，请创建表单识别器资源。

可以使用创建资源

选项 1：Azure 门户

选项 2：Azure CLI。

下面是如何使用 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-name> 替换为<your-resource-group-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 标识库通过 Azure Active Directory 对客户端进行身份验证。若要使用如下所示的 DefaultAzureCredential 提供程序或 Azure SDK 提供的其他凭据提供程序，请安装包 @azure/identity ：

npm install @azure/identity

若要使用服务主体进行身份验证，还需要注册 AAD 应用程序，并通过将角色分配给 "Cognitive Services User" 服务主体来授予对服务的访问权限 (注意：其他角色（如） "Owner" 不会授予必要的权限，仅 "Cognitive Services User" 足以运行示例和示例代码) 。

将 AAD 应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量：AZURE_CLIENT_ID、、AZURE_TENANT_IDAZURE_CLIENT_SECRET。

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

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

关键概念

`DocumentAnalysisClient`

DocumentAnalysisClient 提供使用自定义和预生成模型分析输入文档的操作。它有三种方法：

beginAnalyzeDocument，它使用模型 ID 提供的自定义或预生成模型从输入文档文件流中提取数据。有关所有资源中支持的预生成模型及其模型 ID/输出的信息，请参阅服务的模型文档。
beginAnalyzeDocumentFromUrl，它执行与相同的功能 beginAnalyzeDocument，但提交文件（而不是文件流）的可公开访问 URL。

`DocumentModelAdministrationClient`

DocumentModelAdministrationClient 提供用于管理 (在资源中创建、读取、列出和删除) 模型的操作：

beginBuildDocumentModel 启动操作以从你自己的训练数据集创建新的文档模型。创建的模型可以根据自定义架构提取字段。训练数据应位于 Azure 存储容器中，并根据特定约定进行组织。有关向训练数据集应用标签的更详细说明，请参阅有关创建训练数据集的服务文档。
beginComposeDocumentModel 启动操作，将多个模型组合到单个模型中。当用于自定义表单识别时，新的组合模型将首先对输入文档执行分类，以确定其哪个子模型最合适。
beginCopyModelTo 启动操作，将自定义模型从一个资源复制到另一个资源 (甚至复制到同一资源) 。它需要 CopyAuthorization 目标资源中的，可以使用方法生成 getCopyAuthorization 。
getResourceDetails 检索有关资源限制的信息，例如自定义模型的数量和资源可以支持的最大模型数。
getDocumentModel、 listDocumentModels和 deleteDocumentModel 启用资源中的模型管理。
getOperation 和 listOperations 允许查看模型创建操作的状态，甚至是正在进行的或失败的操作。操作将保留 24 小时。

请注意，也可以使用文档智能服务的图形用户界面（ Document Intelligence Studio）创建模型。

下面“生成模型”示例部分提供了演示如何使用 DocumentModelAdministrationClient生成模型的示例代码片段。

长期运行的操作

(RRO) 长时间运行的操作包括发送到服务以启动操作的初始请求，然后轮询特定时间间隔的结果，以确定操作是否已完成以及操作是失败还是成功。最终，LRO 将失败并出现错误或生成结果。

在 Azure AI 文档智能中，创建模型的操作 (包括复制和撰写模型) 以及分析/数据提取操作都是 RRO。 SDK 客户端提供返回Promise<PollerLike>对象的异步begin<operation-name>方法。对象PollerLike表示操作，该操作在服务的基础结构上异步运行，程序可以通过调用和等待从 begin<operation-name> 方法返回的轮询器上的方法来等待pollUntilDone操作完成。提供了示例代码片段，以在下一部分中演示如何使用长时间运行的操作。

示例

以下部分提供了几个 JavaScript 代码片段，说明了文档智能客户端库中使用的常见模式。

使用模型 ID 分析文档
使用预生成的文档模型
使用预生成的“布局”
使用预生成的“文档”
使用“读取”预生成
生成模型
管理模型

使用模型 ID 分析文档

方法 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 分析文档

作为提供可读流的替代方法，可以使用方法改为 beginAnalyzeDocumentFromUrl 提供可公开访问的 URL。 “可公开访问”意味着 URL 源必须可从服务的基础结构访问， (换句话说，专用 Intranet URL 或使用基于标头或证书的机密的 URL 将不起作用，因为文档智能服务必须能够访问 URL) 。但是，URL 本身可以编码机密，例如查询参数中包含 SAS 令牌的 Azure 存储 Blob URL。

使用预生成的文档模型

方法 beginAnalyzeDocument 还支持使用文档智能服务提供的预生成模型从某些类型的常见文档（如收据、发票、名片、身份证等）中提取字段。预生成模型可以作为模型 ID 字符串提供， (与自定义文档模型相同，请参阅下面的 其他预生成模型 部分) 或使用 DocumentModel 对象。使用时， DocumentModel适用于 JavaScript 的文档智能 SDK 根据模型的架构为生成的提取文档提供更强的 TypeScript 类型，并将其转换为使用 JavaScript 命名约定。

DocumentModel可以在示例目录中找到当前服务 API 版本 (2022-08-31) 的示例prebuilt对象。在以下示例中，我们将使用该 PrebuiltReceiptModel 目录中 [prebuilt-receipt.ts] 文件中的。

由于基于的分析main优势DocumentModel是更强大的 TypeScript 类型约束，以下示例是使用 ECMAScript 模块语法在 TypeScript 中编写的：

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

或者，如上所述，可以使用预生成收据的模型 ID (“prebuilt-receipt”) ，而不是使用 PrebuiltReceiptModel生成更强的返回类型的，但文档字段不会在 TypeScript 中强类型化，并且字段名称通常位于“PascalCase”而不是“camelCase”中。

其他预生成模型

不限于收据！有几个预生成模型可供选择，还有更多模型可供选择。每个预生成模型都有自己的一组受支持字段：

收据，使用 PrebuiltReceiptModel 上述 () 或预生成的收据模型 ID "prebuilt-receipt"。
名片，使用 PrebuiltBusinessCardModel 或其型号 ID "prebuilt-businessCard"。
发票，使用 PrebuiltInvoiceModel 或其模型 ID "prebuilt-invoice"。
使用或其型号 ID "prebuilt-idDocument"的标识文档 (，例如驾驶执照和护照) PrebuiltIdDocumentModel。
W2 Tax Forms (美国) ，使用 PrebuiltTaxUsW2Model 或其模型 ID "prebuilt-tax.us.w2"。
健康保险卡 (美国) ，使用 [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] 或其模型 ID "prebuilt-healthInsuranceCard.us"。

上述每个预生成模型都会生成 documents 模型字段架构) (提取的实例。还有三个预生成模型没有字段架构，因此不会生成 documents。它们分别是：

预生成的布局模型 (请参阅使用) 下面的 “布局”预生成 ，该模型提取有关基本布局 (OCR) 元素（如页面和表）的信息。
预生成的常规文档模型 (请参阅使用) 下面的 “文档”预生成 ，这将在页面元素之间添加键值对 (定向关联，如标记元素) 到布局模型生成的信息。
预生成的读取模型 (请参阅 使用下面的“读取”预生成) ，它仅提取文本元素，如页面字词和行，以及有关文档语言的信息。

有关所有这些模型的字段的信息，请参阅服务的可用预生成模型的文档。

还可以使用 getDocumentModel 方法以编程方式访问所有预生成模型的字段， (其模型 ID) DocumentModelAdministrationClient 并检查 docTypes 结果中的字段。

使用预生成的“布局”

该 "prebuilt-layout" 模型仅提取文档的基本元素（如页面）， (这些元素由文本单词/行和选择标记组成，) 、表格和可视文本样式以及输入文档的文本内容中的边界区域和范围。我们提供了一个名为 PrebuiltLayoutModel 的强类型DocumentModel实例，该实例调用此模型，也可以像往常一样直接使用其模型 ID"prebuilt-layout"。

由于基于的分析main优势DocumentModel是更强大的 TypeScript 类型约束，以下示例是使用 ECMAScript 模块语法在 TypeScript 中编写的：

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" 还提取有关键值对的信息， (页面元素之间的定向关联，例如标记字段) 。此预生成 (常规) 文档模型提供的功能与在以前的文档智能服务迭代中没有标签信息的情况下训练的自定义模型类似，但现在将其作为预生成模型提供，适用于各种文档。我们提供了一个名为 PrebuiltDocumentModel 的强类型DocumentModel实例，该实例调用此模型，也可以像往常一样直接使用其模型 ID"prebuilt-document"。

由于基于的分析main优势DocumentModel是更强大的 TypeScript 类型约束，以下示例是使用 ECMAScript 模块语法在 TypeScript 中编写的：

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" 模型提取文档中的文本信息（如单词和段落），并分析该文本的语言和写作风格 (例如手写与类型集) 。我们提供了一个名为 PrebuiltReadModel 的强类型DocumentModel实例，该实例调用此模型，也可以像往常一样直接使用其模型 ID"prebuilt-read"。

由于基于的分析main优势DocumentModel是更强大的 TypeScript 类型约束，以下示例是使用 ECMAScript 模块语法在 TypeScript 中编写的：

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

对文档进行分类

文档智能服务支持自定义文档分类器，这些分类器可以根据训练数据集将文档分类为一组预定义的类别。可以使用的方法DocumentAnalysisClient通过自定义分类器对文档进行beginClassifyDocument分类。如上所示 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 类创建模型。从标记的训练数据生成模型会创建一个新模型，该模型在你自己的文档上进行训练，生成的模型将能够从这些文档的结构中识别值。模型生成操作接受用于保存训练文档的 Azure 存储 Blob 容器的 SAS 编码 URL。文档智能服务的基础结构将读取容器中的文件，并根据文件的内容创建模型。有关如何创建和构造训练数据容器的更多详细信息，请参阅用于生成模型的文档智能服务文档。

虽然我们提供了这些方法用于以编程方式创建模型，但文档智能服务团队创建了交互式 Web 应用程序 Document Intelligence Studio，用于在 Web 上创建和管理模型。

例如，以下程序使用预先存在的 Azure 存储容器的 SAS 编码 URL 生成自定义文档模型：

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

自定义分类器使用方法（而不是 beginBuildDocumentModel）以类似的方式beginBuildDocumentClassifier生成。有关生成自定义分类器的详细信息，请参阅生成分类器示例，因为输入训练数据的格式略有不同。有关为自定义分类器生成训练数据集的信息，请参阅文档智能服务文档。

管理模型

DocumentModelAdministrationClient 还提供了几种用于访问和列出模型的方法。以下示例演示如何循环访问资源中的模型 (这将包括资源中的自定义模型，以及所有资源) 通用的预生成模型、按 ID 获取模型以及删除模型。

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。或者，可以在运行时通过调用 @azure/logger 中的 setLogLevel 来启用日志记录：

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

setLogLevel("info");

有关如何启用日志的更详细说明，请查看 @azure/logger 包文档。

后续步骤

请查看示例目录，获取演示如何使用此库的详细代码示例，包括上述“示例”部分中未显示的多种功能和方法，例如复制和撰写模型、列出模型管理操作以及删除模型。

贡献

若要为此库做出贡献，请阅读贡献指南，详细了解如何生成和测试代码。

曝光数

通过

适用于 JavaScript 的 Azure AI 文档智能客户端库 - 版本 5.0.0

注意

安装 @azure/ai-form-recognizer 包

入门

目前支持的环境

先决条件

创建表单识别器资源

创建客户端并对其进行身份验证

使用 API 密钥

使用 Azure Active Directory

关键概念

DocumentAnalysisClient

DocumentModelAdministrationClient

长期运行的操作

示例

使用模型 ID 分析文档

通过 URL 分析文档

使用预生成的文档模型

其他预生成模型

使用预生成的“布局”

使用预生成的“文档”

使用“读取”预生成

对文档进行分类

生成模型

管理模型

疑难解答

日志记录

后续步骤

贡献

其他资源

安装 `@azure/ai-form-recognizer` 包

`DocumentAnalysisClient`

`DocumentModelAdministrationClient`