Bagikan melalui

Pustaka klien Azure AI Document Intelligence untuk JavaScript - versi 5.1.0

Azure AI Document Intelligence adalah layanan cloud yang menggunakan pembelajaran mesin untuk menganalisis teks dan data terstruktur dari dokumen Anda. Ini termasuk fitur utama berikut:

  • Tata Letak - Ekstrak teks, struktur tabel, dan tanda pilihan, bersama dengan koordinat wilayah pembatasnya, dari dokumen.
  • Dokumen - Menganalisis entitas, pasangan kunci-nilai, tabel, dan tanda seleksi dari dokumen menggunakan model dokumen bawaan umum.
  • Baca - Baca informasi tentang elemen tekstual, seperti kata dan baris halaman selain informasi bahasa teks.
  • Prabangun - Menganalisis data dari jenis dokumen umum tertentu (seperti tanda terima, faktur, kartu nama, atau dokumen identitas) menggunakan model bawaan.
  • Kustom - Buat model kustom untuk mengekstrak teks, nilai bidang, tanda pilihan, dan data tabel dari dokumen. Model kustom dibuat dengan data Anda sendiri, sehingga disesuaikan dengan dokumen Anda.
  • Pengklasifikasi - Buat pengklasifikasi kustom untuk mengkategorikan dokumen ke dalam kelas yang telah ditentukan sebelumnya.

Kode | sumberPaket (NPM) | Dokumentasi | referensi APIDokumentasi | produkSampel

Nota

Layanan Intelijen Dokumen sebelumnya dikenal sebagai "Azure Form Recognizer." Layanan ini adalah satu dan sama, dan @azure/ai-form-recognizer paket untuk JavaScript adalah paket Azure SDK untuk layanan Azure AI Document Intelligence. Pada saat penulisan, penggantian nama Azure Form Recognizer menjadi Azure AI Document Intelligence sedang berlangsung, sehingga "Form Recognizer" dan "Document Intelligence" dapat digunakan secara bergantian dalam beberapa kasus.

Pasang paket @azure/ai-form-recognizer

Instal pustaka klien Azure Document Intelligence untuk JavaScript dengan npm:

npm install @azure/ai-form-recognizer

Memulai Langkah Pertama

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

Lingkungan yang didukung saat ini

Lihat kebijakan dukungan kami untuk detail selengkapnya.

Prasyarat

Membuat sumber daya Form Recognizer

Catatan: Pada saat penulisan, portal Microsoft Azure masih mengacu pada sumber daya sebagai sumber daya "Pengenal Formulir". Di masa mendatang, ini dapat diperbarui ke sumber daya "Kecerdasan Dokumen". Untuk saat ini, dokumentasi berikut menggunakan nama "Form Recognizer".

Document Intelligence mendukung akses multi-layanan dan layanan tunggal. Buat sumber daya Cognitive Services jika Anda berencana untuk mengakses beberapa layanan kognitif di bawah satu titik akhir/kunci. Hanya untuk akses Form Recognizer, buat sumber daya Form Recognizer.

Anda dapat membuat resource menggunakan

Opsi 1:Portal Microsoft Azure

Opsi 2:Azure CLI.

Di bawah ini adalah contoh bagaimana Anda dapat membuat sumber daya Form Recognizer menggunakan 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

Jika Anda menggunakan Azure CLI, ganti <your-resource-group-name> dan <your-resource-name> dengan nama unik Anda sendiri:

az cognitiveservices account create --kind FormRecognizer --resource-group <your-resource-group-name> --name <your-resource-name> --sku <your-sku-name> --location <your-location>

Membuat dan mengautentikasi klien

Untuk berinteraksi dengan layanan Document Intelligence, Anda harus memilih a DocumentAnalysisClient atau a DocumentModelAdministrationClient, dan membuat instans jenis ini. Dalam contoh berikut, kita akan menggunakan DocumentAnalysisClient. Untuk membuat instans klien untuk mengakses Document Intelligence API, Anda memerlukan endpoint sumber daya Form Recognizer dan .credential Klien dapat menggunakan kunci AzureKeyCredential API sumber daya Anda atau yang TokenCredential menggunakan RBAC Azure Active Directory untuk mengotorisasi klien.

Anda dapat menemukan titik akhir untuk sumber daya Form Recognizer Anda baik di Portal Microsoft Azure atau dengan menggunakan cuplikan Azure CLI di bawah ini:

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

Menggunakan kunci API

Gunakan Portal Microsoft Azure untuk menelusuri sumber daya Form Recognizer Anda dan mengambil kunci API, atau gunakan cuplikan Azure CLI di bawah ini:

