Migrasi Kecerdasan Dokumen v3.1

  • Artikel

Konten ini berlaku untuk:checkmarkv4.0 (pratinjau)checkmarkv3.1 (GA)checkmarkv3.0 (GA)checkmarkv2.1 (GA)

Penting

REST API Kecerdasan Dokumen v3.1 memperkenalkan perubahan yang melanggar dalam permintaan REST API dan menganalisis respons JSON.

Migrasi dari versi API pratinjau v3.1

API pratinjau tidak digunakan lagi secara berkala. Jika Anda menggunakan versi API pratinjau, perbarui aplikasi Anda untuk menargetkan versi GA API. Untuk bermigrasi dari versi API pratinjau 2023-02-28 ke 2023-07-31 versi API (GA) menggunakan SDK, perbarui ke versi SDK spesifik bahasa saat ini.

2023-07-31 API (GA) memiliki beberapa pembaruan dan perubahan dari versi API pratinjau:

  • Fitur yang diaktifkan secara default terbatas pada yang penting untuk model tertentu dengan manfaat berkurangnya latensi dan ukuran respons. Fitur yang ditambahkan dapat diaktifkan melalui nilai enum dalam features parameter.
  • Beberapa fitur tata letak dari bawaan-baca dan keyValuePairs di luar bawaan-{dokumen,faktur} tidak lagi didukung.
  • Menonaktifkan kode batang secara default untuk prabuilt-read dan prebuilt-layout, bahasa untuk prebuilt-read, dan keyValuePairs untuk prebuilt-invoice.
  • Ekstraksi anotasi dihapus.
  • Bidang kueri dan nama umum pasangan kunci-nilai dihapus.
  • File Office/HTML didukung dalam model baca bawaan, mengekstrak kata dan paragraf tanpa kotak pembatas. Gambar yang disematkan tidak lagi didukung. Jika fitur add-on diminta untuk file Office/HTML, array kosong dikembalikan tanpa kesalahan.

Fitur analisis

ID Model Ekstraksi Teks Paragraf Peran Paragraf Tanda Pilihan Tabel Pasangan Kunci-Nilai Bahasa Barcode Analisis Dokumen Rumus* StyleFont* Resolusi Tinggi OCR*
baca bawaan ✓ ✓ O O O O O
prebuilt-layout ✓ ✓ ✓ ✓ ✓ O O O O O
dokumen-bawaan ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-businessCard ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
Faktur Bawaan ✓ ✓ ✓ O O O ✓ O O O
tanda terima bawaan ✓ O O ✓ O O O
prebuilt-healthInsuranceCard.us ✓ O O ✓ O O O
prebuilt-tax.us.w2 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098 ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098E ✓ ✓ O O ✓ O O O
prebuilt-tax.us.1098T ✓ ✓ O O ✓ O O O
kontrak bawaan ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ - Diaktifkan O - Rumus Opsional/StyleFont/OCR Resolusi Tinggi* - Fitur premium dikenakan biaya tambahan

Migrasi dari v3.0

Dibandingkan dengan v3.0, Kecerdasan Dokumen v3.1 memperkenalkan beberapa fitur dan kemampuan baru:

  • Ekstraksi kode batang .
  • Kemampuan add-on termasuk ekstraksi properti resolusi tinggi, rumus, dan font.
  • Model klasifikasi kustom untuk pemisahan dan klasifikasi dokumen.
  • Dukungan ekspansi bahasa dan bidang baru dalam model Faktur dan Tanda Terima .
  • Dukungan jenis dokumen baru dalam model dokumen ID.
  • Model kartu asuransi Kesehatan bawaan baru.
  • File Office/HTML didukung dalam model baca bawaan, mengekstrak kata dan paragraf tanpa kotak pembatas. Gambar yang disematkan tidak lagi didukung. Jika fitur add-on diminta untuk file Office/HTML, array kosong dikembalikan tanpa kesalahan.
  • Kedaluwarsa model untuk model ekstraksi dan klasifikasi kustom - Model kustom baru kami dibangun berdasarkan model dasar besar yang kami perbarui secara berkala untuk peningkatan kualitas. Tanggal kedaluwarsa diperkenalkan ke semua model kustom untuk memungkinkan penghentian model dasar yang sesuai. Setelah model kustom kedaluwarsa, Anda perlu melatih kembali model menggunakan versi API terbaru (model dasar).
