Freigeben über

Dokument Intelligenz-Batchanalyse (Vorschau)

  • Artikel

Wichtig

  • Public Preview-Releases von Dokument Intelligenz bieten frühzeitigen Zugriff auf Features, die sich in der aktiven Entwicklung befinden. Features, Ansätze und Prozesse können sich aufgrund von Benutzerfeedback vor der allgemeinen Verfügbarkeit (General Availability, GA) ändern.
  • Die Public Preview von Dokument Intelligenz-Clientbibliotheken verwendet standardmäßig Version 2024-07-31-preview der REST-API.
  • Die Public Preview 2024-07-31-preview ist derzeit lediglich in den folgenden Azure-Regionen verfügbar. Beachten Sie, dass das benutzerdefinierte generative Modell (Dokumentfeldextraktion) in KI Studio nur in der Region „USA, Norden-Mitte“ verfügbar ist:
    • USA, Osten
    • USA, Westen 2
    • Europa, Westen
    • USA Nord Mitte

Die Batchanalyse-API ermöglicht mithilfe einer asynchronen Anforderung die Massenverarbeitung mehrerer Dokumente. Anstatt Dokumente einzeln zu übermitteln und mehrere Anforderungs-IDs nachzuverfolgen, können Sie eine Sammlung von Rechnungen, eine Reihe von Kreditunterlagen oder eine Gruppe von Dokumenten gleichzeitig zum Trainieren benutzerdefinierter Modelle analysieren.

  • Um die Batchanalyse zu nutzen, benötigen Sie ein Azure Blob Storage-Konto mit bestimmten Containern für Ihre Quelldokumente und die verarbeiteten Ausgaben.
  • Nach Abschluss werden im Ergebnis des Batchvorgangs alle verarbeiteten Einzeldokumente mit ihrem Status wie succeeded, skipped oder failed aufgelistet.
  • Die Vorschauversion der Batch-API ist über die Preise der nutzungsbasierten Bezahlung verfügbar.

Die Batchanalyse wird von den folgenden Modellen unterstützt:

  • Lesen. Extrahieren von Textzeilen, Wörtern, erkannter Sprachen und handschriftlicher Formatvorlagen aus Formularen und Dokumenten

  • Layout: Extrahieren von Text, Tabellen, Auswahlmarkierungen und Strukturinformationen aus Formularen und Dokumenten

  • Benutzerdefinierte Vorlage: Trainieren von Modellen zum Extrahieren von Schlüssel-Wert-Paaren, Auswahlmarkierungen, Tabellen, Signaturfeldern und Regionen aus strukturierten Formularen

  • Benutzerdefiniertes neuronales Modell: Trainieren von Modellen zum Extrahieren angegebener Datenfelder aus strukturierten, teilweise strukturierten und unstrukturierten Dokumenten

  • Benutzerdefiniertes generatives Modell: Trainieren von Modellen zum Extrahieren angegebener Daten aus komplexen Objekten wie geschachtelten Tabellen, abstrahierungsfähigen bzw. generativen Feldern und tatsächlich unstrukturierten Formaten

Leitfaden zur Batchanalyse

  • Die maximale Anzahl der Dokumente, die pro Anforderung für die Batchanalyse verarbeitet werden können (einschließlich übersprungener Dokumente), beträgt 10.000.

  • Der Parameter azureBlobFileListSource kann verwendet werden, um größere Anforderungen in kleinere zu unterteilen.

  • Die Vorgangsergebnisse werden nach Abschluss 24 Stunden aufbewahrt. Die Dokumente und Ergebnisse befinden sich im bereitgestellten Speicherkonto, der Vorgangsstatus ist jedoch nicht mehr 24 Stunden nach Abschluss verfügbar.

Willst du loslegen?

Voraussetzungen

  • Sie benötigen ein aktives Azure-Abonnement. Falls Sie über kein Azure-Abonnement verfügen, können Sie ein kostenloses Konto erstellen.

  • Sobald Ihr Azure-Abonnement im Azure-Portal über eine Dokument Intelligenz-Instanz verfügt, gilt Folgendes: Sie können den kostenlosen Tarif (F0) verwenden, um den Dienst auszuprobieren.

  • Wählen Sie nach erfolgter Bereitstellung Ihrer Ressource Zu Ressource wechseln aus, und rufen Sie Ihren Schlüssel und Endpunkt ab.

    • Sie benötigen den Schlüssel und Endpunkt aus der Ressource, um Ihre Anwendung mit dem Dokument Intelligenz-Dienst zu verbinden. Den Schlüssel und den Endpunkt werden Sie später im Schnellstart in den Code einfügen. Diese Werte sind im Azure-Portal auf der Seite Schlüssel und Endpunkt aufgeführt.

  • Ein Azure Blob Storage-Konto. Sie erstellen Container in Ihrem Azure Blob Storage-Konto für Ihre Quell- und Ergebnisdateien:

    • Quellcontainer: In diesen Container laden Sie Ihre Dateien zur Analyse hoch (erforderlich).
    • Ergebniscontainer: In diesem Container werden Ihre verarbeiteten Dateien gespeichert (optional).

