Migration von Document Intelligence v4.0

SDK-Migrationshandbücher

Anleitungen zum Aktualisieren Ihres Anwendungscodes für die Verwendung der v4.0-SDKs finden Sie in den sprachspezifischen SDK-Migrationshandbüchern in unseren GitHub-Repositorys. Diese Leitfäden enthalten Anweisungen zum Aktualisieren ihres Codes, um die neuen API-Methoden aufzurufen und die aktualisierten Antwortformate zu behandeln, die in v4.0 eingeführt wurden:

• .NET/C#-SDK

• Java SDK

• Python SDK

• JavaScript/TypeScript SDK*

Migrieren von v3.1 zu v4.0

Vorschau-APIs sind in regelmäßigen Abständen veraltet. Wenn Sie eine Vorschau-API-Version verwenden, aktualisieren Sie Ihre Anwendung auf die GA-API-Version. Um von einer Vorschau-API-Version zur API-Version mit dem 2024-11-30 (GA) SDK zu migrieren, aktualisieren Sie auf die aktuelle Version des sprachspezifischen SDK. Frühere v3.x-API-Versionen werden nach veröffentlichten Zeitplänen eingestellt; v3.0 wird am 30. März 2029 eingestellt.

Analyse-Features

✓ – 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 Document Intelligence v3.1 mehrere neue Features und Funktionen ein:

• Barcode-Extraktion
• Add-On-Funktionen, einschließlich hochauflösender Extraktion, Formelextraktion und Extraktion von Schrifteigenschaften.
• Benutzerdefiniertes Klassifizierungsmodell für Dokumentaufteilung und -klassifizierung.
• Spracherweiterung und neue Felder unterstützen das Rechnungs- und Belegmodell .
• Unterstützung des neuen Dokumenttyps im ID-Dokumentmodell .
• Neues vorkonfiguriertes Krankenversicherungskartenmodell.
• Office/HTML-Dateien werden im vorab erstellten Lesemodell unterstützt, wobei Wörter und Absätze ohne Begrenzungsfelder extrahiert werden. 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.
• Modellverfall für benutzerdefinierte Extraktions- und Klassifizierungsmodelle – Unsere neuen benutzerdefinierten Modelle stützen sich auf ein großes Basismodell, das wir regelmäßig aktualisieren, um die Qualität zu verbessern. Es wird ein Ablaufdatum für alle benutzerdefinierten Modelle eingeführt, um die Deaktivierung der entsprechenden Basismodelle zu ermöglichen. Sobald ein benutzerdefiniertes Modell abläuft, müssen Sie das Modell mit der neuesten API-Version (Basismodell) neu 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 das ERGEBNIS-JSON, um das Kontingent und die verwendeten Informationen einzuschließen, damit Sie die aktuelle Verwendung als Teil der von GET /info zurückgegebenen Ressourceninformationen verstehen können.

{
  "customDocumentModels": { ... },
  "customNeuralDocumentModelBuilds": {
    "used": 1,
    "quota": 10,
    "quotaResetDateTime": "2023-03-01T00:00:00Z"
  }
}

• Ein optionaler features Abfrageparameter zum Analysieren von Vorgängen kann optional bestimmte Features aktivieren. Einige Premiumfeatures können zu zusätzlichen Abrechnungen führen. Details finden Sie in der Featureliste "Analysieren ".
• Erweitern Sie extrahierte Währungsfeldobjekte, um nach Möglichkeit ein normalisiertes Währungscodefeld auszugeben. Aktuell können aktuelle Felder 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 Mehrdeutigkeiten aufzulösen oder den Währungscode 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

Document Intelligence v4.0 ist die neueste GA-Version mit den besten Features, den meisten Sprachen und Dokumenttypen sowie einer verbesserten Modellqualität. Informationen zu den in v4.0 verfügbaren Features und Funktionen finden Sie in der Modellübersicht .

Ab v3.0 wurde die Rest-API für Die Dokumentintelligenz neu gestaltet, um die Benutzerfreundlichkeit zu verbessern. In diesem Abschnitt lernen Sie die Unterschiede zwischen Document Intelligence v2.0, v2.1 und v3.1 und der neueren Version der API kennen.

Änderungen an den REST-API-Endpunkten

Die REST-API v3.1 kombiniert die Analysevorgänge für Layoutanalyse, vordefinierte Modelle und benutzerdefinierte Modelle zu einem einzigen Paar von Vorgängen, indem documentModels der Layoutanalyse und modelId den vordefinierten Modellen zugewiesen wird.

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

Analysieren des Vorgangs

