Migration von Dokument Intelligenz v3.1

  • Artikel

Dieser Inhalt gilt für:checkmarkv4.0 (Vorschau)checkmarkv3.1 (allgemeine Verfügbarkeit)checkmarkv3.0 (allgemeine Verfügbarkeit)checkmarkv2.1 (allgemeine Verfügbarkeit)

Wichtig

Die Dokument Intelligenz-REST-API v3.1 führt Breaking Changes in der REST-API-Anforderung ein und analysiert den JSON-Code der Antwort.

Migrieren von API-Vorschauversion v3.1

Vorschau-APIs werden regelmäßig ausgemustert. Wenn Sie eine Vorschauversion der API verwenden, aktualisieren Sie Ihre Anwendung, um auf die allgemein verfügbare API-Version abzuzielen. Wenn Sie mithilfe des SDKs von der API-Version „2023-02-28-preview“ zur (allgemein verfügbaren) API-Version 2023-07-31 migrieren möchten, aktualisieren Sie die aktuelle Version des sprachspezifischen SDKs.

Die (allgemein verfügbare) API 2023-07-31 enthält einige Updates und Änderungen aus den API-Vorschauversionen:

  • Die standardmäßig aktivierten Features sind auf diejenigen beschränkt, die für das jeweilige Modell wesentlich sind, mit dem Vorteil einer geringeren Latenz und Antwortgröße. Hinzugefügte Features können über Enumerationswerte im features-Parameter aktiviert werden.
  • Einige Layoutfeatures aus prebuilt-read und keyValuePairs, die über prebuilt-{document,invoice} hinausgehen, werden nicht mehr unterstützt.
  • Die standardmäßige Deaktivierung von Barcodes für prebuilt-read und prebuilt-layout, Sprachen für prebuilt-read und keyValuePairs für prebuilt-invoice.
  • Die Anmerkungsextraktion wird entfernt.
  • Abfragefelder und allgemeine Namen von Schlüssel-Wert-Paaren werden entfernt.
  • Office-/HTML-Dateien werden im prebuilt-read-Modell unterstützt, das Wörter und Absätze ohne Begrenzungsrahmen extrahiert. Eingebettete Bilder werden nicht mehr unterstützt. Wenn Add-On-Features für Office-/HTML-Dateien angefordert werden, wird ein leeres Array ohne Fehler zurückgegeben.

Analysefeatures

Modell-ID Textextraktion Absätze Absatzrollen Auswahlmarkierungen Tabellen Schlüssel-Wert-Paare Sprachen Barcodes Dokumentanalyse Formeln* StyleFont* Optische Zeichenerkennung mit hoher Auflösung*
prebuilt-read ✓ ✓ O O O O O
prebuilt-layout ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-document ✓ ✓ ✓ ✓ ✓ ✓ O O O O O
prebuilt-businessCard ✓ ✓
prebuilt-idDocument ✓ O O ✓ O O O
Vordefinierte Rechnung ✓ ✓ ✓ O O O ✓ O O O
prebuilt-receipt ✓ 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
prebuilt-contract ✓ ✓ ✓ ✓ O O ✓ O O O
{ customModelName } ✓ ✓ ✓ ✓ ✓ O O ✓ O O O

✓ – Aktiviert O – Optionale Formeln/StyleFont/Optische Zeichenerkennung mit hoher Auflösung* – Premium-Features verursachen zusätzliche Kosten

Migrieren von v3.0

