Analiza wsadowa analizy dokumentów

Interfejs API analizy wsadowej umożliwia zbiorcze przetwarzanie wielu dokumentów przy użyciu jednego żądania asynchronicznego. Zamiast przesyłania dokumentów pojedynczo i śledzenia wielu identyfikatorów żądań, możesz przeanalizować kolekcję dokumentów, takich jak faktury, serię dokumentów kredytowych lub grupę dokumentów niestandardowych jednocześnie. Interfejs API usługi Batch obsługuje odczytywanie dokumentów z usługi Azure Blob Storage i zapisywanie wyników w magazynie obiektów blob.

• Do korzystania z analizy wsadowej potrzebne jest konto usługi Azure Blob Storage z określonymi kontenerami zarówno dla dokumentów źródłowych, jak i przetworzonych danych wyjściowych.
• Po zakończeniu wynik operacji wsadowej wyświetla listę wszystkich pojedynczych dokumentów przetworzonych ze stanem, takim jak succeeded, skippedlub failed.
• Wersja zapoznawcza interfejsu API usługi Batch jest dostępna za pośrednictwem cennika płatności zgodnie z rzeczywistym użyciem.

Wskazówki dotyczące analizy wsadowej

• Maksymalna liczba przetworzonych dokumentów na jedno żądanie analizy wsadowej (w tym pominięte dokumenty) wynosi 10 000.

• Wyniki operacji są zachowywane przez 24 godziny po zakończeniu. Dokumenty i wyniki znajdują się na podanym koncie magazynu, ale stan operacji nie jest już dostępny 24 godziny po zakończeniu.

Chcesz rozpocząć?

Wymagania wstępne

• Potrzebna jest aktywna subskrypcja platformy Azure. Jeśli nie masz subskrypcji platformy Azure, możesz go utworzyć bezpłatnie.

• Po utworzeniu subskrypcji platformy Azure wystąpienie analizy dokumentów w witrynie Azure Portal. Aby wypróbować usługę, możesz użyć bezpłatnej warstwy cenowej (F0).

• Po wdrożeniu zasobu wybierz pozycję Przejdź do zasobu i pobierz klucz i punkt końcowy.

  • Potrzebujesz klucza i punktu końcowego z zasobu, aby połączyć aplikację z usługą Analizy dokumentów. Klucz i punkt końcowy wklejasz do kodu w dalszej części przewodnika Szybki start. Te wartości można znaleźć na stronie Klucze i punkt końcowy witryny Azure Portal.

• Konto usługi Azure Blob Storage. Kontenery utworzysz na koncie usługi Azure Blob Storage dla plików źródłowych i wynikowych:

  • Kontener źródłowy. Ten kontener służy do przekazywania plików do analizy (wymagane).
  • Kontener wyników. W tym kontenerze przechowywane są przetworzone pliki (opcjonalnie).

Możesz wyznaczyć ten sam kontener usługi Azure Blob Storage dla dokumentów źródłowych i przetworzonych. Jednak aby zminimalizować potencjalne szanse na przypadkowe zastąpienie danych, zalecamy wybranie oddzielnych kontenerów.

Autoryzacja kontenera magazynu

Możesz wybrać jedną z następujących opcji, aby autoryzować dostęp do zasobu Dokument.

✔️ Tożsamość zarządzana. Tożsamość zarządzana to jednostka usługi, która tworzy tożsamość firmy Microsoft Entra i określone uprawnienia dla zasobu zarządzanego platformy Azure. Tożsamości zarządzane umożliwiają uruchamianie aplikacji analizy dokumentów bez konieczności osadzania poświadczeń w kodzie. Tożsamości zarządzane to bezpieczniejszy sposób udzielania dostępu do danych magazynu i zastępowania wymagań dotyczących dołączania tokenów sygnatury dostępu współdzielonego (SAS) do źródłowych i adresów URL wyników.

Aby dowiedzieć się więcej, zobacz Tożsamości zarządzane na potrzeby analizy dokumentów.

✔️ Sygnatura dostępu współdzielonego (SAS). Sygnatura dostępu współdzielonego to adres URL, który udziela ograniczonego dostępu przez określony okres do usługi analizy dokumentów. Aby użyć tej metody, należy utworzyć tokeny sygnatury dostępu współdzielonego (SAS) dla kontenerów źródłowych i wynikowych. Kontenery źródłowe i wynikowe muszą zawierać token sygnatury dostępu współdzielonego (SAS) dołączany jako ciąg zapytania. Token można przypisać do kontenera lub określonych obiektów blob.

• Źródłowy kontener lub obiekt blob musi wyznaczyć dostęp do odczytu, zapisu, listy i usuwania.
• Kontener wyników lub obiekt blob musi wyznaczyć zapis, listę, usunąć dostęp.

Aby dowiedzieć się więcej, zobacz Tworzenie tokenów SAS.

Wywoływanie interfejsu API analizy wsadowej

• Określ adres URL kontenera usługi Azure Blob Storage dla zestawu dokumentów źródłowych w obiektach azureBlobSource lub azureBlobFileListSource .

Określanie plików wejściowych

