Dávkové analýzy funkce Document Intelligence

Článek
12/12/2024

Rozhraní API dávkové analýzy umožňuje hromadně zpracovávat více dokumentů pomocí jednoho asynchronního požadavku. Místo toho, abyste museli odesílat dokumenty jednotlivě a sledovat více ID žádostí, můžete analyzovat kolekci dokumentů, jako jsou faktury, řada úvěrových dokumentů nebo skupina vlastních dokumentů současně. Rozhraní API služby Batch podporuje čtení dokumentů ze služby Azure Blob Storage a zápis výsledků do úložiště objektů blob.

Pokud chcete využít dávkovou analýzu, potřebujete účet služby Azure Blob Storage s konkrétními kontejnery pro zdrojové dokumenty i zpracovávané výstupy.
Po dokončení zobrazí výsledek dávkové operace seznam všech jednotlivých dokumentů zpracovaných s jejich stavem, například succeeded, skippednebo failed.
Verze Preview rozhraní API služby Batch je dostupná prostřednictvím cen průběžných plateb.

Pokyny k dávkové analýze

Maximální počet dokumentů zpracovaných na jeden dávkový požadavek na analýzu (včetně přeskočených dokumentů) je 10 000.
Výsledky operace se uchovávají po dobu 24 hodin po dokončení. Dokumenty a výsledky jsou uvedené v zadaném účtu úložiště, ale stav operace už není po dokončení k dispozici 24 hodin.

Jste připravení začít?

Požadavky

Potřebujete aktivní předplatné Azure. Pokud předplatné Azure nemáte, můžete si ho zdarma vytvořit.
Jakmile máte předplatné Azure A instanci Document Intelligence na webu Azure Portal. K vyzkoušení služby můžete použít cenovou úroveň Free (F0).
Po nasazení prostředku vyberte Přejít k prostředku a načtěte svůj klíč a koncový bod.
- K připojení aplikace ke službě Document Intelligence potřebujete klíč a koncový bod z prostředku. Klíč a koncový bod vložíte do kódu později v rychlém startu. Tyto hodnoty najdete na stránce Klíče webu Azure Portal a koncový bod .
Účet služby Azure Blob Storage. Kontejnery vytvoříte ve svém účtu Azure Blob Storage pro zdrojové a výsledné soubory:
- Zdrojový kontejner. V tomto kontejneru nahrajete soubory pro analýzu (povinné).
- Kontejner výsledků V tomto kontejneru jsou uložené vaše zpracované soubory (volitelné).

Pro zdrojové a zpracovávané dokumenty můžete určit stejný kontejner služby Azure Blob Storage. Pokud ale chcete minimalizovat potenciální pravděpodobnost náhodného přepsání dat, doporučujeme zvolit samostatné kontejnery.

Autorizace kontejneru úložiště

Pokud chcete autorizovat přístup k prostředku dokumentu, můžete zvolit jednu z následujících možností.

✔️ Spravovaná identita Spravovaná identita je instanční objekt, který vytvoří identitu Microsoft Entra a konkrétní oprávnění pro spravovaný prostředek Azure. Spravované identity umožňují spouštět aplikaci Document Intelligence, aniž byste museli vkládat přihlašovací údaje do kódu. Spravované identity představují bezpečnější způsob, jak udělit přístup k datům úložiště a nahradit požadavek na zahrnutí tokenů sdíleného přístupového podpisu (SAS) se zdrojovými a výslednými adresami URL.

Další informace najdete v tématu Spravované identity pro funkci Document Intelligence.

Snímek obrazovky s tokem spravované identity (řízení přístupu na základě role)

Důležité

Při použití spravovaných identit nezahrnujte do požadavků HTTP adresu URL tokenu SAS – vaše požadavky selžou. Použití spravovaných identit nahrazuje požadavek na zahrnutí tokenů sdíleného přístupového podpisu (SAS).

✔️ Sdílený přístupový podpis (SAS) Sdílený přístupový podpis je adresa URL, která uděluje omezený přístup po určitou dobu službě Document Intelligence. Pokud chcete tuto metodu použít, musíte pro zdrojové kontejnery a kontejnery výsledků vytvořit tokeny sdíleného přístupového podpisu (SAS). Kontejnery zdroje a výsledku musí obsahovat token sdíleného přístupového podpisu (SAS) připojený jako řetězec dotazu. Token se dá přiřadit ke kontejneru nebo konkrétním objektům blob.

Snímek obrazovky s identifikátorem URI úložiště s připojeným tokenem SAS

Zdrojový kontejner nebo objekt blob musí určit přístup ke čtení, zápisu, výpisu a odstranění.
Kontejner výsledků nebo objekt blob musí určit přístup k zápisu, výpisu a odstranění .

Další informace najdete v tématu Vytváření tokenů SAS.

Volání rozhraní API pro dávkovou analýzu

Zadejte adresu URL kontejneru služby Azure Blob Storage pro zdrojovou sadu dokumentů v rámci azureBlobSource objektů nebo azureBlobFileListSource objektů.

Zadání vstupních souborů