Im Vergleich zu v3.0 führt Dokument Intelligenz v3.1 eine Reihe neuer Features und Funktionen ein:

  • Barcodeextraktion.
  • Add-On-Funktionen, einschließlich hochauflösender Extraktion, Formelextraktion und Extraktion von Schrifteigenschaften.
  • Benutzerdefiniertes Klassifizierungsmodell für die Dokumentaufteilung und -klassifizierung.
  • Unterstützung von Spracherweiterung und neuen Feldern im Rechnungs- und Belegmodell.
  • Unterstützung eines neuen Dokumenttyps im ID-Dokumentmodell.
  • Neues vordefiniertes Krankenversicherungskarten-Modell.
  • Office-/HTML-Dateien werden im prebuilt-read-Modell unterstützt, das Wörter und Absätze ohne Begrenzungsrahmen extrahiert. Eingebettete Bilder werden nicht mehr unterstützt. Wenn Add-On-Features für Office-/HTML-Dateien angefordert werden, wird ein leeres Array ohne Fehler zurückgegeben.
  • Modellablauf für benutzerdefinierte Extraktions- und Klassifizierungsmodelle – Unsere neuen benutzerdefinierten Modelle basieren auf einem großen Basismodell, das wir zur Qualitätsverbesserung regelmäßig aktualisieren. Für alle benutzerdefinierten Modelle wird ein Ablaufdatum eingeführt, um die Einstellung der entsprechenden Basismodelle zu ermöglichen. Sobald ein benutzerdefiniertes Modell abläuft, müssen Sie das Modell mithilfe der neuesten API-Version (Basismodell) erneut trainieren.
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": { ... }
}
  • Buildkontingent für benutzerdefinierte neuronale Modelle – Die Anzahl der neuronalen Modelle, die jedes Abonnement pro Region pro Monat erstellen kann, ist begrenzt. Wir erweitern den JSON-Ergebniscode, um das Kontingent und die verwendeten Informationen einzuschließen, damit Sie die aktuelle Nutzung im Rahmen der von GET /info zurückgegebenen Ressourceninformationen besser verstehen können.
{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}
  • Ein optionaler features-Abfrageparameter für Analysevorgänge kann optional bestimmte Features aktivieren. Einige Premium-Features können zusätzliche Kosten verursachen. Weitere Informationen finden Sie in der Liste der Analysefeatures.
  • Erweitern Sie extrahierte Währungsfeldobjekte, um nach Möglichkeit ein normalisiertes Währungscodefeld auszugeben. Derzeit können aktuelle Felder den Betrag (z. B. 123,45) und currencySymbol (z. B. $) zurückgeben. Dieses Feature ordnet das Währungssymbol einem kanonischen ISO-4217-Code (z. B. USD) zu. Das Modell kann optional den globalen Dokumentinhalt verwenden, um den Währungscode zu unterscheiden oder abzuleiten.
{
  "fields": {
    "Total": {
      "type": "currency",
      "content": "$123.45",
      "valueCurrency": {
        "amount": 123.45,
        "currencySymbol": "$",
        "currencyCode": "USD"
      },
      ...
    }
  }
}

Neben der Verbesserung der Modellqualität wird dringend empfohlen, Ihre Anwendung auf die Verwendung von v3.1 zu aktualisieren, um von diesen neuen Funktionen zu profitieren.

Migrieren von v2.1 oder v2.0

Dokument Intelligenz v3.1 ist die neueste allgemein verfügbare Version mit den umfangreichsten Features, den meisten Sprachen und Dokumenttypen sowie einer verbesserten Modellqualität. Informationen zu den in v3.1 verfügbaren Features und Funktionen finden Sie unter Modellübersicht.

Die Dokument Intelligenz-REST-API ist seit v3.0 überarbeitet, um die Benutzerfreundlichkeit zu verbessern. In diesem Abschnitt erfahren Sie mehr über die Unterschiede zwischen Dokument Intelligenz v2.0, v2.1 und v3.1 und den Wechsel zur neueren Version der API.

Achtung

  • Das REST-API-Release 2023-07-31 enthält einen Breaking Change in der REST-API und analysiert den JSON-Code der Antwort.
  • Die Eigenschaft boundingBox wird in jeder Instanz in polygon umbenannt.

Änderungen an den REST-API-Endpunkten

Die REST-API v3.1 kombiniert die Analysevorgänge für die Layoutanalyse, vordefinierte Modelle und benutzerdefinierte Modelle zu einem einzelnen Paar von Vorgängen, indem documentModels und modelId der Layoutanalyse (prebuilt-layout) und vordefinierten Modellen zugewiesen werden.

POST-Anforderung

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

GET-Anforderung

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

