JavaScript için Azure AI Belge Zekası istemci kitaplığı - sürüm 5.0.0

  • Makale

Azure AI Document Intelligence , belgelerinizdeki metinleri ve yapılandırılmış verileri analiz etmek için makine öğrenmesini kullanan bir bulut hizmetidir. Aşağıdaki ana özellikleri içerir:

  • Düzen - Belgelerden sınırlayıcı bölge koordinatlarıyla birlikte metin, tablo yapıları ve seçim işaretlerini ayıklayın.
  • Belge - Önceden oluşturulmuş genel belge modelini kullanarak belgelerden varlıkları, anahtar-değer çiftlerini, tabloları ve seçim işaretlerini analiz edin.
  • Okuma - Metin dili bilgilerine ek olarak sayfa sözcükleri ve satırlar gibi metin öğeleri hakkındaki bilgileri okuyun.
  • Önceden oluşturulmuş - Önceden oluşturulmuş modelleri kullanarak belirli türlerdeki ortak belgelerden (makbuzlar, faturalar, kartvizitler veya kimlik belgeleri gibi) verileri analiz edin.
  • Özel - Belgelerden metin, alan değerleri, seçim işaretleri ve tablo verilerini ayıklamak için özel modeller oluşturun. Özel modeller kendi verilerinizle oluşturulduğu için belgelerinize uyarlanır.
  • Sınıflandırıcılar - Belgeleri önceden tanımlanmış sınıflara kategorilere ayırmak için özel sınıflandırıcılar oluşturun.

Kaynak kodu | Paket (NPM) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Not

Belge Yönetim Bilgileri hizmeti daha önce "Azure Form Tanıma" olarak biliniyordu. Bu hizmetler bir ve aynıdır ve @azure/ai-form-recognizer JavaScript paketi, Azure AI Document Intelligence hizmeti için Azure SDK paketidir. Yazma sırasında, Azure Form Tanıma'nin Azure Yapay Zeka Belge Zekası'na yeniden adlandırılması devam eder, bu nedenle "Form Tanıma" ve "Belge Zekası" bazı durumlarda birbirinin yerine kullanılabilir.

@azure/ai-form-recognizer paketini yükleyin

ile npmJavaScript için Azure Document Intelligence istemci kitaplığını yükleyin:

npm install @azure/ai-form-recognizer

Başlarken

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

Şu anda desteklenen ortamlar

Daha fazla ayrıntı için destek ilkemize bakın.

Önkoşullar

Form Tanıma kaynağı oluşturma

Not: Yazma sırasında, Azure portal yine de kaynağı "Form Tanıma" kaynak olarak ifade eder. Gelecekte, bu bir "Belge Yönetim Bilgileri" kaynağına güncelleştirilebilir. Şimdilik, aşağıdaki belgelerde "Form Tanıma" adı kullanılmaktadır.

Belge Zekası hem çok hizmetli hem de tek hizmetli erişimi destekler. Tek bir uç nokta/anahtar altında birden çok bilişsel hizmete erişmeyi planlıyorsanız Bilişsel Hizmetler kaynağı oluşturun. Yalnızca Form Tanıma erişim için bir Form Tanıma kaynağı oluşturun.

Kaynağı oluşturmak için

Seçenek 1:Azure Portal

Seçenek 2:Azure CLI.

Aşağıda CLI kullanarak nasıl Form Tanıma kaynağı oluşturabileceğinize ilişkin bir örnek verilmiştir:

# 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 kullanıyorsanız ve <your-resource-name> yerine kendi benzersiz adlarınızı yazın<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>

İstemci oluşturma ve kimlik doğrulaması

Belge Yönetim Bilgileri hizmetiyle etkileşim kurmak için bir DocumentAnalysisClient veya DocumentModelAdministrationClientseçmeniz ve bu tür bir örnek oluşturmanız gerekir. Aşağıdaki örneklerde kullanacağız DocumentAnalysisClient. Belge Yönetim Bilgileri API'sine erişmek üzere bir istemci örneği oluşturmak için Form Tanıma kaynağınızın ve değerinin credentialolması gerekirendpoint. İstemciler, kaynağınızın API anahtarıyla bir veya istemciyi yetkilendirmek için Azure Active Directory RBAC kullanan bir TokenCredential kullanabilirAzureKeyCredential.

