快速入門：根據性偵測 (預覽)

發行項
07/23/2024

遵循本指南使用 Azure AI 內容安全根據性偵測來檢查大型語言模型 (LLM) 的文字回應是否以使用者所提供的來源素材為根據。

必要條件

Azure 訂用帳戶 - 建立免費帳戶
擁有 Azure 訂用帳戶之後，在 Azure 入口網站中建立 Content Safety 資源，以取得您的金鑰和端點。輸入您資源的唯一名稱，選取您的訂用帳戶，然後選取資源群組、支援的區域，以及支援的定價層。然後選取建立。
部署資源需要幾分鐘的時間。完成後，請移至新資源。在左窗格的 [資源管理] 下，選取 [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`	String

要求本文中的參數在此表中定義：

名稱	描述	類型
網域	(選用) `MEDICAL` 或 `GENERIC`。預設值: `GENERIC`。	列舉
工作	(選用) 工作類型：`QnA`、`Summarization`。預設值: `Summarization`。	列舉
qna	(選用) 工作類型為 `QnA` 時，保留 QnA 資料。	String
- `query`	(選用) 這代表 QnA 工作中的問題。字元限制：7,500。	String
text	(必要) 要檢查的 LLM 輸出文字。字元限制：7,500。	String
groundingSources	(必要) 使用基礎來源陣列來驗證 AI 產生的文字。如需限制，請參閱輸入需求。	字串陣列
理由	(選用) 指定是否要使用推理功能。預設值是 `false`。如果 `true`，您需要自備 Azure OpenAI GPT-4 Turbo (1106-preview) 資源，以提供說明。請小心：使用推理會增加處理時間。	布林值

解譯 API 回應

提交要求之後，您會收到 JSON 回應，反映所執行的基礎性分析。以下是一般輸出的樣貌：

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

輸出中的 JSON 物件定義如下：

名稱	描述	類型
ungroundedDetected	指出文字是否呈現非根據性。	布林值
ungroundedPercentage	指定識別為非根據性的文字比例，以介於 0 到 1 之間的數字表示，其中 0 表示沒有未設定背景的內容，1 則表示完全非根據性的內容。	Float
ungroundedDetails	提供具有特定範例和百分比的非根據性內容深入解析。	Array
-`text`	未擱置的特定文字。	String

使用推理檢查基礎性

地面偵測 API 提供在 API 回應中包含推理的選項。啟用推理後，回應會包含 "reasoning" 欄位，詳細說明任何偵測到的非根據性的特定執行個體和說明。

自備 GPT 部署

提示

目前，我們只支援 Azure OpenAI GPT-4 Turbo (1106-preview) 資源，而且不支援其他 GPT 類型。您可以彈性地在任何區域中部署 GPT-4 Turbo (1106-preview) 資源。不過，若要將潛在延遲降到最低，並避免任何地理界限資料隱私權和風險考慮，建議您將它們放在與內容安全資源相同的區域中。如需資料隱私權的完整詳細資料，請參閱 Azure OpenAI Service 的資料、隱私權和安全性指導方針和 Azure AI 內容安全的資料、隱私權和安全性。

若要使用 Azure OpenAIGPT4-Turbo (1106-preview) 資源來啟用推理功能，請使用受控識別讓您的內容安全資源存取 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
```
請稍候片刻以取得回應。

要求本文中的參數在此表中定義：

名稱	描述	類型
網域	(選用) `MEDICAL` 或 `GENERIC`。預設值: `GENERIC`。	列舉
工作	(選用) 工作類型：`QnA`、`Summarization`。預設值: `Summarization`。	列舉
qna	(選用) 工作類型為 `QnA` 時，保留 QnA 資料。	String
- `query`	(選用) 這代表 QnA 工作中的問題。字元限制：7,500。	String
text	(必要) 要檢查的 LLM 輸出文字。字元限制：7,500。	String
groundingSources	(必要) 使用基礎來源陣列來驗證 AI 產生的文字。如需限制，請參閱輸入需求，	字串陣列
理由	(選用) 設定為 `true`，服務會使用 Azure OpenAI 資源來提供說明。請小心：使用推理會增加處理時間，並產生額外費用。	布林值
llmResource	(必要) 如果您想要使用自己的 Azure OpenAIGPT4-Turbo (1106-preview) 資源來啟用推理，請新增此欄位，並包含所用資源的子欄位。	String
- `resourceType`	指定正在使用的資源類型。目前它只允許 `AzureOpenAI`。我們只支援 Azure OpenAI GPT-4 Turbo (1106-preview) 資源，且不支援其他 GPT 類型。	列舉
- `azureOpenAIEndpoint`	Azure OpenAI 服務的端點 URL。	String
- `azureOpenAIDeploymentName`	要使用的特定 GPT 部署名稱。	String

解譯 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 則表示完全非根據性的內容。	Float
ungroundedDetails	提供具有特定範例和百分比的非根據性內容深入解析。	Array
-`text`	未擱置的特定文字。	String
-`offset`	物件，描述不同編碼方式中未設定的文字所在的位置。	String
- `offset > utf8`	UTF-8 編碼中未設定的文字所在的位移位置。	整數
- `offset > utf16`	UTF-16 編碼中未設定的文字所在的位移位置。	整數
- `offset > codePoint`	Ungroundedtext 在 Unicode 程式碼點中的位移位置。	整數
-`length`	物件，描述各種編碼方式中未設定的文字所達到的長度。 (utf8、utf16、codePoint)，類似於位移。	Object
- `length > utf8`	UTF-8 編碼中未設定的文字所達到的長度。	整數
- `length > utf16`	UTF-16 編碼中未設定的文字所達到的長度。	整數
- `length > codePoint`	Unicode 程式碼點的未設定文字長度。	整數
-`reason`	提供偵測到非根據性的說明。	String

清除資源

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

下一步

結合地面偵測與其他 LLM 安全性功能，例如提示防護。

提示防護快速入門

共用方式為

快速入門：根據性偵測 (預覽)

必要條件

檢查基礎而不推理

解譯 API 回應

使用推理檢查基礎性

自備 GPT 部署

提出 API 要求

解譯 API 回應

清除資源

下一步

意見反應

意見反應

其他資源