Analysevorgang

  • Die Anforderungsnutzdaten und das Aufrufmuster bleiben unverändert.
  • Der Analysevorgang gibt das Eingabedokument und inhaltsspezifische Konfigurationen an. Er gibt die Analyseergebnis-URL über den Operation-Location-Header in der Antwort zurück.
  • Fordern Sie diese Analyseergebnis-URL über eine GET-Anforderung an, um den Status des Analysevorgangs zu überprüfen (das empfohlene Mindestintervall zwischen Anforderungen beträgt 1 Sekunde).
  • Bei Erfolg wird der Status auf „Erfolgreich“ festgelegt und analyzeResult im Antworttext zurückgegeben. Wenn Fehler auftreten, wird der Status auf failed festgelegt und ein Fehler zurückgegeben.
Modell v2.0 v2.1 v3.1
Anforderungs-URL-Präfix https://{your-form-recognizer-endpoint}/formrecognizer/v2.0 https://{your-form-recognizer-endpoint}/formrecognizer/v2.1 https://{your-form-recognizer-endpoint}/formrecognizer
Allgemeines Dokument – – /documentModels/prebuilt-document:analyze
Layout /layout/analyze /layout/analyze /documentModels/prebuilt-layout:analyze
Benutzerdefiniert /custom/models/{modelId}/analyze /custom/{modelId}/analyze /documentModels/{modelId}:analyze
Rechnung Nicht zutreffend /prebuilt/invoice/analyze /documentModels/prebuilt-invoice:analyze
Rechnung /prebuilt/receipt/analyze /prebuilt/receipt/analyze /documentModels/prebuilt-receipt:analyze
ID-Dokument Nicht zutreffend /prebuilt/idDocument/analyze /documentModels/prebuilt-idDocument:analyze
Visitenkarte Nicht zutreffend /prebuilt/businessCard/analyze /documentModels/prebuilt-businessCard:analyze
W-2 – – /documentModels/prebuilt-tax.us.w2:analyze
Krankenversicherungskarte – – /documentModels/prebuilt-healthInsuranceCard.us:analyze
Vertrag – – /documentModels/prebuilt-contract:analyze

Analysieren des Anforderungstexts

Der zu analysierende Inhalt wird über den Anforderungstext bereitgestellt. Entweder die URL- oder Base64-codierten Daten können Benutzer sein, um die Anforderung zu erstellen.

Um eine öffentlich zugängliche Web-URL anzugeben, setzen Sie Content-Type auf application/json und senden Sie den folgenden JSON-Text:

{
  "urlSource": "{urlPath}"
}

Die Base 64-Codierung wird auch in Dokument Intelligenz v3.0 unterstützt:

{
  "base64Source": "{base64EncodedContent}"
}

Zusätzlich unterstützte Parameter

Parameter, die weiterhin unterstützt werden:

  • pages: Analysiert nur eine bestimmte Teilmenge von Seiten im Dokument. Liste der indizierten Seitenzahlen für die Analyse (beginnend ab der Zahl 1). Ex. 1-3,5,7-9
  • locale: Gebietsschemahinweis für die Texterkennung und Dokumentanalyse. Der Wert kann nur den Sprachcode (z. B. en, fr) oder das BCP-47-Sprachtag (z. B. „en-US“) enthalten.

Parameter, die nicht mehr unterstützt werden:

  • includeTextDetails

Das neue Antwortformat ist kompakter, und die vollständige Ausgabe wird immer zurückgegeben.

Änderungen zum Analysieren des Ergebnisses

Die Analyseantwort wurde auf die folgenden Ergebnisse der obersten Ebene umgestaltet, um mehrseitige Elemente zu unterstützen.

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

Hinweis

Die analyzeResult-Antwortänderungen umfassen eine Reihe von Änderungen, z. B. der Wechsel von einer Eigenschaft von Seiten zu einer Eigenschaft auf oberster Ebene in 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
}, ...
}
}, ...
]
}

Erstellen oder Trainieren eines Modells