Interfejs API wsadowy obsługuje dwie opcje określania plików do przetworzenia. Jeśli potrzebujesz wszystkich plików w przetworzonym kontenerze lub folderze, a liczba plików jest mniejsza niż limit 10000 dla pojedynczego żądania wsadowego, użyj kontenera azureBlobSource .

Jeśli masz określone pliki w kontenerze lub folderze do przetworzenia lub liczba plików do przetworzenia przekracza maksymalny limit dla pojedynczej partii, użyj .azureBlobFileListSource Podziel zestaw danych na wiele partii i dodaj plik z listą plików do przetworzenia w formacie JSONL w folderze głównym kontenera. Przykładem formatu listy plików jest.

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

Określanie lokalizacji wyników

Określ adres URL kontenera usługi Azure Blob Storage dla wyników analizy wsadowej przy użyciu polecenia resultContainerUrl. Aby uniknąć przypadkowego zastąpienia, zalecamy używanie oddzielnych kontenerów dla dokumentów źródłowych i przetworzonych.

overwriteExisting Ustaw właściwość logiczną na false, jeśli nie chcesz, aby żadne istniejące wyniki z tymi samymi nazwami plików zastąpione. To ustawienie nie ma wpływu na rozliczenia i uniemożliwia zastąpienie wyników tylko po przetworzeniu pliku wejściowego.

Ustaw wartość na resultPrefix przestrzeń nazw wyniki z tego przebiegu interfejsu API wsadowego.

• Jeśli planujesz używać tego samego kontenera zarówno dla danych wejściowych, jak i wyjściowych, ustaw resultContainerUrl parametr i resultPrefix w taki sposób, aby był zgodny z danymi wejściowymi azureBlobSource.
• W przypadku korzystania z tego samego kontenera możesz dołączyć overwriteExisting pole, aby zdecydować, czy zastąpić pliki plikami wyników analizy.

Kompilowanie i uruchamianie żądania POST

Przed uruchomieniem żądania POST zastąp wartości {your-source-container-SAS-URL} i {your-result-container-SAS-URL} wartościami z wystąpień kontenera usługi Azure Blob Storage.

W poniższym przykładzie pokazano, jak dodać azureBlobSource właściwość do żądania:

Zezwalaj tylko na jeden azureBlobSource obiekt lub 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
}

W poniższym przykładzie pokazano, jak dodać azureBlobFileListSource właściwość do żądania:

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
}

Pomyślna odpowiedź

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

Pobieranie wyników interfejsu API analizy wsadowej

Po wykonaniu operacji interfejsu API usługi Batch można pobrać wyniki analizy wsadowej przy użyciuGET operacji . Ta operacja pobiera informacje o stanie operacji, procent ukończenia operacji oraz tworzenie i aktualizowanie daty/godziny operacji.

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

Interpretowanie komunikatów o stanie

Dla każdego dokumentu zestaw ma przypisany stan , succeeded, failedlub skipped. Dla każdego dokumentu dostępne są dwa adresy URL umożliwiające zweryfikowanie wyników: sourceUrl, który jest źródłowym kontenerem magazynu obiektów blob dla dokumentu wejściowego zakończonego powodzeniem, oraz resultUrl, który jest konstruowany przez połączenie resultContainerUrl iresultPrefix w celu utworzenia ścieżki względnej dla pliku źródłowego i .ocr.json.

• Stan notStarted lub running. Operacja analizy wsadowej nie jest inicjowana lub nie została ukończona. Poczekaj, aż operacja zostanie ukończona dla wszystkich dokumentów.

• Stan completed. Operacja analizy wsadowej została zakończona.

• Stan failed. Operacja wsadowa nie powiodła się. Ta odpowiedź zwykle występuje, jeśli występują ogólne problemy z żądaniem. Błędy poszczególnych plików są zwracane w odpowiedzi raportu wsadowego, nawet jeśli wszystkie pliki nie powiodły się. Na przykład błędy magazynu nie zatrzymują całej operacji wsadowej, dzięki czemu można uzyskać dostęp do wyników częściowych za pośrednictwem odpowiedzi raportu wsadowego.

Tylko pliki, które mają succeeded stan, mają właściwość resultUrl wygenerowaną w odpowiedzi. Umożliwia to trenowanie modelu w celu wykrywania nazw plików kończących się i .ocr.json identyfikowania ich jako jedynych plików, które mogą być używane do trenowania.

succeeded Przykład odpowiedzi o stanie:

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

failed Przykład odpowiedzi o stanie:

• Ten błąd jest zwracany tylko wtedy, gdy występują błędy w ogólnym żądaniu wsadowym.
• Po uruchomieniu operacji analizy wsadowej stan operacji pojedynczego dokumentu nie ma wpływu na stan ogólnego zadania wsadowego, nawet jeśli wszystkie pliki mają stan 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}"
                }
            }
        ]
    }
]
...

Przykład odpowiedzi stanu skipped :

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

Wyniki analizy wsadowej pomagają zidentyfikować pliki, które zostały pomyślnie przeanalizowane i zweryfikować wyniki analizy, porównując plik z pliku wyjściowego resultContainerUrlw resultUrl pliku .

Następne kroki

Wyświetlanie przykładów kodu w usłudze GitHub.