你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

快速入门：分析文本内容

项目
06/03/2024

开始使用 Content Safety Studio、REST API 或客户端 SDK 来执行基本的文本审查。 Azure AI 内容安全服务为你提供用于标记不良内容的 AI 算法。请按照以下步骤试用该环境。

注意

示例数据和代码可能包含冒犯性内容。建议用户自行决定。

先决条件

Azure 订阅 - 免费创建订阅
拥有 Azure 订阅后，请在 Azure 门户中创建 Content Safety 资源，以获取密钥和终结点。输入资源的唯一名称，选择订阅，并选择资源组、支持的区域（请参阅上市区域）和支持的定价层。然后选择“创建”。
- 部署资源需要几分钟时间。完成后，选择“转到资源”。在左侧窗格中的“资源管理”下，选择“订阅密钥和终结点”。终结点和任一密钥都用于调用 API。
已安装 cURL

分析文本内容

下一部分介绍使用 cURL 进行请求的示例。将以下命令粘贴到文本编辑器，并进行以下更改。

将 <endpoint> 替换为与资源关联的终结点 URL。
将 <your_subscription_key> 替换为资源附带的密钥之一。
（可选）将正文中的 "text" 字段替换为要分析的你自己的文本。

提示

文本大小和粒度

文本提交的默认最大长度为 10K 个字符。

curl --location --request POST '<endpoint>/contentsafety/text:analyze?api-version=2023-10-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=2023-10-01。示例： `<endpoint>/contentsafety/text:analyze?api-version=2023-10-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 命令。

解释 API 响应

应会在控制台输出中看到显示为 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

参考文档 | 库源代码 | 包 (NuGet) | 示例

先决条件

Azure 订阅 - 免费创建订阅
启用了“.NET 桌面开发”工作负载的 Visual Studio IDE。或者，如果你不打算使用 Visual Studio IDE，则需要当前版本的 .NET Core。
拥有 Azure 订阅后，请在 Azure 门户中创建 Content Safety 资源，以获取密钥和终结点。输入资源的唯一名称，选择订阅，并选择资源组、支持的区域（请参阅上市区域）和支持的定价层。然后选择“创建”。
- 部署资源需要几分钟时间。完成后，选择“转到资源”。在左侧窗格中的“资源管理”下，选择“订阅密钥和终结点”。终结点和任一密钥都用于调用 API。

设置应用程序

创建一个新的 C# 应用程序。

Visual Studio IDE
CLI

打开 Visual Studio，在“开始”下选择“创建新项目”。将模板筛选器设置为 C#/所有平台/控制台。选择“控制台应用”（可在 Windows、Linux 和 macOS 版 .NET 上运行的命令行应用程序），然后选择“下一步”。将项目名称更新为 ContentSafetyQuickstart，然后选择“下一步”。选择“.NET 6.0”或更高版本，然后选择“创建”以创建项目。

安装客户端 SDK

创建新项目后，右键单击“解决方案资源管理器”中的项目解决方案，然后选择“管理 NuGet 包”，以安装客户端 SDK。在打开的包管理器中，选择“浏览”，然后搜索 Azure.AI.ContentSafety。选择“安装” 。

在控制台窗口（例如 cmd、PowerShell 或 Bash）中，使用 dotnet new 命令创建名为 content-safety-quickstart 的新控制台应用。此命令将创建包含单个源文件的简单“Hello World”C# 项目：Program.cs。

dotnet new console -n content-safety-quickstart

将目录更改为新创建的应用文件夹。可使用以下代码生成应用程序：

dotnet build

生成输出不应包含警告或错误。

...
Build succeeded.
  0 Warning(s)
  0 Error(s)
...

安装客户端 SDK

在应用程序目录中，使用以下命令安装适用于 .NET 的计算机视觉客户端 SDK：

dotnet add package Azure.AI.ContentSafety

创建环境变量

在此示例中，你将凭据写入运行应用程序的本地计算机上的环境变量。

提示

请不要直接在代码中包含密钥，并且绝不公开发布密钥。有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要为密钥和终结点设置环境变量，请打开控制台窗口，并按照操作系统和开发环境的说明进行操作。

若要设置 CONTENT_SAFETY_KEY 环境变量，请将 YOUR_CONTENT_SAFETY_KEY 替换为资源的其中一个密钥。
若要设置 CONTENT_SAFETY_ENDPOINT 环境变量，请将 YOUR_CONTENT_SAFETY_ENDPOINT 替换为资源的终结点。

Windows
Linux

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'

setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

export CONTENT_SAFETY_KEY='YOUR_CONTENT_SAFETY_KEY'

export CONTENT_SAFETY_ENDPOINT='YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

分析文本内容

从项目目录中，打开以前创建的 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" 替换为要使用的文本内容。

提示

文本大小和粒度

文本提交的默认最大长度为 10K 个字符。

Visual Studio IDE
CLI