Dávkové rozhraní API podporuje dvě možnosti pro určení souborů, které se mají zpracovat. Pokud potřebujete všechny soubory v kontejneru nebo složce zpracovávané a počet souborů je menší než limit 1 0000 pro jeden dávkový požadavek, použijte azureBlobSource kontejner.

Pokud máte v kontejneru nebo složce konkrétní soubory ke zpracování nebo počet zpracovávaných souborů je nad maximální limit pro jednu dávku, použijte azureBlobFileListSource. Rozdělte datovou sadu do několika dávek a přidejte soubor se seznamem souborů, které se mají zpracovat ve formátu JSONL v kořenové složce kontejneru. Příkladem formátu seznamu souborů je.

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

Určení umístění výsledků

Zadejte adresu URL kontejneru služby Azure Blob Storage pro výsledky dávkové analýzy pomocí resultContainerUrl. Pokud se chcete vyhnout náhodnému přepsání, doporučujeme pro zdrojové a zpracovávané dokumenty používat samostatné kontejnery.

overwriteExisting Pokud nechcete, aby žádné existující výsledky se stejnými názvy souborů přepsaly, nastavte logickou vlastnost na false. Toto nastavení nemá vliv na fakturaci a brání přepsání výsledků pouze po zpracování vstupního souboru.

resultPrefix Nastavte na obor názvů výsledky tohoto spuštění dávkového rozhraní API.

Pokud plánujete použít stejný kontejner pro vstup i výstup, nastavte resultContainerUrl a resultPrefix spárujte vstup azureBlobSource.
Při použití stejného kontejneru můžete zahrnout overwriteExisting pole a rozhodnout se, jestli chcete přepsat všechny soubory se soubory výsledků analýzy.

Sestavení a spuštění požadavku POST

Před spuštěním požadavku POST nahraďte {your-source-container-SAS-URL} a {your-result-container-SAS-URL} hodnotami z instancí kontejneru služby Azure Blob Storage.

Následující ukázka ukazuje, jak do požadavku přidat azureBlobSource vlastnost:

Povolit pouze jeden azureBlobSource nebo 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
}

Následující ukázka ukazuje, jak do požadavku přidat azureBlobFileListSource vlastnost:

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
}

Úspěšná odpověď

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

Načtení výsledků rozhraní API dávkové analýzy

Po spuštění operace rozhraní API služby Batch můžete pomocíGET operace načíst výsledky dávkové analýzy. Tato operace načte informace o stavu operace, procento dokončení operace a vytvoření operace a datum a čas aktualizace.

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

Interpretace stavových zpráv

Pro každý dokument sady je přiřazen stav , buď succeeded, failednebo skipped. Pro každý dokument jsou k dispozici dvě adresy URL pro ověření výsledků: sourceUrl, což je zdrojový kontejner úložiště objektů blob pro úspěšný vstupní dokument, a resultUrlkterý je vytvořen kombinováním resultContainerUrl aresultPrefix vytvořením relativní cesty pro zdrojový soubor a .ocr.json.

Stav notStarted nebo running. Operace dávkové analýzy není inicializována nebo není dokončena. Počkejte, až se operace dokončí pro všechny dokumenty.
Stav completed. Operace dávkové analýzy je dokončena.
Stav failed. Dávková operace se nezdařila. K této odpovědi obvykle dochází v případě, že dochází k celkovým problémům s požadavkem. Selhání jednotlivých souborů se vrátí v odpovědi dávkové sestavy, i když všechny soubory selhaly. Chyby úložiště například nezastaví dávkovou operaci jako celek, abyste měli přístup k částečným výsledkům prostřednictvím odpovědi dávkové sestavy.

Pouze soubory, které mají stav, mají succeeded vlastnost resultUrl vygenerovanou v odpovědi. To umožňuje trénování modelu zjišťovat názvy souborů, které končí .ocr.json , a identifikovat je jako jediné soubory, které lze použít pro trénování.

Příklad odpovědi na succeeded stav:

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

Příklad odpovědi na failed stav:

Tato chyba se vrátí pouze v případě, že v celkové dávkové žádosti dojde k chybám.
Po spuštění operace dávkové analýzy nemá stav jednotlivých operací dokumentu vliv na stav celkové dávkové úlohy, a to ani v případě, že všechny soubory mají stav 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}"
                }
            }
        ]
    }
]
...

skipped Příklad odpovědi na stav:

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

Výsledky dávkové analýzy pomáhají určit, které soubory jsou úspěšně analyzovány a ověřeny výsledky analýzy porovnáním souboru ve resultUrl výstupním souboru v souboru v souboru resultContainerUrl.

Poznámka:

Výsledky analýzy se nevrácejí pro jednotlivé soubory, dokud se nedokončí celá dávková analýza sady dokumentů. Pokud chcete sledovat podrobný průběh nad rámec percentCompleted, můžete monitorovat *.ocr.json soubory, jak jsou zapsány do souboru resultContainerUrl.

Další kroky

Zobrazení ukázek kódu na GitHubu

Sdílet prostřednictvím