你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：有据性检测（预览版）

项目
04/10/2024

按照本指南使用 Azure AI 内容安全有据性检测检查大型语言模型 (LLM) 的文本响应是否以用户提供的源材料为依据。

先决条件

Azure 订阅 - 免费创建订阅
拥有 Azure 订阅后，请在 Azure 门户中创建 Content Safety 资源，以获取密钥和终结点。输入资源的唯一名称，选择订阅，并选择资源组、支持的区域（美国东部 2、美国西部和瑞典中部）和支持的定价层。然后选择“创建”。
- 部署资源需要几分钟时间。完成后，请转到新的资源。在左窗格的“资源管理”下，选择“API 密钥和终结点”。将其中一个订阅密钥值和终结点复制到临时位置供以后使用。
（可选）若要使用推理功能，请创建已部署 GPT 模型的 Azure OpenAI 服务资源。
安装 cURL 或 Python。

在不推理的情况下检查有据性

在不使用推理功能的简单情况下，有据性检测 API 将提交内容的无据性分类为 true 或 false。

cURL
Python

本部分介绍使用 cURL 进行请求的示例。将以下命令粘贴到文本编辑器，并进行以下更改。

将 <endpoint> 替换为与资源关联的终结点 URL。
将 <your_subscription_key> 替换为资源的密钥之一。

（可选）将正文中的 "query" 或 "text" 字段替换为要分析的文本。

curl --location --request POST '<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "domain": "Generic",
  "task": "QnA",
  "qna": {
       "query": "How much does she currently get paid per hour at the bank?"
  },
  "text": "12/hour",
  "groundingSources": [
    "I'm 21 years old and I need to make a decision about the next two years of my life. Within a week. I currently work for a bank that requires strict sales goals to meet. IF they aren't met three times (three months) you're canned. They pay me 10/hour and it's not unheard of to get a raise in 6ish months. The issue is, **I'm not a salesperson**. That's not my personality. I'm amazing at customer service, I have the most positive customer service \"reports\" done about me in the short time I've worked here. A coworker asked \"do you ask for people to fill these out? you have a ton\". That being said, I have a job opportunity at Chase Bank as a part time teller. What makes this decision so hard is that at my current job, I get 40 hours and Chase could only offer me 20 hours/week. Drive time to my current job is also 21 miles **one way** while Chase is literally 1.8 miles from my house, allowing me to go home for lunch. I do have an apartment and an awesome roommate that I know wont be late on his portion of rent, so paying bills with 20hours a week isn't the issue. It's the spending money and being broke all the time.\n\nI previously worked at Wal-Mart and took home just about 400 dollars every other week. So I know i can survive on this income. I just don't know whether I should go for Chase as I could definitely see myself having a career there. I'm a math major likely going to become an actuary, so Chase could provide excellent opportunities for me **eventually**."
  ],
  "reasoning": False
}'

打开命令提示符窗口并运行 cURL 命令。

创建名为“quickstart.py”的新 Python 文件。在首选编辑器或 IDE 中打开新文件。

将 quickstart.py 的内容替换为以下代码。在相应的字段中输入终结点 URL 和密钥。（可选）将正文中的 "query" 或 "text" 字段替换为要分析的文本。

import http.client
import json

