共用方式為

Azure AI 語言的原生檔支援 （預覽）

  • 發行項

重要

  • 原生檔支援是封閉預覽。 若要要求原生文件支援功能的存取權，請完成並提交 [套用] 以存取語言服務預覽 窗體。

  • Azure AI 語言公開預覽版本提供早期存取作用中開發中的功能。

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

Azure AI 語言是雲端式服務，可將自然語言處理 （NLP） 功能套用至文字型數據。 原生文件支援功能可讓您使用 HTTP POST 要求本文以異步方式傳送 API 要求，以傳送您的資料和 HTTP GET 要求查詢字串來擷取已處理的數據。

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

  • 個人標識資訊（PII）。 PII 偵測功能可以在非結構化文字中識別、分類和修訂敏感性資訊。 PiiEntityRecognition API 支援原生文件處理。

  • 檔摘要。 文件摘要會使用自然語言處理來產生檔擷取（突出句子擷取）或抽象（內容文字擷取）摘要。 和 ExtractiveSummarization API 都AbstractiveSummarization支援原生文件處理。

支援的檔案格式

應用程式會使用原生檔案格式來建立、儲存或開啟原生檔。 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. 您可以將 和 貼keylanguage service instance endpoint到程式碼範例中，向語言服務驗證您的要求。 呼叫 API 只需一把金鑰。

建立 Azure Blob 儲存體容器

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

  • 來源容器。 此容器是您上傳原生檔案以供分析的位置（必要）。
  • 目標容器。 此容器是您分析的檔案儲存位置（必要）。

驗證

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

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

Screenshot of a storage url with SAS token appended.

  • 您的 來源 容器或 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 值來編輯這些命令。 選取 或 Document Summarization 程式碼範例項目，嘗試分析原生檔Personally Identifiable Information (PII)：

PII 範例檔

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

建置 POST 要求

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

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

  3. 將下列個人標識資訊 （PII） 要求範例 複製並貼到您的 pii-detection.json 檔案中。 將與 {your-target-container-SAS-URL} 取代{your-source-container-SAS-URL}為您 Azure 入口網站 儲存體 帳戶容器實例中的值：

要求範例

{
    "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" 
            }
        }
    ]
}

執行 POST 要求

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

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

  2. 執行 POST 要求之前，請將 和 {your-key} 取代{your-language-resource-endpoint}為您 Azure 入口網站 語言服務實例的值。

    重要

    當您完成時，請記得從程式碼中移除密鑰，且絕不會公開發佈。 針對生產環境，請使用安全的方式來儲存和存取您的認證，例如 Azure 金鑰保存庫。 如需詳細資訊，請參閱 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）

您會收到包含只讀 Operation-Location 標頭的 202（成功）回應。 此標頭的值包含一個 jobId，可查詢以取得異步操作的狀態，並使用 GET 要求擷取結果：

Screenshot showing the operation-location value in the POST response.

取得分析結果 （GET 要求）

  1. 成功 POST 要求之後，輪詢 POST 要求中傳回的作業位置標頭，以檢視已處理的數據。

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

檢查回應

您會收到 JSON 輸出的 200（成功）回應。 狀態欄位表示作業的結果。 如果作業未完成，狀態的值會「執行中」或「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 要求也會傳回回應標頭，包括 Operation-Location 提供後續 GET 要求中使用的值。

清除資源

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

下一步

PII 偵測概觀文件摘要概觀