Delen via

Batchanalyse van Document Intelligence

Met de batchanalyse-API kunt u maximaal 10.000 documenten bulksgewijs verwerken met één aanvraag. In plaats van documenten één voor één te analyseren en hun respectieve aanvraag-id's bij te houden, kunt u tegelijkertijd een verzameling documenten analyseren, zoals facturen, leningpapieren of aangepaste documenten. De invoerdocumenten moeten worden opgeslagen in een Azure Blob Storage-container. Zodra de documenten zijn verwerkt, schrijft de API de resultaten naar een opgegeven opslagcontainer.

Limieten voor batchanalyse

  • Het maximum aantal documentbestanden dat zich in één batchaanvraag kan bevinden, is 10.000.
  • Resultaten van batchbewerking worden 24 uur na voltooiing bewaard. De status van de batchbewerking is 24 uur nadat de batchverwerking is voltooid, niet meer beschikbaar. De invoerdocumenten en de respectieve resultaatbestanden blijven aanwezig in de opgegeven opslagcontainers.

Vereisten

  • Een actief Azure-abonnement. Als u geen Azure-abonnement hebt, kunt u er gratis een maken.

  • Een Document Intelligence Azure-resource: zodra u uw Azure-abonnement hebt, maakt u een Document Intelligence-resource in Azure Portal. U kunt de gratis prijscategorie (F0) gebruiken om de service uit te proberen. Nadat uw resource is geïmplementeerd, selecteert u 'Ga naar resource' om uw sleutel en eindpunt op te halen. U hebt de resourcesleutel en het eindpunt nodig om uw toepassing te verbinden met de Document Intelligence-service. U kunt deze waarden ook vinden op de pagina Sleutels en eindpunt in Azure Portal.

  • Een Azure Blob Storage-account. Maak twee containers in uw Azure Blob Storage-account voor uw bron- en resultaatbestanden:

    • Broncontainer: In deze container uploadt u documentbestanden voor analyse.
    • Resultaatcontainer: In deze container worden de resultaten van de batchanalyse-API opgeslagen.

Autorisatie van opslagcontainers

Als u wilt toestaan dat de API documenten verwerkt en resultaten schrijft in uw Azure Storage-containers, moet u een van de volgende twee opties gebruiken:

✔️ Beheerde identiteit. Een beheerde identiteit is een service-principal waarmee een Microsoft Entra-identiteit en specifieke machtigingen voor een door Azure beheerde resource worden gemaakt. Met beheerde identiteiten kunt u uw Document Intelligence-toepassing uitvoeren zonder referenties in te sluiten in uw code, een veiligere manier om toegang te verlenen tot opslaggegevens zonder toegangstokens (SAS) in uw code op te slaan.

Bekijk beheerde identiteiten voor Document Intelligence voor meer informatie over het inschakelen van een beheerde identiteit voor uw resource en het verlenen van toegang tot uw opslagcontainer.

Belangrijk

Wanneer u beheerde identiteiten gebruikt, moet u geen SAS-token-URL met uw HTTP-aanvragen opnemen. Als u beheerde identiteiten gebruikt, wordt de vereiste voor het opnemen van sas-tokens (Shared Access Signature) vervangen.

✔️ Shared Access Signature (SAS). Een handtekening voor gedeelde toegang is een URL die beperkte toegang verleent tot uw opslagcontainer. Als u deze methode wilt gebruiken, maakt u SAS-tokens (Shared Access Signature) voor uw bron- en resultaatcontainers. Ga naar de opslagcontainer in Azure Portal en selecteer Gedeelde toegangstokens om een SAS-token en -URL te genereren.

  • Uw broncontainer of blob moet lees-, schrijf-, lijst- en verwijdermachtigingen aanwijzen.
  • Uw resultaatcontainer of blob moet schrijf-, lijst- en verwijdermachtigingen aanwijzen.

Schermopname van de SAS-machtigingsvelden in Azure Portal.

Raadpleeg SAS-tokens maken voor meer informatie over het genereren van SAS-tokens en hoe ze werken.

De batchanalyse-API aanroepen

1. Geef de invoerbestanden op

De batch-API ondersteunt twee opties voor het opgeven van de bestanden die moeten worden verwerkt.

  • Als u alle bestanden in een container of map wilt verwerken en het aantal bestanden kleiner is dan de limiet van 10000, gebruikt u het azureBlobSource object in uw aanvraag.

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

  • Als u niet alle bestanden in een container of map wilt verwerken, maar liever specifieke bestanden in die container of map, gebruikt u het azureBlobFileListSource object. Voor deze bewerking is een JSONL-bestand met een bestandslijst vereist dat de bestanden bevat die moeten worden verwerkt. Sla het JSONL-bestand op in de hoofdmap van de container. Hier volgt een voorbeeld van een JSONL-bestand met twee vermelde bestanden:

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

