文件智慧服務批次分析 (預覽)

發行項
10/16/2024

重要

文件智慧服務公開預覽版本可讓您搶先存取正在積極開發的功能。根據使用者意見反應，功能、方法和流程在正式發行 (GA) 前可能有所變更。
文件智慧服務用戶端程式庫的公開預覽版預設為 REST API 版本 2024-07-31-preview。
公開預覽版 2024-07-31-preview 目前僅適用於下列 Azure 地區。請注意，AI Studio 中的自訂生成 (文件欄位擷取) 模型僅適用美國中北部地區：
- 美國東部
- 美國西部 2
- 西歐
- 美國中北部

批次分析 API 可讓您使用一個非同步要求來大量處理多份文件。您可以同時分析收集的發票、一系列貸款文件或一組自訂模型訓練文件，而不需要個別提交文件並追蹤多個要求識別碼。

若要利用批次分析，您需要具有來源文件和已處理輸出之特定容器的 Azure Blob 儲存體帳戶。
完成時，批次作業結果會列出所有已處理的個別文件及其狀態 (例如 succeeded、skipped 或 failed)。
此 Batch API 預覽版本可透過隨用隨付定價取得。

下列模型支援批次分析：

讀取。從表單和文件中擷取文字行、單字、偵測語言和手寫樣式。
版面配置。從表單和文件中擷取文字、表格、選取標記和結構資訊。
自訂範本。訓練模型，以從結構化表單中擷取機碼值組、選取標記、資料表、簽章欄位和區域。
自訂神經。訓練模型，以從結構化、半結構化和非結構化文件中擷取指定的資料欄位。
自訂生成式。訓練模型，以從巢狀表格、抽象/生成式欄位和真正非結構化格式等複雜物件中擷取指定的資料。

批次分析指引

每個批次分析要求處理的文件數目上限 (包括跳過的文件) 為 10,000 個。
azureBlobFileListSource 參數可用來將較大的要求分成較小的要求。
作業結果會在完成後保留 24 小時。文件和結果會位於提供的儲存體帳戶中，但作業狀態在完成 24 小時後將不再提供。

準備開始了嗎？

必要條件

您需要作用中的 Azure 訂用帳戶。若還沒有 Azure 訂閱，您可以建立免費帳戶。
擁有 Azure 訂閱之後，請在 Azure 入口網站中建立文件智慧服務執行個體。您可以使用免費定價層 (F0) 來試用服務。
部署資源之後，請選取 [前往資源] 擷取金鑰與端點。
- 您需要使用資源的金鑰和端點，將應用程式連線至文件智慧服務。您稍後會在快速入門中將金鑰和端點貼到程式碼中。您可以在 Azure 入口網站的 [金鑰和端點] 頁面上找到這些值。
Azure Blob 儲存體帳戶。您將在 Azure Blob 儲存體帳戶中為您的來源和結果檔案建立容器：
- 來源容器。此容器是上傳檔案進行分析的位置 (必要)。
- 結果容器。此容器是已處理檔案的儲存位置 (必要)。

您可以為來源和已處理的文件指定相同的 Azure Blob 儲存體容器。不過，為了盡可能避免意外覆寫資料，建議您選擇不同的容器。

儲存體容器授權

您可以選擇下列其中一個選項來授權文件服務資源的存取權。

✔️ 受控識別。受控識別是一種服務主體，其會建立 Microsoft Entra 身分識別和 Azure 受控資源的特定權限。受控識別可讓您執行文件智慧服務應用程式，而不需要在程式碼中內嵌認證。受控識別提供更安全的方式來授與儲存體資料的存取權，並取代您包含共用存取簽章權杖 (SAS) 與您的來源和結果 URL 的需求。

若要深入瞭解，請參閱設定文件智慧服務的受控識別。

受控識別流程 (角色型存取控制) 的螢幕擷取畫面。

重要

使用受控識別時，請勿在 HTTP 要求中包含 SAS 權杖 URL，否則您的要求將會失敗。使用受控識別可取代您包含共用存取簽章權杖 (SAS) 的需求。

✔️ 共用存取簽章 (SAS)。共用存取簽章是一個 URL，可將受限制的存取權授與文件智慧服務一段時間。若要使用此方法，您必須為來源和結果容器建立共用存取簽章 (SAS) 權杖。來源和結果容器必須包含共用存取簽章 (SAS) 權杖，並附加為查詢字串。權杖可以指派給您的容器或特定 Blob。

螢幕擷取畫面：附加 SAS 權杖的儲存體 URI。

您的來源容器或 Blob 必須指定讀取、寫入、列出和刪除權限。
您的結果容器或 Blob 必須指定寫入、列出、刪除權限。

若要深入了解，請參閱建立 SAS 權杖。

呼叫批次分析 API

為 azureBlobSource 或 azureBlobFileListSource 物件內的來源文件集指定 Azure Blob 儲存體容器 URL。
使用 resultContainerUrl，為您的批次分析結果指定 Azure Blob 儲存體容器 URL。為了避免意外覆寫，建議您針對來源和已處理的文件使用不同的容器。
- 如果您使用相同的容器，請將 resultContainerUrl 和 resultPrefix 設定為符合您的輸入 azureBlobSource。
- 使用相同的容器時，您可以包含 overwriteExisting 欄位，以決定是否要使用分析結果檔覆寫任何檔案。

建置並執行 POST 要求

執行 POST 要求之前，請將 {your-source-container-SAS-URL} 和 {your-result-container-SAS-URL} 取代為您的 Azure Blob 儲存體容器執行個體的值。

只允許一個 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
  }
]

成功回應

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

擷取批次分析 API 結果

執行 Batch API 作業之後，您可以使用 GET 作業來擷取批次分析結果。此作業會擷取作業狀態資訊、作業完成百分比，以及作業建立和更新日期/時間。

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

解譯狀態訊息

針對每個文件集，會指派一個狀態，可能是 succeeded、failed 或 skipped。針對每個文件，會提供兩個 URL 來驗證結果：sourceUrl 是成功輸入文件的來源 Blob 儲存體容器，而 resultUrl 是結合 resultContainerUrl 和resultPrefix 建構而成，以建立來源檔案的相對路徑和 .ocr.json。

狀態 notStarted 或 running。批次分析作業未起始或未完成。請等候所有文件的作業完成。
狀態 completed。批次分析作業已完成。
狀態 failed。批次作業失敗。如果要求整體有問題，通常會出現此回應。批次報表回應中會傳回個別檔案的失敗，即使所有檔案都失敗也一樣。例如，儲存體錯誤不會停止整個批次作業，因此您可以透過批次報表回應存取部分結果。

只有具有 succeeded 狀態的檔案才會在回應中產生 resultUrl 屬性。這可讓模型訓練偵測以 .ocr.json 結尾的檔案名稱，並將其識別為唯一可用於訓練的檔案。

succeeded 狀態回應的範例如下：

[
  "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 狀態回應的範例如下：

只有在整體批次要求中有錯誤時，才會傳回此錯誤。
批次分析作業啟動之後，個別文件作業狀態不會影響整體批次工作的狀態，即使所有檔案的狀態都是 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 狀態回應的範例如下：

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

批次分析結果可協助您藉由比較 resultUrl 中的檔案與 resultContainerUrl 中的輸出檔案，識別已成功分析哪些檔案並驗證分析結果。

注意

在完成整份文件集批次分析之前，不會傳回個別檔案的分析結果。若要追蹤 percentCompleted 以外的詳細進度，您可以在寫入 resultContainerUrl 時監視 *.ocr.json 檔案。

下一步

檢視 GitHub 上的程式碼範例。

共用方式為