Azure.AI.ContentSafety 1.0.0

Azure AI Content Safety 客户端库 for .NET

Azure AI Content Safety 可在应用程序和服务中检测有害的用户生成内容和 AI 生成内容。内容安全包括多个 API，可帮助您检测有害

• 文本分析 API：扫描文本以识别色情、暴力、仇恨和自残，具有多个严重级别。
• 图像分析 API：扫描图像以识别色情、暴力、仇恨和自残，具有多个严重级别。
• 文本块列表管理 API：默认的 AI 分类器足够满足大多数内容安全需求；但是，您可能需要针对特定用例的术语进行筛选。您可以使用 Text API 使用术语块列表。

源代码 | 软件包 (NuGet) | API 参考文档 | 产品文档

入门指南

安装软件包

使用 NuGet 安装 .NET 客户端库

dotnet add package Azure.AI.ContentSafety

先决条件

• 您需要一个 Azure 账户 来使用此软件包。
• Azure AI 内容安全（如果不存在可用的资源），您可以通过 创建一个新的资源。

认证客户端

获取端点

您可以通过使用 Azure 门户 或 Azure CLI 来找到 Azure AI 内容安全服务资源的端点。

# Get the endpoint for the Azure AI Content Safety service resource
az cognitiveservices account show --name "resource-name" --resource-group "resource-group-name" --query "properties.endpoint"

使用 API 密钥创建 ContentSafetyClient/BlocklistClient

• 步骤 1：获取 API 密钥

  API 密钥可以在 Azure 门户 中找到，或者通过运行以下 Azure CLI 命令。

  az cognitiveservices account keys list --name "<resource-name>" --resource-group "<resource-group-name>"
  

• 步骤 2：使用 AzureKeyCredential 创建 ContentSafetyClient

  将 API 密钥作为字符串传递给 AzureKeyCredential 的实例。

  string endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
  string key = "<api_key>";
  
  ContentSafetyClient contentSafetyClient = new ContentSafetyClient(new Uri(endpoint), new AzureKeyCredential(key));
  BlocklistClient blocklistClient = new BlocklistClient(new Uri(endpoint), new AzureKeyCredential(key));
  

使用 Microsoft Entra ID 凭证创建 ContentSafetyClient/BlocklistClient

• 步骤 1：为您的资源启用 Microsoft Entra ID。请参阅此文档 使用 Microsoft Entra ID 进行身份验证 了解如何为您的资源启用 Microsoft Entra ID 的步骤。

  主要步骤如下：

  • 使用自定义子域创建资源。
  • 创建服务主体并为其分配 Cognitive Services User 角色。

• 步骤 2：将 Microsoft Entra 应用程序的客户端 ID、租户 ID 和客户端机密的值设置为环境变量：AZURE_CLIENT_ID、TENANT_ID、AZURE_CLIENT_SECRET。DefaultAzureCredential 将使用这些环境变量中的值。并且您需要安装 Azure.Identity 软件包才能使用 DefaultAzureCredential。

    string endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
  
    ContentSafetyClient contentSafetyClient = new ContentSafetyClient(new Uri(endpoint), new DefaultAzureCredential());
    BlocklistClient blocklistClient = new BlocklistClient(new Uri(endpoint), new DefaultAzureCredential());
  

关键概念

可用功能

此服务提供了多种类型分析。下表描述了当前可用的 API。

伤害类别

内容安全识别四种不同类型的令人反感的内容。

分类可以是多标签的。例如，当文本样本通过文本审查模型时，它可能被分类为包含性内容和暴力。

严重级别

服务应用的每个伤害类别都附带严重级别评级。严重级别旨在表示显示已标记内容的后果的严重程度。

文本：当前版本的文本模型支持从0到7的完整严重级别 scales。分类器会检测该范围内的所有严重性。如果用户指定，它可以返回0、2、4和6的裁剪严重级别尺度；每个相邻的两个级别映射到单个级别。您可以通过文本内容严重级别定义了解详细信息。

• [0,1] → 0
• [2,3] → 2
• [4,5] → 4
• [6,7] → 6

图像：当前版本的图像模型支持完整的0-7严重级别scales的裁剪版本。分类器仅返回0、2、4和6的严重性；每个相邻的两个级别映射到单个级别。您可以通过图像内容严重级别定义了解详细信息。

