Belge Yönetim Bilgileri v3.1 geçişi

  • Makale

Bu içerik şunlar için geçerlidir:checkmark v4.0 (önizleme)checkmarkv3.1 (GA)checkmarkv3.0 (GA)checkmarkv2.1 (GA)

Önemli

Document Intelligence REST API v3.1, REST API isteğinde hataya neden olan değişiklikler sunar ve JSON yanıtını analiz eder.

v3.1 önizleme API sürümünden geçiş

Önizleme API'leri düzenli aralıklarla kullanım dışıdır. Önizleme API'sinin sürümünü kullanıyorsanız uygulamanızı GA API sürümünü hedef alan şekilde güncelleştirin. SDK'yı kullanarak 2023-02-28-preview API sürümünden 2023-07-31 (GA) API sürümüne geçmek için, dile özgü SDK'nın geçerli sürümüne güncelleştirin.

2023-07-31 (GA) API'sinde önizleme API'sinin sürümünden birkaç güncelleştirme ve değişiklik vardır:

  • Varsayılan olarak etkinleştirilen özellikler, düşük gecikme süresi ve yanıt boyutu avantajıyla belirli bir model için gerekli olan özelliklerle sınırlıdır. Eklenen özellikler parametresindeki features sabit listesi değerleri aracılığıyla etkinleştirilebilir.
  • Önceden oluşturulmuş-okuma ve keyValuePair'lerden önceden oluşturulmuş-{document,invoice} dışındaki bazı düzen özellikleri artık desteklenmemektedir.
  • Önceden oluşturulmuş-okunmuş ve önceden oluşturulmuş düzen için barkodları varsayılan olarak devre dışı bırakma, önceden oluşturulmuş okuma dilleri ve önceden oluşturulmuş fatura için keyValuePairs.
  • Ek açıklama ayıklama kaldırılır.
  • Sorgu alanları ve anahtar-değer çiftlerinin ortak adları kaldırılır.
  • Office/HTML dosyaları, kutuları sınırlamadan sözcükleri ve paragrafları ayıklayarak önceden oluşturulmuş okuma modelinde desteklenir. Katıştırılmış görüntüler artık desteklenmiyor. Office/HTML dosyaları için eklenti özellikleri istenirse, hatasız boş bir dizi döndürülür.

Analiz özellikleri

Model Kimliği Metin Ayıklama Paragraf Paragraf Rolleri Seçim İşaretleri Tablolar Anahtar-Değer Çiftleri Diller Barkod Belge Analizi Formül* StyleFont* OCR Yüksek Çözünürlük*
önceden oluşturulmuş okuma ✓ ✓ O O O O O
önceden oluşturulmuş düzen ✓ ✓ ✓ ✓ ✓ O O O O O
önceden oluşturulmuş belge ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
önceden oluşturulmuş businessCard ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
önceden oluşturulmuş fatura ✓ ✓ ✓ O O O ✓ O O O
önceden oluşturulmuş makbuz ✓ O O ✓ O O O
prebuilt-healthInsuranceCard.us ✓ O O ✓ O O O
prebuilt-tax.us.w2 ✓ ✓ O O ✓ O O O
önceden oluşturulmuş 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
önceden oluşturulmuş sözleşme ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ - Etkin O - İsteğe Bağlı Formüller/StyleFont/OCR Yüksek Çözünürlük* - Ek maliyetler doğuran premium özellikler

v3.0'dan geçiş

