Freigeben über

Dokument Intelligenz-Batchanalyse

Mit der Batchanalyse-API können Sie bis zu 10.000 Dokumente mithilfe einer Anforderung massenweise verarbeiten. Anstatt Dokumente einzeln zu analysieren und ihre jeweiligen Anforderungs-IDs nachzuverfolgen, können Sie gleichzeitig eine Sammlung von Dokumenten wie Rechnungen, Kreditpapieren oder benutzerdefinierten Dokumenten analysieren. Die Eingabedokumente müssen in einem Azure Blob Storage-Container gespeichert werden. Sobald die Dokumente verarbeitet wurden, schreibt die API die Ergebnisse in einen angegebenen Speichercontainer.

Grenzwerte für Die Batchanalyse

  • Die maximale Anzahl von Dokumentdateien, die sich in einer einzelnen Batchanforderung befinden können, beträgt 10.000.
  • Die Ergebnisse des Batchvorgangs werden 24 Stunden nach Abschluss aufbewahrt. Der Status des Batchvorgangs ist 24 Stunden nach Abschluss der Batchverarbeitung nicht mehr verfügbar. Die Eingabedokumente und die entsprechenden Ergebnisdateien verbleiben in den bereitgestellten Speichercontainern.

Voraussetzungen

  • Eine aktive Azure-Subscription. Falls Sie über kein Azure-Abonnement verfügen, können Sie ein kostenloses Konto erstellen.

  • Eine Document Intelligence Azure-Ressource: Nachdem Sie Ihr Azure-Abonnement haben, erstellen Sie eine Document Intelligence-Ressource im Azure-Portal. Sie können das kostenlose Preisniveau (F0) verwenden, um den Dienst zu testen. Nachdem Ihre Ressource bereitgestellt wurde, wählen Sie "Zur Ressource wechseln" aus, um Ihren Schlüssel und Endpunkt abzurufen. Sie benötigen den Ressourcenschlüssel und den Endpunkt, um Ihre Anwendung mit dem Dokumentintelligenzdienst zu verbinden. Sie finden diese Werte auch auf der Seite "Schlüssel" und "Endpunkt " im Azure-Portal.

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

    • Quellcontainer: In diesem Container laden Sie Dokumentdateien zur Analyse hoch.
    • Ergebniscontainer: In diesem Container werden Ergebnisse aus der Batchanalyse-API gespeichert.

Speichercontainerautorisierung

Damit die API Dokumente verarbeiten und Ergebnisse in Ihren Azure-Speichercontainern schreiben kann, müssen Sie die Verwendung einer der folgenden beiden Optionen 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. Verwaltete Identitäten ermöglichen es Ihnen, Ihre Document Intelligence-Anwendung auszuführen, ohne Anmeldeinformationen in Ihren Code einbetten zu müssen, eine sicherere Möglichkeit, Zugriff auf Speicherdaten zu gewähren, ohne Zugriffssignaturtoken (SAS) in Ihren Code einzubetten.

Überprüfen Sie verwaltete Identitäten für Die Dokumentintelligenz , um zu erfahren, wie Sie eine verwaltete Identität für Ihre Ressource aktivieren und ihm Zugriff auf Ihren Speichercontainer gewähren.

Wichtig

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

✔️ Shared Access Signature (SAS). Eine Signatur für freigegebenen Zugriff ist eine URL, die eingeschränkten Zugriff auf Ihren Speichercontainer gewährt. Um diese Methode zu verwenden, erstellen Sie SAS-Token (Shared Access Signature) für Ihre Quell- und Ergebniscontainer. Wechseln Sie zum Speichercontainer im Azure-Portal, und wählen Sie "Freigegebene Zugriffstoken" aus, um SAS-Token und URL zu generieren.

  • Ihr Quellcontainer oder Blob muss Lese-, Schreib-, Listen- und Löschberechtigungen festlegen.
  • Ihr Ergebniscontainer oder Blob muss Schreib-, Listen-, Löschberechtigungen festlegen.

Screenshot der SAS-Berechtigungsfelder im Azure-Portal.

Überprüfen Sie die Erstellung von SAS-Token , um mehr über das Generieren von SAS-Token und deren Funktionsweise zu erfahren.

Aufrufen der Batchanalyse-API

1. Angeben der Eingabedateien

Die Batch-API unterstützt zwei Optionen zum Angeben der zu verarbeitenden Dateien.

  • Wenn Sie alle Dateien in einem Container oder einem Ordner verarbeiten möchten und die Anzahl der Dateien kleiner als der Grenzwert von 10000 ist, verwenden Sie das azureBlobSource Objekt in Ihrer Anforderung.

    POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken"

},
{
   "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
   "resultPrefix": "trainingDocsResult/"
}

  • Wenn Sie nicht alle Dateien in einem Container oder Ordner verarbeiten möchten, sondern bestimmte Dateien in diesem Container oder Ordner, verwenden Sie das azureBlobFileListSource Objekt. Für diesen Vorgang ist eine JSONL-Datei für die Dateiliste erforderlich, die die zu verarbeitenden Dateien auflistet. Speichern Sie die JSONL-Datei im Stammordner des Containers. Hier ist eine Beispiel-JSONL-Datei mit zwei aufgeführten Dateien:

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

Verwenden Sie eine Dateilistendatei JSONL mit den folgenden Bedingungen:

  • Wenn Sie bestimmte Dateien anstelle aller Dateien in einem Container verarbeiten müssen;
  • Wenn die Gesamtzahl der Dateien im Eingabecontainer oder Ordner den Grenzwert von 10.000 Dateibatchverarbeitung überschreitet;
  • Wenn Sie mehr Kontrolle darüber wünschen, welche Dateien in jeder Batchanforderung verarbeitet werden;
POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobFileListSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "fileList": "myFileList.jsonl"
    ...
  },
  ...
}

In beiden Optionen ist eine Container-URL oder eine Container-SAS-URL erforderlich. Verwenden Sie container-URL, wenn Sie verwaltete Identität verwenden, um auf Ihren Speichercontainer zuzugreifen. Wenn Sie die Signatur für den freigegebenen Zugriff (Shared Access Signature, SAS) verwenden, verwenden Sie eine SAS-URL.

2. Angeben des Speicherorts der Ergebnisse

  • Geben Sie die URL des Azure Blob Storage-Containers (oder die SAS-URL des Containers) an, an der Die Ergebnisse mit resultContainerURL dem Parameter gespeichert werden sollen. Es wird empfohlen, separate Container für Quelle und Ergebnisse zu verwenden, um versehentliches Überschreiben zu verhindern.

  • Legen Sie die overwriteExisting boolesche Eigenschaft fest, um False zu verhindern, dass alle vorhandenen Ergebnisse für dasselbe Dokument überschrieben werden. Wenn Sie vorhandene Ergebnisse überschreiben möchten, legen Sie den Booleschen Wert auf True. Sie werden weiterhin für die Verarbeitung des Dokuments in Rechnung gestellt, auch wenn vorhandene Ergebnisse nicht überschrieben werden.

  • Dient resultPrefix zum Gruppieren und Speichern von Ergebnissen in einem bestimmten Containerordner.

3. Erstellen und Ausführen der POST-Anforderung

Denken Sie daran, die folgenden Beispielcontainer-URL-Werte durch echte Werte aus Ihren Azure Blob Storage-Containern zu ersetzen.

Dieses Beispiel zeigt eine POST-Anforderung mit azureBlobSource Eingabe

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

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

Dieses Beispiel zeigt eine POST-Anforderung mit azureBlobFileListSource und eine Dateilisteneingabe.

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

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

Hier ist ein Beispiel für eine erfolgreiche Antwort.

202 Accepted
Operation-Location: /documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30

4. API-Ergebnisse abrufen

Verwenden Sie den GET Vorgang, um Die Ergebnisse der Batchanalyse abzurufen, nachdem der POST-Vorgang ausgeführt wurde. Der GET-Vorgang ruft Statusinformationen, Prozentsatz des Batchabschlusses sowie Erstellungs- und Aktualisierungsdatum/-uhrzeit des Vorgangs ab. Diese Informationen werden erst 24 Stunden nach Abschluss der Batchanalyse aufbewahrt.

GET {endpoint}/documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30
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"
...
}

5. Interpretieren von Statusmeldungen

Für jedes verarbeitete Dokument wird ein Status zugewiesen, entweder succeeded, , failed, , running, notStartedoder skipped. Es wird eine Quell-URL bereitgestellt, bei der es sich um den Quell-BLOB-Speichercontainer für das Eingabedokument handelt.

  • 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 succeeded: Der Batchvorgang war erfolgreich, und das Eingabedokument wurde verarbeitet. Die Ergebnisse sind verfügbar unter resultUrl, die durch Kombinieren resultContainerUrl, , resultPrefix, input filenameund .ocr.json Erweiterung erstellt wird. Nur Dateien, die erfolgreich waren, weisen die Eigenschaft resultUrlauf.

    Beispiel für eine succeeded-Statusantwort:

    {
    "resultId": "myresultId-",
    "status": "succeeded",
    "percentCompleted": 100,
    "createdDateTime": "2025-01-01T00:00:000",
    "lastUpdatedDateTime": "2025-01-01T00:00:000",
    "result": {
        "succeededCount": 10,000,
        "failedCount": 0,
        "skippedCount": 0,
        "details": [
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document1.pdf.ocr.json",
                "status": "succeeded"
            },
          ...
            {
                "sourceUrl": "https://{your-source-container}/inputFolder/document10000.pdf",
                "resultUrl": "https://{your-result-container}/resultsFolder/document10000.pdf.ocr.json",
                "status": "succeeded"
            }
       ]

     }
}

  • Status failed: Dieser Fehler wird nur dann zurückgegeben, wenn in der gesamten Batchanforderung Fehler auftreten. Sobald der Batchanalysevorgang gestartet wird, wirkt sich der Status des einzelnen Dokumentvorgangs nicht auf den Status des gesamten Batchauftrags aus, auch wenn alle Dateien den Status failedhaben.

    Beispiel für eine failed-Statusantwort:

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

  • Status skipped: Dieser Status tritt in der Regel auf, wenn die Ausgabe für das Dokument bereits im angegebenen Ausgabeordner vorhanden ist und die overwriteExisting boolesche Eigenschaft auf false.

    Beispiel für eine skipped-Statusantwort:

    [
     "result": {
     "succeededCount": 3,
     "failedCount": 0,
     "skippedCount": 2,
     "details": [
         ...
         "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
         "status": "skipped",
         "error": {
             "code": "OutputExists",
             "message": "Analysis skipped because result file https://{your-result-container}/resultsFolder/document1.pdf.ocr.json already exists."
              }
         ]
     }
]
...

    Hinweis

    Analyseergebnisse werden erst für einzelne Dateien zurückgegeben, wenn die Analyse für den gesamten Batch abgeschlossen ist. Um den detaillierten Fortschritt nachzuverfolgen percentCompleted, können Sie Dateien überwachen *.ocr.json , während sie in die resultContainerUrlDatei geschrieben sind.

Nächste Schritte

Anzeigen von Codebeispielen auf GitHub

  • Last updated on