Dela via

Batchanalys för dokumentinformation

  • Artikel

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 dokument som fakturor, en serie lånedokument eller en grupp anpassade dokument samtidigt. Batch-API:et stöder läsning av dokument från Azure Blob Storage och skrivning av resultaten till bloblagring.

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

Vägledning för batchanalys

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

  • Å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 indatafilerna

Batch-API:et stöder två alternativ för att ange vilka filer som ska bearbetas. Om du behöver alla filer i en container eller mapp som bearbetas och antalet filer är mindre än gränsen på 1 0000 för en enskild batchbegäran använder du containern azureBlobSource .

Om du har specifika filer i containern eller mappen att bearbeta eller om antalet filer som ska bearbetas överskrider maxgränsen för en enskild batch använder du azureBlobFileListSource. Dela upp datamängden i flera batchar och lägg till en fil med listan över filer som ska bearbetas i ett JSONL-format i rotmappen i containern. Ett exempel på fillisteformatet är.

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

Ange resultatplatsen

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.

Ange den overwriteExisting booleska egenskapen till false om du inte vill att några befintliga resultat med samma filnamn ska skrivas över. Den här inställningen påverkar inte faktureringen och förhindrar bara att resultat skrivs över när indatafilen har bearbetats.

resultPrefix Ange till namnrymd för resultatet från den här körningen av batch-API:et.

  • Om du planerar att använda samma container för både indata och utdata anger du 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.

Följande exempel visar hur du azureBlobSource lägger till egenskapen i begäran:

Tillåt endast en eller azureBlobSource azureBlobFileListSource.

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
}

Följande exempel visar hur du azureBlobFileListSource lägger till egenskapen i begäran:

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
}

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.