Catatan: Terkadang kunci API disebut sebagai "kunci langganan" atau "kunci API langganan."

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

Setelah Anda memiliki kunci API dan titik akhir, Anda dapat menggunakannya sebagai berikut:

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

Menggunakan Azure Active Directory

Otorisasi kunci API digunakan di sebagian besar contoh, tetapi Anda juga dapat mengautentikasi klien dengan Azure Active Directory menggunakan pustaka Azure Identity. Untuk menggunakan penyedia DefaultAzureCredential yang ditunjukkan di bawah ini atau penyedia kredensial lain yang disediakan dengan Azure SDK, instal @azure/identity paket:

npm install @azure/identity

Untuk mengautentikasi menggunakan perwakilan layanan, Anda juga perlu mendaftarkan aplikasi AAD dan memberikan akses ke layanan dengan menetapkan "Cognitive Services User" peran ke perwakilan layanan Anda (catatan: peran lain seperti tidak "Owner" akan memberikan izin yang diperlukan, hanya "Cognitive Services User" akan cukup untuk menjalankan contoh dan kode sampel).

Atur nilai ID klien, ID penyewa, dan rahasia klien aplikasi AAD sebagai variabel lingkungan: 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,
);

Awan Berdaulat

Sambungkan ke lingkungan cloud Azure alternatif (seperti Azure China atau Azure Government) dengan menentukan opsi saat audience membuat klien Anda. Gunakan KnownFormRecognizerAudience enum untuk memilih nilai yang benar untuk lingkungan Anda.

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

