適用於 JavaScript 的 Azure AI Document Intelligence 用戶端連結庫 - 5.0.0 版

發行項
07/04/2024

Azure AI Document Intelligence 是一種雲端服務，會使用機器學習來分析檔中的文字和結構化數據。它包含下列主要功能：

版面配置 - 從檔擷取文字、表格結構和選取標記及其周框區域座標。
檔 - 使用一般預先建置的檔模型，分析來自文件的實體、索引鍵/值組、數據表和選取標記。
閱讀 - 除了文字語言資訊之外，請閱讀文字元素的相關信息，例如頁面文字和行。
預先建置 - 使用預先建置的模型，分析特定類型通用文件的數據（例如收據、發票、名片或身分識別檔）。
自訂 - 建置自定義模型，以從檔擷取文字、域值、選取標記和數據表數據。自定義模型是使用您自己的數據所建置，因此會針對您的檔量身打造。
分類器 - 建置自定義分類器，將檔分類為預先定義的類別。

注意

檔智慧服務先前稱為「Azure 窗體辨識器」。這些服務相同，而適用於 JavaScript 的 @azure/ai-form-recognizer 套件是適用於 Azure AI Document Intelligence 服務的 Azure SDK 套件。在撰寫本文時，Azure 窗體辨識器重新命名至 Azure AI 檔智慧正在進行中，因此在某些情況下，「表單辨識器」和「檔智慧」可能會交替使用。

安裝 `@azure/ai-form-recognizer` 套件

使用 npm安裝適用於 JavaScript 的 Azure Document Intelligence 用戶端連結庫：

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-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 服務互動，您必須選取 DocumentAnalysisClient 或 DocumentModelAdministrationClient，並建立此類型的實例。在下列範例中，我們將使用 DocumentAnalysisClient。若要建立用戶端實例來存取檔智慧 API，您需要窗體辨識器資源的 endpoint 和 credential。用戶端可以使用 AzureKeyCredential 搭配資源的 API 金鑰，或使用 Azure Active Directory RBAC 來授權用戶端的 TokenCredential。

您可以在 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 驗證用戶端。若要使用 azure SDK 所顯示 DefaultAzureCredential 提供者或其他認證提供者，請安裝 @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 服務的圖形使用者介面來建立模型：Document Intelligence Studio。

在「建置模型」範例區段中，您可以在下方的一節中找到說明如何使用 DocumentModelAdministrationClient 建置模型的程序代碼段。。

長時間執行的作業

長時間執行的作業（LRO）是作業，其中包含傳送至服務以啟動作業的初始要求，然後輪詢結果在特定間隔，以判斷作業是否已完成，以及作業是否失敗或成功。最後，LRO 會失敗併產生錯誤或產生結果。

在 Azure AI 檔智慧中，建立模型（包括複製和撰寫模型）以及分析/數據擷取作業的作業都是 RLO。 SDK 用戶端會提供傳回 Promise<PollerLike> 物件的異步 begin<operation-name> 方法。 PollerLike 物件代表以異步方式在服務基礎結構上執行的作業，而程式可以藉由在從 begin<operation-name> 方法傳迴的輪詢器上呼叫和等候 pollUntilDone 方法，等待作業完成。提供範例代碼段來說明在下一節中使用長時間執行的作業。

例子

下一節提供數個 JavaScript 代碼段，說明 Document Intelligence 用戶端連結庫中所使用的常見模式。

使用模型標識碼分析檔
使用預先建置的檔模型
使用預先建置的「版面配置」
使用預先建置的「檔」
使用預先建置的「讀取」
建置模型
管理模型

使用模型標識碼分析檔

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 來源（換句話說，私人內部網路 URL 或使用標頭或憑證型秘密的 URL，將無法運作，因為檔智慧服務必須能夠存取 URL）。不過，URL 本身可以編碼秘密，例如 Azure 記憶體 Blob URL，其中包含查詢參數中的 SAS 令牌。

使用預先建置的檔模型

beginAnalyzeDocument 方法也支援使用文件智慧服務提供的預先建置模型，從特定類型的常用檔擷取字段，例如收據、發票、名片、身分識別檔等。預先建置的模型可能會以模型標識符字串的形式提供（與自定義檔模型相同，請參閱下列 其他預先建置的模型 一節），或使用 DocumentModel 物件。使用 DocumentModel時，Document Intelligence SDK for JavaScript 會根據模型的架構，為產生的擷取檔提供更強的 TypeScript 類型，而且會轉換成使用 JavaScript 命名慣例。

在 prebuilt 範例目錄中找到目前服務 API 版本（2022-08-31）的範例 DocumentModel 物件。在下列範例中，我們將使用該目錄中 [prebuilt-receipt.ts] 檔案的 PrebuiltReceiptModel。

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

或者，如前所述，而不是使用 PrebuiltReceiptModel，這會產生更強的傳回類型，可以使用預建收據的模型標識符（“prebuilt-receipt”），但檔字段不會在 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。它們是：

預先建置的版面配置模型（請參閱 使用下方的「版面配置」預先建置），其會擷取基本版面配置（OCR）元素的相關信息，例如頁面和數據表。
預先建置的一般檔模型（請參閱 使用下方的「檔」預先建置），其會將索引鍵/值組（例如已標記元素等卷標元素之間的導向關聯）新增至版面配置模型所產生的資訊。
預先建置的讀取模型（請參閱 使用下方的「讀取」預先建置），其只會擷取文字元素，例如頁面字和行，以及文件語言的相關信息。

