检测和编辑本机文档中的个人身份信息（预览版）

2025-10-16

重要

Azure AI 语言公共预览版提供了对当前处于正在开发状态的功能的提前访问权限。
根据用户反馈，在正式发布（正式版）之前，功能、方法和流程可能会发生变化。

Azure AI 语言是一项基于云的服务，可将自然语言处理 (NLP) 功能应用于基于文本的数据。本机文档支持功能让你能够以异步方式发送 API 请求，从而使用 HTTP POST 请求正文来发送数据，使用 HTTP GET 请求查询字符串来检索状态结果。已处理的文档位于 Azure Blob 存储目标容器中。

原生文档是指用于创建原始文档的文件格式，例如 Microsoft Word (docx) 或可移植文档文件 (pdf)。有了原生文档支持，在使用 Azure AI 语言资源功能之前无需再进行文本预处理。目前，本机文档支持适用于以下功能：

个人身份信息 (PII)。 PII 检测功能可以识别、分类和编修非结构化文本中的敏感信息。 PiiEntityRecognition API 支持本机文档处理。
文档摘要。文档摘要使用自然语言处理为文档生成提取性（重点句子提取）或抽象性（上下文字词提取）摘要。 AbstractiveSummarization 和 ExtractiveSummarization API 都支持本机文档处理。

支持的文档格式

应用程序使用本机文件格式创建、保存或打开本机文档。目前，PII 和文档摘要功能支持以下本机文档格式：

文件类型	文件扩展名	DESCRIPTION
文本	`.txt`	无格式的文本文档。
PDF	`.pdf`	可移植文档格式的文件和扫描的 PDF 文件。
Microsoft Word	`.docx`	Microsoft Word 文档文件。

输入准则

支持的文件格式

类型	支持和限制
图像中的文本	不支持带有嵌入文本的数字图像。
数字表	不支持扫描文档中的表。

文档大小

特征	输入限制
每个请求的文档总数	≤ 40
每个请求的内容总大小	≤ 10 MB

包括带有 HTTP 请求的本机文档

让我们开始吧：

对于此项目，我们使用 cURL 命令行工具进行 REST API 调用。

注释

大多数 Windows 10 和 Windows 11 以及大多数 macOS 和 Linux 发行版都预安装了 cURL 包。可以使用以下命令检查包版本：Windows：curl.exe -V macOS：curl -V Linux：curl --version
一个有效的 Azure 帐户。如果没有，可以创建一个试用帐户。
一个 Azure Blob 存储帐户。你还需要在 Azure Blob 存储帐户中为源文件和目标文件创建容器：
- 源容器。此容器用于上传原始文件以进行分析（必需）。
- 目标容器。此容器用于存储已分析的文件（必需）。
单服务语言资源（不是多服务 Azure AI 服务资源）：

完成语言资源项目和实例详细信息字段，如下所示：
1. 订阅。选择一个可用的 Azure 订阅。
2. 资源组。你可以创建新的资源组，或将资源添加到预先存在的具有相同生命周期、权限和策略的资源组。
3. 资源区域。选择“全球”，除非你的业务或应用程序需要特定区域。如果打算使用系统分配的托管标识进行身份验证，请选择一个地理区域，如“中国北部”。
4. 名称。输入您为资源选择的名称。所选名称在 Azure 中必须唯一。
5. 定价层。可以使用免费定价层 (Free F0) 试用该服务，然后再升级到付费层进行生产。
6. 选择 审阅 + 创建。
7. 查看服务条款，然后选择“创建”以部署资源。
8. 成功部署资源后，选择转到资源。

获取你的密钥和语言服务端点

对语言服务的请求需要一个只读密钥和自定义终结点来对访问进行身份验证。

如果已创建新资源，请在部署该资源后选择“转到资源”。如果有现有的语言服务资源，请直接导航到资源页。
在左侧导航栏中的资源管理下，选择密钥和终结点。
可以将你的 key 和 language service instance endpoint 复制粘贴到代码示例中，从而对向语言服务的请求进行身份验证。发出 API 调用只需一个密钥。

创建 Azure Blob 存储容器

在你的 Azure Blob 存储帐户中为源文件和目标文件创建容器。

源容器。此容器用于上传原始文件以进行分析（必需）。
目标容器。此容器用于存储已分析的文件（必需）。

身份验证

语言资源需要被授予对存储帐户的访问权限，然后才能创建、读取或删除 blob。有两种主要方法可用于授予对存储数据的访问权限：

共享访问签名 (SAS) 令牌。用户委派 SAS 令牌是通过 Microsoft Entra 凭据保护的。 SAS 令牌提供对 Azure 存储帐户中资源的安全委托式访问。
托管标识基于角色的访问控制 (RBAC)。 Azure 资源托管标识是一种服务主体，可为 Azure 托管资源创建 Microsoft Entra 标识和特定权限。

对于此项目，我们通过在查询字符串中追加共享访问签名 (SAS) 令牌来对 source location 和 target location URL 的访问进行身份验证。每个令牌都分配给特定的 blob（文件）。

附加了 SAS 令牌的存储网址的屏幕截图。

