Delen via

Batchanalyse van Document Intelligence (preview)

  • Artikel

Belangrijk

  • Openbare preview-versies van Document Intelligence bieden vroegtijdige toegang tot functies die actief zijn in ontwikkeling. Functies, benaderingen en processen kunnen veranderen, vóór algemene beschikbaarheid (GA), op basis van feedback van gebruikers.
  • De openbare preview-versie van Document Intelligence-clientbibliotheken is standaard ingesteld op REST API-versie 2024-07-31-preview.
  • Openbare preview-versie 2024-07-31-preview is momenteel alleen beschikbaar in de volgende Azure-regio's. Houd er rekening mee dat het aangepaste model voor generatieve (extractie van documentvelden) in AI Studio alleen beschikbaar is in de regio VS - noord-centraal:
    • VS - oost
    • VS - west 2
    • Europa -west
    • VS - noord-centraal

Met de batchanalyse-API kunt u meerdere documenten bulksgewijs verwerken met één asynchrone aanvraag. In plaats van documenten afzonderlijk in te dienen en meerdere aanvraag-id's bij te houden, kunt u een verzameling facturen, een reeks leningdocumenten of een groep aangepaste modeltrainingsdocumenten tegelijk analyseren.

  • Als u batchanalyse wilt gebruiken, hebt u een Azure Blob Storage-account met specifieke containers nodig voor zowel uw brondocumenten als de verwerkte uitvoer.
  • Na voltooiing bevat het resultaat van de batchbewerking alle afzonderlijke documenten die zijn verwerkt met hun status, zoals succeeded, skippedof failed.
  • De Preview-versie van de Batch-API is beschikbaar via prijzen voor betalen per gebruik.

De volgende modellen ondersteunen batchanalyse:

  • Lezen. Extraheer tekstregels, woorden, gedetecteerde talen en handgeschreven stijl uit formulieren en documenten.

  • Indeling. Tekst, tabellen, selectiemarkeringen en structuurgegevens extraheren uit formulieren en documenten.

  • Aangepaste sjabloon. Modellen trainen om sleutel-waardeparen, selectiemarkeringen, tabellen, handtekeningvelden en regio's uit gestructureerde formulieren te extraheren.

  • Aangepaste neurale. Modellen trainen om opgegeven gegevensvelden te extraheren uit gestructureerde, semi-gestructureerde en ongestructureerde documenten.

  • Aangepaste generatieve. Train modellen om opgegeven gegevens te extraheren uit complexe objecten, zoals geneste tabellen, abstractieve/generatieve velden en werkelijk ongestructureerde indelingen.

Richtlijnen voor batchanalyse

  • Het maximum aantal documenten dat per aanvraag voor één batchanalyse wordt verwerkt (inclusief overgeslagen documenten) is 10.000.

  • De azureBlobFileListSource parameter kan worden gebruikt om grotere aanvragen op te splitsen in kleinere aanvragen.

  • De resultaten van de bewerking worden 24 uur na voltooiing bewaard. De documenten en resultaten bevinden zich in het opgegeven opslagaccount, maar de bewerkingsstatus is 24 uur na voltooiing niet meer beschikbaar.

Klaar om aan de slag te gaan?

Vereisten

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

  • Zodra u uw Azure-abonnement een Document Intelligence-exemplaar hebt in Azure Portal. U kunt de gratis prijscategorie (F0) gebruiken om de service te proberen.

  • Nadat uw resource is geïmplementeerd, selecteert u Ga naar de resource en haalt u uw sleutel en eindpunt op.

    • U hebt de sleutel en het eindpunt van de resource nodig om uw toepassing te verbinden met de Document Intelligence-service. U plakt uw sleutel en eindpunt verderop in de code in de quickstart. U vindt deze waarden op de pagina Sleutels en eindpunten van Azure Portal.

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

    • Broncontainer. In deze container uploadt u uw bestanden voor analyse (vereist).
    • Resultaatcontainer. In deze container worden uw verwerkte bestanden opgeslagen (optioneel).

U kunt dezelfde Azure Blob Storage-container aanwijzen voor bron- en verwerkte documenten. Als u echter de potentiële kans op het per ongeluk overschrijven van gegevens wilt minimaliseren, raden we u aan afzonderlijke containers te kiezen.

Autorisatie van opslagcontainers

U kunt een van de volgende opties kiezen om toegang tot uw documentresource te autoriseren.

