JavaScript için Azure AI Belge Yönetim Bilgileri istemci kitaplığı - sürüm 5.1.0

Azure AI Belge Yönetim Bilgileri , belgelerinizdeki metin ve yapılandırılmış verileri analiz etmek için makine öğrenimini kullanan bir bulut hizmetidir. Aşağıdaki ana özellikleri içerir:

• Düzen - Belgelerden metin, tablo yapıları ve seçim işaretlerini sınırlayıcı bölge koordinatlarıyla birlikte ayıklayın.
• Belge - Önceden oluşturulmuş genel belge modelini kullanarak belgelerdeki 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 öğeleriyle ilgili bilgileri okuyun.
• Önceden oluşturulmuş - Önceden oluşturulmuş modelleri kullanarak belirli türdeki yaygın 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şturulur, bu nedenle belgelerinize göre uyarlanır.
• Sınıflandırıcılar - Belgeleri önceden tanımlanmış sınıflar halinde kategorilere ayırmak için özel sınıflandırıcılar oluşturun.

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

Uyarı

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 Belge Yönetim Bilgileri hizmeti için Azure SDK paketidir. Yazma sırasında, Azure Form Tanıma'nın Azure AI Belge Bilgileri olarak yeniden adlandırılması devam etmektedir, bu nedenle bazı durumlarda "Form Tanıma" ve "Belge Yönetim Bilgileri" birbirinin yerine kullanılabilir.

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

JavaScript için Azure Belge Yönetim Bilgileri istemci kitaplığını şu şekilde npmyükleyin:

npm install @azure/ai-form-recognizer

Başlangıç Yapmak

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

Şu anda desteklenen ortamlar

• Node.js LTS sürümleri
• Safari, Chrome, Edge ve Firefox'un en son sürümleri.

Daha fazla bilgi için bkz. destek ilkesi.

Önkoşullar

• Azure aboneliği
• Bilişsel Hizmetler veya Form Tanıma kaynağı. Kaynağı oluşturmanız gerekiyorsa Azure CLI veya Azure Portal'ı kullanabilirsiniz.

Form Tanıma kaynağı oluşturma

Not: Yazma sırasında, Azure portal kaynağa "Form Tanıyıcı" kaynağı olarak atıfta bulunmaya devam eder. Gelecekte, bu bir "Belge İstihbaratı" kaynağına güncellenebilir. Şimdilik, aşağıdaki belgelerde "Form Tanıma" adı kullanılmaktadır.

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

Kaynağı kullanarak oluşturabilirsiniz

Seçenek 1:Azure Portalı

Seçenek 2:Azure CLI.

Aşağıda, CLI kullanarak bir Form Tanıma kaynağı oluşturmaya 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 <your-resource-group-name> ve <your-resource-name> kendi benzersiz adlarınızla değiştirin:

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ı yapma

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

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

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

Bir API anahtarı kullanın

Form Tanıma kaynağınıza göz atmak ve bir API anahtarı almak için Azure Portal'ı kullanın veya aşağıdaki Azure CLI kod parçacığını kullanın:

Not: Bazen API anahtarı "abonelik anahtarı" veya "abonelik API anahtarı" olarak adlandırılır.

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:

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

Azure Active Directory'yi kullanma

Örneklerin çoğunda API anahtarı yetkilendirmesi kullanılır, ancak Azure Kimlik kitaplığını kullanarak istemcinin kimliğini Azure Active Directory ile 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

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

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.

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

Bağımsız Bulutlar

İstemcinizi oluştururken seçeneği belirterek alternatif Azure bulut ortamlarına audience (Azure Çin veya Azure Kamu gibi) bağlanın. KnownFormRecognizerAudience Ortamınız için doğru değeri seçmek için sabit listesini kullanın.

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