• [0,1] → 0
• [2,3] → 2
• [4,5] → 4
• [6,7] → 6

文本黑名单管理

支持以下操作来管理您的文本黑名单

• 创建或修改黑名单
• 列出所有黑名单
• 按黑名单名称获取黑名单
• 将黑名单项添加到黑名单中
• 从黑名单中删除黑名单项
• 按黑名单名称列出黑名单中的所有黑名单项
• 按黑名单ID和黑名单名称获取黑名单中的黑名单项
• 删除黑名单及其所有黑名单项

您可以在分析文本时设置要使用的黑名单，然后可以从返回的响应中获取黑名单匹配结果。

线程安全

我们保证所有客户端实例方法都是线程安全的且相互独立（指南）。这确保了重用客户端实例的建议始终是安全的，即使在跨线程的情况下。

其他概念

客户端选项 | 访问响应 | 长运行操作 | 处理失败 | 诊断 | 模拟 | 客户生命周期

示例

以下部分提供了多个代码片段，涵盖了一些常见的内容安全服务任务，包括

• 分析文本
• 分析图像
• 管理文本黑名单

请参阅以下示例数据，其中使用了这里的数据。更多示例，请参阅样例。

分析文本

无黑名单分析文本

string text = "You are an idiot";

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("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);

有黑名单分析文本

// After you edit your blocklist, it usually takes effect in 5 minutes, please wait some time before analyzing with blocklist after editing.
var request = new AnalyzeTextOptions("I h*te you and I want to k*ll you");
request.BlocklistNames.Add(blocklistName);
request.HaltOnBlocklistHit = true;

Response<AnalyzeTextResult> response;
try
{
    response = contentSafetyClient.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;
}

if (response.Value.BlocklistsMatch != null)
{
    Console.WriteLine("\nBlocklist match result:");
    foreach (var matchResult in response.Value.BlocklistsMatch)
    {
        Console.WriteLine("BlocklistName: {0}, BlocklistItemId: {1}, BlocklistText: {2}, ", matchResult.BlocklistName, matchResult.BlocklistItemId, matchResult.BlocklistItemText);
    }
}

分析图像

string datapath = Path.Combine(Path.GetDirectoryName(Assembly.GetExecutingAssembly().Location), "Samples", "sample_data", "image.jpg");
ContentSafetyImageData image = new ContentSafetyImageData(BinaryData.FromBytes(File.ReadAllBytes(datapath)));

var request = new AnalyzeImageOptions(image);

Response<AnalyzeImageResult> response;
try
{
    response = client.AnalyzeImage(request);
}
catch (RequestFailedException ex)
{
    Console.WriteLine("Analyze image failed.\nStatus code: {0}, Error code: {1}, Error message: {2}", ex.Status, ex.ErrorCode, ex.Message);
    throw;
}

Console.WriteLine("Hate severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == ImageCategory.Hate)?.Severity ?? 0);
Console.WriteLine("SelfHarm severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == ImageCategory.SelfHarm)?.Severity ?? 0);
Console.WriteLine("Sexual severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == ImageCategory.Sexual)?.Severity ?? 0);
Console.WriteLine("Violence severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == ImageCategory.Violence)?.Severity ?? 0);

管理文本黑名单

创建或更新文本黑名单

var blocklistName = "TestBlocklist";
var blocklistDescription = "Test blocklist management";

var data = new
{
    description = blocklistDescription,
};

var createResponse = blocklistClient.CreateOrUpdateTextBlocklist(blocklistName, RequestContent.Create(data));
if (createResponse.Status == 201)
{
    Console.WriteLine("\nBlocklist {0} created.", blocklistName);
}
else if (createResponse.Status == 200)
{
    Console.WriteLine("\nBlocklist {0} updated.", blocklistName);
}

添加黑名单项

string blockItemText1 = "k*ll";
string blockItemText2 = "h*te";

var blockItems = new TextBlocklistItem[] { new TextBlocklistItem(blockItemText1), new TextBlocklistItem(blockItemText2) };
var addedBlockItems = blocklistClient.AddOrUpdateBlocklistItems(blocklistName, new AddOrUpdateTextBlocklistItemsOptions(blockItems));

if (addedBlockItems != null && addedBlockItems.Value != null)
{
    Console.WriteLine("\nBlockItems added:");
    foreach (var addedBlockItem in addedBlockItems.Value.BlocklistItems)
    {
        Console.WriteLine("BlockItemId: {0}, Text: {1}, Description: {2}", addedBlockItem.BlocklistItemId, addedBlockItem.Text, addedBlockItem.Description);
    }
}

列出文本黑名单

var blocklists = blocklistClient.GetTextBlocklists();
Console.WriteLine("\nList blocklists:");
foreach (var blocklist in blocklists)
{
    Console.WriteLine("BlocklistName: {0}, Description: {1}", blocklist.Name, blocklist.Description);
}

获取文本黑名单

var getBlocklist = blocklistClient.GetTextBlocklist(blocklistName);
if (getBlocklist != null && getBlocklist.Value != null)
{
    Console.WriteLine("\nGet blocklist:");
    Console.WriteLine("BlocklistName: {0}, Description: {1}", getBlocklist.Value.Name, getBlocklist.Value.Description);
}

列出黑名单项

var allBlockitems = blocklistClient.GetTextBlocklistItems(blocklistName);
Console.WriteLine("\nList BlockItems:");
foreach (var blocklistItem in allBlockitems)
{
    Console.WriteLine("BlocklistItemId: {0}, Text: {1}, Description: {2}", blocklistItem.BlocklistItemId, blocklistItem.Text, blocklistItem.Description);
}

获取黑名单项

var getBlockItemId = addedBlockItems.Value.BlocklistItems[0].BlocklistItemId;
var getBlockItem = blocklistClient.GetTextBlocklistItem(blocklistName, getBlockItemId);
Console.WriteLine("\nGet BlockItem:");
Console.WriteLine("BlockItemId: {0}, Text: {1}, Description: {2}", getBlockItem.Value.BlocklistItemId, getBlockItem.Value.Text, getBlockItem.Value.Description);

删除黑名单项

var removeBlockItemId = addedBlockItems.Value.BlocklistItems[0].BlocklistItemId;
var removeBlockItemIds = new List<string> { removeBlockItemId };
var removeResult = blocklistClient.RemoveBlocklistItems(blocklistName, new RemoveTextBlocklistItemsOptions(removeBlockItemIds));

if (removeResult != null && removeResult.Status == 204)
{
    Console.WriteLine("\nBlockItem removed: {0}.", removeBlockItemId);
}

删除文本黑名单

var deleteResult = blocklistClient.DeleteTextBlocklist(blocklistName);
if (deleteResult != null && deleteResult.Status == 204)
{
    Console.WriteLine("\nDeleted blocklist.");
}

故障排除

常规

当你使用.NET SDK通过Azure AI内容安全客户端库进行交互时，服务返回的错误将导致返回与REST API请求相同的HTTP状态代码以及由我们的服务定义的错误代码的RequestFailedException。您可以像下面这样解析RequestFailedException

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;
}

示例控制台输出

Analyze text failed.
Status code: 400, Error code: InvalidRequestBody, Error message: The length of given text 1158 exceeds the limit 1000. | Request Id: a04c7c32-ef27-4c23-8b18-07545b24765b, Timestamp: 2023-06-01T16:43:52Z.

错误代码定义如下

设置控制台日志记录

查看日志的最简单方法是启用控制台日志记录。要创建输出到控制台的消息的Azure SDK日志监听器，请使用AzureEventSourceListener.CreateConsoleLogger方法。

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

有关其他日志记录机制的更多信息，请参阅诊断样例。

下一步

附加文档

有关Azure内容安全的更多详细文档，请参阅docs.microsoft.com上的Azure AI内容安全。

贡献

此项目欢迎贡献和建议。大多数贡献需要您同意贡献者许可协议（CLA），声明您有权利并且实际上确实有权授予我们使用您贡献的权利。有关详细信息，请访问cla.microsoft.com。

当您提交拉取请求时，CLA机器人将自动确定您是否需要提供CLA，并以适当的格式（例如标签、评论）装饰PR。只需遵循机器人提供的说明即可。您只需在我们的CLA中使用所有回购所有repo进行一次此操作。

本项目遵循了微软开源行为准则。有关更多信息，请参阅行为准则FAQ，或通过[email protected]与我们联系，提出任何额外的问题或意见。