conn = http.client.HTTPSConnection("<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview")
payload = json.dumps({
  "domain": "Generic",
  "task": "QnA",
  "qna": {
    "query": "How much does she currently get paid per hour at the bank?"
  },
  "text": "12/hour",
  "groundingSources": [
    "I'm 21 years old and I need to make a decision about the next two years of my life. Within a week. I currently work for a bank that requires strict sales goals to meet. IF they aren't met three times (three months) you're canned. They pay me 10/hour and it's not unheard of to get a raise in 6ish months. The issue is, **I'm not a salesperson**. That's not my personality. I'm amazing at customer service, I have the most positive customer service \"reports\" done about me in the short time I've worked here. A coworker asked \"do you ask for people to fill these out? you have a ton\". That being said, I have a job opportunity at Chase Bank as a part time teller. What makes this decision so hard is that at my current job, I get 40 hours and Chase could only offer me 20 hours/week. Drive time to my current job is also 21 miles **one way** while Chase is literally 1.8 miles from my house, allowing me to go home for lunch. I do have an apartment and an awesome roommate that I know wont be late on his portion of rent, so paying bills with 20hours a week isn't the issue. It's the spending money and being broke all the time.\n\nI previously worked at Wal-Mart and took home just about 400 dollars every other week. So I know i can survive on this income. I just don't know whether I should go for Chase as I could definitely see myself having a career there. I'm a math major likely going to become an actuary, so Chase could provide excellent opportunities for me **eventually**."
  ],
  "reasoning": False
})
headers = {
  'Ocp-Apim-Subscription-Key': '<your_subscription_key>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

重要

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

使用 python 命令运行应用程序：
```
python quickstart.py
```
片刻之后即可获得响应。

若要测试摘要任务而不是问题解答 (QnA) 任务，请使用以下示例 JSON 正文：

{
    "domain": "Medical",
    "task": "Summarization",
    "text": "Ms Johnson has been in the hospital after experiencing a stroke.",
    "groundingSources": ["Our patient, Ms. Johnson, presented with persistent fatigue, unexplained weight loss, and frequent night sweats. After a series of tests, she was diagnosed with Hodgkin’s lymphoma, a type of cancer that affects the lymphatic system. The diagnosis was confirmed through a lymph node biopsy revealing the presence of Reed-Sternberg cells, a characteristic of this disease. She was further staged using PET-CT scans. Her treatment plan includes chemotherapy and possibly radiation therapy, depending on her response to treatment. The medical team remains optimistic about her prognosis given the high cure rate of Hodgkin’s lymphoma."],
    "reasoning": false
}

URL 中必须包含以下字段：

名称	必需	说明	类型
API 版本	必须	这是要使用的 API 版本。当前版本为：api-version=2024-02-15-preview。示例： `<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview`	字符串

请求正文中的参数在此表中定义：

名称	说明	类型
domain	（可选）`MEDICAL` 或 `GENERIC`。默认值：`GENERIC`。	Enum
任务	（可选）任务类型：`QnA`、`Summarization`。默认值：`Summarization`。	Enum
问题与解答	（可选）当任务类型为 `QnA` 时保存 QnA 数据。	字符串
- `query`	（可选）这表示 QnA 任务中的问题。字符限制：7,500。	字符串
text	（必需）要检查的 LLM 输出文本。字符限制：7,500。	字符串
groundingSources	（必需）使用一组有据源来验证 AI 生成的文本。在单个请求中最多可以分析 55,000 个字符的有据源.。	字符串数组
reasoning	（可选）指定是否使用推理功能。默认值为 `false`。如果 `true`，则需要自带 Azure OpenAI GPT-4 Turbo 资源以提供说明。请注意：使用推理会增加处理时间。	布尔

解释 API 响应

提交请求后，将收到反映执行的有据性分析的 JSON 响应。下面是典型输出的外观：

{
    "ungroundedDetected": true,
    "ungroundedPercentage": 1,
    "ungroundedDetails": [
        {
            "text": "12/hour."
        }
    ]
}

输出中的 JSON 对象定义如下：

名称	说明	类型
ungroundedDetected	指示文本是否表现出无据性。	布尔
ungroundedPercentage	指定被识别为无据的文本的比例，表示为 0 到 1 之间的数字，其中 0 表示没有无据内容，1 表示完全为无据内容。	浮点
ungroundedDetails	通过具体示例和百分比提供对无据内容的见解。	数组
-`text`	无据的特定文本。	字符串

在推理的情况下检查有据性

有据性检测 API 提供了在 API 响应中包含推理的选项。启用推理后，响应包括一个 "reasoning" 字段，详细说明了特定实例以及对任何检测到的无据性的解释。请注意：使用推理会增加处理时间，并产生额外的费用。

自带 GPT 部署

提示

目前，我们仅支持 Azure OpenAI GPT-4 Turbo 资源，不支持其他 GPT 类型。 GPT-4 Turbo 资源可部署在任何区域中；但是，建议其与内容安全资源位于同一区域中，以最大程度地减少可能的延迟。

若要使用 Azure OpenAI GPT4-Turbo 资源启用推理功能，请使用托管标识以允许内容安全资源访问 Azure OpenAI 资源：

为 Azure AI 内容安全启用托管标识。

在 Azure 门户中导航到 Azure AI 内容安全实例。在“设置”类别下找到“标识”部分。启用系统分配的托管标识。此操作向 Azure AI 内容安全实例授予可在 Azure 中识别和使用的标识，可用于访问其他资源。
为托管标识分配角色。

导航到 Azure OpenAI 实例，选择“添加角色分配”开始将 Azure OpenAI 角色分配到 Azure AI 内容安全标识的过程。

选择“用户”或“参与者”角色。

发出 API 请求

在对有据性检测 API 的请求中，将 "reasoning" 正文参数设置为 true，并提供其他所需的参数：

 {
  "reasoning": true,
  "llmResource": {
    "resourceType": "AzureOpenAI",
    "azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
    "azureOpenAIDeploymentName": "<your_deployment_name>"
  }
}

cURL
Python

本部分介绍使用 cURL 进行请求的示例。将以下命令粘贴到文本编辑器，并进行以下更改。

将 <endpoint> 替换为与资源关联的终结点 URL。
将 <your_subscription_key> 替换为资源的密钥之一。

（可选）将正文中的 "query" 或 "text" 字段替换为要分析的文本。

curl --location --request POST '<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "domain": "Generic",
  "task": "QnA",
  "qna": {
       "query": "How much does she currently get paid per hour at the bank?"
  },
  "text": "12/hour",
  "groundingSources": [
    "I'm 21 years old and I need to make a decision about the next two years of my life. Within a week. I currently work for a bank that requires strict sales goals to meet. IF they aren't met three times (three months) you're canned. They pay me 10/hour and it's not unheard of to get a raise in 6ish months. The issue is, **I'm not a salesperson**. That's not my personality. I'm amazing at customer service, I have the most positive customer service \"reports\" done about me in the short time I've worked here. A coworker asked \"do you ask for people to fill these out? you have a ton\". That being said, I have a job opportunity at Chase Bank as a part time teller. What makes this decision so hard is that at my current job, I get 40 hours and Chase could only offer me 20 hours/week. Drive time to my current job is also 21 miles **one way** while Chase is literally 1.8 miles from my house, allowing me to go home for lunch. I do have an apartment and an awesome roommate that I know wont be late on his portion of rent, so paying bills with 20hours a week isn't the issue. It's the spending money and being broke all the time.\n\nI previously worked at Wal-Mart and took home just about 400 dollars every other week. So I know i can survive on this income. I just don't know whether I should go for Chase as I could definitely see myself having a career there. I'm a math major likely going to become an actuary, so Chase could provide excellent opportunities for me **eventually**."
  ],
  "reasoning": true,
  "llmResource": {
        "resourceType": "AzureOpenAI",
        "azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
        "azureOpenAIDeploymentName": "<your_deployment_name>"
}'

打开命令提示符窗口并运行 cURL 命令。

创建名为“quickstart.py”的新 Python 文件。在首选编辑器或 IDE 中打开新文件。

将 quickstart.py 的内容替换为以下代码。在相应的字段中输入终结点 URL 和密钥。（可选）将正文中的 "query" 或 "text" 字段替换为要分析的文本。

import http.client
import json

conn = http.client.HTTPSConnection("<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview")
payload = json.dumps({
  "domain": "Generic",
  "task": "QnA",
  "qna": {
    "query": "How much does she currently get paid per hour at the bank?"
  },
  "text": "12/hour",
  "groundingSources": [
    "I'm 21 years old and I need to make a decision about the next two years of my life. Within a week. I currently work for a bank that requires strict sales goals to meet. IF they aren't met three times (three months) you're canned. They pay me 10/hour and it's not unheard of to get a raise in 6ish months. The issue is, **I'm not a salesperson**. That's not my personality. I'm amazing at customer service, I have the most positive customer service \"reports\" done about me in the short time I've worked here. A coworker asked \"do you ask for people to fill these out? you have a ton\". That being said, I have a job opportunity at Chase Bank as a part time teller. What makes this decision so hard is that at my current job, I get 40 hours and Chase could only offer me 20 hours/week. Drive time to my current job is also 21 miles **one way** while Chase is literally 1.8 miles from my house, allowing me to go home for lunch. I do have an apartment and an awesome roommate that I know wont be late on his portion of rent, so paying bills with 20hours a week isn't the issue. It's the spending money and being broke all the time.\n\nI previously worked at Wal-Mart and took home just about 400 dollars every other week. So I know i can survive on this income. I just don't know whether I should go for Chase as I could definitely see myself having a career there. I'm a math major likely going to become an actuary, so Chase could provide excellent opportunities for me **eventually**."
  ],
  "reasoning": True
  "llmResource": {
   "resourceType": "AzureOpenAI",
   "azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
   "azureOpenAIDeploymentName": "<your_deployment_name>"
  }
})
headers = {
  'Ocp-Apim-Subscription-Key': '<your_subscription_key>',
  'Content-Type': 'application/json'
}
conn.request("POST", "/contentsafety/text:detectGroundedness?api-version=2024-02-15-preview", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))