Gebruik een bestand met JSONL de volgende voorwaarden:

  • Wanneer u specifieke bestanden moet verwerken in plaats van alle bestanden in een container;
  • Wanneer het totale aantal bestanden in de invoercontainer of map de verwerkingslimiet van 10.000 bestandsbatches overschrijdt;
  • Wanneer u meer controle wilt over welke bestanden in elke batchaanvraag worden verwerkt;
POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

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

Een container-URL of een SAS-URL voor containers is vereist in beide opties. Gebruik container-URL als u beheerde identiteit gebruikt voor toegang tot uw opslagcontainer. Als u Shared Access Signature (SAS) gebruikt, gebruikt u een SAS-URL.

2. Geef de locatie van de resultaten op

  • Geef de URL van de Azure Blob Storage-container (of SAS-URL voor containers) op waar u de resultaten wilt opslaan met behulp van resultContainerURL de parameter. U wordt aangeraden afzonderlijke containers voor bron en resultaten te gebruiken om onbedoeld overschrijven te voorkomen.

  • Stel de overwriteExisting booleaanse eigenschap in op False en voorkom dat bestaande resultaten voor hetzelfde document worden overschreven. Als u bestaande resultaten wilt overschrijven, stelt u de Booleaanse waarde in op True. U wordt nog steeds gefactureerd voor het verwerken van het document, zelfs als bestaande resultaten niet worden overschreven.

  • Hiermee resultPrefix kunt u resultaten groeperen en opslaan in een specifieke containermap.

3. De POST-aanvraag bouwen en uitvoeren

Vergeet niet om de volgende voorbeeldcontainer-URL-waarden te vervangen door echte waarden uit uw Azure Blob Storage-containers.

In dit voorbeeld ziet u een POST-aanvraag met azureBlobSource invoer

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
}

In dit voorbeeld ziet u een POST-aanvraag met azureBlobFileListSource en invoer van een bestandslijst

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 volgt een voorbeeld van een geslaagd antwoord

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

4. API-resultaten ophalen

Gebruik de GET bewerking om batchanalyseresultaten op te halen nadat de POST-bewerking is uitgevoerd. De GET-bewerking haalt statusinformatie, batchvoltooiingspercentage en het maken en bijwerken van de datum/tijd van de bewerking op. Deze informatie wordt slechts 24 uur bewaard nadat de batchanalyse is voltooid.

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. Statusberichten interpreteren

Voor elk verwerkt document wordt een status toegewezen, ofwel succeeded, failedrunning, notStartedof skipped. Er wordt een bron-URL, de bron-blobopslagcontainer voor het invoerdocument, opgegeven.

  • Status notStarted of running. De batchanalysebewerking wordt niet gestart of is niet voltooid. Wacht totdat de bewerking is voltooid voor alle documenten.

  • Status completed. De batchanalysebewerking is voltooid.

  • Status succeeded. De batchbewerking is voltooid en het invoerdocument is verwerkt. De resultaten zijn beschikbaar op resultUrl, dat wordt gemaakt door combinatie resultContainerUrl, resultPrefix, en input filename.ocr.json extensie. Alleen bestanden die zijn geslaagd, hebben de eigenschap resultUrl.

    Voorbeeld van een succeeded statusantwoord:

    {
    "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. Deze fout wordt alleen geretourneerd als er fouten zijn in de algehele batchaanvraag. Zodra de batchanalysebewerking is gestart, heeft de afzonderlijke documentbewerkingsstatus geen invloed op de status van de algehele batchtaak, zelfs als alle bestanden de status failedhebben.

    Voorbeeld van een failed statusantwoord:

    [
    "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: Deze status treedt meestal op wanneer uitvoer voor het document al aanwezig is in de opgegeven uitvoermap en de overwriteExisting booleaanse eigenschap is ingesteld op false.

    Voorbeeld van skipped statusantwoord:

    [
     "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."
              }
         ]
     }
]
...

    Notitie

    Analyseresultaten worden pas geretourneerd voor afzonderlijke bestanden als de analyse voor de hele batch is voltooid. Als u gedetailleerde voortgang verder percentCompletedwilt bijhouden, kunt u bestanden bewaken *.ocr.json terwijl ze in het resultContainerUrlbestand worden geschreven.

Volgende stappen

Codevoorbeelden weergeven op GitHub.

  • Last updated on