GET /documentModels/{customModelId}?api-version={apiVersion}
{
  "modelId": "{customModelId}",
  "description": "{customModelDescription}",
  "createdDateTime": "2023-09-24T12:54:35Z",
  "expirationDateTime": "2025-01-01T00:00:00Z",
  "apiVersion": "2023-07-31",
  "docTypes": { ... }
}
  • Kuota build model neural kustom - Jumlah model neural yang dapat dibangun setiap langganan per wilayah setiap bulan terbatas. Kami memperluas hasil JSON untuk menyertakan kuota dan informasi yang digunakan untuk membantu Anda memahami penggunaan saat ini sebagai bagian dari informasi sumber daya yang dikembalikan oleh GET /info.
{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}
  • Parameter kueri opsional features untuk Menganalisis operasi dapat mengaktifkan fitur tertentu secara opsional. Beberapa fitur premium dapat dikenakan penagihan tambahan. Lihat Menganalisis daftar fitur untuk detailnya.
  • Perluas objek bidang mata uang yang diekstrak untuk menghasilkan bidang kode mata uang yang dinormalisasi jika memungkinkan. Saat ini, bidang saat ini dapat mengembalikan jumlah (misalnya 123,45) dan mata uangSymbol (misalnya $). Fitur ini memetakan simbol mata uang ke kode ISO 4217 kanonis (misalnya USD). Model ini dapat secara opsional menggunakan konten dokumen global untuk membedakan atau menyimpulkan kode mata uang.
{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Selain peningkatan kualitas model, Anda sangat disarankan untuk memperbarui aplikasi Anda untuk menggunakan v3.1 untuk mendapatkan manfaat dari kemampuan baru ini.

Migrasi dari v2.1 atau v2.0

Kecerdasan Dokumen v3.1 adalah versi GA terbaru dengan fitur terkaya, sebagian besar bahasa dan cakupan jenis dokumen, dan kualitas model yang ditingkatkan. Lihat gambaran umum model untuk fitur dan kemampuan yang tersedia di v3.1.

Mulai dari v3.0, REST API Kecerdasan Dokumen dirancang ulang untuk kegunaan yang lebih baik. Di bagian ini, pelajari perbedaan antara Kecerdasan Dokumen v2.0, v2.1 dan v3.1 dan cara pindah ke versi API yang lebih baru.

Perhatian

  • Rilis REST API 2023-07-31 mencakup perubahan yang melanggar dalam respons analisis REST API JSON.
  • Properti boundingBox diganti namanya menjadi polygon di setiap instans.

Perubahan pada titik akhir REST API

REST API v3.1 menggabungkan operasi analisis untuk analisis tata letak, model bawaan, dan model kustom ke dalam satu pasang operasi dengan menetapkan documentModels dan modelId ke analisis tata letak (tata letak bawaan) dan model bawaan.

Permintaan POST

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31

Permintaan GET

https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31

Operasi Analyze

  • Payload permintaan dan pola panggilan tetap tidak berubah.
  • Operasi Analyze menentukan dokumen input dan konfigurasi khusus konten, operasi ini mengembalikan URL hasil analisis melalui header Operation-Location dalam respons.
  • Polling URL Hasil Analisis ini, melalui permintaan GET untuk memeriksa status operasi analisis (interval minimum yang disarankan antara permintaan adalah 1 detik).
  • Setelah sukses, status diatur ke berhasil dan analyzeResult dikembalikan dalam badan respons. Jika terjadi kesalahan, status diatur ke failed, dan kesalahan dikembalikan.
Model v2.0 v2.1 v3.1
Meminta prefiks URL https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Dokumen umum T/A T/A /documentModels/prebuilt-document:analyze
Tata letak /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Adat /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Faktur T/A /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Tanda terima /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Dokumen ID T/A /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Kartu nama T/A /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 T/A T/A /documentModels/prebuilt-tax.us.w2:analyze
Kartu asuransi kesehatan T/A T/A /documentModels/prebuilt-healthInsuranceCard.us:analyze
Kontrak T/A T/A /documentModels/prebuilt-contract:analyze

Menganalisis badan permintaan

Konten yang akan dianalisis disediakan melalui badan permintaan. Baik URL atau data yang dikodekan base64 dapat digunakan untuk membuat permintaan.

Untuk menentukan URL web yang dapat diakses publik, atur Jenis Konten keapplication/json dan kirim isi JSON berikut:

{
  "urlSource": "{urlPath}"
}

Pengodean Base 64 juga didukung dalam Kecerdasan Dokumen v3.0:

{
  "base64Source": "{base64EncodedContent}"
}

Parameter tambahan yang didukung

Parameter yang terus didukung:

  • pages : Hanya menganalisis subset halaman tertentu dalam dokumen. Daftar nomor halaman yang diindeks dari angka 1 untuk dianalisis. Mis. "1-3,5,7-9"
  • locale : Petunjuk lokal untuk pengenalan teks dan analisis dokumen. Nilai hanya dapat berisi kode bahasa (misalnya , enfr) atau tag bahasa BCP 47 (mis. "en-US").

Paramater yang tidak lagi didukung:

  • includeTextDetails

Format respons baru lebih ringkas dan output penuh selalu dikembalikan.

Perubahan untuk hasil analisis

Respons analisis direfaktor ke hasil tingkat atas berikut untuk mendukung elemen multi-halaman.

  • pages
  • tables
  • keyValuePairs
  • entities
  • styles
  • documents

Catatan

Perubahan respons AnalyzeResult mencakup sejumlah perubahan seperti naik dari properti halaman ke properti tingkat atas dalam analyzeResult.


{
// Basic analyze result metadata
"apiVersion": "2022-08-31", // REST API version used
"modelId": "prebuilt-invoice", // ModelId used
"stringIndexType": "textElements", // Character unit used for string offsets and lengths:
// textElements, unicodeCodePoint, utf16CodeUnit // Concatenated content in global reading order across pages.
// Words are generally delimited by space, except CJK (Chinese, Japanese, Korean) characters.
// Lines and selection marks are generally delimited by newline character.
// Selection marks are represented in Markdown emoji syntax (:selected:, :unselected:).
"content": "CONTOSO LTD.\nINVOICE\nContoso Headquarters...", "pages": [ // List of pages analyzed
{
// Basic page metadata
"pageNumber": 1, // 1-indexed page number
"angle": 0, // Orientation of content in clockwise direction (degree)
"width": 0, // Page width
"height": 0, // Page height
"unit": "pixel", // Unit for width, height, and polygon coordinates
"spans": [ // Parts of top-level content covered by page
{
"offset": 0, // Offset in content
"length": 7 // Length in content
}
], // List of words in page
"words": [
{
"text": "CONTOSO", // Equivalent to $.content.Substring(span.offset, span.length)
"boundingBox": [ ... ], // Position in page
"confidence": 0.99, // Extraction confidence
"span": { ... } // Part of top-level content covered by word
}, ...
], // List of selectionMarks in page
"selectionMarks": [
{
"state": "selected", // Selection state: selected, unselected
"boundingBox": [ ... ], // Position in page
"confidence": 0.95, // Extraction confidence
"span": { ... } // Part of top-level content covered by selection mark
}, ...
], // List of lines in page
"lines": [
{
"content": "CONTOSO LTD.", // Concatenated content of line (may contain both words and selectionMarks)
"boundingBox": [ ... ], // Position in page
"spans": [ ... ], // Parts of top-level content covered by line
}, ...
]
}, ...
], // List of extracted tables
"tables": [
{
"rowCount": 1, // Number of rows in table
"columnCount": 1, // Number of columns in table
"boundingRegions": [ // Polygons or Bounding boxes potentially across pages covered by table
{
"pageNumber": 1, // 1-indexed page number
"polygon": [ ... ], // Previously Bounding box, renamed to polygon in the 2022-08-31 API
}
],
"spans": [ ... ], // Parts of top-level content covered by table // List of cells in table
"cells": [
{
"kind": "stub", // Cell kind: content (default), rowHeader, columnHeader, stub, description
"rowIndex": 0, // 0-indexed row position of cell
"columnIndex": 0, // 0-indexed column position of cell
"rowSpan": 1, // Number of rows spanned by cell (default=1)
"columnSpan": 1, // Number of columns spanned by cell (default=1)
"content": "SALESPERSON", // Concatenated content of cell
"boundingRegions": [ ... ], // Bounding regions covered by cell
"spans": [ ... ] // Parts of top-level content covered by cell
}, ...
]
}, ...
], // List of extracted key-value pairs
"keyValuePairs": [
{
"key": { // Extracted key
"content": "INVOICE:", // Key content
"boundingRegions": [ ... ], // Key bounding regions
"spans": [ ... ] // Key spans
},
"value": { // Extracted value corresponding to key, if any
"content": "INV-100", // Value content
"boundingRegions": [ ... ], // Value bounding regions
"spans": [ ... ] // Value spans
},
"confidence": 0.95 // Extraction confidence
}, ...
],
"styles": [
{
"isHandwritten": true, // Is content in this style handwritten?
"spans": [ ... ], // Spans covered by this style
"confidence": 0.95 // Detection confidence
}, ...
], // List of extracted documents
"documents": [
{
"docType": "prebuilt-invoice", // Classified document type (model dependent)
"boundingRegions": [ ... ], // Document bounding regions
"spans": [ ... ], // Document spans
"confidence": 0.99, // Document splitting/classification confidence // List of extracted fields
"fields": {
"VendorName": { // Field name (docType dependent)
"type": "string", // Field value type: string, number, array, object, ...
"valueString": "CONTOSO LTD.",// Normalized field value
"content": "CONTOSO LTD.", // Raw extracted field content
"boundingRegions": [ ... ], // Field bounding regions
"spans": [ ... ], // Field spans
"confidence": 0.99 // Extraction confidence
}, ...
}
}, ...
]
}

Membangun atau melatih model

Objek model memiliki tiga pembaruan di API baru

  • modelId sekarang adalah properti yang dapat diatur pada model untuk nama yang dapat dibaca manusia.
  • modelName berganti nama menjadi description
  • buildMode adalah properti dengan nilai template untuk model formulir kustom neural untuk model neural kustom.

Operasi build ini dipanggil untuk melatih model. Payload permintaan dan pola panggilan tetap tidak berubah. Operasi build menentukan model dan himpunan data pelatihan, yang mengembalikan hasilnya melalui header Operation-Location dalam respons. Polling URL operasi model ini, melalui permintaan GET untuk memeriksa status operasi build (interval minimum yang disarankan antara permintaan adalah 1 detik). Tidak seperti v2.1, URL ini bukan lokasi sumber daya model. Sebagai gantinya, URL model dapat dibangun dari modelId yang diberikan, juga diambil dari properti resourceLocation dalam respons. Setelah sukses, status diatur ke succeeded dan hasilnya berisi info model kustom. Jika kesalahan ditemukan, status ditetapkan ke failed dan kesalahan akan ditampilkan.

Kode berikut adalah permintaan build sampel menggunakan token SAS. Perhatikan garis miring belakangnya saat mengatur awalan atau jalur folder.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:build?api-version=2022-08-31

{
  "modelId": {modelId},
  "description": "Sample model",
  "buildMode": "template",
  "azureBlobSource": {
    "containerUrl": "https://{storageAccount}.blob.core.windows.net/{containerName}?{sasToken}",
    "prefix": "{folderName/}"
  }
}

Perubahan untuk compose

Model compose sekarang terbatas pada satu tingkat dimensi. Model yang disusun sekarang konsisten dengan model kustom dengan penambahan properti modelId dan description.

POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
  "modelId": "{composedModelId}",
  "description": "{composedModelDescription}",
  "componentModels": [
    { "modelId": "{modelId1}" },
    { "modelId": "{modelId2}" },
  ]
}