使用 python 命令运行应用程序：
```
python quickstart.py
```
片刻之后即可获得响应。

请求正文中的参数在此表中定义：

名称	说明	类型
domain	（可选）`MEDICAL` 或 `GENERIC`。默认值：`GENERIC`。	Enum
任务	（可选）任务类型：`QnA`、`Summarization`。默认值：`Summarization`。	Enum
问题与解答	（可选）当任务类型为 `QnA` 时保存 QnA 数据。	字符串
- `query`	（可选）这表示 QnA 任务中的问题。字符限制：7,500。	字符串
text	（必需）要检查的 LLM 输出文本。字符限制：7,500。	字符串
groundingSources	（必需）使用一组有据源来验证 AI 生成的文本。在单个请求中最多可以分析 55,000 个字符的有据源.。	字符串数组
reasoning	（可选）设置为 `true`，该服务使用 Azure OpenAI 资源提供说明。请注意：使用推理会增加处理时间，并产生额外的费用。	布尔
llmResource	（必需）如果要使用自己的 Azure OpenAI GPT4-Turbo 资源来启用推理，请添加此字段，并包括所用资源的子字段。	字符串
- `resourceType`	指定要使用的资源的类型。目前只允许 `AzureOpenAI`。我们仅支持 Azure OpenAI GPT-4 Turbo 资源，不支持其他 GPT 类型。 GPT-4 Turbo 资源可部署在任何区域中；但是，建议其与内容安全资源位于同一区域中，以最大程度地减少可能的延迟。	Enum
- `azureOpenAIEndpoint`	Azure OpenAI 服务的终结点 URL。	字符串
- `azureOpenAIDeploymentName`	要使用的特定 GPT 部署的名称。	字符串

