你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
快速入门:使用有据性检测(预览版)
本指南介绍如何使用上下文关联检测 API。 此功能根据提供的源文档自动检测并纠正上下文不关联的文本,确保生成的内容与事实或预期参考相符。 下面,我们将探讨几个常见场景,以帮助你了解如何以及何时应用这些功能来实现最佳结果。
先决条件
- Azure 订阅 - 免费创建订阅
- 拥有 Azure 订阅后,请在 Azure 门户中创建 Content Safety 资源 ,以获取密钥和终结点。 输入资源的唯一名称,选择订阅,并选择资源组、支持的区域和支持的定价层。 然后选择“创建”。
- 部署资源需要几分钟时间。 完成后,请转到新的资源。 在左窗格的“资源管理”下,选择“API 密钥和终结点”。 将其中一个订阅密钥值和终结点复制到临时位置供以后使用。
- (可选)若要使用推理功能,请创建已部署 GPT 模型的 Azure OpenAI 服务资源。
- 安装 cURL 或 Python。
在不推理的情况下检查有据性
在不使用推理功能的简单情况下,有据性检测 API 将提交内容的无据性分类为 true
或 false
。
本部分介绍使用 cURL 进行请求的示例。 将以下命令粘贴到文本编辑器,并进行以下更改。
将
<endpoint>
替换为与资源关联的终结点 URL。将
<your_subscription_key>
替换为资源的密钥之一。(可选)将正文中的
"query"
或"text"
字段替换为要分析的文本。curl --location --request POST '<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-09-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 命令。
若要测试摘要任务而不是问题解答 (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-09-15-preview。 示例: <endpoint>/contentsafety/text:detectGroundedness?api-version=2024-09-15-preview |
字符串 |
请求正文中的参数在此表中定义:
名称 | 说明 | 类型 |
---|---|---|
domain | (可选)MEDICAL 或 GENERIC 。 默认值:GENERIC 。 |
Enum |
任务 | (可选)任务类型:QnA 、Summarization 。 默认值:Summarization 。 |
Enum |
问题与解答 | (可选)当任务类型为 QnA 时保存 QnA 数据。 |
字符串 |
- query |
(可选)这表示 QnA 任务中的问题。 字符限制:7,500。 | 字符串 |
text | (必需)要检查的 LLM 输出文本。 字符限制:7,500。 | 字符串 |
groundingSources | (必需)使用一组有据源来验证 AI 生成的文本。 有关限制,请参阅输入要求。 | 字符串数组 |
reasoning | (可选)指定是否使用推理功能。 默认值为 false 。 如果为 true ,则你需要自带 Azure OpenAI GPT4o(0513、0806 版本)来提供解释。 请注意:使用推理会增加处理时间。 |
布尔 |
解释 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 GPT4o(0513、0806 版本)** 资源,而不支持其他 GPT 类型。 你可以灵活地在任何区域部署 Azure OpenAI GPT4o(0513、0806 版本)资源。 但是,为了尽量减少潜在的延迟并避免任何地理边界数据隐私和风险问题,我们建议将这些资源放置在与内容安全资源相同的区域。 有关数据隐私的全面详细信息,请参阅 Azure OpenAI 服务的数据、隐私和安全指南和 Azure AI 内容安全的数据、隐私和安全性。
若要使用 Azure OpenAI GPT4o(0513, 0806 版)资源启用推理功能,请使用托管标识以允许内容安全资源访问 Azure OpenAI 资源:
为 Azure AI 内容安全启用托管标识。
在 Azure 门户中导航到 Azure AI 内容安全实例。 在“设置”类别下找到“标识”部分。 启用系统分配的托管标识。 此操作向 Azure AI 内容安全实例授予可在 Azure 中识别和使用的标识,可用于访问其他资源。
为托管标识分配角色。
导航到 Azure OpenAI 实例,选择“添加角色分配”开始将 Azure OpenAI 角色分配到 Azure AI 内容安全标识的过程。
选择“用户”或“参与者”角色。
发出 API 请求
在对有据性检测 API 的请求中,将 "reasoning"
正文参数设置为 true
,并提供其他所需的参数:
{
"domain": "Medical",
"task": "Summarization",
"text": "The patient name is Kevin.",
"groundingSources": [
"The patient name is Jane."
],
"reasoning": true,
"llmResource": {
"resourceType": "AzureOpenAI",
"azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
"azureOpenAIDeploymentName": "<your_deployment_name>"
}
}
本部分介绍使用 cURL 进行请求的示例。 将以下命令粘贴到文本编辑器,并进行以下更改。
请将
<endpoint>
替换为与你的 Azure AI 内容安全资源关联的终结点 URL。将
<your_subscription_key>
替换为资源的密钥之一。请将
<your_OpenAI_endpoint>
替换为与你的 Azure OpenAI 资源关联的终结点 URL。请将
<your_deployment_name>
替换为你的 Azure OpenAI 部署名称。(可选)将正文中的
"query"
或"text"
字段替换为要分析的文本。curl --location --request POST '<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-09-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 命令。
请求正文中的参数在此表中定义:
名称 | 说明 | 类型 |
---|---|---|
domain | (可选)MEDICAL 或 GENERIC 。 默认值:GENERIC 。 |
Enum |
任务 | (可选)任务类型:QnA 、Summarization 。 默认值:Summarization 。 |
Enum |
问题与解答 | (可选)当任务类型为 QnA 时保存 QnA 数据。 |
字符串 |
- query |
(可选)这表示 QnA 任务中的问题。 字符限制:7,500。 | 字符串 |
text | (必需)要检查的 LLM 输出文本。 字符限制:7,500。 | 字符串 |
groundingSources | (必需)使用一组有据源来验证 AI 生成的文本。 有关限制,请参阅输入要求。 | 字符串数组 |
reasoning | (可选)设置为 true ,该服务使用 Azure OpenAI 资源提供说明。 请注意:使用推理会增加处理时间,并产生额外的费用。 |
布尔 |
llmResource | (必需)如果要使用自己的 Azure OpenAI GPT4o(0513, 0806 版)资源来启用推理,请添加此字段,并包括所用资源的子字段。 | 字符串 |
- resourceType |
指定要使用的资源的类型。 目前只允许 AzureOpenAI 。 我们仅支持 Azure OpenAI GPT4o(0513、0806 版本)资源,而不支持其他 GPT 类型。 |
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 |
提供检测到的无据性的说明。 | 字符串 |
使用纠正功能检查上下文关联性
上下文关联性检测 API 包含一个纠正功能,可以根据提供的基础源自动纠正文本中检测到的任何上下文不关联性。 启用纠正功能时,响应会包含一个 "correction Text"
字段,该字段显示与基础源一致的已纠正文本。
连接自己的 GPT 部署
提示
目前,更正功能仅支持 **Azure OpenAI GPT4o(0513、0806 版本)** 资源。 为了最大程度地减少延迟并遵守数据隐私准则,建议将 Azure OpenAI GPT4o(0513、0806 版本)资源部署到内容安全资源所在的同一区域。 有关数据隐私的更多详细信息,请参阅 Azure OpenAI 服务的数据、隐私和安全指南和 Azure AI 内容安全的数据、隐私和安全性。
若要使用 Azure OpenAI GPT4o(0513, 0806 版)资源启用纠正功能,请使用托管标识以允许内容安全资源访问 Azure OpenAI 资源。 按照前面部分中所述的步骤设置托管标识。
发出 API 请求
在对上下文关联性检测 API 的请求中,请将 "correction"
正文参数设置为 true
,并提供其他必要参数:
{
"domain": "Medical",
"task": "Summarization",
"text": "The patient name is Kevin.",
"groundingSources": [
"The patient name is Jane."
],
"correction": true,
"llmResource": {
"resourceType": "AzureOpenAI",
"azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
"azureOpenAIDeploymentName": "<your_deployment_name>"
}
}
本部分演示一个使用 cURL 的示例请求。 请根据需要替换占位符:
- 请将
<endpoint>
替换为你的资源的终结点 URL。 - 将
<your_subscription_key>
替换为订阅密钥。 - (可选)将“text”字段替换为你要分析的文本。
curl --location --request POST '<endpoint>/contentsafety/text:detectGroundedness?api-version=2024-09-15-preview' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"domain": "Generic",
"task": "Summarization",
"text": "The patient name is Kevin.",
"groundingSources": [
"The patient name is Jane."
],
"correction": true,
"llmResource": {
"resourceType": "AzureOpenAI",
"azureOpenAIEndpoint": "<your_OpenAI_endpoint>",
"azureOpenAIDeploymentName": "<your_deployment_name>"
}
}'
请求正文中的参数在此表中定义:
名称 | 说明 | 类型 |
---|---|---|
domain | (可选)MEDICAL 或 GENERIC 。 默认值:GENERIC 。 |
Enum |
任务 | (可选)任务类型:QnA 、Summarization 。 默认值:Summarization 。 |
Enum |
问题与解答 | (可选)当任务类型为 QnA 时保存 QnA 数据。 |
字符串 |
- query |
(可选)这表示 QnA 任务中的问题。 字符限制:7,500。 | 字符串 |
text | (必需)要检查的 LLM 输出文本。 字符限制:7,500。 | 字符串 |
groundingSources | (必需)使用一组有据源来验证 AI 生成的文本。 有关限制,请参阅输入要求。 | String Array |
纠正 | (可选)设置为 true ,服务将使用 Azure OpenAI 资源提供纠正的文本,确保与基础源保持一致。 请注意:使用纠正功能会增加处理时间并产生额外的费用。 |
布尔 |
llmResource | (必需)如果要使用自己的 Azure OpenAI GPT4o(0513, 0806 版)资源来启用推理,请添加此字段,并包括所用资源的子字段。 | 字符串 |
- resourceType |
指定要使用的资源的类型。 目前只允许 AzureOpenAI 。 我们仅支持 Azure OpenAI GPT4o(0513、0806 版本)资源,而不支持其他 GPT 类型。 |
Enum |
- azureOpenAIEndpoint |
Azure OpenAI 服务的终结点 URL。 | 字符串 |
- azureOpenAIDeploymentName |
要使用的特定 GPT 部署的名称。 | 字符串 |
解释 API 响应
响应中有一个 "correction Text"
字段,其中包含纠正的文本,确保与提供的基础源保持一致。
纠正功能检测到 Kevin
上下文不关联,因为它与基础源 Jane
冲突。 API 返回纠正的文本:"The patient name is Jane."
{
"ungroundedDetected": true,
"ungroundedPercentage": 1,
"ungroundedDetails": [
{
"text": "The patient name is Kevin"
}
],
"correction Text": "The patient name is Jane"
}
输出中的 JSON 对象定义如下:
名称 | 说明 | 类型 |
---|---|---|
ungroundedDetected | 指示是否检测到上下文不关联的内容。 | 布尔 |
ungroundedPercentage | 上下文不关联的内容在文本中所占的比例。 | 浮点 |
ungroundedDetails | 上下文不关联的内容的详细信息,包括特定的文本段。 | 数组 |
-text |
无据的特定文本。 | 字符串 |
-offset |
描述无据文本在各种编码中的位置的对象。 | 字符串 |
- offset > utf8 |
无据文本在 UTF-8 编码中的偏移位置。 | Integer |
- offset > utf16 |
无据文本在 UTF-16 编码中的偏移位置。 | Integer |
-length |
描述无据文本在各种编码中的长度的对象。 (utf8、utf16、codePoint),类似于偏移量。 | Object |
- length > utf8 |
无据文本在 UTF-8 编码中的长度。 | Integer |
- length > utf16 |
无据文本在 UTF-16 编码中的长度。 | Integer |
- length > codePoint |
无据文本相对于 Unicode 码位的长度。 | Integer |
-correction Text |
纠正的文本,确保与基础源保持一致。 | 字符串 |
清理资源
如果想要清理并移除 Azure AI 服务订阅,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。
相关内容
- 有据性检测概念
- 将有据性检测与其他 LLM 安全功能(如 Prompt Shields)结合使用。