Sie können denselben Azure Blob Storage-Container für Quelldokumente und verarbeitete Dokumente festlegen. Um jedoch potenzielle Chancen für ein versehentliches Überschreiben von Daten zu minimieren, wird die Auswahl separater Container empfohlen.

Speichercontainerautorisierung

Sie können eine der folgenden Optionen auswählen, um den Zugriff auf Ihre Dokumentressource zu autorisieren.

✔️ Verwaltete Identität. Eine verwaltete Identität ist ein Dienstprinzipal, der eine Microsoft Entra-Identität und bestimmte Berechtigungen für von Azure verwaltete Ressourcen erstellt. Mit verwalteten Identitäten können Sie Ihre Dokument Intelligenz-Anwendung ausführen, ohne Anmeldeinformationen in Ihren Code einbetten zu müssen. Verwaltete Identitäten sind eine sicherere Möglichkeit, Zugriff auf Speicherdaten zu gewähren und die Anforderung zu ersetzen, dass Sie SAS-Token (Shared Access Signature) in Ihre Quell- und Ergebnis-URLs einschließen müssen.

Weitere Informationen finden Sie unter Verwaltete Identitäten für Dokument Intelligenz.

Screenshot des Flows für die verwaltete Identität (rollenbasierte Zugriffssteuerung)

Wichtig

  • Wenn Sie verwaltete Identitäten verwenden, schließen Sie keine SAS-Token-URL in Ihre HTTP-Anforderungen ein – Ihre Anforderungen schlagen sonst fehl. Die Verwendung verwalteter Identitäten ersetzt die Anforderung, dass Sie SAS-Token (Shared Access Signature) einschließen müssen.

✔️ Shared Access Signature (SAS). Eine Shared Access Signature-URL gewährt für einen bestimmten Zeitraum eingeschränkten Zugriff auf Ihren Dokument Intelligenz-Dienst. Um diese Methode zu verwenden, müssen Sie SAS-Token (Shared Access Signature) für Ihre Quell- und Ergebniscontainer erstellen. Die Quell- und Ergebniscontainer müssen ein SAS-Token (Shared Access Signature) enthalten, das als Abfragezeichenfolge angefügt wird. Das Token kann Ihrem Container oder bestimmten Blobs zugewiesen sein.

Screenshot: Speicher-URI mit angehängtem SAS-Token

  • Ihr Quellcontainer oder Blob muss den Zugriff für das Lesen, Schreiben, Auflisten und Löschen festlegen.
  • Ihr Ergebniscontainer oder Blob muss den Zugriff für das Schreiben, Auflisten und Löschen festlegen.

Weitere Informationen finden Sie unter Erstellen von SAS-Token.

Aufrufen der Batchanalyse-API

  • Geben Sie die URL des Azure Blob Storage-Containers für Ihre Quelldokumentmappe innerhalb der Objekte azureBlobSource oder azureBlobFileListSource an.

  • Geben Sie mithilfe von resultContainerUrl die URL des Azure Blob Storage-Containers für die Ergebnisse Ihrer Batchanalyse an. Um ein versehentliches Überschreiben zu vermeiden, wird die Verwendung separater Container für Quelldokumente und verarbeitete Dokumente empfohlen.

    • Wenn Sie denselben Container verwenden, legen Sie resultContainerUrl und resultPrefix so fest, dass diese Ihrer Eingabe von azureBlobSource entsprechen.
    • Wenn Sie denselben Container verwenden, können Sie das Feld overwriteExisting einschließen, um festzulegen, ob Dateien mit den Analyseergebnisdateien überschrieben werden sollen.

Erstellen und Ausführen der POST-Anforderung

Ersetzen Sie vor dem Ausführen der POST-Anforderung {Ihre-Quellcontainer-SAS-URL} und {Ihre-Ergebniscontainer-SAS-URL} durch die Werte Ihrer Azure Blob Storage-Containerinstanzen.

Nur azureBlobSource oder azureBlobFileListSource zulassen

POST /documentModels/{modelId}:analyzeBatch

[
  {
    "azureBlobSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "prefix": "trainingDocs/"
    },
    "azureBlobFileListSource": {
      "containerUrl": "{your-source-container-SAS-URL}",
      "fileList": "myFileList.jsonl"
    },
    "resultContainerUrl": "{your-result-container-SAS-URL}",
    "resultPrefix": "trainingDocsResult/",
    "overwriteExisting": false
  }
]

Erfolgreiche Antwort

202 Accepted
Operation-Location: /documentModels/{modelId}/analyzeBatchResults/{resultId}

Abrufen von Ergebnissen der Batchanalyse-API