Jika Anda tidak menentukan audience opsi, defaultnya cocok untuk Azure Public Cloud (https://cognitiveservices.azure.com).

Konsep utama

DocumentAnalysisClient

DocumentAnalysisClient menyediakan operasi untuk menganalisis dokumen input menggunakan model kustom dan bawaan. Ini memiliki tiga metode:

  • beginAnalyzeDocument, yang mengekstrak data dari aliran file dokumen input menggunakan model kustom atau bawaan yang diberikan oleh ID modelnya. Untuk informasi tentang model bawaan yang didukung di semua sumber daya dan ID/output modelnya, lihat dokumentasi model layanan.
  • beginAnalyzeDocumentFromUrl, yang menjalankan fungsi yang sama dengan beginAnalyzeDocument, tetapi mengirimkan URL file yang dapat diakses publik, bukan aliran file.

DocumentModelAdministrationClient

DocumentModelAdministrationClient menyediakan operasi untuk mengelola (membuat, membaca, mencantumkan, dan menghapus) model dalam sumber daya:

  • beginBuildDocumentModel memulai operasi untuk membuat model dokumen baru dari kumpulan data pelatihan Anda sendiri. Model yang dibuat dapat mengekstrak bidang sesuai dengan skema khusus. Data pelatihan diharapkan terletak di kontainer Azure Storage dan diatur sesuai dengan konvensi tertentu. Lihat dokumentasi layanan tentang membuat kumpulan data pelatihan untuk penjelasan lebih rinci tentang penerapan label ke kumpulan data pelatihan.
  • beginComposeDocumentModel memulai operasi untuk menyusun beberapa model menjadi satu model. Saat digunakan untuk pengenalan formulir kustom, model baru yang disusun pertama-tama akan melakukan klasifikasi dokumen input untuk menentukan submodel mana yang paling sesuai.
  • beginCopyModelTo memulai operasi untuk menyalin model kustom dari satu sumber daya ke sumber daya lainnya (atau bahkan ke sumber daya yang sama). Ini membutuhkan sumber CopyAuthorization daya dari target, yang dapat dihasilkan menggunakan metode tersebut getCopyAuthorization .
  • getResourceDetails Mengambil informasi tentang batas sumber daya, seperti jumlah model kustom dan jumlah maksimum model yang dapat didukung sumber daya.
  • getDocumentModel, listDocumentModels, dan deleteDocumentModel aktifkan pengelolaan model di sumber daya.
  • getOperation listOperations dan aktifkan melihat status operasi pembuatan model, bahkan operasi yang sedang berlangsung atau yang gagal. Operasi ditahan selama 24 jam.

Harap dicatat bahwa model juga dapat dibuat menggunakan antarmuka pengguna grafis layanan Document Intelligence: Document Intelligence Studio.

Contoh cuplikan kode yang menggambarkan penggunaan DocumentModelAdministrationClient untuk membuat model dapat ditemukan di bawah ini, di bagian contoh "Membuat Model".

Operasi jangka panjang

Operasi jangka panjang (LRO) adalah operasi yang terdiri dari permintaan awal yang dikirim ke layanan untuk memulai operasi, diikuti dengan polling untuk hasil pada interval tertentu untuk menentukan apakah operasi telah selesai dan apakah gagal atau berhasil. Pada akhirnya, LRO akan gagal dengan kesalahan atau menghasilkan hasil.

Di Azure AI Document Intelligence, operasi yang membuat model (termasuk menyalin dan menyusun model) serta operasi analisis/ekstraksi data adalah LRO. Klien SDK menyediakan metode asinkron begin<operation-name> yang mengembalikan Promise<PollerLike> objek. Objek mewakili PollerLike operasi, yang berjalan secara asinkron pada infrastruktur layanan, dan program dapat menunggu operasi selesai dengan memanggil dan menunggu pollUntilDone metode pada poller yang dikembalikan dari begin<operation-name> metode. Contoh cuplikan kode disediakan untuk mengilustrasikan penggunaan operasi yang berjalan lama di bagian berikutnya.

Contoh

Bagian berikut menyediakan beberapa cuplikan kode JavaScript yang menggambarkan pola umum yang digunakan di pustaka klien Document Intelligence.

Menganalisis dokumen dengan ID model

Metode ini beginAnalyzeDocument dapat mengekstrak bidang dan data tabel dari dokumen. Analisis dapat menggunakan model kustom, yang dilatih dengan data Anda sendiri, atau model bawaan yang disediakan oleh layanan (lihat Menggunakan Model Bawaan di bawah). Model kustom disesuaikan dengan dokumen Anda sendiri, jadi hanya boleh digunakan dengan dokumen dengan struktur yang sama dengan salah satu jenis dokumen dalam model (mungkin ada beberapa, seperti dalam model yang disusun).

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

Menganalisis dokumen dari URL

Sebagai alternatif untuk menyediakan aliran yang dapat dibaca, URL yang dapat diakses publik dapat disediakan sebagai gantinya menggunakan metode tersebut beginAnalyzeDocumentFromUrl . "Dapat diakses publik" berarti bahwa sumber URL harus dapat diakses dari infrastruktur layanan (dengan kata lain, URL intranet privat, atau URL yang menggunakan rahasia berbasis header atau sertifikat, tidak akan berfungsi, karena layanan Document Intelligence harus dapat mengakses URL). Namun, URL itu sendiri dapat mengkodekan rahasia, seperti URL blob Azure Storage yang berisi token SAS dalam parameter kueri.

Menggunakan model dokumen bawaan

Metode ini beginAnalyzeDocument juga mendukung pengekstrakan bidang dari jenis dokumen umum tertentu seperti tanda terima, faktur, kartu nama, dokumen identitas, dan lainnya menggunakan model bawaan yang disediakan oleh layanan Intelijen Dokumen. Model bawaan dapat disediakan sebagai string ID model (sama dengan model dokumen kustom—lihat bagian model bawaan lainnya di bawah) atau menggunakan DocumentModel objek. Saat menggunakan DocumentModel, Document Intelligence SDK untuk JavaScript menyediakan jenis TypeScript yang jauh lebih kuat untuk dokumen yang diekstrak yang dihasilkan berdasarkan skema model, dan akan dikonversi untuk menggunakan konvensi penamaan JavaScript.

Contoh DocumentModel objek untuk versi API layanan saat ini (2022-08-31) dapat ditemukan di prebuilt direktori sampel. Dalam contoh berikut, kita akan menggunakan PrebuiltReceiptModel file from [prebuilt-receipt.ts] di direktori tersebut.

Karena manfaat DocumentModelutama analisis berbasis adalah batasan jenis TypeScript yang lebih kuat, contoh berikut ditulis dalam TypeScript menggunakan sintaks modul 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);

Atau, seperti yang disebutkan di atas, alih-alih menggunakan PrebuiltReceiptModel, yang menghasilkan jenis pengembalian yang lebih kuat, ID model tanda terima bawaan ("prabuilt-receipt") dapat digunakan, tetapi bidang dokumen tidak akan diketik dengan kuat di TypeScript, dan nama bidang umumnya akan berada di "PascalCase", bukan "camelCase".

Model bawaan lainnya

