共用方式為


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

本指南說明如何使用建基偵測 API。 此功能會根據所提供的來源文件自動偵測及更正未建基的文字,確保生成的內容與事實或預定的參考一致。 以下我們會探索數個常見案例,以協助您了解如何及何時套用這些功能,以達到最佳結果。

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入您資源的唯一名稱,選取您的訂用帳戶,然後選取資源群組、支援的區域,以及支援的定價層。 然後選取建立
  • 部署資源需要幾分鐘的時間。 完成後,請移至新資源。 在左窗格的 [資源管理] 下,選取 [API 金鑰與端點]。 將其中一個訂用帳戶密鑰值和端點複製到暫存位置,以供稍後使用。
  • (選用) 如果您想要使用推理功能,請使用已部署的 GPT 模型建立 Azure OpenAI 服務資源。
  • 已安裝 cURLPython

檢查基礎而不推理

在沒有推理功能的簡單案例中,基礎性偵測 API 會將送出內容的背景性分類為 truefalse

本節會逐步解說 cURL 的範例要求。 將下列命令貼上至文字編輯器,並進行下列變更。

  1. <endpoint> 取代為與資源相關聯的端點 URL。

  2. <your_subscription_key> 取代為您資源的其中一個金鑰。

  3. 或者,將本文中的 "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 String

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

名稱 描述 類型
網域 (選用) MEDICALGENERIC。 預設值: GENERIC 列舉
工作 (選用) 工作類型:QnASummarization。 預設值: 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 服務的資料、隱私權和安全指導方針 (英文) 和 Azure AI 內容安全的資料、隱私權和安全 (英文)。

若要使用 Azure OpenAIGPT4-Turbo (1106-preview) 資源來啟用推理功能,請使用受控識別讓您的內容安全資源存取 Azure OpenAI 資源:

  1. 為 Azure AI 內容安全啟用受控識別。

    在 Azure 入口網站中,瀏覽至 Azure AI 內容安全執行個體。 在 [設定] 類別下尋找 [身分識別] 區段。 啟用系統指派的受控識別。 此動作會授與 Azure AI 內容安全執行個體身分識別,以在 Azure 中辨識及用於存取其他資源。

    Azure 入口網站中內容安全身分識別資源的螢幕擷取畫面。

  2. 將角色指派給受控識別。

    瀏覽至您的 Azure OpenAI 執行個體,選取 [新增角色指派],以開始將 Azure OpenAI 角色指派給 Azure AI 內容安全身分識別的流程。

    Azure 入口網站中新增角色指派的螢幕擷取畫面。

    選擇使用者參與者角色。

    Azure 入口網站的螢幕擷取畫面,其中顯示清單中的參與者和使用者角色。

提出 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 的範例要求。 將下列命令貼上至文字編輯器,並進行下列變更。

  1. <endpoint> 取代為與 Azure AI 內容安全資源相關聯的端點 URL。

  2. <your_subscription_key> 取代為您資源的其中一個金鑰。

  3. <your_OpenAI_endpoint> 取代為與 Azure OpenAI 資源相關聯的端點 URL。

  4. <your_deployment_name> 取代為您 Azure OpenAI 部署的名稱。

  5. 或者,將本文中的 "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>"
    }'
    
  6. 開啟命令提示字元,並執行 cURL 命令。

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

名稱 描述 類型
網域 (選用) MEDICALGENERIC。 預設值: GENERIC 列舉
工作 (選用) 工作類型:QnASummarization。 預設值: 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

使用更正功能檢查建基

根據性偵測 API 包含一項更正功能,可根據所提供的基礎來源,自動更正文字中任何偵測到的非根據性。 啟用更正功能時,回應會包含 "correction Text" 欄位,其中呈現與基礎來源對齊的更正文字。

自備 GPT 部署

提示

目前,更正功能僅支援 Azure OpenAI GPT-4 Turbo (1106-preview) 資源。 若要將延遲降至最低並遵守資料隱私權指導方針,建議您在與內容安全資源相同的區域中部署 GPT-4 Turbo (1106-preview) 資源。 如需資料隱私權的更多詳細資料,請參閱 Azure OpenAI 服務的資料、隱私權和安全指導方針 (英文) 和 Azure AI 內容安全的資料、隱私權和安全 (英文)。

若要使用 Azure OpenAI GPT4-Turbo (1106-preview) 資源來啟用更正功能,請使用受控識別讓您的內容安全資源存取 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> 取代為訂用帳戶金鑰。
  • 或者,將 [文字] 欄位取代為您要分析的文字。
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>"
  }
}'

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

名稱 描述 類型
網域 (選用) MEDICALGENERIC。 預設值: GENERIC 列舉
工作 (選用) 工作類型:QnASummarization。 預設值: Summarization 列舉
qna (選用) 工作類型為 QnA 時,保留 QnA 資料。 String
- query (選用) 這代表 QnA 工作中的問題。 字元限制:7,500。 String
text (必要) 要檢查的 LLM 輸出文字。 字元限制:7,500。 String
groundingSources (必要) 使用基礎來源陣列來驗證 AI 產生的文字。 如需限制,請參閱輸入需求 字串陣列
correction (選用) 設定為 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 回應

回應包含的 "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 文字中未建基內容的比例。 Float
ungroundedDetails 未建基內容的詳細資料,包括特定的文字區段。 陣列
-text 未擱置的特定文字。 String
-offset 物件,描述不同編碼方式中未設定的文字所在的位置。 String
- offset > utf8 UTF-8 編碼中未設定的文字所在的位移位置。 整數
- offset > utf16 UTF-16 編碼中未設定的文字所在的位移位置。 整數
-length 物件,描述各種編碼方式中未設定的文字所達到的長度。 (utf8、utf16、codePoint),類似於位移。 Object
- length > utf8 UTF-8 編碼中未設定的文字所達到的長度。 整數
- length > utf16 UTF-16 編碼中未設定的文字所達到的長度。 整數
- length > codePoint Unicode 程式碼點的未設定文字長度。 整數
-correction Text 更正的文字,確保與建基來源的一致性。 String

清除資源

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