Dela via

Batchanalys för dokumentinformation (förhandsversion)

  • Artikel

Viktigt!

  • Versioner av den offentliga förhandsversionen av Document Intelligence ger tidig åtkomst till funktioner som är i aktiv utveckling. Funktioner, metoder och processer kan ändras, före allmän tillgänglighet (GA), baserat på användarfeedback.
  • Den offentliga förhandsversionen av Dokumentinformationsklientbiblioteken är som standard REST API version 2024-07-31-preview.
  • Den offentliga förhandsversionen 2024-07-31-preview är för närvarande endast tillgänglig i följande Azure-regioner. Observera att modellen för anpassad generativ (extrahering av dokumentfält) i AI Studio endast är tillgänglig i regionen USA, norra centrala:
    • USA, östra
    • USA, västra 2
    • Europa, västra
    • USA, norra centrala

Med BATCH-analys-API:et kan du massbearbeta flera dokument med hjälp av en asynkron begäran. I stället för att behöva skicka dokument individuellt och spåra flera begärande-ID:t kan du analysera en samling fakturor, en serie lånedokument eller en grupp anpassade modellträningsdokument samtidigt.

  • För att kunna använda batchanalys behöver du ett Azure Blob Storage-konto med specifika containrar för både källdokumenten och de bearbetade utdata.
  • När du har slutfört batchåtgärdsresultatet visas alla enskilda dokument som bearbetas med deras status, till exempel succeeded, skippedeller failed.
  • Förhandsversionen av Batch API är tillgänglig via betala per användning-priser.

Följande modeller stöder batchanalys:

  • Läsa. Extrahera textrader, ord, identifierade språk och handskriven stil från formulär och dokument.

  • Layout. Extrahera text, tabeller, markeringar och strukturinformation från formulär och dokument.

  • Anpassad mall. Träna modeller för att extrahera nyckel/värde-par, markeringsmarkeringar, tabeller, signaturfält och regioner från strukturerade formulär.

  • Anpassad neural. Träna modeller för att extrahera angivna datafält från strukturerade, halvstrukturerade och ostrukturerade dokument.

  • Anpassad generativ. Träna modeller för att extrahera angivna data från komplexa objekt som kapslade tabeller, abstrakta/generativa fält och verkligt ostrukturerade format.

Vägledning för batchanalys

  • Det maximala antalet dokument som bearbetas per enskild batchanalysbegäran (inklusive överhoppade dokument) är 10 000.

  • Parametern azureBlobFileListSource kan användas för att dela upp större begäranden i mindre.

  • Åtgärdsresultat behålls i 24 timmar efter slutförande. Dokumenten och resultaten finns i det angivna lagringskontot, men åtgärdsstatusen är inte längre tillgänglig 24 timmar efter slutförandet.

Är du redo att börja?

Förutsättningar

  • Du behöver en aktiv Azure-prenumeration. Om du inte har en Azure-prenumeration kan du skapa en kostnadsfritt.

  • När du har din Azure-prenumeration har du en dokumentinformationsinstans i Azure Portal. Du kan använda den kostnadsfria prisnivån (F0) för att prova tjänsten.

  • När resursen har distribuerats väljer du Gå till resurs och hämtar nyckeln och slutpunkten.

    • Du behöver nyckeln och slutpunkten från resursen för att ansluta ditt program till dokumentinformationstjänsten. Du klistrar in nyckeln och slutpunkten i koden senare i snabbstarten. Du hittar dessa värden på sidan Azure Portal nycklar och slutpunkt.

  • Ett Azure Blob Storage-konto. Du skapar containrar i ditt Azure Blob Storage-konto för käll- och resultatfilerna:

    • Källcontainer. I den här containern laddar du upp dina filer för analys (krävs).
    • Resultatcontainer. I den här containern lagras dina bearbetade filer (valfritt).

Du kan ange samma Azure Blob Storage-container för källdokument och bearbetade dokument. Men för att minimera potentiella chanser att oavsiktligt skriva över data rekommenderar vi att du väljer separata containrar.

Auktorisering av lagringscontainer

Du kan välja något av följande alternativ för att auktorisera åtkomst till dokumentresursen.

✔️ Hanterad identitet. En hanterad identitet är ett huvudnamn för tjänsten som skapar en Microsoft Entra-identitet och specifika behörigheter för en Azure-hanterad resurs. Med hanterade identiteter kan du köra ditt dokumentinformationsprogram utan att behöva bädda in autentiseringsuppgifter i koden. Hanterade identiteter är ett säkrare sätt att bevilja åtkomst till lagringsdata och ersätta kravet på att du ska inkludera signaturtoken för delad åtkomst (SAS) med dina käll- och resultat-URL:er.

