共用方式為

Azure AI 語言的原生文件支援 (預覽)

  • 發行項

重要

  • 原生文件支援為閘道預覽。 若要要求存取原生文件支援功能，請填寫並提交申請存取語言服務預覽表單。

  • Azure AI 語言公開預覽版本提供了正在開發期間之功能的早期存取權。

  • 根據使用者意見反應，功能、方法和流程在正式發行 (GA) 前可能有所變更。

Azure AI 語言是一項雲端式服務，它將自然語言處理 (NLP) 功能應用於文字型資料。 原生文件支援功能可讓您非同步傳送 API 要求，使用 HTTP POST 要求本文傳送資料並使用 HTTP GET 要求查詢字串來擷取狀態結果。 已處理的文件位於您的 Azure Blob 儲存體目標容器中。

原生文件是指用來建立原始文件的檔案格式，例如 Microsoft Word (docx) 或可攜式文件檔案 (pdf)。 原生文件支援代表在使用 Azure AI 語言資源功能之前，不再需要進行文字前置處理。 目前，原生文件支援適用於下列功能：

  • 個人識別資訊 (PII)。 PII 偵測功能可以識別、分類及修訂非結構化文字中的敏感資訊。 PiiEntityRecognition API 支援原生文件處理。

  • 文件摘要。 文件摘要會使用自然語言處理來產生文件的擷取 (主要句子擷取) 或抽象 (內容文字擷取) 摘要。 AbstractiveSummarization 和 ExtractiveSummarization API 皆支援原生文件處理。

支援的文件格式

應用程式會使用原生檔案格式來建立、儲存或開啟原生文件。 目前 PII 和文件摘要功能支援下列原生文件格式：

檔案類型 副檔名 描述
Text .txt 未格式化的文字文件。
Adobe PDF .pdf 可攜式文件檔案格式的文件。
Microsoft Word .docx Microsoft Word 文件檔案。

輸入指導方針

支援的檔案格式

類型 支援和限制
PDF 不支援完整掃描的 PDF。
影像中的文字 不支援內嵌文字的數位影像。
數位資料表 不支援掃描文件中的資料表。

文件大小

屬性 輸入限制
每個要求的文件總數 不超過 20 個
每個要求的內容大小總計 不超過 1 MB

使用 HTTP 要求包含原生文件

現在就開始吧：

  • 在此專案中，我們使用 cURL 命令列工具來進行 REST API 呼叫。

    注意

    cURL 套件已預先安裝在大部分 Windows 10 和 Windows 11 和大部分 macOS 和 Linux 發行版本上。 您可以使用下列命令來檢查套件版本：Windows：curl.exe -V macOS curl -V Linux：curl --version

  • 如果未安裝 cURL，則以下是適用於您的平台的安裝連結：

  • 作用中的 Azure 帳戶。 如果您沒有帳戶，您可以建立免費帳戶。

  • Azure Blob 儲存體帳戶。 您也必須在 Azure Blob 儲存體帳戶中為來源和目標檔案建立容器：

    • 來源容器。 可會在此容器中上傳要分析的原生檔案 (必要)。
    • 目標容器。 此容器是分析的檔案所將儲存之處 (必要)。

  • 單一服務語言工具資源 (不是多服務 Azure AI 服務資源)：

    完成語言資源專案和執行個體詳細資料欄位，如下所示：

    1. 訂用帳戶。 選取您可用的一個 Azure 訂用帳戶。

    2. 資源群組。 您可以建立新的資源群組，或將資源新增至共用相同生命週期、權限和原則的預先存在資源群組。

    3. 資源區域。 除非您的業務或應用程式需要特定區域，否則請選擇 [全域]。 如果您打算使用系統指派的受控識別 (RBAC) 進行驗證，請選擇地理區域，例如美國西部。

    4. 名稱. 輸入您為資源選擇的名稱。 您所選擇的名稱在 Azure 中必須是唯一的。

    5. 定價層。 您可以使用免費定價層 (Free F0) 來試用服務，之後可升級至付費層以用於實際執行環境。

    6. 選取 [檢閱 + 建立] 。

    7. 檢閱服務條款，然後選取 [建立] 以部署資源。

    8. 成功部署資源之後，請選取 [移至資源]。