Form Tanıma kaynağınızın uç noktasını Azure Portal'da veya aşağıdaki Azure CLI parçacığını kullanarak bulabilirsiniz:

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

API anahtarı kullanma

azure portalını kullanarak Form Tanıma kaynağınıza göz atın ve bir API anahtarı alın veya aşağıdaki Azure CLI parçacığını kullanın:

Not: Bazen API anahtarına "abonelik anahtarı" veya "abonelik API anahtarı" denir.

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

BIR API anahtarınız ve uç noktanız olduğunda, bunu aşağıdaki gibi kullanabilirsiniz:

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

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

Azure Active Directory kullanma

API anahtarı yetkilendirmesi örneklerin çoğunda kullanılır, ancak Azure Kimlik kitaplığını kullanarak Azure Active Directory ile istemcinin kimliğini de doğrulayabilirsiniz. Aşağıda gösterilen DefaultAzureCredential sağlayıcısını veya Azure SDK ile sağlanan diğer kimlik bilgisi sağlayıcılarını kullanmak için lütfen paketi yükleyin @azure/identity :

npm install @azure/identity

Hizmet sorumlusu kullanarak kimlik doğrulaması yapmak için, bir AAD uygulamasını kaydetmeniz ve rolü hizmet sorumlunuza atayarak "Cognitive Services User" hizmete erişim vermeniz gerekir (not: gibi "Owner" diğer roller gerekli izinleri vermez, yalnızca "Cognitive Services User" örnekleri ve örnek kodu çalıştırmak için yeterli olur).

AAD uygulamasının istemci kimliği, kiracı kimliği ve istemci gizli dizisi değerlerini ortam değişkenleri olarak ayarlayın: 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());

Önemli kavramlar

DocumentAnalysisClient

DocumentAnalysisClient özel ve önceden oluşturulmuş modelleri kullanarak giriş belgelerini analiz etmeye yönelik işlemler sağlar. Üç yöntemi vardır:

  • beginAnalyzeDocument, model kimliği tarafından verilen özel veya önceden oluşturulmuş bir model kullanarak giriş belgesi dosya akışından verileri ayıklar. Tüm kaynaklarda desteklenen önceden oluşturulmuş modeller ve model kimlikleri/çıkışları hakkında bilgi için lütfen hizmetin model belgelerine bakın.
  • beginAnalyzeDocumentFromUrl, ile aynı işlevi beginAnalyzeDocumentgerçekleştirir ancak dosya akışı yerine bir dosyanın genel olarak erişilebilen URL'sini gönderir.

DocumentModelAdministrationClient

DocumentModelAdministrationClient kaynaktaki modelleri yönetme (oluşturma, okuma, listeleme ve silme) işlemleri sağlar:

  • beginBuildDocumentModel kendi eğitim veri kümenizden yeni bir belge modeli oluşturmak için bir işlem başlatır. Oluşturulan model özel bir şemaya göre alanları ayıklayabilir. Eğitim verilerinin bir Azure Depolama kapsayıcısında bulunması ve belirli bir kurala göre düzenlenmesi beklenir. Eğitim veri kümesine etiket uygulamanın daha ayrıntılı bir açıklaması için hizmetin eğitim veri kümesi oluşturma belgelerine bakın.
  • beginComposeDocumentModel tek bir modelde birden çok model oluşturmak için bir işlem başlatır. Özel form tanıma için kullanıldığında, yeni oluşturulan model ilk olarak hangi alt modellerinin en uygun olduğunu belirlemek için giriş belgelerinin sınıflandırmasını gerçekleştirir.
  • beginCopyModelTo özel modeli bir kaynaktan diğerine (hatta aynı kaynağa) kopyalamak için bir işlem başlatır. Yöntemi kullanılarak getCopyAuthorization oluşturulabilen hedef kaynaktan bir CopyAuthorization gerektirir.
  • getResourceDetails kaynağın sınırları hakkında özel model sayısı ve kaynağın destekleyebileceğiniz maksimum model sayısı gibi bilgileri alır.
  • getDocumentModel, listDocumentModelsve deleteDocumentModel kaynaktaki modelleri yönetmeyi etkinleştirin.
  • getOperation ve listOperations model oluşturma işlemlerinin durumunu, devam eden veya başarısız olan işlemleri bile görüntülemeyi etkinleştirin. İşlemler 24 saat boyunca tutulur.

