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

Azure DocumentIntelligence (以前为 FormRecognizer) 适用于 JavaScript 的 REST 客户端库 - 版本 1.0.0-beta.2

项目
03/22/2024

从文档中提取内容、布局和结构化数据。

请严重依赖 REST 客户端文档来使用此库

注意：表单识别器已改名为“文档智能”。请将迁移指南从 @azure/ai-form-recognizer 检查到 @azure-rest/ai-document-intelligence。

关键链接：

此版本的客户端库默认为 "2024-02-29-preview" 服务版本。

此表显示了 SDK 版本与服务支持的 API 版本之间的关系：

SDK 版本	服务支持的 API 版本
1.0.0-beta.2	2024-02-29-preview
1.0.0-beta.1	2023-10-31-preview

请通过较旧的服务 API 版本依赖于已 @azure/ai-form-recognizer 停用模型（例如 "prebuilt-businessCard" 和 "prebuilt-document"）的较旧库。有关详细信息，请参阅更改日志。

下表描述了每个客户端及其支持的 API 版本 () 之间的关系：

服务 API 版本	支持的客户端	包
2024-02-29-preview	DocumentIntelligenceClient	`@azure-rest/ai-document-intelligence` 版本 `1.0.0-beta.2`
2023-10-31-preview	DocumentIntelligenceClient	`@azure-rest/ai-document-intelligence` 版本 `1.0.0-beta.1`
2023-07-31	DocumentAnalysisClient 和 DocumentModelAdministrationClient	`@azure/ai-form-recognizer` 版本 `^5.0.0`
2022 年 8 月 1 日	DocumentAnalysisClient 和 DocumentModelAdministrationClient	`@azure/ai-form-recognizer` 版本 `^4.0.0`

入门

目前支持的环境

LTS 版本的 Node.js

先决条件

必须具有 Azure 订阅才能使用此包。

安装 `@azure-rest/ai-document-intelligence` 包

使用安装 Azure DocumentIntelligence (以前的FormRecognizer) 适用于 JavaScript npm的 REST 客户端库：

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

创建 `DocumentIntelligenceClient` 并对其进行身份验证

若要使用 Azure Active Directory (AAD) 令牌凭据，请提供从 @azure/标识库获取的所需凭据类型的实例。

若要使用 AAD 进行身份验证，必须先 npm 安装 @azure/identity

安装后，可以选择要使用的@azure/identity凭据类型。例如， DefaultAzureCredential 可用于对客户端进行身份验证。

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

使用令牌凭据

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

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

使用 API 密钥

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

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

文档模型

分析预生成布局 (urlSource)

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

分析预生成布局 (base64Source)

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

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

继续从初始响应创建轮询程序

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

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

Markdown 内容格式

支持使用 Markdown 内容格式以及默认纯文本的输出。目前，仅“预生成布局”支持此操作。 Markdown 内容格式在聊天或自动化使用方案中被视为一种更友好的 LLM 使用格式。

服务遵循 Markdown 格式的 GFM 规范 (GitHub 风格的 Markdown) 。还引入了值“text”或“markdown”的新 contentFormat 属性，以指示结果内容格式。

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

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

查询字段

指定此功能标志后，服务将进一步提取通过 queryFields 查询参数指定的字段的值，以补充模型定义为回退的任何现有字段。

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

拆分选项

在旧 @azure/ai-form-recognizer 版库支持的早期 API 版本中，文档拆分和分类操作 ("/documentClassifiers/{classifierId}:analyze") 始终尝试将输入文件拆分为多个文档。

为了启用更广泛的方案集，服务引入了新的“2023-10-31-preview”服务版本的“拆分”查询参数。支持以下值：

split: "auto"

让服务确定拆分的位置。
split: "none"

整个文件被视为单个文档。不执行拆分。
split: "perPage"

每页被视为一个单独的文档。每个空页都保留为自己的文档。

文档分类器 #Build

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

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

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

获取信息

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

列出文档模型

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

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

疑难解答

日志记录

启用日志记录可能有助于发现有关故障的有用信息。若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。或者，可以在运行时通过调用 @azure/logger 中的 setLogLevel 来启用日志记录：

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

setLogLevel("info");

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

通过