Analiza wsadowa analizy dokumentów

Interfejs API analizy wsadowej umożliwia zbiorcze przetwarzanie maksymalnie 10 000 dokumentów przy użyciu jednego żądania. Zamiast analizować dokumenty jeden po drugim i śledzić ich odpowiednie identyfikatory żądań, można jednocześnie analizować kolekcję dokumentów, takich jak faktury, dokumenty pożyczkowe lub dokumenty niestandardowe. Dokumenty wejściowe muszą być przechowywane w kontenerze usługi Azure Blob Storage. Po przetworzeniu dokumentów interfejs API zapisuje wyniki w określonym kontenerze magazynu.

Limity analizy wsadowej

• Maksymalna liczba plików dokumentów, które mogą znajdować się w pojedynczym żądaniu wsadowym, wynosi 10 000.
• Wyniki operacji wsadowych są zachowywane przez 24 godziny po zakończeniu. Stan operacji wsadowej nie jest już dostępny 24 godziny po zakończeniu przetwarzania wsadowego. Dokumenty wejściowe i odpowiednie pliki wyników pozostają w udostępnionych kontenerach magazynu.

Wymagania wstępne

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

• Zasób analizy dokumentów platformy Azure: po utworzeniu subskrypcji platformy Azure utwórz zasób 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" , aby pobrać klucz i punkt końcowy. Aby połączyć aplikację z usługą Document Intelligence, potrzebny jest klucz zasobu i punkt końcowy. Te wartości można również znaleźć na stronie Klucze i punkt końcowy w witrynie Azure Portal.

• Konto usługi Azure Blob Storage. Utwórz dwa kontenery 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 dokumentów do analizy.
  • Kontener wyników: w tym kontenerze są przechowywane wyniki z interfejsu API analizy wsadowej.

Autoryzacja kontenera magazynu

Aby umożliwić interfejsowi API przetwarzanie dokumentów i zapisywanie wyników w kontenerach usługi Azure Storage, musisz autoryzować przy użyciu jednej z następujących dwóch opcji:

✔️ 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, bezpieczniejszego sposobu udzielania dostępu do danych magazynu bez uwzględniania tokenów sygnatury dostępu (SAS) w kodzie.

Zapoznaj się z tematem Tożsamości zarządzane na potrzeby analizy dokumentów , aby dowiedzieć się, jak włączyć tożsamość zarządzaną zasobu i udzielić jej dostępu do kontenera magazynu.

✔️ Sygnatura dostępu współdzielonego (SAS). Sygnatura dostępu współdzielonego to adres URL, który udziela ograniczonego dostępu do kontenera magazynu. Aby użyć tej metody, utwórz tokeny sygnatury dostępu współdzielonego (SAS) dla kontenerów źródłowych i wynikowych. Przejdź do kontenera magazynu w witrynie Azure Portal i wybierz pozycję "Tokeny dostępu współdzielonego" , aby wygenerować token SAS i adres URL.

• Źródłowy kontener lub obiekt blob musi wyznaczyć uprawnienia do odczytu, zapisu, listy i usuwania.
• Kontener wyników lub obiekt blob musi wyznaczyć uprawnienia do zapisu, listy, usuwania .

Zapoznaj się z artykułem Tworzenie tokenów SAS , aby dowiedzieć się więcej na temat generowania tokenów SAS i sposobu ich działania.

Wywoływanie interfejsu API analizy wsadowej

1. Określ pliki wejściowe

Interfejs API wsadowy obsługuje dwie opcje określania plików do przetworzenia.

• Jeśli chcesz przetworzyć wszystkie pliki w kontenerze lub folderze, a liczba plików jest mniejsza niż limit 10000, użyj azureBlobSource obiektu w żądaniu.

  POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30
  
  {
    "azureBlobSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken"
  
  },
  {
     "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
     "resultPrefix": "trainingDocsResult/"
  }
  
  
  

• Jeśli nie chcesz przetwarzać wszystkich plików w kontenerze lub folderze, ale raczej określonych plików w tym kontenerze lub folderze, użyj azureBlobFileListSource obiektu . Ta operacja wymaga pliku JSONL listy plików, który zawiera listę plików do przetworzenia. Zapisz plik JSONL w folderze głównym kontenera. Oto przykładowy plik JSONL z dwoma wymienionymi plikami:

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

Użyj pliku listy JSONL plików z następującymi warunkami:

• Jeśli musisz przetworzyć określone pliki zamiast wszystkich plików w kontenerze;
• Gdy łączna liczba plików w kontenerze wejściowym lub folderze przekracza limit przetwarzania wsadowego 10 000 plików;
• Jeśli chcesz mieć większą kontrolę nad tym, które pliki są przetwarzane w każdym żądaniu wsadowym;

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobFileListSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "fileList": "myFileList.jsonl"
    ...
  },
  ...
}

Adres URL kontenera lub adres URL sygnatury dostępu współdzielonego kontenera jest wymagany w obu opcjach. Użyj adresu URL kontenera, jeśli używasz tożsamości zarządzanej, aby uzyskać dostęp do kontenera magazynu. Jeśli używasz sygnatury dostępu współdzielonego (SAS), użyj adresu URL sygnatury dostępu współdzielonego.

2. Określ lokalizację wyników

• Określ adres URL kontenera usługi Azure Blob Storage (lub adres URL sygnatury dostępu współdzielonego kontenera) dla miejsca przechowywania wyników przy użyciu resultContainerURL parametru . Zalecamy używanie oddzielnych kontenerów dla źródła i wyników, aby zapobiec przypadkowemu zastąpieniu.