Seçeneği belirtmezseniz audience , varsayılan değer Azure Genel Bulutu için uygundur (https://cognitiveservices.azure.com).

Temel kavramlar

DocumentAnalysisClient

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

• beginAnalyzeDocument, model kimliği tarafından verilen özel veya önceden oluşturulmuş bir modeli kullanarak bir giriş belgesi dosya akışından veri ayıklar. Tüm kaynaklarda desteklenen önceden oluşturulmuş modeller ve bunların model kimlikleri/çıkışları hakkında daha fazla bilgi için lütfen hizmetin modellerle ilgili belgelerine bakın.
• beginAnalyzeDocumentFromUrl, ile aynı işlevi beginAnalyzeDocumentyerine getirir, ancak bir dosya akışı yerine bir dosyanın herkesin erişebileceği bir URL'sini gönderir.

DocumentModelAdministrationClient

DocumentModelAdministrationClient Kaynaktaki modelleri yönetmek (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, alanları özel bir şemaya göre 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 uygulama hakkında daha ayrıntılı bir açıklama için hizmetin eğitim veri kümesi oluşturma belgelerine bakın.
• beginComposeDocumentModel Birden çok modeli tek bir modelde oluşturmak için bir işlem başlatır. Özel form tanıma için kullanıldığında, yeni oluşturulan model, alt modellerinden hangisinin en uygun olduğunu belirlemek için önce giriş belgelerinin bir sınıflandırmasını gerçekleştirir.
• beginCopyModelTo Özel bir modeli bir kaynaktan diğerine (hatta aynı kaynağa) kopyalamak için bir işlem başlatır. Yöntem kullanılarak getCopyAuthorization oluşturulabilen hedef kaynaktan bir CopyAuthorization gerektirir.
• getResourceDetails Özel modellerin sayısı ve kaynağın destekleyebileceği en fazla model sayısı gibi kaynağın sınırları hakkındaki bilgileri alır.
• getDocumentModel deleteDocumentModel ve listDocumentModelskaynaktaki modelleri yönetmeyi etkinleştirin.
• getOperation ve listOperations devam eden veya başarısız olan işlemler de dahil olmak üzere model oluşturma işlemlerinin durumunu görüntülemeyi etkinleştirin. İşlemler 24 saat boyunca saklanır.

Modellerin Document Intelligence servisinin grafik kullanıcı arayüzü olan Document Intelligence Studio kullanılarak da oluşturulabileceğini lütfen unutmayın.

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

Uzun süreli işlemler

Uzun süre çalışan işlemler (LRO'lar), bir işlemi başlatmak için hizmete gönderilen ilk istekten ve ardından işlemin tamamlanıp tamamlanmadığını ve başarısız mı yoksa başarılı mı olduğunu belirlemek için belirli bir aralıkta bir sonuç yoklamasından oluşan işlemlerdir. Sonuçta, LRO ya bir hatayla başarısız olacak ya da bir sonuç üretecektir.

Azure Yapay Zeka Belge Bilgileri'nde, model oluşturan işlemlerin (model kopyalama ve oluşturma dahil) yanı sıra analiz/veri ayıklama işlemleri LRO'lardır. SDK istemcileri, nesneleri döndüren Promise<PollerLike> zaman uyumsuz begin<operation-name> yöntemler sağlar. NesnePollerLike, hizmetin altyapısında zaman uyumsuz olarak çalışan işlemi temsil eder ve bir program, yöntemden begin<operation-name> döndürülen poller'da yöntemi çağırarak ve bekleyerek pollUntilDone işlemin tamamlanmasını bekleyebilir. Sonraki bölümde uzun süre çalışan işlemlerin kullanımı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 çeşitli JavaScript kod parçacıkları sağlanmaktadır.

• Model kimliğine sahip bir belgeyi analiz etme
• Önceden oluşturulmuş belge modellerini kullanma
• Önceden oluşturulmuş "düzeni" kullanın
• Önceden oluşturulmuş "belgeyi" kullanın
• Önceden oluşturulmuş "okuma" özelliğini kullanın
• Model oluşturma
• Modelleri yönetme

Model kimliğine sahip bir belgeyi analiz etme

Yöntem beginAnalyzeDocument , 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 bir model kendi belgelerinize göre uyarlanmıştır, bu nedenle yalnızca modeldeki belge türlerinden biriyle aynı yapıya sahip belgelerle kullanılmalıdır (oluşturulmuş bir modelde olduğu gibi birden çok belge olabilir).

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

Bir URL'den bir belgeyi analiz etme

Okunabilir bir akış sağlamaya alternatif olarak, yöntem kullanılarak beginAnalyzeDocumentFromUrl bunun yerine herkesin erişebileceği 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, Belge Yönetim Bilgisi hizmetinin URL'ye erişebilmesi gerektiğinden, özel bir intranet URL'si veya başlık ya da sertifika tabanlı gizli diziler kullanan URL'ler çalışmaz). 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öntem beginAnalyzeDocument ayrıca Belge Yönetim Bilgileri hizmeti tarafından sağlanan önceden oluşturulmuş modelleri kullanarak makbuzlar, faturalar, kartvizitler, kimlik belgeleri ve daha fazlası gibi belirli ortak belge türlerinden alanların ayıklanmasını da destekler. Önceden oluşturulmuş modeller, model kimlik dizeleri (özel belge modelleriyle aynı - aşağıdaki diğer önceden oluşturulmuş modeller bölümüne bakın) veya bir DocumentModel nesne kullanılarak sağlanabilir. JavaScript için DocumentModelBelge Yönetim Bilgileri SDK'sı, modelin şemasına bağlı olarak sonuçta ayıklanan 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 from [prebuilt-receipt.ts] dosyasını kullanacağızPrebuiltReceiptModel.

Tabanlı analizin DocumentModelana yararı daha güçlü TypeScript tür kısıtlamaları olduğundan, aşağıdaki örnek ECMAScript modülü sözdizimi kullanılarak TypeScript'te yazılmıştır:

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

Alternatif olarak, yukarıda belirtildiği gibi, PrebuiltReceiptModeldaha güçlü dönüş türünü üreten , yerine önceden oluşturulmuş girişin model kimliği ("prebuilt-receipt") 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ğilsiniz! Aralarından seçim yapabileceğiniz birkaç önceden oluşturulmuş model var ve daha fazlası yolda. Önceden oluşturulmuş her modelin kendi desteklenen alan kümesi vardır:

• Makbuzlar, (yukarıdaki gibi) veya önceden oluşturulmuş makbuz model kimliğini "prebuilt-receipt"kullanarak PrebuiltReceiptModel .
• Kartvizitler, veya model kimliğini "prebuilt-businessCard"kullanarakPrebuiltBusinessCardModel.
• Faturalar, veya model kimliğini "prebuilt-invoice"kullanarakPrebuiltInvoiceModel.
• Kimlik Belgeleri (ehliyet ve pasaport gibi), veya model kimliğini "prebuilt-idDocument"kullanarakPrebuiltIdDocumentModel.
• W2 Vergi Formları (Amerika Birleşik Devletleri), model kimliğini veya model kimliğini "prebuilt-tax.us.w2"kullanarakPrebuiltTaxUsW2Model.
• Sağlık Sigortası Kartları (Amerika Birleşik Devletleri), [PrebuiltHealthInsuranceCardUsModel][samples-prebuilt-healthinsurancecard.us] veya model kimliğini "prebuilt-healthInsuranceCard.us"kullanarak.

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

• Sayfalar ve tablolar gibi temel düzen (OCR) öğeleri hakkında bilgi ayıklayan önceden oluşturulmuş Düzen modeli (aşağıdaki "önceden oluşturulmuş düzen" bölümüne bakın).
• Mizanpaj modeli tarafından üretilen bilgilere anahtar-değer çiftleri (etiketli öğeler gibi sayfa öğeleri arasında yönlendirilmiş ilişkilendirmeler) ekleyen önceden oluşturulmuş Genel Belge modeli (aşağıdaki "önceden oluşturulmuş "belge "yi kullanma bölümüne bakın).
• Belgenin diliyle ilgili bilgilerle birlikte yalnızca sayfa sözcükleri ve satırlar gibi metin öğelerini ayıklayan önceden oluşturulmuş Okuma modeli (aşağıdaki "önceden oluşturulmuş "okuma" modelini kullanma bölümüne bakın).

Bu modellerin tümünün alanları hakkında daha fazla bilgi için, hizmetin kullanılabilir önceden oluşturulmuş modellerle ilgili belgelerine bakın.

Önceden oluşturulmuş tüm modellerin alanlarına, sonuçta alanın yöntemi (model kimliklerine göre) DocumentModelAdministrationClient kullanılarak getDocumentModel ve incelenerek docTypes programlı olarak da erişilebilir.

Önceden oluşturulmuş "düzeni" kullanın

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

Tabanlı analizin DocumentModelana yararı daha güçlü TypeScript tür kısıtlamaları olduğundan, aşağıdaki örnek ECMAScript modülü sözdizimi kullanılarak TypeScript'te yazılmıştır:

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

Önceden oluşturulmuş "belgeyi" kullanın

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

Tabanlı analizin DocumentModelana yararı daha güçlü TypeScript tür kısıtlamaları olduğundan, aşağıdaki örnek ECMAScript modülü sözdizimi kullanılarak TypeScript'te yazılmıştır:

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

Önceden oluşturulmuş "okuma" özelliğini kullanın

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

Tabanlı analizin DocumentModelana yararı daha güçlü TypeScript tür kısıtlamaları olduğundan, aşağıdaki örnek ECMAScript modülü sözdizimi kullanılarak TypeScript'te yazılmıştır:

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

Belgeyi sınıflandırma

Belge Yönetim Bilgileri hizmeti, belgeleri bir eğitim veri kümesine dayalı olarak önceden tanımlanmış bir kategoriler kümesine sınıflandırabilen özel belge sınıflandırıcılarını destekler. Belgeler, yöntemi kullanılarak beginClassifyDocumentDocumentAnalysisClientözel bir sınıflandırıcı ile 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 bir belgenin genel olarak erişilebilir bir URL'sini kabul eden bir beginClassifyDocumentFromUrl karşılığı vardır.

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

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

Özel bir sınıflandırıcıyı eğitme hakkında daha fazla 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ı kullanarak DocumentModelAdministrationClient model oluşturmayı da destekler. Etiketli eğitim verilerinden bir model oluşturmak, kendi belgeleriniz üzerinde 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 belgelerini tutan bir Azure Depolama Blob kapsayıcısına SAS ile kodlanmış bir URL'yi kabul eder. Belge İstihbaratı servisinin altyapısı, kapsayıcıdaki dosyaları okuyacak ve içeriklerine göre bir model oluşturacaktır. Eğitim veri kapsayıcısının nasıl oluşturulacağı ve yapılandırılacağı hakkında daha fazla ayrıntı için, model oluşturmak için Belge Yönetim Bilgileri hizmetinin belgelerine bakın.

Programlı model oluşturma için bu yöntemleri sağlarken, Belge Yönetim Bilgileri hizmet ekibi, web üzerinde model oluşturmaya ve yönetmeye olanak tanıyan etkileşimli bir web uygulaması olan Document Intelligence Studio'yu oluşturmuştur.

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

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

Özel sınıflandırıcılar, yerine beginBuildDocumentModelyöntemi beginBuildDocumentClassifier kullanılarak benzer şekilde oluşturulur. Giriş eğitim verileri biraz farklı bir biçimde sağlandığından, özel bir 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 bir sınıflandırıcı için eğitim veri kümesi oluşturma hakkında daha fazla bilgi için Belge Yönetim Bilgileri hizmeti belgelerine bakın.

Modelleri yönetme

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

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

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

Sorun giderme

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

Ağaç kesimi

Loglamayı etkinleştirmek, hatalarla ilgili yararlı bilgilerin ortaya çıkması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, çalışma zamanında setLogLevel@azure/logger çağrılarak günlük tutma etkinleştirilebilir.

import { setLogLevel } from "@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

Yukarıdaki "Örnekler" bölümünde gösterilmeyen modelleri kopyalama ve oluşturma, model yönetimi işlemlerini listeleme ve modelleri silme gibi ç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 lütfen örnekler dizinine göz atın.

Katkıda Bulunmak

Bu kitaplığa katkıda bulunmak istiyorsanız kodu oluşturma ve test etme hakkında daha fazla bilgi edinmek için lütfen katkıda bulunma kılavuzu okuyun.