v3.0 ile karşılaştırıldığında, Document Intelligence v3.1 birkaç yeni özellik ve özellik sunar:

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": { ... }
}
  • Özel sinir modeli derleme kotası - Her aboneliğin her ay bölge başına oluşturabileceği sinir modeli sayısı sınırlıdır. Sonuç JSON değerini kotayı içerecek şekilde genişlettik ve GET /info tarafından döndürülen kaynak bilgilerinin bir parçası olarak geçerli kullanımı anlamanıza yardımcı olmak için bilgileri kullandık.
{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}
  • İşlemleri analiz etmek için isteğe bağlı features bir sorgu parametresi, isteğe bağlı olarak belirli özellikleri etkinleştirebilir. Bazı premium özellikler ek faturalamaya neden olabilir. Ayrıntılar için Özellik listesini analiz etme bölümüne bakın.
  • Mümkün olduğunda normalleştirilmiş bir para birimi kodu alanı çıkarmak için ayıklanan para birimi alanı nesnelerini genişletin. Şu anda, geçerli alanlar tutar (örn. 123,45) ve currencySymbol (örn. $) döndürebilir. Bu özellik, para birimi simgesini kurallı iso 4217 koduyla (ör. ABD doları) eşler. Model isteğe bağlı olarak genel belge içeriğini kullanarak para birimi kodunu kesinleştirebilir veya çıkarsayabilir.
{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Model kalitesini iyileştirmenin yanı sıra, bu yeni özelliklerden yararlanmak için uygulamanızı v3.1 kullanacak şekilde güncelleştirmeniz kesinlikle önerilir.

v2.1 veya v2.0'dan geçiş

Document Intelligence v3.1, en zengin özelliklere, çoğu dil ve belge türü kapsamına ve geliştirilmiş model kalitesine sahip en son GA sürümüdür. v3.1'de kullanılabilen özellikler ve özellikler için modele genel bakış bölümüne bakın.

v3.0'dan başlayarak, Daha iyi kullanılabilirlik için Belge Zekası REST API'si yeniden tasarlanmıştır. Bu bölümde, Belge Zekası v2.0, v2.1 ve v3.1 arasındaki farkları ve API'nin daha yeni sürümüne nasıl geçeceğinizi öğrenin.

Dikkat

  • REST API 2023-07-31 sürümü REST API analiz yanıtı JSON'unda hataya neden olan bir değişiklik içerir.
  • boundingBox Özelliği her örnekte olarak polygon yeniden adlandırılır.

REST API uç noktalarındaki değişiklikler

v3.1 REST API düzen analizi, önceden oluşturulmuş modeller ve özel modeller için çözümleme işlemlerini düzen analizi (önceden oluşturulmuş düzen) ve modelId önceden oluşturulmuş modeller atayarak documentModels tek bir işlem çiftinde birleştirir.

POST isteği

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

GET isteği

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

İşlemi analiz etme

  • İstek yükü ve çağrı düzeni değişmeden kalır.
  • Çözümle işlemi giriş belgesini ve içeriğe özgü yapılandırmaları belirtir, yanıttaki Operation-Location üst bilgisi aracılığıyla analiz sonucu URL'sini döndürür.
  • Analiz işleminin durumunu denetlemek için bir GET isteği aracılığıyla bu Çözümleme Sonucu URL'sini yok edin (istekler arasında önerilen en düşük aralık 1 saniyedir).
  • Başarılı olduğunda durum başarılı olarak ayarlanır ve yanıt gövdesinde analyzeResult döndürülür. Hatalarla karşılaşılırsa, durum olarak ayarlanır failedve bir hata döndürülür.
Model v2.0 v2.1 v3.1
İstek URL'si ön eki https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Genel belge Geçersiz Geçersiz /documentModels/prebuilt-document:analyze
Düzen /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Özel /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Fatura Yok /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Makbuz /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
Kimlik belgesi Yok /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Kartvizit Yok /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 Geçersiz Geçersiz /documentModels/prebuilt-tax.us.w2:analyze
Sağlık sigortası kartı Geçersiz Geçersiz /documentModels/prebuilt-healthInsuranceCard.us:analyze
Sözleşme Geçersiz Geçersiz /documentModels/prebuilt-contract:analyze

İstek gövdesini analiz etme

Analiz edilecek içerik istek gövdesi aracılığıyla sağlanır. İsteği oluşturmak için URL veya base64 ile kodlanmış veriler kullanıcı olabilir.

Genel olarak erişilebilen bir web URL'si belirtmek için İçerik Türü'nü application/json olarak ayarlayın ve aşağıdaki JSON gövdesini gönderin:

{
  "urlSource": "{urlPath}"
}

Temel 64 kodlaması, Belge Zekası v3.0'da da desteklenir:

{
  "base64Source": "{base64EncodedContent}"
}

Ayrıca desteklenen parametreler

Desteklenmeye devam eden parametreler:

  • pages : Belgedeki sayfaların yalnızca belirli bir alt kümesini analiz edin. Analiz edilen numaradan dizine alınan sayfa numaralarının 1 listesi. Örneğin "1-3,5,7-9"
  • locale : Metin tanıma ve belge analizi için yerel ayar ipucu. Değer yalnızca dil kodunu (örn. en, fr) veya BCP 47 dil etiketini (örn. "en-US") içerebilir.

Parametreler artık desteklenmiyor:

  • includeTextDetails

Yeni yanıt biçimi daha kompakttır ve her zaman tam çıkış döndürülür.

Sonucu analiz etmek için yapılan değişiklikler

Analiz yanıtı, çok sayfalı öğeleri desteklemek için aşağıdaki üst düzey sonuçlara yeniden düzenlenmiştir.

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

Dekont

analyzeResult yanıt değişiklikleri, sayfaların özelliğinden analyzeResult içindeki üst kaldıraç özelliğine geçme gibi çeşitli değişiklikler içerir.


{
// 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
}, ...
}
}, ...
]
}