• overwriteExisting Ustaw właściwość logiczną na False wartość i zapobiegaj zastępowaniu wszystkich istniejących wyników dla tego samego dokumentu. Jeśli chcesz zastąpić wszystkie istniejące wyniki, ustaw wartość logiczną na Truewartość . Nadal są naliczane opłaty za przetwarzanie dokumentu, nawet jeśli żadne istniejące wyniki nie zostaną zastąpione.

• Służy resultPrefix do grupowania i przechowywania wyników w określonym folderze kontenera.

3. Skompiluj i uruchom żądanie POST

Pamiętaj, aby zastąpić następujące przykładowe wartości adresu URL kontenera rzeczywistymi wartościami kontenerów usługi Azure Blob Storage.

W tym przykładzie pokazano żądanie POST z danymi wejściowymi azureBlobSource

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
  "azureBlobSource": {
    "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
    "prefix": "inputDocs/"
  },
  {
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "batchResults/",
  "overwriteExisting": true
}

W tym przykładzie pokazano żądanie POST z danymi wejściowymi azureBlobFileListSource listy plików i

POST {endpoint}/documentintelligence/documentModels/{modelId}:analyzeBatch?api-version=2024-11-30

{
   "azureBlobFileListSource": {
      "containerUrl": "https://myStorageAccount.blob.core.windows.net/myContainer?mySasToken",
      "fileList": "myFileList.jsonl"
    },
{
  "resultContainerUrl": "https://myStorageAccount.blob.core.windows.net/myOutputContainer?mySasToken",
  "resultPrefix": "batchResults/",
  "overwriteExisting": true
}

Oto przykład pomyślnej odpowiedzi

202 Accepted
Operation-Location: /documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30

4. Pobieranie wyników interfejsu API

Użyj operacji , GET aby pobrać wyniki analizy wsadowej po wykonaniu operacji POST. Operacja GET pobiera informacje o stanie, procent ukończenia partii oraz tworzenie i aktualizowanie daty/godziny operacji. Te informacje są przechowywane tylko przez 24 godziny po zakończeniu analizy wsadowej.

GET {endpoint}/documentintelligence/documentModels/{modelId}/analyzeBatchResults/{resultId}?api-version=2024-11-30
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"
...
}

5. Interpretowanie komunikatów o stanie

Dla każdego przetworzonego dokumentu jest przypisywany stan , succeeded, failed, running, notStartedlub skipped. Podano źródłowy adres URL, który jest źródłowym kontenerem magazynu obiektów blob dla dokumentu wejściowego.

• 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 succeeded. Operacja wsadowa zakończyła się pomyślnie, a dokument wejściowy został przetworzony. Wyniki są dostępne w witrynie resultUrl, która jest tworzona przez połączenie resultContainerUrl, resultPrefix, input filenamei .ocr.json rozszerzenia. Tylko pliki, które zakończyły się pomyślnie, mają właściwość resultUrl.

  succeeded Przykład odpowiedzi o stanie:

  {
      "resultId": "myresultId-",
      "status": "succeeded",
      "percentCompleted": 100,
      "createdDateTime": "2025-01-01T00:00:000",
      "lastUpdatedDateTime": "2025-01-01T00:00:000",
      "result": {
          "succeededCount": 10,000,
          "failedCount": 0,
          "skippedCount": 0,
          "details": [
              {
                  "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
                  "resultUrl": "https://{your-result-container}/resultsFolder/document1.pdf.ocr.json",
                  "status": "succeeded"
              },
            ...
              {
                  "sourceUrl": "https://{your-source-container}/inputFolder/document10000.pdf",
                  "resultUrl": "https://{your-result-container}/resultsFolder/document10000.pdf.ocr.json",
                  "status": "succeeded"
              }
         ]
  
       }
  }
  

• Stan failed. Ten błąd jest zwracany tylko wtedy, gdy występują błędy w ogólnym żądaniu wsadowym. Po rozpoczęciu 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.

  failed Przykład odpowiedzi o stanie:

  [
      "result": {
      "succeededCount": 0,
      "failedCount": 2,
      "skippedCount": 0,
      "details": [
          "sourceUrl": "https://{your-source-container}/inputFolder/document1.jpg",
          "status": "failed",
          "error": {
              "code": "InvalidArgument",
              "message": "Invalid argument.",
              "innererror": {
                "code": "InvalidSasToken",
                "message": "The shared access signature (SAS) is invalid: {details}"
                  }
              }
          ]
      }
  ]
  ...
  

• Stan skipped: zazwyczaj ten stan występuje, gdy dane wyjściowe dokumentu są już obecne w określonym folderze wyjściowym, a overwriteExisting właściwość logiczna jest ustawiona na falsewartość .

  Przykład odpowiedzi stanu skipped :

  [
       "result": {
       "succeededCount": 3,
       "failedCount": 0,
       "skippedCount": 2,
       "details": [
           ...
           "sourceUrl": "https://{your-source-container}/inputFolder/document1.pdf",
           "status": "skipped",
           "error": {
               "code": "OutputExists",
               "message": "Analysis skipped because result file https://{your-result-container}/resultsFolder/document1.pdf.ocr.json already exists."
                }
           ]
       }
  ]
  ...
  

  Uwaga

  Wyniki analizy nie są zwracane dla poszczególnych plików do momentu ukończenia analizy całej partii. Aby śledzić szczegółowy postęp poza percentCompletedusługą , możesz monitorować *.ocr.json pliki podczas ich zapisywania w pliku resultContainerUrl.

Następne kroki

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