Migracja analizy dokumentów w wersji 3.1
Ta zawartość dotyczy:
v4.0 (wersja zapoznawcza)v3.1 (GA)v3.0 (GA)v2.1 (GA)
Ważne
Interfejs API REST analizy dokumentów w wersji 3.1 wprowadza zmiany powodujące niezgodność w żądaniu interfejsu API REST i analizują dane JSON odpowiedzi.
Migrowanie z wersji 3.1 w wersji zapoznawczej interfejsu API
Interfejsy API w wersji zapoznawczej są okresowo przestarzałe. Jeśli używasz wersji zapoznawczej interfejsu API, zaktualizuj aplikację do wersji interfejsu API ogólnodostępnej. Aby przeprowadzić migrację z wersji interfejsu API 2023-02-28-preview do 2023-07-31 wersji interfejsu API (GA) przy użyciu zestawu SDK, zaktualizuj do bieżącej wersji zestawu SDK specyficznego dla języka.
Interfejs 2023-07-31 API (GA) zawiera kilka aktualizacji i zmian w wersji zapoznawczej interfejsu API:
- Funkcje, które są domyślnie włączone, są ograniczone do tych, które są niezbędne do określonego modelu z korzyścią dla mniejszego opóźnienia i rozmiaru odpowiedzi. Dodatkowe funkcje można włączyć za pomocą wartości wyliczenia w parametrze
features. - Niektóre funkcje układu ze wstępnie utworzonego odczytu i parametru keyValuePairs poza wstępnie utworzonym dokumentem,fakturą} nie są już obsługiwane.
- Wyłączenie kodów kreskowych domyślnie dla wstępnie utworzonego i wstępnie utworzonego układu, języków wstępnie skompilowanego odczytu i parametru keyValuePairs dla wstępnie utworzonej faktury.
- Wyodrębnianie adnotacji jest usuwane.
- Pola zapytań i nazwy pospolite par klucz-wartość są usuwane.
- Pliki pakietu Office/HTML są obsługiwane w wstępnie utworzonym modelu odczytu, wyodrębniając wyrazy i akapity bez pól ograniczenia. Obrazy osadzone nie są już obsługiwane. Jeśli wymagane są funkcje dodatku dla plików pakietu Office/HTML, pusta tablica jest zwracana bez błędów.
Funkcje analizy
| Model ID | Wyodrębnianie tekstu | Ustępów | Role akapitu | Znaczniki zaznaczenia | Tabele | Pary klucz-wartość | Języki | Kodów kreskowych | Analiza dokumentów | Formuły* | StyleFont* | Wysoka rozdzielczość OCR* |
|---|---|---|---|---|---|---|---|---|---|---|---|---|
| odczyt wstępnie utworzony | ✓ | ✓ | O | O | O | O | O | |||||
| wstępnie utworzony układ | ✓ | ✓ | ✓ | ✓ | ✓ | O | O | O | O | O | ||
| wstępnie utworzony dokument | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | O | O | O | O | O | |
| wstępnie utworzona karta biznesowa | ✓ | ✓ | ||||||||||
| prebuilt-idDocument | ✓ | O | O | ✓ | O | O | O | |||||
| wstępnie utworzona faktura | ✓ | ✓ | ✓ | O | O | O | ✓ | O | O | O | ||
| wstępnie utworzone potwierdzenie | ✓ | 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 | ||||
| wstępnie utworzony kontrakt | ✓ | ✓ | ✓ | ✓ | O | O | ✓ | O | O | O | ||
| { customModelName } | ✓ | ✓ | ✓ | ✓ | ✓ | O | O | ✓ | O | O | O |
√ - Włączone O - Opcjonalne formuły/StyleFont/OCR High Resolution* — funkcje w warstwie Premium generują dodatkowe koszty
Migrowanie z wersji 3.0
W porównaniu z wersją 3.0 analiza dokumentów w wersji 3.1 wprowadza kilka nowych funkcji i możliwości:
- Wyodrębnianie kodów kreskowych .
- Funkcje dodatków, w tym wyodrębnianie właściwości o wysokiej rozdzielczości, formule i czcionki.
- Niestandardowy model klasyfikacji dla podziału i klasyfikacji dokumentów.
- Rozszerzenie języka i nowe pola obsługują model faktur i paragonów .
- Obsługa nowego typu dokumentu w modelu dokumentów identyfikatorów .
- Nowy wstępnie utworzony model karty ubezpieczenia zdrowotnego.
- Pliki pakietu Office/HTML są obsługiwane w wstępnie utworzonym modelu odczytu, wyodrębniając wyrazy i akapity bez pól ograniczenia. Obrazy osadzone nie są już obsługiwane. Jeśli wymagane są funkcje dodatku dla plików pakietu Office/HTML, pusta tablica jest zwracana bez błędów.
- Wygaśnięcie modelu dla niestandardowych modeli wyodrębniania i klasyfikacji — nasze nowe modele niestandardowe są oparte na dużym modelu podstawowym, który okresowo aktualizujemy w celu poprawy jakości. Data wygaśnięcia jest wprowadzana do wszystkich modeli niestandardowych w celu umożliwienia wycofania odpowiednich modeli podstawowych. Po wygaśnięciu modelu niestandardowego należy ponownie wytrenować model przy użyciu najnowszej wersji interfejsu API (modelu podstawowego).
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": { ... }
}
- Limit przydziału kompilacji niestandardowego modelu neuronowego — liczba modeli neuronowych, które każda subskrypcja może tworzyć w poszczególnych regionach każdego miesiąca, jest ograniczona. Rozszerzymy wynik JSON, aby uwzględnić limit przydziału i użyte informacje, aby ułatwić zrozumienie bieżącego użycia w ramach informacji o zasobie zwracanych przez polecenie GET /info.
{
"customDocumentModels": { ... },
"customNeuralDocumentModelBuilds": {
"used": 1,
"quota": 10,
"quotaResetDateTime": "2023-03-01T00:00:00Z"
}
}
- Opcjonalny
featuresparametr zapytania do funkcji Analizuj operacje może opcjonalnie włączyć określone funkcje. Niektóre funkcje w warstwie Premium mogą powodować naliczanie dodanych rozliczeń. Aby uzyskać szczegółowe informacje, zobacz Analizowanie listy funkcji. - Rozszerz wyodrębnione obiekty pól waluty, aby w miarę możliwości wygenerować znormalizowane pole kodu waluty. Obecnie bieżące pola mogą zwracać kwotę (np. 123,45) i walutĘSymbol (np. $). Ta funkcja mapuje symbol waluty na kanoniczny kod ISO 4217 (np. USD). Model może opcjonalnie używać globalnej zawartości dokumentu do uściślania lub wnioskowania kodu waluty.
{
"fields": {
"Total": {
"type": "currency",
"content": "$123.45",
"valueCurrency": {
"amount": 123.45,
"currencySymbol": "$",
"currencyCode": "USD"
},
...
}
}
}
Oprócz poprawy jakości modelu zdecydowanie zaleca się zaktualizowanie aplikacji do korzystania z wersji 3.1 w celu skorzystania z tych nowych funkcji.
Migrowanie z wersji 2.1 lub 2.0
Analiza dokumentów w wersji 3.1 to najnowsza wersja ogólnie dostępna z najbogatszymi funkcjami, większością języków i pokryciem typów dokumentów oraz ulepszoną jakością modelu. Zapoznaj się z omówieniem modelu, aby zapoznać się z funkcjami i możliwościami dostępnymi w wersji 3.1.
Począwszy od wersji 3.0, interfejs API REST analizy dokumentów został przeprojektowany w celu zapewnienia lepszej użyteczności. W tej sekcji poznasz różnice między analizą dokumentów w wersji 2.0, 2.1 i 3.1 oraz dowiedz się, jak przejść do nowszej wersji interfejsu API.
Uwaga
- Interfejs API REST 2023-07-31 zawiera zmianę powodującą niezgodność w kodzie JSON analizy odpowiedzi interfejsu API REST.
- Nazwa
boundingBoxwłaściwości jest zmieniana napolygonw każdym wystąpieniu.
Zmiany w punktach końcowych interfejsu API REST
Interfejs API REST w wersji 3.1 łączy operacje analizy układu, wstępnie utworzone modele i modele niestandardowe w jedną parę operacji, przypisując documentModels i modelId do analizy układu (wstępnie utworzony układ) i wstępnie utworzonych modeli.
Żądanie POST
https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2023-07-31
Żądanie GET
https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}/AnalyzeResult/{resultId}?api-version=2023-07-31
Operacja analizowania
- Ładunek żądania i wzorzec wywołania pozostają niezmienione.
- Operacja Analizuj określa konfiguracje dokumentu wejściowego i specyficzne dla zawartości. Zwraca on adres URL wyniku analizy za pośrednictwem nagłówka Operation-Location w odpowiedzi.
- Sonduj ten adres URL wyniku analizy za pośrednictwem żądania GET, aby sprawdzić stan operacji analizy (minimalny zalecany interwał między żądaniami wynosi 1 sekundę).
- Po pomyślnym zakończeniu stan jest ustawiony na powodzenie, a funkcja analyzeResult jest zwracana w treści odpowiedzi. Jeśli wystąpią błędy, zostanie ustawiony stan na
failed, a zwracany jest błąd.
| Model | Wersja 2.0 | Wersja 2.1 | Wersja 3.1 |
|---|---|---|---|
| Prefiks adresu URL żądania | https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 | https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 | https://{your-form-recognizer-endpoint}/formrecognizer |
| Dokument ogólny | Brak | Brak | /documentModels/prebuilt-document:analyze |
| Układ | /layout/analyze | /layout/analyze | /documentModels/prebuilt-layout:analyze |
| Okres niestandardowy | /custom/models/{modelId}/analyze | /custom/{modelId}/analyze | /documentModels/{modelId}:analyze |
| Faktura | Nie dotyczy | /prebuilt/invoice/analyze | /documentModels/prebuilt-invoice:analyze |
| Otrzymania | /prebuilt/receipt/analyze | /prebuilt/receipt/analyze | /documentModels/prebuilt-receipt:analyze |
| Dokument tożsamości | Nie dotyczy | /prebuilt/idDocument/analyze | /documentModels/prebuilt-idDocument:analyze |
| Wizytówka | Nie dotyczy | /prebuilt/businessCard/analyze | /documentModels/prebuilt-businessCard:analyze |
| W-2 | Brak | Brak | /documentModels/prebuilt-tax.us.w2:analyze |
| Karta ubezpieczenia zdrowotnego | Brak | Brak | /documentModels/prebuilt-healthInsuranceCard.us:analyze |
| Kontrakt | Brak | Brak | /documentModels/prebuilt-contract:analyze |
Analizowanie treści żądania
Zawartość do przeanalizowania jest dostarczana za pośrednictwem treści żądania. Adres URL lub zakodowane w formacie base64 dane mogą być użytkownikiem, aby utworzyć żądanie.
Aby określić publicznie dostępny internetowy adres URL, ustaw typ zawartości na wartość application/json i wyślij następującą treść JSON:
{
"urlSource": "{urlPath}"
}
Kodowanie Base 64 jest również obsługiwane w usłudze Document Intelligence w wersji 3.0:
{
"base64Source": "{base64EncodedContent}"
}
Dodatkowo obsługiwane parametry
Parametry, które nadal są obsługiwane:
pages: Analizowanie tylko określonego podzestawu stron w dokumencie. Lista numerów stron indeksowanych z liczby1do przeanalizowania. Np. "1-3,5,7-9"locale: Wskazówka ustawień regionalnych na potrzeby rozpoznawania tekstu i analizy dokumentów. Wartość może zawierać tylko kod języka (np.en,fr) lub tag języka BCP 47 (np. "en-US").
Parametry nie są już obsługiwane:
- includeTextDetails
Nowy format odpowiedzi jest bardziej kompaktowy, a pełne dane wyjściowe są zawsze zwracane.
Zmiany w wyniku analizy
Analiza odpowiedzi jest refaktoryzowana do następujących wyników najwyższego poziomu w celu obsługi elementów wielostronicowych.
pagestableskeyValuePairsentitiesstylesdocuments
Uwaga
Zmiany odpowiedzi analyzeResult obejmują wiele zmian, takich jak przejście z właściwości stron do właściwości górnej dźwigni w ramach funkcji 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
}, ...
}
}, ...
]
}
Kompilowanie lub trenowanie modelu
Obiekt modelu ma trzy aktualizacje w nowym interfejsie API
modelIdjest teraz właściwością, którą można ustawić w modelu dla nazwy czytelnej dla człowieka.modelNamezmieniono nazwę nadescriptionbuildModeto nowa właściwość z wartościamitemplateniestandardowych modeli formularzy lubneuralniestandardowych modeli neuronowych.
Operacja build jest wywoływana w celu wytrenowania modelu. Ładunek żądania i wzorzec wywołania pozostają niezmienione. Operacja kompilacji określa model i zestaw danych trenowania, zwraca wynik za pośrednictwem nagłówka Operation-Location w odpowiedzi. Sonduj ten adres URL operacji modelu za pośrednictwem żądania GET, aby sprawdzić stan operacji kompilacji (minimalny zalecany interwał między żądaniami wynosi 1 sekundę). W przeciwieństwie do wersji 2.1 ten adres URL nie jest lokalizacją zasobu modelu. Zamiast tego adres URL modelu można utworzyć z danego identyfikatora modelId, również pobrany z właściwości resourceLocation w odpowiedzi. Po pomyślnych krokach stan jest ustawiony na succeeded , a wynik zawiera informacje o modelu niestandardowym. Jeśli występują błędy, stan jest ustawiony na failed, a zwracany jest błąd.
Poniższy kod to przykładowe żądanie kompilacji przy użyciu tokenu SAS. Zwróć uwagę na końcowy ukośnik podczas ustawiania prefiksu lub ścieżki folderu.
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/}"
}
}
Zmiany w modelu redagowania
Tworzenie modelu jest teraz ograniczone do pojedynczego poziomu zagnieżdżania. Skomponowane modele są teraz spójne z modelami niestandardowymi z dodatkami modelId i description właściwościami.
POST https://{your-form-recognizer-endpoint}/formrecognizer/documentModels:compose?api-version=2022-08-31
{
"modelId": "{composedModelId}",
"description": "{composedModelDescription}",
"componentModels": [
{ "modelId": "{modelId1}" },
{ "modelId": "{modelId2}" },
]
}
Zmiany w kopiowaniu modelu
Wzorzec wywołania dla modelu kopiowania pozostaje niezmieniony:
- Autoryzuj operację kopiowania za pomocą zasobu docelowego wywołującego polecenie
authorizeCopy. Teraz żądanie POST. - Prześlij autoryzację do zasobu źródłowego, aby skopiować wywołanie modelu
copyTo - Sonduj zwróconą operację, aby zweryfikować pomyślne zakończenie operacji
Jedynymi zmianami funkcji modelu kopiowania są:
- Akcja HTTP w obiekcie
authorizeCopyjest teraz żądaniem POST. - Ładunek autoryzacji zawiera wszystkie informacje potrzebne do przesłania żądania kopiowania.
Autoryzowanie kopii
POST https://{targetHost}/formrecognizer/documentModels:authorizeCopy?api-version=2022-08-31
{
"modelId": "{targetModelId}",
"description": "{targetModelDescription}",
}
Użyj treści odpowiedzi z akcji autoryzowania, aby skonstruować żądanie kopii.
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"
}
Zmiany w modelach listy
Modele list są teraz rozszerzone, aby zwracać wstępnie utworzone i niestandardowe modele. Wszystkie wstępnie utworzone nazwy modeli zaczynają się od prebuilt-. Zwracane są tylko modele ze stanem powodzenia. Aby wyświetlić listę modeli, które zakończyły się niepowodzeniem lub są w toku, zobacz Operacje listy.
Żądanie przykładowych modeli listy
GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels?api-version=2022-08-31
Zmień, aby pobrać model
Ponieważ model get zawiera teraz wstępnie utworzone modele, operacja get zwraca docTypes słownik. Każdy opis typu dokumentu zawiera nazwę, opcjonalny opis, schemat pola i opcjonalną pewność pola. Schemat pola opisuje listę pól, które potencjalnie są zwracane z typem dokumentu.
GET https://{your-form-recognizer-endpoint}/formrecognizer/documentModels/{modelId}?api-version=2022-08-31
Nowa operacja pobierania informacji
Operacja info w usłudze zwraca liczbę modeli niestandardowych i limit modelu niestandardowego.
GET https://{your-form-recognizer-endpoint}/formrecognizer/info? api-version=2022-08-31
Przykładowa odpowiedź
{
"customDocumentModels": {
"count": 5,
"limit": 100
}
}