• Die Anforderungsnutzlast und das Aufrufmuster bleiben unverändert.
• Der Analyze Vorgang gibt das Eingabedokument und inhaltsspezifische Konfigurationen an, es gibt die analysierte Ergebnis-URL über den Operation-Location Header in der Antwort zurück.
• Rufen Sie die Analyze Result URL über eine GET-Anforderung ab, um den Status des Analyze Vorgangs zu überprüfen (minimales empfohlenes Intervall zwischen Anforderungen beträgt 1 Sekunde).
• Nach Erfolg wird der Status auf "succeeded" festgelegt und "analyzeResult " im Antworttext zurückgegeben. Wenn Fehler auftreten, wird der Status auf failed gesetzt und ein Fehler wird zurückgegeben.

Analysieren des Anforderungstexts

Der zu analysierende Inhalt wird über den Anforderungskörper bereitgestellt. Entweder die URL oder base64-codierte Daten können verwendet werden, um die Anforderung zu erstellen.

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

{
  "urlSource": "{urlPath}"
}

Die Base64-Codierung wird auch in Document Intelligence v3.0 unterstützt:

{
  "base64Source": "{base64EncodedContent}"
}

Zusätzlich unterstützte Parameter

Parameter, die weiterhin unterstützt werden:

• pages : Analysieren Sie 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) oder fr 47 Sprachtag (z. B. BCP"en-US") enthalten.

Parameter werden nicht mehr unterstützt:

• TextdetailsEinfügen

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

Änderungen zur Analyse des Ergebnisses

Die Analyseantwort wurde auf die folgenden Ergebnisse der obersten Ebene umgestaltet und unterstützt mehrseitige Elemente.

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

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

Modell erstellen oder trainieren

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

• 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 Werten template für benutzerdefinierte Formularmodelle oder neural für benutzerdefinierte neurale Modelle.

Der build Vorgang wird aufgerufen, um ein Modell zu trainieren. Die Anforderungsnutzlast und das Aufrufmuster bleiben unverändert. Der Buildvorgang gibt das Modell- und Schulungsdatenset an, es gibt das Ergebnis über den Operation-Location Header in der Antwort zurück. Rufen Sie diese Modellvorgangs-URL über eine GET-Anforderung ab, um den Status des Buildvorgangs zu überprüfen (minimales empfohlenes Intervall 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 modelId erstellt werden, die auch aus der resourceLocation-Eigenschaft in der Antwort abgerufen wird. Nach Erfolg wird der Status auf succeeded festgelegt, und das Ergebnis enthält benutzerdefinierte Modellinformationen. Wenn Fehler auftreten, wird der Status auf failed gesetzt 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 am Zusammenstellungsmodell

Das Zusammensetzen von Modellen ist jetzt auf eine einzelne Schachtelungsebene beschränkt. Zusammengesetzte Modelle sind jetzt mit benutzerdefinierten Modellen konsistent durch die Hinzufügung der modelId- und description-Eigenschaften.

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, indem Sie die Zielressource mit authorizeCopy aufrufen. Jetzt eine POST-Anforderung.
• Übermitteln Sie die Autorisierung an die Quellressource und kopieren Sie den Modellaufruf copyTo
• Den zurückgegebenen Vorgang abfragen, um festzustellen, ob der Vorgang erfolgreich abgeschlossen wurde

Die einzigen Änderungen an der Kopiermodellfunktion sind:

• HTTP-Aktion für die authorizeCopy ist jetzt eine POST-Anforderung.
• Die Autorisierungsnutzlast enthält alle Informationen, die zum Senden der Kopieranforderung erforderlich sind.

Autorisieren der 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 werden erweitert, um jetzt vorgefertigte und benutzerdefinierte Modelle zurückzugeben. Alle vordefinierten Modellnamen beginnen mit prebuilt-. Es werden nur Modelle mit dem Status "Erfolgreich" zurückgegeben. Um Modelle aufzulisten, die entweder fehlgeschlagen sind oder in Bearbeitung sind, sehen Sie Operationsliste nach.

Anforderung von Beispiellistenmodellen

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

Änderung des Vorgangs zum Abrufen des Modells

Da Get Model jetzt vordefinierte Modelle enthalten sind, gibt der Get Vorgang ein docTypes Wörterbuch zurück. Jede Dokumenttypbeschreibung enthält Namen, optionale Beschreibung, Feldschema und optionale Feldvertrauenssicherheit. 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 Get-Info-Vorgang

Der info Vorgang für den Dienst gibt die Anzahl der benutzerdefinierten Modelle und die Begrenzung des benutzerdefinierten Modells zurück.

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

Beispielantwort

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

Nächste Schritte

• Überprüfen der neuen REST-API
• Was ist Document Intelligence?
• Dokumentintelligenz Schnellstart 0