Anda tidak terbatas pada tanda terima! Ada beberapa model siap pakai untuk dipilih, dengan lebih banyak lagi yang sedang dalam perjalanan. Setiap model bawaan memiliki serangkaian bidang yang didukung:

  • Tanda terima, menggunakan PrebuiltReceiptModel (seperti di atas) atau ID "prebuilt-receipt"model tanda terima bawaan .
  • Kartu nama, menggunakan PrebuiltBusinessCardModel atau ID "prebuilt-businessCard"modelnya .
  • Faktur, menggunakan PrebuiltInvoiceModel atau ID "prebuilt-invoice"modelnya .
  • Dokumen Identitas (seperti SIM dan paspor), menggunakan PrebuiltIdDocumentModel atau ID modelnya "prebuilt-idDocument".
  • Formulir Pajak W2 (Amerika Serikat), menggunakan PrebuiltTaxUsW2Model atau ID "prebuilt-tax.us.w2"modelnya .
  • Kartu Asuransi Kesehatan (Amerika Serikat), menggunakan [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] atau ID "prebuilt-healthInsuranceCard.us"modelnya .

Masing-masing model bawaan di atas menghasilkan documents (contoh yang diekstraksi dari skema bidang model). Ada juga tiga model bawaan yang tidak memiliki skema lapangan dan karenanya tidak menghasilkan documents. Mereka adalah:

  • Model Tata Letak bawaan (lihat Menggunakan "tata letak" bawaan di bawah), yang mengekstrak informasi tentang elemen tata letak dasar (OCR) seperti halaman dan tabel.
  • Model Dokumen Umum bawaan (lihat Menggunakan "dokumen" yang dibuat sebelumnya di bawah), yang menambahkan pasangan nilai kunci (asosiasi terarah antara elemen halaman, seperti elemen berlabel) ke informasi yang dihasilkan oleh model tata letak.
  • Model Baca bawaan (lihat Menggunakan prabawaan "baca" di bawah), yang hanya mengekstrak elemen tekstual, seperti kata dan baris halaman, bersama dengan informasi tentang bahasa dokumen.

Untuk informasi tentang bidang semua model ini, lihat dokumentasi layanan tentang model bawaan yang tersedia.

Bidang semua model bawaan juga dapat diakses secara terprogram menggunakan getDocumentModel metode (dengan ID modelnya) DocumentModelAdministrationClient dan memeriksa docTypes bidang dalam hasilnya.

Gunakan "tata letak" bawaan

Model hanya "prebuilt-layout" mengekstrak elemen dasar dokumen, seperti halaman, (yang terdiri dari kata/garis teks, dan tanda pilihan), tabel, dan gaya teks visual bersama dengan wilayah dan rentang pembatasannya dalam konten teks dokumen input. Kami menyediakan instance yang diketik DocumentModel dengan kuat bernama PrebuiltLayoutModel yang memanggil model ini, atau seperti biasa ID "prebuilt-layout" modelnya dapat digunakan secara langsung.

Karena manfaat DocumentModelutama analisis berbasis adalah batasan jenis TypeScript yang lebih kuat, contoh berikut ditulis dalam TypeScript menggunakan sintaks modul 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}"`);
  }
}

Gunakan "dokumen" bawaan

Model mengekstrak "prebuilt-document" informasi tentang pasangan kunci-nilai (asosiasi terarah antara elemen halaman, seperti bidang berlabel) selain properti yang dihasilkan oleh metode ekstraksi tata letak. Model dokumen bawaan (umum) ini menyediakan fungsionalitas yang serupa dengan model kustom yang dilatih tanpa informasi label dalam iterasi layanan Document Intelligence sebelumnya, tetapi sekarang disediakan sebagai model bawaan yang berfungsi dengan berbagai macam dokumen. Kami menyediakan instance yang diketik DocumentModel dengan kuat bernama PrebuiltDocumentModel yang memanggil model ini, atau seperti biasa ID "prebuilt-document" modelnya dapat digunakan secara langsung.

