Freigeben über

Dokument Intelligenz-Batchanalyse

  • Artikel

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 Dokumenten wie Rechnungen, eine Reihe von Kreditunterlagen oder eine Gruppe von Dokumenten gleichzeitig zum Trainieren benutzerdefinierter Modelle analysieren. Die Batch-API unterstützt das Lesen der Dokumente aus Azure Blob Storage und das Schreiben der Ergebnisse in Blob Storage.

  • 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.

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.

  • 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.

Angeben der Eingabedateien

Die Batch-API unterstützt zwei Optionen zum Angeben der zu verarbeitenden Dateien. Wenn Sie alle Dateien in einem Container oder Ordner verarbeiten müssen und die Anzahl der Dateien kleiner als der Grenzwert von 10.000 für eine einzelne Batchanforderung ist, verwenden Sie den Container azureBlobSource.

Wenn Sie bestimmte Dateien im Container oder Ordner verarbeiten müssen oder die Anzahl der zu verarbeitenden Dateien über dem maximalen Grenzwert für einen einzelnen Batch liegt, verwenden Sie azureBlobFileListSource. Teilen Sie das Dataset in mehrere Batches auf, und fügen Sie eine Datei mit der Liste der Dateien hinzu, die im JSONL-Format im Stammordner des Containers verarbeitet werden sollen. Ein Beispiel für das Format der Dateiliste.

{"file": "Adatum Corporation.pdf"}
{"file": "Best For You Organics Company.pdf"}

Angeben des Speicherorts der Ergebnisse

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.

Legen Sie die boolesche Eigenschaft overwriteExisting auf „false” fest, wenn vorhandene Ergebnisse mit denselben Dateinamen nicht überschrieben werden sollen. Diese Einstellung wirkt sich nicht auf die Abrechnung aus und verhindert nur, dass die Ergebnisse nach der Verarbeitung der Eingabedatei überschrieben werden.

Legen Sie resultPrefix auf den Namespace der Ergebnisse aus dieser Batch-API fest.

  • Wenn Sie beabsichtigen, denselben Container sowohl für die Eingabe als auch für die Ausgabe zu verwenden, legen Sie resultContainerUrl und resultPrefix so fest, dass sie Ihrer Eingabe-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.

Im folgenden Beispiel wird gezeigt, wie Sie der Anforderung die Eigenschaft azureBlobSource hinzufügen:

Nur azureBlobSource oder azureBlobFileListSource zulassen

POST /documentModels/{modelId}:analyzeBatch

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "trainingDocs/"
  },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "layoutresult/",
  "overwriteExisting": true
}

Im folgenden Beispiel wird gezeigt, wie Sie der Anforderung die Eigenschaft azureBlobFileListSource hinzufügen:

POST /documentModels/{modelId}:analyzeBatch

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "customresult/",
  "overwriteExisting": true
}

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