源容器或 blob 必须指定读取和列出访问权限。
目标容器或 blob 必须指定写入和列出访问权限。

小窍门

由于我们正在处理单个文件 (blob)，因此建议在 blob 级别委托 SAS 访问。

请求头和参数

参数	DESCRIPTION
`-X POST <endpoint>`	指定用于访问 API 的语言资源终结点。
`--header Content-Type: application/json`	用于发送 JSON 数据的内容类型。
`--header "Ocp-Apim-Subscription-Key:<key>`	指定用于访问 API 的语言资源密钥。
`-data`	包含要随请求传递的数据的 JSON 文件。

以下 cURL 命令从 BASH shell 中执行。请使用自己的资源名称、资源密钥和 JSON 值编辑这些命令。通过选择 Personally Identifiable Information (PII) 或 Document Summarization 代码示例项目来尝试分析本地文档：

PII 示例文档

对于此快速入门，你需要将源文档上传到源容器。对于此项目，可以下载我们的 Microsoft Word 示例文档或 Adobe PDF。源语言为英语。

生成 POST 请求

使用首选编辑器或 IDE，为应用创建一个名为 native-document 的新目录。
在 native-document 目录中创建名为 pii-detection.json 的新 json 文件。
将以下个人身份信息 (PII) 请求示例复制粘贴到你的 pii-detection.json 文件中。使用 Azure 门户存储帐户容器实例中的值替换 {your-source-container-SAS-URL} 和 {your-target-container-SAS-URL}：

请求示例

{ 
    "displayName": "Document PII Redaction example", 
    "analysisInput": { 
        "documents": [ 
            { 
                "language": "en-US", 
                "id": "Output-1", 
                "source": { 
                    "location": "{your-source-blob-with-SAS-URL}" 
                }, 
                "target": { 
                    "location": "{your-target-container-with-SAS-URL}" 
                } 
            } 
        ] 
    }, 
    "tasks": [ 
        { 
            "kind": "PiiEntityRecognition", 
            "taskName": "Redact PII Task 1", 
            "parameters": { 
                "redactionPolicy": { 
                    "policyKind": "entityMask"  // Optional. Defines redactionPolicy; changes behavior based on value. Options: noMask, characterMask (default), and entityMask. 
                }, 
                "piiCategories": [ 
                    "Person", 
                    "Organization" 
                ], 
                "excludeExtractionData": false  // Default is false. If true, only the redacted document is stored, without extracted entities data. 
            } 
        } 
    ] 
}

源 location 值是源文档 (blob) 的 SAS URL，而不是源容器 SAS URL。
redactionPolicy 可能的值为 UseRedactionCharacterWithRefId（默认值）或 UseEntityTypeName。有关详细信息，请参阅 PiiTask 参数。

运行 POST 请求

下面是 POST 请求的初步结构：

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

在运行 POST 请求之前，将 {your-language-resource-endpoint} 和 {your-key} 替换为你的 Azure 门户语言服务实例中的值。

重要

完成后，请记住将密钥从代码中删除，并且永远不要公开发布该密钥。对于生产来说，请使用安全的方式存储和访问凭据，例如 Azure Key Vault。有关详细信息，请参阅 Azure AI 服务安全性。

PowerShell

   cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs?api-version=2024-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=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}" --data "@pii-detection.json"

示例响应如下：

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=2024-11-15-preview
apim-request-id: e7d6fa0c-0efd-416a-8b1e-1cd9287f5f81
x-ms-region: China North 2
Date: Thu, 25 Jan 2024 15:12:32 GMT

POST 响应 (jobId)

你会收到包含只读 Operation-Location 标头的 202（成功）响应。此标头的值包含一个 jobId，可以查询它以获取异步操作的状态，并使用 GET 请求检索结果：

显示 POST 响应中的操作位置值的屏幕截图。

获取分析结果（GET 请求）

在成功的 POST 请求后，轮询 POST 请求中返回的操作位置标头以查看已处理的数据。

下面是 GET 请求的初步结构：

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

运行该命令之前，请进行以下更改：
- 将 {jobId} 替换为 POST 响应中的 Operation-Location 标头。
- 将 {your-language-resource-endpoint} 和 {your-key} 替换为你的 Azure 门户中语言服务实例中的值。

Get 请求

    cmd /c curl "{your-language-resource-endpoint}/language/analyze-documents/jobs/{jobId}?api-version=2024-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=2024-11-15-preview" --header "Content-Type: application/json" --header "Ocp-Apim-Subscription-Key: {your-key}"

检查响应

收到 JSON 输出为 200（成功）的响应。 status 字段指示操作的结果。如果操作未完成，status 的值为 "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.chinacloudapi.cn/sample-input/input.pdf"
              },
              "targets": [
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.chinacloudapi.cn/sample-output/df6611a3-fe74-44f8-b8d4-58ac7491cb13/PiiEntityRecognition-0001/input.result.json"
                },
                {
                  "kind": "AzureBlob",
                  "location": "https://myaccount.blob.core.chinacloudapi.cn/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 资源，可以删除单个资源或整个资源组。如果删除资源组，也会删除包含的所有资源。

Azure 门户
Azure CLI

后续步骤

PII 检测概述