Karena manfaat DocumentModelutama analisis berbasis adalah batasan jenis TypeScript yang lebih kuat, contoh berikut ditulis dalam TypeScript menggunakan sintaks modul 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})`);
  }
}

Gunakan pra-file "baca"

Model ini "prebuilt-read" mengekstrak informasi tekstual dalam dokumen seperti kata dan paragraf dan menganalisis bahasa dan gaya penulisan (misalnya tulisan tangan vs. set huruf) dari teks tersebut. Kami menyediakan instance yang diketik DocumentModel dengan kuat bernama PrebuiltReadModel yang memanggil model ini, atau seperti biasa ID "prebuilt-read" modelnya dapat digunakan secara langsung.

Karena manfaat DocumentModelutama analisis berbasis adalah batasan jenis TypeScript yang lebih kuat, contoh berikut ditulis dalam TypeScript menggunakan sintaks modul 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);
  }
}

Mengklasifikasikan dokumen

Layanan Document Intelligence mendukung pengklasifikasi dokumen kustom yang dapat mengklasifikasikan dokumen ke dalam sekumpulan kategori yang telah ditentukan sebelumnya berdasarkan kumpulan data pelatihan. Dokumen dapat diklasifikasikan dengan pengklasifikasi khusus menggunakan beginClassifyDocument metode DocumentAnalysisClient. Seperti beginAnalyzeDocument di atas, metode ini menerima file atau aliran yang berisi dokumen yang akan diklasifikasikan, dan memiliki beginClassifyDocumentFromUrl mitra yang menerima URL yang dapat diakses publik ke dokumen sebagai gantinya.

Contoh berikut menunjukkan cara mengklasifikasikan dokumen menggunakan pengklasifikasi kustom:

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

Untuk informasi tentang melatih pengklasifikasi kustom, lihat bagian tentang pelatihan pengklasifikasi di akhir bagian berikutnya.

Membuat model

SDK juga mendukung pembuatan model menggunakan DocumentModelAdministrationClient kelas. Membangun model dari data pelatihan berlabel membuat model baru yang dilatih pada dokumen Anda sendiri, dan model yang dihasilkan akan dapat mengenali nilai dari struktur dokumen tersebut. Operasi pembuatan model menerima URL yang dikodekan SAS ke kontainer Azure Storage Blob yang menyimpan dokumen pelatihan. Infrastruktur layanan Document Intelligence akan membaca file dalam kontainer dan membuat model berdasarkan kontennya. Untuk detail selengkapnya tentang cara membuat dan menyusun kontainer data pelatihan, lihat dokumentasi layanan Document Intelligence untuk membangun model.

Meskipun kami menyediakan metode ini untuk pembuatan model terprogram, tim layanan Document Intelligence telah membuat aplikasi web interaktif, Document Intelligence Studio, yang memungkinkan pembuatan dan pengelolaan model di web.

Misalnya, program berikut membangun model dokumen kustom menggunakan URL yang dikodekan SAS ke kontainer Azure Storage yang sudah ada sebelumnya:

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

Pengklasifikasi kustom dibuat dengan cara yang sama menggunakan metode beginBuildDocumentModeldaripada beginBuildDocumentClassifier . Silakan lihat contoh pengklasifikasi build untuk informasi selengkapnya tentang membuat pengklasifikasi kustom, karena data pelatihan input disediakan dalam format yang sedikit berbeda. Untuk informasi tentang membangun kumpulan data pelatihan untuk pengklasifikasi kustom, lihat dokumentasi layanan Document Intelligence.

Mengelola beragam model

DocumentModelAdministrationClient juga menyediakan beberapa metode untuk mengakses dan mencantumkan model. Contoh berikut menunjukkan cara mengulangi model dalam sumber daya (ini akan mencakup model kustom dalam sumber daya serta model bawaan yang umum untuk semua sumber daya), mendapatkan model berdasarkan ID, dan menghapus model.

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

Metode listDocumentClassifiers serupa dan getDocumentClassifier tersedia untuk mencantumkan dan mendapatkan informasi tentang pengklasifikasi kustom selain deleteDocumentClassifier untuk menghapus pengklasifikasi khusus.

Penyelesaian Masalah

Untuk bantuan terkait pemecahan masalah, lihat panduan pemecahan masalah .

Penebangan kayu

Mengaktifkan pengelogan dapat membantu menemukan informasi yang berguna tentang kegagalan. Untuk melihat log permintaan dan respons HTTP, atur variabel lingkungan AZURE_LOG_LEVEL ke info. Atau, pengelogan dapat diaktifkan saat runtime dengan memanggil setLogLevel di @azure/logger:

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

setLogLevel("info");

Untuk instruksi lebih rinci tentang cara mengaktifkan log, Anda dapat melihat dokumen paket @azure/logger.

Langkah selanjutnya

Silakan lihat direktori sampel untuk sampel kode terperinci yang menunjukkan cara menggunakan pustaka ini termasuk beberapa fitur dan metode yang tidak ditampilkan di bagian "Contoh" di atas, seperti menyalin dan menyusun model, mencantumkan operasi manajemen model, dan menghapus model.

Berpartisipasi

Jika Anda ingin berkontribusi pada pustaka ini, baca panduan berkontribusi untuk mempelajari selengkapnya tentang cara membuat dan menguji kode.

  • Last updated on