快速入門:分析文字內容
開始使用 Content Safety Studio、REST API 或用戶端 SDK 來執行基本文字調節。 Azure AI 內容安全服務提供 AI 演算法來標記令人反感的內容。 請遵循下列步驟來試用。
如需有關文字審核的詳細資訊,請參閱有害類別概念頁面。 關於 API 輸入限制,請參閱概觀的輸入要求一節。
注意
樣本資料和程式碼可能包含冒犯性內容。 建議使用者斟酌使用。
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入您資源的唯一名稱,選取您的訂用帳戶,然後選取資源群組、支援的區域 (參閱區域可用性) 以及支援的定價層。 然後選取建立。
- 部署資源需要幾分鐘的時間。 完成後,選取 [移至資源]。 在左側窗格中,於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 端點和其中一個金鑰是用以呼叫 API。
- 已安裝 cURL
分析文字內容
下一節會逐步解說 cURL 的範例要求。 將下列命令貼上至文字編輯器,並進行下列變更。
- 將
<endpoint>
取代為與資源相關聯的端點 URL。 - 將
<your_subscription_key>
取代為資源自帶的金鑰之一。 - 或者,將本文中的
"text"
欄位取代為您要分析的文字。
curl --location --request POST '<endpoint>/contentsafety/text:analyze?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
"text": "I hate you",
"categories": ["Hate", "Sexual", "SelfHarm", "Violence"],
"blocklistNames": ["string"],
"haltOnBlocklistHit": true,
"outputType": "FourSeverityLevels"
}'
下欄欄位必須包含在 URL 中:
名稱 | 必要 | 描述 | 類型 |
---|---|---|---|
API 版本 | 必要 | 這是要檢查的 API 版本。 目前的版本為:api-version=2024-09-01。 範例: <endpoint>/contentsafety/text:analyze?api-version=2024-09-01 |
String |
要求本文中的參數在此表中定義:
名稱 | 必要 | 描述 | 類型 |
---|---|---|---|
text | 必要 | 這是要檢查的原始文字。 可以包含其他非 ascii 字元。 | String |
categories | 選擇性 | 假定這是類別名稱的陣列。 如需可用類別名稱的清單,請參閱危害類別指南。 如果未指定任何類別,則會使用這四個類別。 我們使用多個類別來取得單一要求中的分數。 | String |
blocklistNames | 選擇性 | 文字區塊名稱。 僅支援下列字元:0-9 A-Z a-z - . _ ~ 。 您可以在這裡附加多個清單名稱。 |
Array |
haltOnBlocklistHit | 選擇性 | 當設定為 true 時,在封鎖清單被叫用的情況下,將不會針對有害內容執行進一步分析。 當設定為 false 時,無論在封鎖清單是否被叫用的情況下,將會針對所有有害內容的進一步執行分析。 |
布林值 |
outputType | 選擇性 | "FourSeverityLevels" 或 "EightSeverityLevels" 。 四或八個層級的輸出嚴重性,此值可以是 0,2,4,6 或 0,1,2,3,4,5,6,7 。 |
String |
請參閱下列範例要求本文:
{
"text": "I hate you",
"categories": ["Hate", "Sexual", "SelfHarm", "Violence"],
"blocklistNames": ["array"],
"haltOnBlocklistHit": false,
"outputType": "FourSeverityLevels"
}
開啟命令提示視窗,貼上已編輯的 cURL 命令,然後執行它。
輸出
您應該會在主控台輸出中看到顯示為 JSON 資料的文字調節結果。 例如:
{
"blocklistsMatch": [
{
"blocklistName": "string",
"blocklistItemId": "string",
"blocklistItemText": "string"
}
],
"categoriesAnalysis": [
{
"category": "Hate",
"severity": 2
},
{
"category": "SelfHarm",
"severity": 0
},
{
"category": "Sexual",
"severity": 0
},
{
"category": "Violence",
"severity": 0
}
]
}
輸出中的 JSON 欄位定義如下:
名稱 | 描述 | 類型 |
---|---|---|
categoriesAnalysis | API 預測的每個輸出類別。 分類可以為多標籤的。 例如,當文字範例透過文字調節模型執行時,可以同時分類為性內容和暴力內容。 傷害類別 | String |
嚴重性 | 輸入內容的嚴重性越高,這個值就越大。 | 整數 |
參考文件 | 程式庫來源程式碼 | 套件 (NuGet) | 範例
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 已啟用具有工作負載 .NET 桌面開發的 Visual Studio 整合式開發環境 (IDE)。 或者,如果您不打算使用 Visual Studio 整合式開發環境 (IDE),則您需要目前的 .NET Core 版本。
- 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入您資源的唯一名稱,選取您的訂用帳戶,然後選取資源群組、支援的區域 (參閱區域可用性) 以及支援的定價層。 然後選取建立。
- 部署資源需要幾分鐘的時間。 完成後,選取 [移至資源]。 在左側窗格中,於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 端點和其中一個金鑰是用以呼叫 API。
設定應用程式
建立新的 C# 應用程式。
開啟 Visual Studio,然後在 [開始] 下,選取 [建立新專案]。 將範本篩選設定為 C#/所有平台/主控台。 選取 [主控台應用程式] (可在 Windows、Linux 和 macOS 上的 .NET 上執行的命令列應用程式),然後選擇 [下一步]。 將專案名稱更新為 ContentSafetyQuickstart,然後選擇 [下一步]。 選取 .NET 6.0 或更新版本,然後選擇 [建立] 以建立專案。
安裝用戶端 SDK
建立新專案後,以滑鼠右鍵按一下 [方案總管] 中的專案解決方案,然後選取 [管理 NuGet 套件],以安裝用戶端 SDK。 在開啟的封裝管理員中,選取 [瀏覽] 並搜尋 Azure.AI.ContentSafety
。 選取 [安裝]。
建立環境變數
在此範例中,您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。
- 若要設定
CONTENT_SAFETY_KEY
環境變數,請以您其中一個資源索引碼取代YOUR_CONTENT_SAFETY_KEY
。 - 若要設定
CONTENT_SAFETY_ENDPOINT
環境變數,請將YOUR_CONTENT_SAFETY_ENDPOINT
取代為您資源的端點。
重要
如果您使用 API 金鑰,請將其安全地儲存在別處,例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰,且切勿公開張貼金鑰。
如需 AI 服務安全性的詳細資訊,請參閱驗證對 Azure AI 服務的要求 (英文)。
setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'
新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。
分析文字內容
從專案目錄中,開啟先前建立的 Program.cs 檔案。 貼上下列程式碼:
using System;
using Azure.AI.ContentSafety;
namespace Azure.AI.ContentSafety.Dotnet.Sample
{
class ContentSafetySampleAnalyzeText
{
public static void AnalyzeText()
{
// retrieve the endpoint and key from the environment variables created earlier
string endpoint = Environment.GetEnvironmentVariable("CONTENT_SAFETY_ENDPOINT");
string key = Environment.GetEnvironmentVariable("CONTENT_SAFETY_KEY");
ContentSafetyClient client = new ContentSafetyClient(new Uri(endpoint), new AzureKeyCredential(key));
string text = "Your input text";
var request = new AnalyzeTextOptions(text);
Response<AnalyzeTextResult> response;
try
{
response = client.AnalyzeText(request);
}
catch (RequestFailedException ex)
{
Console.WriteLine("Analyze text failed.\nStatus code: {0}, Error code: {1}, Error message: {2}", ex.Status, ex.ErrorCode, ex.Message);
throw;
}
Console.WriteLine("\nAnalyze text succeeded:");
Console.WriteLine("Hate severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == TextCategory.Hate)?.Severity ?? 0);
Console.WriteLine("SelfHarm severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == TextCategory.SelfHarm)?.Severity ?? 0);
Console.WriteLine("Sexual severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == TextCategory.Sexual)?.Severity ?? 0);
Console.WriteLine("Violence severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == TextCategory.Violence)?.Severity ?? 0);
}
static void Main()
{
AnalyzeText();
}
}
}
將 "Your input text"
取代為您想要使用的文字內容。
從 IDE 視窗頂端的 [偵錯] 功能表選取 [開始偵錯] (或按 F5) 來建置並執行應用程式。
參考文件 | 程式庫來源程式碼 | 套件 (PyPI) | 範例 |
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入您資源的唯一名稱,選取您的訂用帳戶,然後選取資源群組、支援的區域 (參閱區域可用性) 以及支援的定價層。 然後選取建立。
- 部署資源需要幾分鐘的時間。 完成後,選取 [移至資源]。 在左側窗格中,於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 端點和其中一個金鑰是用以呼叫 API。
- Python 3.x
- 您安裝的 Python 應包含 pip。 您可以在命令列上執行
pip --version
來檢查是否已安裝 pip。 安裝最新版本的 Python 以取得 pip。
- 您安裝的 Python 應包含 pip。 您可以在命令列上執行
建立環境變數
在此範例中,您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。
- 若要設定
CONTENT_SAFETY_KEY
環境變數,請以您其中一個資源索引碼取代YOUR_CONTENT_SAFETY_KEY
。 - 若要設定
CONTENT_SAFETY_ENDPOINT
環境變數,請將YOUR_CONTENT_SAFETY_ENDPOINT
取代為您資源的端點。
重要
如果您使用 API 金鑰,請將其安全地儲存在別處,例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰,且切勿公開張貼金鑰。
如需 AI 服務安全性的詳細資訊,請參閱驗證對 Azure AI 服務的要求 (英文)。
setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'
新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。
分析文字內容
下一節會逐步解說 Python SDK 的範例要求。
開啟命令提示字元,瀏覽至您的專案資料夾,然後建立名為 quickstart.py 的新檔案。
執行此命令以安裝 Azure AI Content Safety 程式庫:
pip install azure-ai-contentsafety
將下列程式碼複製到 quickstart.py:
import os from azure.ai.contentsafety import ContentSafetyClient from azure.core.credentials import AzureKeyCredential from azure.core.exceptions import HttpResponseError from azure.ai.contentsafety.models import AnalyzeTextOptions, TextCategory def analyze_text(): # analyze text key = os.environ["CONTENT_SAFETY_KEY"] endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"] # Create an Azure AI Content Safety client client = ContentSafetyClient(endpoint, AzureKeyCredential(key)) # Contruct request request = AnalyzeTextOptions(text="Your input text") # Analyze text try: response = client.analyze_text(request) except HttpResponseError as e: print("Analyze text failed.") if e.error: print(f"Error code: {e.error.code}") print(f"Error message: {e.error.message}") raise print(e) raise hate_result = next(item for item in response.categories_analysis if item.category == TextCategory.HATE) self_harm_result = next(item for item in response.categories_analysis if item.category == TextCategory.SELF_HARM) sexual_result = next(item for item in response.categories_analysis if item.category == TextCategory.SEXUAL) violence_result = next(item for item in response.categories_analysis if item.category == TextCategory.VIOLENCE) if hate_result: print(f"Hate severity: {hate_result.severity}") if self_harm_result: print(f"SelfHarm severity: {self_harm_result.severity}") if sexual_result: print(f"Sexual severity: {sexual_result.severity}") if violence_result: print(f"Violence severity: {violence_result.severity}") if __name__ == "__main__": analyze_text()
將
"Your input text"
取代為您想要使用的文字內容。然後使用快速入門檔案上的
python
命令執行應用程式。python quickstart.py
參考文件 | 程式庫原始程式碼 | 成品 (Maven) | 範例
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 最新版的 Java Development Kit (JDK)
- Gradle 建置工具,或其他相依性管理員。
- 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入您資源的唯一名稱,選取您的訂用帳戶,然後選取資源群組、支援的區域 (參閱區域可用性) 以及支援的定價層。 然後選取建立。
- 部署資源需要幾分鐘的時間。 完成後,選取 [移至資源]。 在左側窗格中,於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 端點和其中一個金鑰是用以呼叫 API。
設定應用程式
建立新的 Gradle 專案。
在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中,為您的應用程式建立新的目錄,並瀏覽至該目錄。
mkdir myapp && cd myapp
從您的工作目錄執行 gradle init
命令。 此命令會建立 Gradle 的基本組建檔案,包括 build.gradle.kts,此檔案將在執行階段用來建立及設定您的應用程式。
gradle init --type basic
出現選擇 DSL 的提示時,請選取 [Kotlin]。
在您的工作目錄中執行下列命令,以建立專案來源資料夾:
mkdir -p src/main/java
瀏覽至新的資料夾,並建立名為 ContentSafetyQuickstart.java 的檔案。
安裝用戶端 SDK
本快速入門會使用 Gradle 相依性管理員。 您可以在 Maven 中央存放庫中找到用戶端程式庫和其他相依性管理員的資訊。
找出 build.gradle.kts,並使用您慣用的 IDE 或文字編輯器加以開啟。 然後,在其中複製下列組建組態。 此組態會將專案定義為進入點為 ContentSafetyQuickstart 類別的 Java 應用程式。 它會匯入 Azure AI 視覺程式庫。
plugins {
java
application
}
application {
mainClass.set("ContentSafetyQuickstart")
}
repositories {
mavenCentral()
}
dependencies {
implementation(group = "com.azure", name = "azure-ai-contentsafety", version = "1.0.0")
}
建立環境變數
在此範例中,您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。
- 若要設定
CONTENT_SAFETY_KEY
環境變數,請以您其中一個資源索引碼取代YOUR_CONTENT_SAFETY_KEY
。 - 若要設定
CONTENT_SAFETY_ENDPOINT
環境變數,請將YOUR_CONTENT_SAFETY_ENDPOINT
取代為您資源的端點。
重要
如果您使用 API 金鑰,請將其安全地儲存在別處,例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰,且切勿公開張貼金鑰。
如需 AI 服務安全性的詳細資訊,請參閱驗證對 Azure AI 服務的要求 (英文)。
setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'
新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。
分析文字內容
在慣用的編輯器或 IDE 中開啟 ContentSafetyQuickstart.java,並貼上下列程式碼。 將 <your text sample>
取代為您想要使用的文字內容。
import com.azure.ai.contentsafety.ContentSafetyClient;
import com.azure.ai.contentsafety.ContentSafetyClientBuilder;
import com.azure.ai.contentsafety.models.AnalyzeTextOptions;
import com.azure.ai.contentsafety.models.AnalyzeTextResult;
import com.azure.ai.contentsafety.models.TextCategoriesAnalysis;
import com.azure.core.credential.KeyCredential;
import com.azure.core.util.Configuration;
public class ContentSafetyQuickstart {
public static void main(String[] args) {
// get endpoint and key from environment variables
String endpoint = System.getenv("CONTENT_SAFETY_ENDPOINT");
String key = System.getenv("CONTENT_SAFETY_KEY");
ContentSafetyClient contentSafetyClient = new ContentSafetyClientBuilder()
.credential(new KeyCredential(key))
.endpoint(endpoint).buildClient();
AnalyzeTextResult response = contentSafetyClient.analyzeText(new AnalyzeTextOptions("<your text sample>"));
for (TextCategoriesAnalysis result : response.getCategoriesAnalysis()) {
System.out.println(result.getCategory() + " severity: " + result.getSeverity());
}
}
}
瀏覽回專案根資料夾,並使用下列項目建置應用程式:
gradle build
然後,使用 gradle run
命令加以執行:
gradle run
輸出
Hate severity: 0
SelfHarm severity: 0
Sexual severity: 0
Violence severity: 0
參考文件 | 程式庫來源程式碼 | 套件 (npm) | 範例 |
必要條件
- Azure 訂用帳戶 - 建立免費帳戶
- 最新版的 Node.js
- 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入您資源的唯一名稱,選取您的訂用帳戶,然後選取資源群組、支援的區域 (參閱區域可用性) 以及支援的定價層。 然後選取建立。
- 部署資源需要幾分鐘的時間。 完成後,選取 [移至資源]。 在左側窗格中,於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 端點和其中一個金鑰是用以呼叫 API。
設定應用程式
建立新的 Node.js 應用程式。 在主控台視窗 (例如 cmd、PowerShell 或 Bash) 中,為您的應用程式建立新的目錄,並瀏覽至該目錄。
mkdir myapp && cd myapp
執行命令 npm init
,以使用 package.json
檔案建立節點應用程式。
npm init
安裝用戶端 SDK
安裝 @azure-rest/ai-content-safety
npm 套件:
npm install @azure-rest/ai-content-safety
此外,請安裝 dotenv
模組以使用環境變數:
npm install dotenv
您應用程式的 package.json
檔案會隨著相依性而更新。
建立環境變數
在此範例中,您會在執行應用程式的本機電腦上將認證寫入環境變數。
若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。
- 若要設定
CONTENT_SAFETY_KEY
環境變數,請以您其中一個資源索引碼取代YOUR_CONTENT_SAFETY_KEY
。 - 若要設定
CONTENT_SAFETY_ENDPOINT
環境變數,請將YOUR_CONTENT_SAFETY_ENDPOINT
取代為您資源的端點。
重要
如果您使用 API 金鑰,請將其安全地儲存在別處,例如 Azure Key Vault。 請勿在程式碼中直接包含 API 金鑰,且切勿公開張貼金鑰。
如需 AI 服務安全性的詳細資訊,請參閱驗證對 Azure AI 服務的要求 (英文)。
setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'
新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。
分析文字內容
在目錄建立新的檔案 index.js。 在您慣用的編輯器或 IDE 中開啟該檔案,並貼上下列程式碼。 將 <your text sample>
取代為您想要使用的文字內容。
const ContentSafetyClient = require("@azure-rest/ai-content-safety").default,
{ isUnexpected } = require("@azure-rest/ai-content-safety");
const { AzureKeyCredential } = require("@azure/core-auth");
// Load the .env file if it exists
require("dotenv").config();
async function main() {
// get endpoint and key from environment variables
const endpoint = process.env["CONTENT_SAFETY_ENDPOINT"];
const key = process.env["CONTENT_SAFETY_KEY"];
const credential = new AzureKeyCredential(key);
const client = ContentSafetyClient(endpoint, credential);
// replace with your own sample text string
const text = "<your sample text>";
const analyzeTextOption = { text: text };
const analyzeTextParameters = { body: analyzeTextOption };
const result = await client.path("/text:analyze").post(analyzeTextParameters);
if (isUnexpected(result)) {
throw result;
}
for (let i = 0; i < result.body.categoriesAnalysis.length; i++) {
const textCategoriesAnalysisOutput = result.body.categoriesAnalysis[i];
console.log(
textCategoriesAnalysisOutput.category,
" severity: ",
textCategoriesAnalysisOutput.severity
);
}
}
main().catch((err) => {
console.error("The sample encountered an error:", err);
});
使用快速入門檔案上使用 node
命令執行應用程式。
node index.js
輸出
Hate severity: 0
SelfHarm severity: 0
Sexual severity: 0
Violence severity: 0
清除資源
如果您想要清除和移除 Azure AI 服務訂用帳戶,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。
相關內容
- 傷害類別
- 使用 Content Safety Studio 設定每個類別和測試資料集的篩選,匯出程式碼並部署。