从 IDE 窗口顶部的“调试”菜单中选择“开始调试”（或按 F5），以生成并运行应用程序。

使用以下命令从应用程序目录生成并运行应用程序：

dotnet build
dotnet run

参考文档 | 库源代码 | 包 (PyPI) | 示例 |

先决条件

Azure 订阅 - 免费创建订阅
拥有 Azure 订阅后，请在 Azure 门户中创建 Content Safety 资源，以获取密钥和终结点。输入资源的唯一名称，选择订阅，并选择资源组、支持的区域（请参阅上市区域）和支持的定价层。然后选择“创建”。
- 部署资源需要几分钟时间。完成后，选择“转到资源”。在左侧窗格中的“资源管理”下，选择“订阅密钥和终结点”。终结点和任一密钥都用于调用 API。
Python 3.x
- 你的 Python 安装应包含 pip。可以通过在命令行上运行 pip --version 来检查是否安装了 pip。通过安装最新版本的 Python 获取 pip。

创建环境变量

在此示例中，你将凭据写入运行应用程序的本地计算机上的环境变量。

提示

请不要直接在代码中包含密钥，并且绝不公开发布密钥。有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要为密钥和终结点设置环境变量，请打开控制台窗口，并按照操作系统和开发环境的说明进行操作。

若要设置 CONTENT_SAFETY_KEY 环境变量，请将 YOUR_CONTENT_SAFETY_KEY 替换为资源的其中一个密钥。
若要设置 CONTENT_SAFETY_ENDPOINT 环境变量，请将 YOUR_CONTENT_SAFETY_ENDPOINT 替换为资源的终结点。

Windows
Linux

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'

setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

export CONTENT_SAFETY_KEY='YOUR_CONTENT_SAFETY_KEY'

export CONTENT_SAFETY_ENDPOINT='YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

分析文本内容

下一部分介绍使用 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" 替换为要使用的文本内容。

提示

文本大小和粒度

文本提交的默认最大长度为 10K 个字符。
然后，使用快速入门文件中的 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")
}

创建环境变量

在此示例中，你将凭据写入运行应用程序的本地计算机上的环境变量。

提示

请不要直接在代码中包含密钥，并且绝不公开发布密钥。有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要为密钥和终结点设置环境变量，请打开控制台窗口，并按照操作系统和开发环境的说明进行操作。

若要设置 CONTENT_SAFETY_KEY 环境变量，请将 YOUR_CONTENT_SAFETY_KEY 替换为资源的其中一个密钥。
若要设置 CONTENT_SAFETY_ENDPOINT 环境变量，请将 YOUR_CONTENT_SAFETY_ENDPOINT 替换为资源的终结点。

Windows
Linux

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'

setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

export CONTENT_SAFETY_KEY='YOUR_CONTENT_SAFETY_KEY'

export CONTENT_SAFETY_ENDPOINT='YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

分析文本内容

在首选编辑器或 IDE 中打开 ContentSafetyQuickstart.java，并粘贴以下代码。将 <your text sample> 替换为要使用的文本内容。

提示

文本大小和粒度

文本提交的默认最大长度为 10K 个字符。

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 文件创建一个 node 应用程序。

npm init

安装客户端 SDK

安装 @azure-rest/ai-content-safety npm 包：

npm install @azure-rest/ai-content-safety

另请安装 dotenv 模块以使用环境变量：

npm install dotenv

应用的 package.json 文件将使用依赖项进行更新。

创建环境变量

在此示例中，你将凭据写入运行应用程序的本地计算机上的环境变量。

提示

请不要直接在代码中包含密钥，并且绝不公开发布密钥。有关 Azure Key Vault 等更多身份验证选项，请参阅 Azure AI 服务安全性一文。

若要为密钥和终结点设置环境变量，请打开控制台窗口，并按照操作系统和开发环境的说明进行操作。

若要设置 CONTENT_SAFETY_KEY 环境变量，请将 YOUR_CONTENT_SAFETY_KEY 替换为资源的其中一个密钥。
若要设置 CONTENT_SAFETY_ENDPOINT 环境变量，请将 YOUR_CONTENT_SAFETY_ENDPOINT 替换为资源的终结点。

Windows
Linux

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'

setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后，可能需要重启任何正在运行的、将读取环境变量的程序（包括控制台窗口）。

export CONTENT_SAFETY_KEY='YOUR_CONTENT_SAFETY_KEY'

export CONTENT_SAFETY_ENDPOINT='YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后，请从控制台窗口运行 source ~/.bashrc，使更改生效。

分析文本内容

在目录中创建新文件 index.js。在偏好的编辑器或 IDE 中打开它，并粘贴以下代码。将 <your text sample> 替换为要使用的文本内容。

提示

文本大小和粒度

文本提交的默认最大长度为 10K 个字符。

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 为每个类别配置筛选器并测试数据集，导出代码并部署。

Content Safety Studio 快速入门