你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn。
快速入门:分析文本内容
开始使用 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 |
字符串 |
请求正文中的参数在此表中定义:
名称 | 必需 | 说明 | 类型 |
---|---|---|---|
text | 必需 | 这是要检查的原始文本。 可以包含其他非 ascii 字符。 | 字符串 |
categories | 可选 | 假定这是类别名称的数组。 有关可用categories名称的列表,请参阅危害类别指南。 如果未指定categories,则使用所有四个categories。 我们使用多个类别在单个请求中获取分数。 | 字符串 |
blocklistNames | 可选 | 文本阻止列表名称。 仅支持以下字符:0-9 A-Z a-z - . _ ~ 。 可以在此处附加多个列表名称。 |
数组 |
haltOnBlocklistHit | 可选 | 如果设置为 true ,则不会在命中阻止列表的情况下进一步分析有害内容。 如果设置为 false ,则执行对有害内容的所有分析,无论是否命中阻止列表。 |
布尔 |
outputType | 可选 | "FourSeverityLevels" 或 "EightSeverityLevels" 。 输出严重性分为四个或八个级别,该值可以是 0,2,4,6 或 0,1,2,3,4,5,6,7 。 |
字符串 |
请参阅以下示例请求正文:
{
"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 预测的每个输出类。 分类可以是多标记的。 例如,当文本样本通过文本审查模型运行时,它可以被分类为性内容和暴力内容。 有害categories | 字符串 |
严重性 | 输入内容的严重性越高,此值越大。 | Integer |
先决条件
- 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 密钥,并且切勿公开发布该密钥。
有关 Azure 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),以生成并运行应用程序。
先决条件
- 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 密钥,并且切勿公开发布该密钥。
有关 Azure 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 开发工具包 (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 或文本编辑器将其打开。 然后在该文件中复制以下生成配置。 此配置将项目定义一个 Java 应用程序,其入口点为 ContentSafetyQuickstart 类。 它会导入 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 密钥,并且切勿公开发布该密钥。
有关 Azure 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
先决条件
- Azure 订阅 - 免费创建订阅
- 最新版本的 Node.js
- 拥有 Azure 订阅后,请在 Azure 门户中创建 Content Safety 资源 ,以获取密钥和终结点。 输入资源的唯一名称,选择订阅,并选择资源组、支持的区域(请参阅上市区域)和支持的定价层。 然后选择“创建”。
- 部署资源需要几分钟时间。 完成后,选择“转到资源”。 在左侧窗格中的“资源管理”下,选择“订阅密钥和终结点”。 终结点和任一密钥都用于调用 API。
设置应用程序
创建新的 Node.js 应用程序。 在控制台窗口(例如 cmd、PowerShell 或 Bash)中,为应用创建一个新目录并导航到该目录。
mkdir myapp && cd myapp
运行 npm init
命令以使用 package.json
文件创建一个 node 应用程序。
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 密钥,并且切勿公开发布该密钥。
有关 Azure 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 服务订阅,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。
相关内容
- 有害categories
- 使用 Content Safety Studio 为每个类别配置筛选器并测试数据集,导出代码并部署。