Das Modellobjekt verfügt in der neuen API über drei Updates.

  • modelId ist jetzt eine Eigenschaft, die für ein Modell für einen lesbaren Namen festgelegt werden kann.
  • modelName wird umbenannt in description.
  • buildMode ist eine neue Eigenschaft mit dem Wert template für benutzerdefinierte Formularmodelle oder neural für benutzerdefinierte neuronale Modelle.

Der build-Vorgang wird aufgerufen, um ein Modell zu trainieren. Die Anforderungsnutzdaten und das Aufrufmuster bleiben unverändert. Der Erstellungsvorgang gibt das Modell und das Trainingsdataset an und gibt das Ergebnis über den Operation-Location-Header in der Antwort zurück. Fordern Sie diese Modellvorgangs-URL über eine GET-Anforderung an, um den Status des Erstellungsvorgangs zu überprüfen (das empfohlene Mindestintervall zwischen Anforderungen beträgt 1 Sekunde). Im Gegensatz zu v2.1 ist diese URL nicht der Ressourcenspeicherort des Modells. Stattdessen kann die Modell-URL aus der angegebenen Modell-ID konstruiert werden, die auch aus der resourceLocation-Eigenschaft in der Antwort abgerufen wird. Bei Erfolg wird der Status auf succeeded festgelegt, und das Ergebnis enthält die benutzerdefinierten Modellinformationen. Wenn Fehler auftreten, wird der Status auf failed festgelegt und der Fehler zurückgegeben.

Der folgende Code ist eine Beispielbuildanforderung mit einem SAS-Token. Beachten Sie beim Festlegen des Präfix- oder Ordnerpfads den nachgestellten Schrägstrich.

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

Änderungen beim Zusammenstellen des Modells

Das Zusammensetzen von Modellen ist jetzt auf eine einzelne Schachtelungsebene beschränkt. Zusammengestellte Modelle sind jetzt mit benutzerdefinierten Modellen durch das Hinzufügen von modelId- und description-Eigenschaften konsistent.

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

Änderungen am Kopiermodell

Das Aufrufmuster für das Kopiermodell bleibt unverändert:

  • Autorisieren Sie den Kopiervorgang mit der Zielressource, die authorizeCopy aufruft. Jetzt eine POST-Anforderung.
  • Übermitteln Sie die Autorisierung an die Quellressource, um das Modell zu kopieren, das copyTo aufruft.
  • Rufen Sie den zurückgegebenen Vorgang ab, um den erfolgreichen Abschluss des Vorgangs zu überprüfen.

Die einzigen Änderungen an der Kopiermodellfunktion sind:

  • Die HTTP-Aktion für authorizeCopy ist jetzt eine POST-Anforderung.
  • Die Autorisierungsnutzdaten enthalten alle Informationen, die zum Übermitteln der Kopieranforderung erforderlich sind.

Autorisieren Sie die Kopie

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

Verwenden Sie den Antworttext der Autorisierungsaktion, um die Anforderung für die Kopie zu erstellen.

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

Änderungen an Listenmodellen

Listenmodelle wurden erweitert, um jetzt vordefinierte und benutzerdefinierte Modelle zurückzugeben. Alle vordefinierten Modellnamen beginnen mit prebuilt-. Nur Modelle mit dem Status „Erfolgreich“ werden zurückgegeben. Informationen zum Auflisten von Modellen, die entweder fehlerhaft oder in Bearbeitung sind, finden Sie unter Auflisten von Vorgängen.

Beispielanforderung für Listenmodelle

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

Änderung zum Abrufen des Modells

Da „get model“ jetzt auch vordefinierte Modelle enthält, gibt der GET-Vorgang ein docTypes-Wörterbuch zurück. Jeder Dokumenttyp wird durch seinen Namen, eine optionale Beschreibung, ein Feldschema und eine optionale Feldkonfidenz beschrieben. Das Feldschema beschreibt die Liste der Felder, die möglicherweise mit dem Dokumenttyp zurückgegeben werden.

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

Neuer Vorgang zum Abrufen von Informationen

Der info-Vorgang für den Dienst gibt die Anzahl der benutzerdefinierten Modelle und den Grenzwert für benutzerdefinierte Modelle zurück.

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

Beispiel für eine Antwort

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

Nächste Schritte