Model oluşturma veya eğitma

Model nesnesinin yeni API'de üç güncelleştirmesi vardır

  • modelId artık bir modelde insan tarafından okunabilir bir ad için ayarlanabilen bir özelliktir.
  • modelName olarak yeniden adlandırıldı description
  • buildMode, özel form modelleri veya neural özel sinir modelleri için değerlerine template sahip yeni bir özelliktir.

Bir build modeli eğitmek için işlem çağrılır. İstek yükü ve çağrı düzeni değişmeden kalır. Derleme işlemi modeli ve eğitim veri kümesini belirtir, yanıtın Operation-Location üst bilgisi aracılığıyla sonucu döndürür. Derleme işleminin durumunu denetlemek için get isteği aracılığıyla bu model işlemi URL'sini yoklama (istekler arasında önerilen en düşük aralık 1 saniyedir). v2.1'in aksine, bu URL modelin kaynak konumu değildir. Bunun yerine, model URL'si verilen model Kimliği'nden oluşturulabilir ve yanıttaki resourceLocation özelliğinden de alınabilir. Başarılı olduğunda durum olarak ayarlanır succeeded ve sonuç özel model bilgilerini içerir. Hatalarla karşılaşılırsa, durum olarak failedayarlanır ve hata döndürülür.

Aşağıdaki kod, SAS belirteci kullanan örnek bir derleme isteğidir. Ön ek veya klasör yolunu ayarlarken sondaki eğik çizgiye dikkat edin.

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/}"
  }
}

Model oluşturma değişiklikleri

Model oluşturma artık tek iç içe yerleştirme düzeyiyle sınırlıdır. Oluşturulan modeller artık ve description özelliklerinin eklenmesiyle modelId özel modellerle tutarlı hale geliyor.

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

Modeli kopyalama değişiklikleri

Kopyalama modeli için çağrı düzeni değişmeden kalır:

  • Kopyalama işlemini hedef kaynak çağrısıyla authorizeCopyyetkilendirilin. Şimdi bir POST isteği.
  • Model çağrısını kopyalamak için kaynak kaynağa yetkilendirmeyi gönderin copyTo
  • İşlemin başarıyla tamamlandığını doğrulamak için döndürülen işlemi yoklama

Kopyalama modeli işlevinde yapılan tek değişiklikler şunlardır:

  • üzerindeki authorizeCopy HTTP eylemi artık bir POST isteğidir.
  • Yetkilendirme yükü, kopyalama isteğini göndermek için gereken tüm bilgileri içerir.

Kopyayı yetkilendirme

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

Kopyalama isteğini oluşturmak için yetkilendirme eyleminden yanıt gövdesini kullanın.

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"
}

Liste modellerinde yapılan değişiklikler

Liste modelleri artık önceden oluşturulmuş ve özel modeller döndürecek şekilde genişletilmiştir. Önceden oluşturulmuş tüm model adları ile prebuilt-başlar. Yalnızca durumu başarılı olan modeller döndürülür. Başarısız olan veya devam eden modelleri listelemek için bkz . İşlemleri Listeleme.

Örnek liste modelleri isteği

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

Modeli almak için değiştirme

Get modeli artık önceden oluşturulmuş modelleri içerdiğinden get işlemi bir docTypes sözlük döndürür. Her belge türü açıklaması ad, isteğe bağlı açıklama, alan şeması ve isteğe bağlı alan güvenilirliği içerir. Alan şeması, belge türüyle döndürülme olasılığı olan alanların listesini açıklar.

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

Yeni bilgi alma işlemi

info Hizmet üzerindeki işlem, özel model sayısını ve özel model sınırını döndürür.

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

Örnek yanıt

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

Sonraki adımlar