解释 API 响应

提交请求后，将收到反映执行的有据性分析的 JSON 响应。下面是典型输出的外观：

{
    "ungroundedDetected": true,
    "ungroundedPercentage": 1,
    "ungroundedDetails": [
        {
            "text": "12/hour.",
            "offset": {
                "utF8": 0,
                "utF16": 0,
                "codePoint": 0
            },
            "length": {
                "utF8": 8,
                "utF16": 8,
                "codePoint": 8
            },
            "reason": "None. The premise mentions a pay of \"10/hour\" but does not mention \"12/hour.\" It's neutral. "
        }
    ]
}

输出中的 JSON 对象定义如下：

名称	说明	类型
ungroundedDetected	指示文本是否表现出无据性。	布尔
ungroundedPercentage	指定被识别为无据的文本的比例，表示为 0 到 1 之间的数字，其中 0 表示没有无据内容，1 表示完全为无据内容。	浮点
ungroundedDetails	通过具体示例和百分比提供对无据内容的见解。	数组
-`text`	无据的特定文本。	字符串
-`offset`	描述无据文本在各种编码中的位置的对象。	字符串
- `offset > utf8`	无据文本在 UTF-8 编码中的偏移位置。	Integer
- `offset > utf16`	无据文本在 UTF-16 编码中的偏移位置。	Integer
- `offset > codePoint`	无据文本相对于 Unicode 码位的偏移位置。	Integer
-`length`	描述无据文本在各种编码中的长度的对象。（utf8、utf16、codePoint），类似于偏移量。	Object
- `length > utf8`	无据文本在 UTF-8 编码中的长度。	Integer
- `length > utf16`	无据文本在 UTF-16 编码中的长度。	Integer
- `length > codePoint`	无据文本相对于 Unicode 码位的长度。	Integer
-`reason`	提供检测到的无据性的说明。	字符串

清理资源

如果想要清理并移除 Azure AI 服务订阅，可以删除资源或资源组。删除资源组同时也会删除与之相关联的任何其他资源。

后续步骤

将有据性检测与其他 LLM 安全功能（如 Prompt Shields）结合使用。

Prompt Shields 快速入门