快速入門：基礎偵測（預覽）

發行項
06/13/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`	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	提供具有特定範例和百分比之非前景內容的深入解析。	陣列
-`text`	未擱置的特定文字。	String

使用推理檢查基礎性

地面偵測 API 提供在 API 回應中包含推理的選項。啟用推理后，回應會包含一個 "reasoning" 字段，詳細說明任何偵測到的不景度的特定實例和說明。

自備 GPT 部署

提示

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

若要使用 Azure OpenAI GPT4-Turbo （1106-preview）資源來啟用推理功能，請使用受控識別讓您的 Content Safety 資源存取 Azure OpenAI 資源：

啟用 Azure AI 內容安全性的受控識別。

流覽至 Azure 入口網站中的 Azure AI 內容安全性實例。在 [設定] 類別下尋找 [身分識別] 區段。啟用系統指派的受控識別。此動作會授與 Azure AI Content Safety 實例身分識別，以在 Azure 中辨識及用於存取其他資源。
將角色指派給受控識別。

流覽至您的 Azure OpenAI 實例，選取 [ 新增角色指派 ] 以開始將 Azure OpenAI 角色指派給 Azure AI Content Safety 身分識別的程式。

選擇 [使用者] 或 [參與者] 角色。

提出 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 OpenAI GPT4-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	提供具有特定範例和百分比之非前景內容的深入解析。	陣列
-`text`	未擱置的特定文字。	String
-`offset`	物件，描述不同編碼方式中未設定之文字的位置。	String
- `offset > utf8`	UTF-8 編碼中未設定之文字的位移位置。	整數
- `offset > utf16`	UTF-16 編碼中未設定之文字的位移位置。	整數
- `offset > codePoint`	Ungrounded text 在 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 回應

清除資源

下一步

意見反應

意見反應

其他資源

共用方式為

快速入門：基礎偵測 （預覽）

必要條件

檢查基礎而不推理

解譯 API 回應

使用推理檢查基礎性

自備 GPT 部署

提出 API 要求

解譯 API 回應

清除資源

下一步

意見反應

意見反應

其他資源

快速入門：基礎偵測（預覽）