Modellerin, Belge Zekası hizmetinin grafik kullanıcı arabirimi olan Document Intelligence Studio kullanılarak da oluşturulabileceğini lütfen unutmayın.

Model oluşturmak için kullanımını DocumentModelAdministrationClient gösteren örnek kod parçacıkları aşağıda "Model Derleme" örnek bölümünde bulunabilir.

Uzun süre çalışan işlemler

Uzun süre çalışan işlemler (LLO'lar), bir işlemi başlatmak için hizmete gönderilen ilk isteklerden oluşan ve ardından işlemin tamamlanıp tamamlanmadığını ve başarılı olup olmadığını belirlemek için belirli bir aralıkta bir sonucu yoklamadan oluşan işlemlerdir. Sonuç olarak, LRO bir hatayla başarısız olur veya bir sonuç üretir.

Azure AI Belge Zekası'nda model oluşturan işlemler (modelleri kopyalama ve oluşturma dahil) ve analiz/veri ayıklama işlemleri LLO'lardır. SDK istemcileri, nesneleri döndüren Promise<PollerLike> zaman uyumsuz begin<operation-name> yöntemler sağlar. PollerLike nesnesi, hizmetin altyapısında zaman uyumsuz olarak çalışan işlemi temsil eder ve bir program yönteminden begin<operation-name> döndürülen poller üzerinde yöntemini çağırarak ve bekleyerek pollUntilDone işlemin tamamlanmasını bekleyebilir. Sonraki bölümde uzun süre çalışan işlemlerin kullanılmasını göstermek için örnek kod parçacıkları sağlanmıştır.

Örnekler

Aşağıdaki bölümde, Belge Yönetim Bilgileri istemci kitaplıklarında kullanılan yaygın desenleri gösteren birkaç JavaScript kod parçacığı sağlanır.

Model kimliğiyle belgeyi analiz etme

beginAnalyzeDocument yöntemi, belgelerden alanları ve tablo verilerini ayıklayabilir. Analiz, kendi verilerinizle eğitilmiş özel bir model veya hizmet tarafından sağlanan önceden oluşturulmuş bir model kullanabilir (aşağıdaki Önceden Oluşturulmuş Modelleri Kullanma bölümüne bakın). Özel model kendi belgelerinize uyarlanmıştır, bu nedenle yalnızca modeldeki belge türlerinden biriyle aynı yapıdaki belgelerle kullanılmalıdır (örneğin, oluşturulan modelde birden çok olabilir).

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'den belge çözümleme

Okunabilir bir akış sağlamaya alternatif olarak, yöntemi kullanılarak beginAnalyzeDocumentFromUrl genel olarak erişilebilir bir URL sağlanabilir. "Genel olarak erişilebilir", URL kaynaklarının hizmetin altyapısından erişilebilir olması gerektiği anlamına gelir (başka bir deyişle, özel intranet URL'si veya üst bilgi veya sertifika tabanlı gizli diziler kullanan URL'ler çalışmaz çünkü Belge Yönetim Bilgileri hizmetinin URL'ye erişebilmesi gerekir). Ancak, URL'nin kendisi sorgu parametrelerinde SAS belirteci içeren bir Azure Depolama blob URL'si gibi bir gizli diziyi kodlayabilir.

Önceden oluşturulmuş belge modellerini kullanma

Yöntemi ayrıca beginAnalyzeDocument , Belge Yönetim Bilgileri hizmeti tarafından sağlanan önceden oluşturulmuş modelleri kullanarak makbuzlar, faturalar, kartvizitler, kimlik belgeleri ve daha fazlası gibi bazı yaygın belge türlerinden alan ayıklamayı destekler. Önceden oluşturulmuş modeller model kimliği dizeleri olarak (özel belge modelleriyle aynı şekilde— aşağıdaki diğer önceden oluşturulmuş modeller bölümüne bakın) veya bir DocumentModel nesne kullanılarak sağlanabilir. kullanırken DocumentModel, JavaScript için Belge Zekası SDK'sı modelin şemasına göre elde edilen belgeler için çok daha güçlü bir TypeScript türü sağlar ve JavaScript adlandırma kurallarını kullanacak şekilde dönüştürülür.

Geçerli hizmet API sürümü (2022-08-31) için örnek DocumentModel nesneler samples dizininde prebuiltbulunabilir. Aşağıdaki örnekte, bu dizindeki [prebuilt-receipt.ts] dosyasından dosyasını kullanacağızPrebuiltReceiptModel.

Tabanlı analizin DocumentModeltemel avantajı daha güçlü TypeScript türü kısıtlamaları olduğundan, ECMAScript modülü söz dizimi kullanılarak TypeScript'te aşağıdaki örnek yazılır:

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

Alternatif olarak, yukarıda bahsedildiği gibi, daha güçlü dönüş türünü oluşturan yerine PrebuiltReceiptModel, önceden oluşturulmuş makbuzun model kimliği ("önceden oluşturulmuş alındı") kullanılabilir, ancak belge alanları TypeScript'te kesin olarak yazılmaz ve alan adları genellikle "camelCase" yerine "PascalCase" içinde olur.

Diğer önceden oluşturulmuş modeller

Makbuzlarla sınırlı değilsin! Aralarından seçim yapabileceğiniz birkaç önceden oluşturulmuş model vardır ve daha fazlası da yoldadır. Önceden oluşturulmuş her modelin kendi desteklenen alanlar kümesi vardır:

  • Makbuzlar, kullanarak PrebuiltReceiptModel (yukarıda olduğu gibi) veya önceden oluşturulmuş makbuz modeli kimliğini kullanır "prebuilt-receipt".
  • veya model kimliğini "prebuilt-businessCard"kullanarak PrebuiltBusinessCardModel kartvizitler.
  • veya model kimliğini "prebuilt-invoice"kullanarak PrebuiltInvoiceModel faturalar.
  • veya model kimliğini "prebuilt-idDocument"kullanarak PrebuiltIdDocumentModel Kimlik Belgeleri (sürücü lisansları ve pasaportlar gibi).
  • kullanarak veya model kimliğini "prebuilt-tax.us.w2"kullanarak PrebuiltTaxUsW2Model W2 Vergi Formları (Birleşik Devletler).
  • [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] veya model kimliğini "prebuilt-healthInsuranceCard.us"kullanarak Sağlık Sigortası Kartları (Birleşik Devletler).

Yukarıdaki önceden oluşturulmuş modellerin her biri üretir documents (modelin alan şemasının ayıklanan örnekleri). Ayrıca, alan şemaları olmayan ve bu nedenle üretmeyen documentsönceden oluşturulmuş üç model vardır. Bunlar:

  • Sayfalar ve tablolar gibi temel düzen (OCR) öğeleri hakkındaki bilgileri ayıklayan önceden oluşturulmuş Düzen modeli (aşağıda önceden oluşturulmuş "düzeni" kullanma bölümüne bakın).
  • Düzen modeli tarafından üretilen bilgilere anahtar-değer çiftleri (etiketlenmiş öğeler gibi sayfa öğeleri arasında yönlendirilmiş ilişkilendirmeler) ekleyen önceden oluşturulmuş Genel Belge modeli (aşağıda önceden oluşturulmuş "belgeyi" kullanma bölümüne bakın).
  • Önceden oluşturulmuş Okuma modeli (bkz. Aşağıda önceden oluşturulmuş "okuma" modelini kullanın ), yalnızca sayfa sözcükleri ve satırlar gibi metin öğelerini ve belgenin diliyle ilgili bilgileri ayıklar.

Tüm bu modellerin alanları hakkında bilgi için hizmetin kullanılabilir önceden oluşturulmuş modellerin belgelerine bakın.

Önceden oluşturulmuş tüm modellerin alanlarına, yöntemi (model kimlikleri tarafından) DocumentModelAdministrationClient kullanılarak getDocumentModel ve sonuçtaki alan incelenerek docTypes program aracılığıyla da erişilebilir.

Önceden oluşturulmuş "düzeni" kullanma

Model "prebuilt-layout" , belgenin yalnızca sayfalar (metin sözcükleri/satırlar ve seçim işaretlerinden oluşan) temel öğelerini, tabloları ve görsel metin stillerini, bunların sınırlayıcı bölgelerini ve giriş belgelerinin metin içeriği içindeki yayılmalarını ayıklar. Bu modeli çağıran, türü kesin olarak belirlenmiş DocumentModel bir örnek PrebuiltLayoutModel sağlarız veya her zaman olduğu gibi model kimliği "prebuilt-layout" doğrudan kullanılabilir.

Tabanlı analizin DocumentModeltemel avantajı daha güçlü TypeScript türü kısıtlamaları olduğundan, ECMAScript modülü söz dizimi kullanılarak TypeScript'te aşağıdaki örnek yazılır:

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

Önceden oluşturulmuş "belgeyi" kullanma

Model, "prebuilt-document" düzen ayıklama yöntemi tarafından üretilen özelliklere ek olarak anahtar-değer çiftleri (etiketlenmiş alanlar gibi sayfa öğeleri arasındaki yönlendirilmiş ilişkilendirmeler) hakkındaki bilgileri ayıklar. Bu önceden oluşturulmuş (genel) belge modeli, Belge Yönetim Bilgileri hizmetinin önceki yinelemelerinde etiket bilgisi olmadan eğitilen özel modellere benzer işlevsellik sağlar, ancak artık çok çeşitli belgelerle çalışan önceden oluşturulmuş bir model olarak sağlanır. Bu modeli çağıran, türü kesin olarak belirlenmiş DocumentModel bir örnek PrebuiltDocumentModel sağlarız veya her zaman olduğu gibi model kimliği "prebuilt-document" doğrudan kullanılabilir.

Tabanlı analizin DocumentModeltemel avantajı daha güçlü TypeScript türü kısıtlamaları olduğundan, ECMAScript modülü söz dizimi kullanılarak TypeScript'te aşağıdaki örnek yazılır:

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

Önceden oluşturulmuş "okuma" özelliğini kullanma

Model, "prebuilt-read" bir belgedeki sözcükler ve paragraflar gibi metinsel bilgileri ayıklar ve bu metnin dilini ve yazma stilini (el yazısı ve tür kümesi gibi) analiz eder. Bu modeli çağıran, türü kesin olarak belirlenmiş DocumentModel bir örnek PrebuiltReadModel sağlarız veya her zaman olduğu gibi model kimliği "prebuilt-read" doğrudan kullanılabilir.

Tabanlı analizin DocumentModeltemel avantajı daha güçlü TypeScript türü kısıtlamaları olduğundan, ECMAScript modülü söz dizimi kullanılarak TypeScript'te aşağıdaki örnek yazılır:

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

Belgeyi sınıflandırma

Belge Yönetim Bilgileri hizmeti, belgeleri eğitim veri kümesine göre önceden tanımlanmış bir kategori kümesine sınıflandırabilen özel belge sınıflandırıcılarını destekler. Belgeler, yöntemi DocumentAnalysisClientkullanılarak özel bir sınıflandırıcı ile beginClassifyDocument sınıflandırılabilir. Yukarıdaki gibi beginAnalyzeDocument , bu yöntem sınıflandırılacak belgeyi içeren bir dosyayı veya akışı kabul eder ve bunun yerine belgenin genel olarak erişilebilen URL'sini kabul eden bir karşılığı vardır beginClassifyDocumentFromUrl .

Aşağıdaki örnekte, özel sınıflandırıcı kullanarak bir belgenin nasıl sınıflandırılacağı gösterilmektedir:

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

Özel sınıflandırıcıyı eğitme hakkında bilgi için sonraki bölümün sonundaki sınıflandırıcı eğitimi bölümüne bakın.

Model oluşturma

SDK, sınıfını DocumentModelAdministrationClient kullanarak model oluşturmayı da destekler. Etiketli eğitim verilerinden model oluşturmak, kendi belgelerinizde eğitilen yeni bir model oluşturur ve sonuçta elde edilen model bu belgelerin yapılarından değerleri tanıyabilir. Model oluşturma işlemi, eğitim belgelerinin bulunduğu Azure Depolama Blobu kapsayıcısının SAS ile kodlanmış URL'sini kabul eder. Belge Yönetim Bilgileri hizmetinin altyapısı kapsayıcıdaki dosyaları okur ve içeriğine göre bir model oluşturur. Eğitim veri kapsayıcısı oluşturma ve yapılandırma hakkında daha fazla ayrıntı için, Model oluşturmaya yönelik Belge Yönetim Bilgileri hizmetinin belgelerine bakın.

Programlı model oluşturmak için bu yöntemleri sağlarken, Document Intelligence hizmet ekibi web'de model oluşturmayı ve yönetmeyi sağlayan etkileşimli bir web uygulaması ( Document Intelligence Studio) oluşturmuştur.

Örneğin, aşağıdaki program önceden var olan bir Azure Depolama kapsayıcısının SAS ile kodlanmış URL'sini kullanarak özel bir belge modeli oluşturur:

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

Özel sınıflandırıcılar, yerine yöntemi beginBuildDocumentModelkullanılarak beginBuildDocumentClassifier benzer şekilde oluşturulur. Giriş eğitim verileri biraz farklı bir biçimde sağlandığından, özel sınıflandırıcı oluşturma hakkında daha fazla bilgi için lütfen derleme sınıflandırıcı örneğine bakın. Özel sınıflandırıcı için eğitim veri kümesi oluşturma hakkında bilgi için Bkz. Belge Yönetim Bilgileri hizmeti belgeleri.

Modelleri yönetme

DocumentModelAdministrationClient ayrıca modellere erişmek ve modelleri listelemek için çeşitli yöntemler sağlar. Aşağıdaki örnek, bir kaynaktaki modeller arasında nasıl yineleme yapılacağını gösterir (hem kaynaktaki özel modelleri hem de tüm kaynaklar için ortak olan önceden oluşturulmuş modelleri içerir), kimliğe göre model alma ve modeli silme.

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

Benzer yöntemler ve getDocumentClassifier özel sınıflandırıcıları listDocumentClassifiers silmeye ek olarak özel sınıflandırıcıları listelemek deleteDocumentClassifier ve bunlar hakkında bilgi almak için de kullanılabilir.

Sorun giderme

Sorun giderme konusunda yardım için sorun giderme kılavuzuna bakın.

Günlüğe Kaydetme

Günlüğe kaydetmenin etkinleştirilmesi hatalarla ilgili yararlı bilgilerin ortaya çıkarılmasına yardımcı olabilir. HTTP isteklerinin ve yanıtlarının günlüğünü görmek için ortam değişkenini AZURE_LOG_LEVEL olarak infoayarlayın. Alternatif olarak, günlüğü çalışma zamanında içinde çağrılarak setLogLevel@azure/loggeretkinleştirilebilir:

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

setLogLevel("info");

Günlükleri etkinleştirme hakkında daha ayrıntılı yönergeler için @azure/günlükçü paketi belgelerine bakabilirsiniz.

Sonraki adımlar

Modelleri kopyalama ve oluşturma, model yönetimi işlemlerini listeleme ve modelleri silme gibi yukarıdaki "Örnekler" bölümünde gösterilmeyen çeşitli özellikler ve yöntemler de dahil olmak üzere bu kitaplığın nasıl kullanılacağını gösteren ayrıntılı kod örnekleri için samples dizinine göz atın.

Katkıda bulunma

Bu kitaplığa katkıda bulunmak isterseniz, kodu derleme ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzunu okuyun.

İzlenimler