擷取金鑰和語言服務端點

對語言服務的要求需要唯讀金鑰和自訂端點，才能驗證存取權。

  1. 如果您已建立新的資源，在部署之後，請選取 [前往資源]。 如果您擁有現有的語言服務資源，請直接瀏覽至您的資源頁面。

  2. 在左側滑軌中，於 [資源管理] 下選取 [金鑰和端點]。

  3. 您可以複製 key 和 language service instance endpoint 並將其貼到程式碼範例中，以驗證您對語言服務的要求。 呼叫 API 只需一把金鑰。

建立 Azure Blob 儲存體容器

在 Azure Blob 儲存體帳戶中為來源和目標檔案建立容器。

  • 來源容器。 可會在此容器中上傳要分析的原生檔案 (必要)。
  • 目標容器。 此容器是分析的檔案所將儲存之處 (必要)。

驗證

您的語言資源需要授與對儲存體帳戶的存取權，才能建立、讀取或刪除 Blob。 有兩個主要方法可用來授與儲存體資料的存取權：

  • 共用存取簽章 (SAS) 權杖。 會使用 Microsoft Entra 認證來保護使用者委派 SAS 權杖。 SAS 權杖會對您 Azure 儲存體帳戶中的資源提供安全的委派存取權。

  • 受控識別角色型存取控制 (RBAC)。 適用於 Azure 資源的受控識別是一種服務主體，其會建立 Microsoft Entra 身分識別和 Azure 受控資源的特定權限。

在此專案中，我們會使用附加為查詢字串的共用存取簽章 (SAS) 權杖，驗證對 source location 和 target location URL 的存取權。 每個權杖都會指派給特定的 Blob (檔案)。

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

  • 您的來源容器或 Blob 必須具有指定的讀取和列出存取權。
  • 您的目標容器或 Blob 必須具有指定的寫入和列出存取權。

提示

由於我們正在處理單一檔案 (Blob)，因此建議您在 Blob 層級委派 SAS 存取權。

要求標頭和參數

parameter 描述
-X POST <endpoint> 指定用於存取 API 的語言資源端點。
--header Content-Type: application/json 用於傳送 JSON 資料的內容類型。
--header "Ocp-Apim-Subscription-Key:<key> 指定用於存取 API 的語言資源金鑰。
-data 包含您想要隨要求傳遞之資料的 JSON 檔案。

下列 cURL 命令是從 BASH 殼層執行。 使用您自己的資源名稱、資源金鑰和 JSON 值來編輯這些命令。 透過選取 Personally Identifiable Information (PII) 或 Document Summarization 範例程式碼專案，嘗試分析原生文件：

PII 範例文件

針對此快速入門，您需要上傳至來源容器的來源文件。 您可以為此專案下載 Microsoft Word 範例文件或 Adobe PDF。 來源語言為英文。

建置 POST 要求

  1. 使用您慣用的編輯器或 IDE，為名為 native-document 的應用程式建立新目錄。

  2. 在您的原生文件目錄中，建立名為 pii-detection.json 的新 JSON 檔案。

  3. 將下列個人識別資訊 (PII) 要求範例複製並貼上您的 pii-detection.json 檔案中。 使用 Azure 入口網站儲存體帳戶容器執行個體的值取代 {your-source-container-SAS-URL} 和 {your-target-container-SAS-URL}：

要求範例

{
    "displayName": "Extracting Location & US Region",
    "analysisInput": {
        "documents": [
            {
                "language": "en-US",
                "id": "Output-excel-file",
                "source": {
                    "location": "{your-source-blob-with-SAS-URL}"
                },
                "target": {
                    "location": "{your-target-container-with-SAS-URL}"
                }
            } 
        ]
    },
    "tasks": [
        {
            "kind": "PiiEntityRecognition",
            "parameters":{
                "excludePiiCategories" : ["PersonType", "Category2", "Category3"],
                "redactionPolicy": "UseRedactionCharacterWithRefId" 
            }
        }
    ]
}

  • 來源 location 值是來源文件 (Blob) 的 SAS URL，而不是來源容器 SAS URL。

  • redactionPolicy 可能的值為 UseRedactionCharacterWithRefId (預設) 或 UseEntityTypeName。 如需詳細資訊，請參閱 PiiTask 參數。

