Udostępnij za pośrednictwem


Migracja analizy dokumentów w wersji 3.1

Ta zawartość dotyczy: Znacznik wersja 4.0 (wersja zapoznawcza) Znacznik v3.1 (GA) v3.0 (GA) Znacznik v2.1 (GA) Znacznik

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 Kody kreskowe 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 features parametr 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 boundingBox właściwości jest zmieniana na polygon w każdym wystąpieniu.

Zmiany w punktach końcowych interfejsu API REST

Interfejs API REST w wersji 3.1 łączy operacje analizy na potrzeby analizy układu, wstępnie utworzonych modeli i modeli niestandardowych w jedną parę operacji przez przypisanie documentModels i modelId do analizy układu (.). /prebuilt-layout) i wstępnie utworzone modele.

Żą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
Paragon /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 liczby 1 do 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.

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

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

  • modelId jest teraz właściwością, którą można ustawić w modelu dla nazwy czytelnej dla człowieka.
  • modelName zmieniono nazwę na description
  • buildMode to nowa właściwość z wartościami template niestandardowych modeli formularzy lub neural niestandardowych 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 authorizeCopy jest 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
  }
}

Następne kroki