如需所有這些模型之字段的相關信息，請參閱服務檔的可用預先建置模型。

所有預先建置模型的欄位也可以使用 DocumentModelAdministrationClient 的 getDocumentModel 方法，以程式設計方式存取，並檢查結果中的 docTypes 欄位。

使用「版面配置」預先建置

"prebuilt-layout" 模型只會擷取檔的基本元素，例如頁面（包含文字文字/行和選取標記）、表格和可視化文字樣式，以及其周框區域，以及輸入檔文字內容中的範圍。我們提供名為 PrebuiltLayoutModel 的強型別 DocumentModel 實例，以叫用此模型，或盡可能直接使用其模型標識符 "prebuilt-layout"。

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

使用預先建置的 “document”

除了版面配置擷取方法所產生的屬性之外，"prebuilt-document" 模型也會擷取索引鍵/值組的相關信息（頁面元素之間的導向關聯，例如標記的欄位）。此預先建置（一般）檔模型提供與先前檔智慧服務反覆專案中未加上標籤資訊而定型的自定義模型類似的功能，但現在會以預先建置的模型的形式提供，可與各種檔搭配使用。我們提供名為 PrebuiltDocumentModel 的強型別 DocumentModel 實例，以叫用此模型，或盡可能直接使用其模型標識符 "prebuilt-document"。

由於 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 實例，以叫用此模型，或盡可能直接使用其模型標識符 "prebuilt-read"。

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

分類檔

Document Intelligence 服務支援自定義檔分類器，可根據定型數據集，將檔分類成一組預先定義的類別。您可以使用 DocumentAnalysisClient的 beginClassifyDocument 方法，將文件分類為自定義分類器。如同上述 beginAnalyzeDocument，此方法會接受包含要分類檔的檔案或數據流，而且其具有可接受檔可公開存取 URL 的 beginClassifyDocumentFromUrl 對應專案。

下列範例示範如何使用自定義分類器來分類檔：

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。 Document Intelligence 服務的基礎結構會讀取容器中的檔案，並根據其內容建立模型。如需如何建立及建構定型數據容器的詳細資訊，請參閱 Document Intelligence 服務的檔，以建置模型。

雖然我們提供這些方法來建立程序設計模型，但 Document Intelligence 服務小組已建立互動式 Web 應用程式，Document Intelligence Studio，以在網路上建立和管理模型。

例如，下列程式會使用 SAS 編碼的 URL，建置自定義檔模型至預先存在的 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);
});

除了刪除自定義分類器 deleteDocumentClassifier 之外，listDocumentClassifiers 和 getDocumentClassifier 類似的方法可用於列出和取得自定義分類器的相關信息。

故障排除

如需疑難解答的協助，請參閱疑難解答指南。

伐木

啟用記錄可能有助於找出有關失敗的實用資訊。若要查看 HTTP 要求和回應的記錄，請將 AZURE_LOG_LEVEL 環境變數設定為 info。或者，您可以在運行時間啟用記錄，方法是在 @azure/logger中呼叫 setLogLevel：

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

setLogLevel("info");

如需如何啟用記錄的詳細指示，請參閱@azure/記錄器套件檔。

後續步驟

如需詳細的程式代碼範例，請參閱範例目錄，以瞭解如何使用此連結庫，包括上述一節中未顯示的數個功能和方法，例如複製和撰寫模型、列出模型管理作業，以及刪除模型。

貢獻

如果您想要參與此連結庫，請閱讀參與指南，以深入瞭解如何建置和測試程序代碼。

共用方式為

適用於 JavaScript 的 Azure AI Document Intelligence 用戶端連結庫 - 5.0.0 版

注意

安裝 `@azure/ai-form-recognizer` 套件

開始

目前支持的環境

先決條件

建立表單辨識器資源

建立及驗證用戶端

使用 API 金鑰

使用 Azure Active Directory

重要概念

`DocumentAnalysisClient`

`DocumentModelAdministrationClient`

長時間執行的作業

例子

使用模型標識碼分析檔

從 URL 分析檔

使用預先建置的檔模型

其他預建模型

使用「版面配置」預先建置

使用預先建置的 “document”

使用「讀取」預先建置

分類檔

建置模型

管理模型

故障排除

伐木

後續步驟

貢獻

其他資源

共用方式為

適用於 JavaScript 的 Azure AI Document Intelligence 用戶端連結庫 - 5.0.0 版

注意

安裝 @azure/ai-form-recognizer 套件

開始

目前支持的環境

先決條件

建立表單辨識器資源

建立及驗證用戶端

使用 API 金鑰

使用 Azure Active Directory

重要概念

DocumentAnalysisClient

DocumentModelAdministrationClient

長時間執行的作業

例子

使用模型標識碼分析檔

從 URL 分析檔

使用預先建置的檔模型

其他預建模型

使用「版面配置」預先建置

使用預先建置的 “document”

使用「讀取」預先建置

分類檔

建置模型

管理模型

故障排除

伐木

後續步驟

貢獻

其他資源

安裝 `@azure/ai-form-recognizer` 套件

`DocumentAnalysisClient`

`DocumentModelAdministrationClient`