Mer information finns i Hanterade identiteter för Dokumentinformation.

Skärmbild av hanterat identitetsflöde (rollbaserad åtkomstkontroll).

Viktigt!

  • När du använder hanterade identiteter ska du inte inkludera en SAS-token-URL med dina HTTP-begäranden– dina begäranden misslyckas. Att använda hanterade identiteter ersätter kravet på att du ska inkludera signaturtoken för delad åtkomst (SAS).

✔️ Signatur för delad åtkomst (SAS). En signatur för delad åtkomst är en URL som ger begränsad åtkomst under en angiven tidsperiod till din dokumentinformationstjänst. Om du vill använda den här metoden måste du skapa SAS-token (Signatur för delad åtkomst) för dina käll- och resultatcontainrar. Käll- och resultatcontainrarna måste innehålla en SAS-token (Signatur för delad åtkomst) som läggs till som en frågesträng. Token kan tilldelas till din container eller specifika blobar.

Skärmbild av lagrings-URI med SAS-token bifogad.

  • Källcontainern eller bloben måste ange läs-, skriv-, list- och borttagningsåtkomst.
  • Din resultatcontainer eller blob måste ange skriv-, list- och borttagningsåtkomst .

Mer information finns i Skapa SAS-token.

Anropa batchanalys-API:et

  • Ange url:en för Azure Blob Storage-containern för källdokumentuppsättningen i objekten azureBlobSource eller azureBlobFileListSource .

  • Ange url:en för Azure Blob Storage-containern för batchanalysresultatet med hjälp av resultContainerUrl. För att undvika oavsiktlig överskrivning rekommenderar vi att du använder separata containrar för källdokument och bearbetade dokument.

    • Om du använder samma container ställer du in resultContainerUrl och resultPrefix matchar dina indata azureBlobSource.
    • När du använder samma container kan du inkludera fältet overwriteExisting för att bestämma om du vill skriva över några filer med analysresultatfilerna.

Skapa och kör POST-begäran

Innan du kör POST-begäran ersätter du {your-source-container-SAS-URL} och {your-result-container-SAS-URL} med värdena från dina Azure Blob Storage-containerinstanser.

Tillåt endast en eller azureBlobSource azureBlobFileListSource.

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

Lyckat svar

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

Hämta api-resultat för batchanalys

När batch-API-åtgärden har körts kan du hämta batchanalysresultatet med hjälp av åtgärdenGET . Den här åtgärden hämtar information om åtgärdsstatus, procent för slutförande av åtgärden och skapande av åtgärder och uppdateringsdatum/tid.

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

Tolka statusmeddelanden

För varje dokument en uppsättning tilldelas en status, antingen succeeded, failedeller skipped. För varje dokument finns det två URL:er som tillhandahålls för att verifiera resultatet: sourceUrl, som är källbloblagringscontainern för det lyckade indatadokumentet och resultUrl, som skapas genom att kombinera resultContainerUrl ochresultPrefix skapa den relativa sökvägen för källfilen och .ocr.json.

  • Status notStarted eller running. Batchanalysåtgärden initieras inte eller slutförs inte. Vänta tills åtgärden har slutförts för alla dokument.

  • Status completed. Batchanalysåtgärden är klar.

  • Status failed. Batchåtgärden misslyckades. Det här svaret inträffar vanligtvis om det finns övergripande problem med begäran. Fel på enskilda filer returneras i batchrapportsvaret, även om alla filer misslyckades. Lagringsfel stoppar till exempel inte batchåtgärden som helhet, så att du kan komma åt partiella resultat via batchrapportens svar.

Endast filer som har status succeeded har egenskapen resultUrl genererad i svaret. Detta gör det möjligt för modellträning att identifiera filnamn som slutar med .ocr.json och identifiera dem som de enda filer som kan användas för träning.

Exempel på ett succeeded statussvar:

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

Exempel på ett failed statussvar:

  • Det här felet returneras endast om det finns fel i den övergripande batchbegäran.
  • När batchanalysåtgärden har startats påverkar inte statusen för enskilda dokumentåtgärder statusen för det övergripande batchjobbet, även om alla filer har statusen failed.
[
    "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}"
                }
            }
        ]
    }
]
...

Exempel på skipped statussvar:

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

Batchanalysresultaten hjälper dig att identifiera vilka filer som analyseras och validera analysresultaten genom att jämföra filen i resultUrl med utdatafilen i resultContainerUrl.

Kommentar

Analysresultat returneras inte för enskilda filer förrän hela batchanalysen för dokumentuppsättningen har slutförts. Om du vill spåra detaljerade framsteg utöver percentCompletedkan du övervaka *.ocr.json filer när de skrivs resultContainerUrltill .

Nästa steg

Visa kodexempel på GitHub.