執行 POST 要求

  1. 以下是 POST 要求的初步結構：

       POST {your-language-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview

  2. 執行 POST 要求之前，請使用 Azure 入口網站語言服務執行個體中的值取代 {your-language-resource-endpoint} 和 {your-key}。

    重要

    完成時，請記得從程式碼中移除金鑰，且不要公開張貼金鑰。 在生產環境中，請使用安全的方式來儲存和存取您的認證，例如 Azure Key Vault。 如需詳細資訊，請參閱 Azure AI 服務安全性。

    PowerShell

       cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" -i -X POST --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

    命令提示字元/終端機

       curl -v -X POST "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

  3. 以下是範例回應：

    HTTP/1.1 202 Accepted
Content-Length: 0
operation-location: https://{your-language-resource-endpoint}/language/analyze-documents/jobs/f1cc29ff-9738-42ea-afa5-98d2d3cabf94?api-version=2023-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: West US 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

POST 回應 (jobId)

您收到 202 (Success) 回應，其中包含唯讀 Operation-Location 標頭。 此標頭的值包含 jobId，可透過查詢以取得非同步作業的狀態，並且可使用 GET 要求來擷取結果：

顯示 POST 回應中 operation-location 值的螢幕擷取畫面。

取得分析結果 (GET 要求)

  1. 成功完成 POST 要求之後，請輪詢 POST 要求中傳回的 operation-location 標頭，以檢視已處理的資料。

  2. 以下是 GET 要求的初步結構：

      GET {your-language-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview

  3. 執行命令之前，請進行下列變更：

    • 將 {jobId} 取代為 POST 回應中的 Operation-Location 標頭。

    • 將 {your-language-resource-endpoint} 和 {your-key} 取代為 Azure 入口網站中語言服務執行個體的值。

取得要求

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" -i -X GET --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

    curl -v -X GET "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2023-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

檢查回應

您收到 200 (Success) 回應及 JSON 輸出。 狀態欄位會指出作業的結果。 如果作業未完成，狀態的值將會是 "running" 或 "notStarted"，此時您應該以手動方式或透過指令碼再次呼叫 API。 我們建議您在每個呼叫之前間隔一秒以上的時間。

範例回覆

{
  "jobId": "f1cc29ff-9738-42ea-afa5-98d2d3cabf94",
  "lastUpdatedDateTime": "2024-01-24T13:17:58Z",
  "createdDateTime": "2024-01-24T13:17:47Z",
  "expirationDateTime": "2024-01-25T13:17:47Z",
  "status": "succeeded",
  "errors": [],
  "tasks": {
    "completed": 1,
    "failed": 0,
    "inProgress": 0,
    "total": 1,
    "items": [
      {
        "kind": "PiiEntityRecognitionLROResults",
        "lastUpdateDateTime": "2024-01-24T13:17:58.33934Z",
        "status": "succeeded",
        "results": {
          "documents": [
            {
              "id": "doc_0",
              "source": {
                "kind": "AzureBlob",
                "location": "https://myaccount.blob.core.windows.net/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.windows.net/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.docx"
                }
              ],
              "warnings": []
            }
          ],
          "errors": [],
          "modelVersion": "2023-09-01"
        }
      }
    ]
  }
}

成功完成時：

  • 已分析的文件可在您的目標容器中找到。
  • 成功的 POST 方法會傳回 202 Accepted 回應碼，指出服務已建立批次要求。
  • POST 要求也會傳回回應標頭，包括提供後續 GET 要求中使用的值的 Operation-Location。

清除資源

如果您想要清除和移除 Azure AI 服務訂用帳戶，則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

下一步

PII 偵測概觀 文件摘要概觀