Nachdem der Vorgang der Batch-API ausgeführt wurde, können Sie die Ergebnisse der Batchanalyse mithilfe des GET-Vorgangs abrufen. Dieser Vorgang ruft Statusinformationen, den Prozentsatz des Abschlusses sowie Datum/Uhrzeit für die Erstellung und Aktualisierung des Vorgangs ab.

GET /documentModels/{modelId}/analyzeBatchResults/{resultId}
200 OK

{
  "status": "running",      // notStarted, running, completed, failed
  "percentCompleted": 67,   // Estimated based on the number of processed documents
  "createdDateTime": "2021-09-24T13:00:46Z",
  "lastUpdatedDateTime": "2021-09-24T13:00:49Z"
...
}

Interpretieren von Statusmeldungen

Für jedes Dokument wird ein Status festgelegt, entweder succeeded, failed oder skipped. Für jedes Dokument werden zwei URLs bereitgestellt, um die Ergebnisse zu überprüfen: die sourceUrl-URL, bei der es sich um den Blob Storage-Quellcontainer für Ihr erfolgreiches Eingabedokument handelt, und die resultUrl-URL, die erstellt wird, indem resultContainerUrl und resultPrefix kombiniert werden, um den relativen Pfad für die Quelldatei und .ocr.json zu erstellen.

  • Status notStarted oder running: Der Batchanalysevorgang wird nicht initiiert oder nicht abgeschlossen. Warten Sie, bis der Vorgang für alle Dokumente abgeschlossen ist.

  • Status completed: Der Batchanalysevorgang ist abgeschlossen.

  • Status failed: Beim Batchvorgang ist ein Fehler aufgetreten. Diese Antwort tritt in der Regel dann auf, wenn allgemeine Probleme mit der Anforderung auftreten. Fehler bei einzelnen Dateien werden in der Antwort des Batchberichts zurückgegeben, selbst wenn für alle Dateien ein Fehler aufgetreten ist. Beispiel: Speicherfehler stoppen den Batchvorgang nicht als Ganzes, wodurch Sie über die Antwort des Batchberichts auf Teilergebnisse zugreifen können.

Lediglich bei Dateien mit dem Status succeeded wurde in der Antwort die resultUrl-Eigenschaft generiert. Dadurch können beim Trainieren von Modellen Dateinamen erkannt werden, die mit .ocr.json enden, und als die einzigen Dateien identifiziert werden, die für das Training verwendet werden können.

Beispiel für eine succeeded-Statusantwort:

[
  "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
      {
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
          "code": "InvalidArgument",
          "message": "Invalid argument.",
          "innererror": {
            "code": "InvalidSasToken",
            "message": "The shared access signature (SAS) is invalid: {details}"
                   }
               }
          }
      ]
   }
]
...

Beispiel für eine failed-Statusantwort:

  • Dieser Fehler wird nur dann zurückgegeben, wenn in der gesamten Batchanforderung Fehler auftreten.
  • Nachdem der Batchanalysevorgang gestartet wurde, wirkt sich der Vorgangsstatus der einzelnen Dokumente nicht auf den Status des gesamten Batchauftrags aus, selbst wenn alle Dateien den Status failed aufweisen.
[
    "result": {
    "succeededCount": 0,
    "failedCount": 2,
    "skippedCount": 2,
    "details": [
        "sourceUrl": "https://{your-source-container}/myContainer/trainingDocs/file2.jpg",
        "status": "failed",
        "error": {
            "code": "InvalidArgument",
            "message": "Invalid argument.",
            "innererror": {
              "code": "InvalidSasToken",
              "message": "The shared access signature (SAS) is invalid: {details}"
                }
            }
        ]
    }
]
...

Beispiel für eine skipped-Statusantwort:

[
    "result": {
    "succeededCount": 3,
    "failedCount": 0,
    "skippedCount": 2,
    "details": [
        ...
        "sourceUrl": "https://myStorageAccount.blob.core.windows.net/myContainer/trainingDocs/file4.jpg",
        "status": "skipped",
        "error": {
            "code": "OutputExists",
            "message": "Analysis skipped because result file {path} already exists."
             }
        ]
    }
]
...

Anhand der Ergebnisse der Batchanalyse können Sie ermitteln, welche Dateien erfolgreich analysiert und überprüft wurden, indem Sie die Datei in der resultUrl-URL mit der Ausgabedatei in der resultContainerUrl-URL vergleichen.

Hinweis

Analyseergebnisse werden erst dann für einzelne Dateien zurückgegeben, wenn die Batchanalyse der gesamten Dokumentenmappen abgeschlossen ist. Um den detaillierten Fortschritt nach percentCompleted nachzuverfolgen, können Sie *.ocr.json-Dateien überwachen, während diese in die resultContainerUrl-URL geschrieben werden.

Nächste Schritte

Anzeigen von Codebeispielen auf GitHub