✔️ 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 uw code in te sluiten. Beheerde identiteiten zijn een veiligere manier om toegang te verlenen tot opslaggegevens en om de vereiste voor het opnemen van sas-tokens (Shared Access Signature) te vervangen door uw bron- en resultaat-URL's.

Zie Beheerde identiteiten voor Document Intelligence voor meer informatie.

Schermopname van de stroom van beheerde identiteiten (op rollen gebaseerd toegangsbeheer).

Belangrijk

  • Wanneer u beheerde identiteiten gebruikt, neemt u geen SAS-token-URL op met uw HTTP-aanvragen. Uw aanvragen mislukken. 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 gedurende een opgegeven periode beperkte toegang verleent aan uw Document Intelligence-service. Als u deze methode wilt gebruiken, moet u SAS-tokens (Shared Access Signature) maken voor uw bron- en resultaatcontainers. De bron- en resultaatcontainers moeten een SAS-token (Shared Access Signature) bevatten, toegevoegd als een querytekenreeks. Het token kan worden toegewezen aan uw container of specifieke blobs.

Schermopname van opslag-URI met een SAS-token toegevoegd.

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

Zie SAS-tokens maken voor meer informatie.

De batchanalyse-API aanroepen

  • Geef de URL van de Azure Blob Storage-container op voor uw brondocumentset in de azureBlobSource of azureBlobFileListSource objecten.

  • Geef de URL van de Azure Blob Storage-container op voor uw batchanalyseresultaten met behulp van resultContainerUrl. Om onbedoeld overschrijven te voorkomen, raden we u aan afzonderlijke containers te gebruiken voor bron- en verwerkte documenten.

    • Als u dezelfde container gebruikt, stelt u deze in resultContainerUrl en resultPrefix komt deze overeen met uw invoer azureBlobSource.
    • Wanneer u dezelfde container gebruikt, kunt u het overwriteExisting veld opnemen om te bepalen of u bestanden met de analyseresultatenbestanden wilt overschrijven.

De POST-aanvraag bouwen en uitvoeren

Voordat u de POST-aanvraag uitvoert, vervangt u {your-source-container-SAS-URL} en {your-result-container-SAS-URL} door de waarden uit uw Azure Blob Storage-containerinstanties.

Sta slechts één of azureBlobSource azureBlobFileListSourceéén toe.

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
  }
]

Geslaagde reactie

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

Api-resultaten voor batchanalyse ophalen

Nadat de Batch API-bewerking is uitgevoerd, kunt u de batchanalyseresultaten ophalen met behulp van deGET bewerking. Met deze bewerking worden informatie over de bewerkingsstatus, voltooiingspercentage van de bewerking en het maken en bijwerken van datum/tijd opgehaald.

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

Statusberichten interpreteren

Voor elk document is er een status toegewezen, ofwel succeeded, failedof skipped. Voor elk document zijn er twee URL's opgegeven om de resultaten te valideren: sourceUrl, dit is de bron-blobopslagcontainer voor uw geslaagde invoerdocument, en resultUrl, dat is samengesteld door het relatieve pad voor het bronbestand te combineren resultContainerUrl enresultPrefix te maken en .ocr.json.

  • 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 failed. De batchbewerking is mislukt. Dit antwoord treedt meestal op als er algemene problemen zijn met de aanvraag. Fouten voor afzonderlijke bestanden worden geretourneerd in de reactie van het batchrapport, zelfs als alle bestanden zijn mislukt. Opslagfouten stoppen bijvoorbeeld de batchbewerking niet als geheel, zodat u gedeeltelijke resultaten kunt openen via het batchrapportantwoord.

Alleen bestanden met een succeeded status hebben de eigenschap resultUrl gegenereerd in het antwoord. Hierdoor kan modeltraining bestandsnamen detecteren die eindigen .ocr.json en identificeren als de enige bestanden die kunnen worden gebruikt voor training.

Voorbeeld van een succeeded statusantwoord:

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

Voorbeeld van een failed statusantwoord:

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

Voorbeeld van skipped statusantwoord:

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

Met de resultaten van de batchanalyse kunt u bepalen welke bestanden met succes worden geanalyseerd en gevalideerd door het bestand in het resultUrl bestand te vergelijken met het uitvoerbestand in de resultContainerUrl.

Notitie

Analyseresultaten worden pas geretourneerd voor afzonderlijke bestanden als de volledige batchanalyse van de documentenset 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.