Perubahan pada model salin

Pola panggilan untuk model salin tetap tidak berubah:

  • Otorisasi operasi salin dengan panggilan sumber daya target authorizeCopy. Sekarang permintaan POST.
  • Kirimkan otorisasi ke sumber daya sumber untuk menyalin panggilan model copyTo
  • Polling operasi yang dikembalikan untuk memvalidasi operasi berhasil selesai

Satu-satunya perubahan pada fungsi model salin adalah:

  • Tindakan HTTP pada authorizeCopy sekarang adalah permintaan POST.
  • Payload otorisasi berisi semua informasi yang diperlukan untuk mengirimkan permintaan salin.

Mengotorisasi salinan

POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
  "modelId": "{targetModelId}",
  "description": "{targetModelDescription}",
}

Gunakan badan respons dari tindakan otorisasi untuk membangun permintaan untuk salinan.

POST https://{sourceHost}/formrecognizer/documentModels/{sourceModelId}:copyTo?api-version=2022-08-31
{
  "targetResourceId": "{targetResourceId}",
  "targetResourceRegion": "{targetResourceRegion}",
  "targetModelId": "{targetModelId}",
  "targetModelLocation": "https://{targetHost}/formrecognizer/documentModels/{targetModelId}",
  "accessToken": "{accessToken}",
  "expirationDateTime": "2021-08-02T03:56:11Z"
}

Perubahan pada model daftar

Model daftar diperluas untuk sekarang mengembalikan model bawaan dan kustom. Semua nama model bawaan dimulai dengan prebuilt-. Hanya model dengan status berhasil yang dikembalikan. Untuk membuat daftar model yang gagal atau sedang berlangsung, lihat Operasi Daftar.

Contoh permintaan model daftar

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31

Perubahan untuk model GET

Karena model get sekarang mencakup model bawaan, operasi get mengembalikan kamus docTypes. Setiap deskripsi jenis dokumen mencakup nama, deskripsi opsional, skema bidang, dan keyakinan bidang opsional. Skema bidang menjelaskan daftar bidang yang berpotensi dikembalikan dengan jenis dokumen.

GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31

Operasi get info baru

Operasi info pada layanan mengembalikan jumlah model kustom dan batas model kustom.

GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31

Respons sampel

{
  "customDocumentModels": {
    "count": 5,
    "limit": 100
  }
}

Langkah berikutnya