Azure AI 语言的本机文档支持（预览版）
重要
- Azure AI 语言公共预览版提供了对当前处于正在开发状态的功能的提前访问权限。
- 在正式发布 (GA) 之前，根据用户反馈，功能、方法和流程可能会发生更改。
Azure AI 语言是一项基于云的服务，可将自然语言处理 (NLP) 功能应用于基于文本的数据。 本机文档支持功能让你能够以异步方式发送 API 请求，从而使用 HTTP POST 请求正文来发送数据，使用 HTTP GET 请求查询字符串来检索状态结果。 已处理的文档位于 Azure Blob 存储目标容器中。
本机文档是指用于创建原始文档（如 Microsoft Word (docx) 或可移植文档文件 (pdf)）的文件格式。 有了原生文档支持，在使用 Azure AI 语言资源功能之前无需再进行文本预处理。 目前，本机文档支持适用于以下功能：
个人身份信息 (PII)。 PII 检测功能可以识别、分类和编修非结构化文本中的敏感信息。
PiiEntityRecognitionAPI 支持本机文档处理。文档摘要。 文档摘要使用自然语言处理为文档生成提取性（重点句子提取）或抽象性（上下文字词提取）摘要。
AbstractiveSummarization和ExtractiveSummarizationAPI 都支持本机文档处理。
支持的文档格式
应用程序使用本机文件格式创建、保存或打开本机文档。 目前，PII 和文档摘要功能支持以下本机文档格式：
| 文件类型 | 文件扩展名 | 说明 |
|---|---|---|
| 文本 | .txt |
无格式的文本文档。 |
| Adobe PDF | .pdf |
可移植文档文件格式的文档。 |
| Microsoft Word | .docx |
Microsoft Word 文档文件。 |
输入准则
支持的文件格式
| 类型 | 支持和限制 |
|---|---|
| 不支持完全扫描的 PDF。 | |
| 图像中的文本 | 不支持带有嵌入文本的数字图像。 |
| 数字表 | 不支持扫描文档中的表。 |
文档大小
| Attribute | 输入限制 |
|---|---|
| 每个请求的文档总数 | ≤ 20 |
| 每个请求的内容总大小 | ≤ 10 MB |
包括带有 HTTP 请求的本机文档
让我们开始吧：
对于此项目，我们使用 cURL 命令行工具进行 REST API 调用。
注意
大多数 Windows 10 和 Windows 11 以及大多数 macOS 和 Linux 发行版都预装了 cURL 包。 可以使用以下命令检查包版本：Windows：
curl.exe -VmacOS：curl -VLinux：curl --version如果未安装 cURL，下面是你的平台的安装链接：
一个 Azure Blob 存储帐户。 你还需要在 Azure Blob 存储帐户中为源文件和目标文件创建容器：
- 源容器。 此容器用于上传本机文件以进行分析（必需）。
- 目标容器。 此容器用于存储已分析的文件（必需）。
单服务语言资源（不是多服务 Azure AI 服务资源）：
完成语言资源项目和实例详细信息字段，如下所示：
订阅。 选择一个可用的 Azure 订阅。
资源组。 可以创建新资源组，或将资源添加到共享相同生命周期、权限和策略的预先存在的资源组。
资源区域。 选择“全球”，除非你的业务或应用程序需要特定区域。 如果打算使用系统分配的托管标识 (RBAC) 进行身份验证，请选择一个地理区域，如“中国北部”。
名称. 输入为资源选择的名称。 所选名称在 Azure 中必须唯一。
定价层。 可以使用免费定价层 (
Free F0) 试用该服务，然后再升级到付费层进行生产。选择“查看 + 创建” 。
查看服务条款，然后选择“创建”以部署资源。
成功部署资源后，选择“转到资源”。
检索你的密钥和语言服务终结点
对语言服务的请求需要一个只读密钥和自定义终结点来对访问进行身份验证。
如果已创建新资源，请在部署该资源后选择“转到资源”。 如果有现有的语言服务资源，请直接导航到资源页。
在左侧导航栏中的“资源管理”下，选择“密钥和终结点”。
可以将你的
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（文件）。
- 源容器或 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 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)
你将收到 202（成功）响应，其中包含只读的 Operation-Location 标头。 此标头的值包含一个 jobId，可以查询它以获取异步操作的状态，并使用 GET 请求检索结果：
获取分析结果（GET 请求）
成功 POST 请求后，轮询 POST 请求中返回的 operation-location 标头以查看已处理的数据。
下面是 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 服务订阅，可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。