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

适用于 JavaScript 的 Azure AI 内容安全 REST 客户端库 - 版本 1.0.1

Azure AI 内容安全 检测应用程序和服务中有害的用户生成和 AI 生成的内容。 内容安全包括文本和图像 API，可用于检测有害材料。

• 文本分析 API：扫描文本以获取性内容、暴力、仇恨和多严重性级别的自我伤害。
• 图像分析 API：扫描图像中具有多严重性级别的性内容、暴力、仇恨和自我伤害。
• 文本阻止列表管理 API：默认的 AI 分类器足以满足大多数内容安全需求;但是，可能需要筛选特定于用例的术语。 可以创建与文本 API 一起使用的术语阻止列表。

请严重依赖 REST 客户端文档， 使用此库

关键链接：

• 源代码
• 包 （NPM）
• API 参考文档
• 示例

开始

当前支持的环境

• Node.js 的 LTS 版本

先决条件

• 需要 Azure 订阅 才能使用此包。
• Azure AI 内容安全 资源（如果没有现有资源）可以 创建新的资源。

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

使用 npm安装适用于 JavaScript 的 Azure AI 内容安全 REST 客户端 REST 客户端库：

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

创建和验证 ContentSafetyClient

获取终结点

可以使用 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"

使用 AzureKeyCredential 创建 ContentSafetyClient

• 步骤 1：获取 API 密钥

API 密钥可以在 Azure 门户 中找到，也可以运行以下 Azure CLI 命令：

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

• 步骤 2：使用 AzureKeyCredential 创建 ContentSafetyClient

若要将 API 密钥用作 credential 参数，请将密钥作为字符串传递到 AzureKeyCredential实例中。

import { AzureKeyCredential } from "@azure/core-auth";
import ContentSafetyClient from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const key = "<api_key>";
const credential = new AzureKeyCredential(key);
const client = ContentSafetyClient(endpoint, credential);

使用 Microsoft Entra ID（前 Azure Active Directory（AAD）令牌凭据创建 ContentSafetyClient

• 步骤 1：为资源启用Microsoft Entra ID，请参阅此认知服务身份验证文档 使用 Microsoft Entra ID进行身份验证。用于为资源启用 AAD 的步骤。

  主要步骤包括：

  • 使用自定义子域创建资源。
  • 创建服务主体并向其分配认知服务用户角色。

• 步骤 2：将 AAD 应用程序的客户端 ID、租户 ID 和客户端机密的值设置为环境变量：AZURE_CLIENT_ID、AZURE_TENANT_ID、AZURE_CLIENT_SECRET

若要使用 AAD 进行身份验证，必须先 npm 安装 @azure/identity。 设置后，可以从 @azure/identity 中选择要使用的 凭据 类型。 例如，可以使用 DefaultAzureCredential 对客户端进行身份验证。

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

关键概念

可用功能

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

特征	描述
文本分析 API	扫描文本以查找多严重性级别的性内容、暴力、仇恨和自我伤害。
图像分析 API	扫描图像中具有多严重性级别的性内容、暴力、仇恨和自我伤害。
文本阻止列表管理 API	默认的 AI 分类器足以满足大多数内容安全需求。 但是，可能需要筛选特定于用例的术语。 可以创建与文本 API 一起使用的术语阻止列表。

伤害类别

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

类别	描述
恨	仇恨是指任何攻击或使用贬义或歧视性语言的内容，以引用基于该组的某些区分属性的人或标识组。 这包括包括但不限于种族、种族、国籍、性别认同和表达、性取向、宗教、移民身份、能力地位、个人外貌和身体规模。
性的	性描述与解剖器官和生殖器、浪漫关系、色情或深情术语所描绘的行为、怀孕、身体性行为等内容，包括那些被描绘成攻击或强迫性暴力行为，以对抗自己意志的行为、卖淫、色情和虐待行为。
暴力	暴力描述与旨在伤害、伤害、损害或杀害某人或某物的物理行为相关的内容。 它还包括武器、枪支和相关实体，如制造商、协会、立法和类似实体。
自我伤害	自我伤害描述与旨在故意伤害、伤害或伤害他人身体或自杀的身体行为相关的内容。

分类可以多标记。 例如，当文本示例通过文本审查模型时，它可以归类为性内容和暴力。

严重性级别

服务适用的每个危害类别也附带严重性级别分级。 严重性级别旨在指示显示已标记内容的后果的严重性。

文本：文本模型的当前版本支持 完全 0-7 严重性缩放。 默认情况下，响应将输出 4 个值：0、2、4 和 6。 每个相邻级别映射到一个级别。 用户可以在请求中使用“outputType”，并将其设置为“EightSeverityLevels”来获取输出中的 8 个值：0,1,2,3,4,5,6,7。 有关详细信息，可以参考 文本内容严重性级别定义。

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

映像：映像模型的当前版本支持完整 0-7 严重性缩放 剪裁版本。 分类器仅返回严重性 0、2、4 和 6;每个两个相邻级别映射到单个级别。 有关详细信息，可以参考 图像内容严重性级别定义。

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

文本阻止列表管理

支持以下作来管理文本阻止列表：

• 创建或修改阻止列表
• 列出所有阻止列表
• 按 blocklistName 获取阻止列表
• 将 blockItems 添加到阻止列表
• 从阻止列表中删除 blockItems
• 按 blocklistName 列出阻止列表中的所有 blockItems
• 通过 blockItemId 和 blocklistName 在阻止列表中获取 blockItem
• 删除阻止列表及其所有 blockItems

可以设置分析文本时要使用的阻止列表，然后可以从返回的响应中获取阻止列表匹配结果。

例子

以下部分提供了几个代码片段，这些代码片段涵盖了 TypeScript 和 JavaScript中一些最常见的内容安全服务任务，包括：

• 分析文本
• 分析图像
• 管理文本阻止列表

分析文本

在没有阻止列表的情况下分析文本

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const text = "This is a 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,
  );
}

使用阻止列表分析文本

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, {
  CreateOrUpdateTextBlocklistParameters,
  isUnexpected,
} from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

async function createOrUpdateTextBlocklist() {
  const blocklistName = "TestBlocklist";
  const blocklistDescription = "Test blocklist management.";
  const createOrUpdateTextBlocklistParameters: CreateOrUpdateTextBlocklistParameters = {
    contentType: "application/merge-patch+json",
    body: {
      description: blocklistDescription,
    },
  };

  const result = await client
    .path("/text/blocklists/{blocklistName}", blocklistName)
    .patch(createOrUpdateTextBlocklistParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log(
    "Blocklist created or updated: Name",
    result.body.blocklistName,
    ", Description: ",
    result.body.description,
  );
}

async function addBlockItems() {
  const blocklistName = "TestBlocklist";
  const blockItemText1 = "sample";
  const blockItemText2 = "text";
  const addOrUpdateBlocklistItemsParameters = {
    body: {
      blocklistItems: [
        {
          description: "Test block item 1",
          text: blockItemText1,
        },
        {
          description: "Test block item 2",
          text: blockItemText2,
        },
      ],
    },
  };

  const result = await client
    .path("/text/blocklists/{blocklistName}:addOrUpdateBlocklistItems", blocklistName)
    .post(addOrUpdateBlocklistItemsParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log("Block items added: ");
  if (result.body.blocklistItems) {
    for (const blockItem of result.body.blocklistItems) {
      console.log(
        "BlockItemId: ",
        blockItem.blocklistItemId,
        ", Text: ",
        blockItem.text,
        ", Description: ",
        blockItem.description,
      );
    }
  }
}

async function analyzeTextWithBlocklists() {
  const blocklistName = "TestBlocklist";
  const inputText = "This is a sample to test text with blocklist.";
  const analyzeTextParameters = {
    body: {
      text: inputText,
      blocklistNames: [blocklistName],
      haltOnBlocklistHit: false,
    },
  };

  const result = await client.path("/text:analyze").post(analyzeTextParameters);

  if (isUnexpected(result)) {
    throw result;
  }

  console.log("Blocklist match results: ");
  if (result.body.blocklistsMatch) {
    for (const blocklistMatchResult of result.body.blocklistsMatch) {
      console.log(
        "BlocklistName: ",
        blocklistMatchResult.blocklistName,
        ", BlockItemId: ",
        blocklistMatchResult.blocklistItemId,
        ", BlockItemText: ",
        blocklistMatchResult.blocklistItemText,
      );
    }
  }
}

try {
  await createOrUpdateTextBlocklist();
  await addBlockItems();
  await analyzeTextWithBlocklists();
} catch (err) {
  console.error("The sample encountered an error:", err);
}

分析图像

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";
import { readFileSync } from "node:fs";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const image_path = "./samples-dev/example-data/image.png";

const imageBuffer = readFileSync(image_path);
const base64Image = imageBuffer.toString("base64");
const analyzeImageOption = { image: { content: base64Image } };
const analyzeImageParameters = { body: analyzeImageOption };

const result = await client.path("/image:analyze").post(analyzeImageParameters);

if (isUnexpected(result)) {
  throw result;
}

for (let i = 0; i < result.body.categoriesAnalysis.length; i++) {
  const imageCategoriesAnalysisOutput = result.body.categoriesAnalysis[i];
  console.log(
    imageCategoriesAnalysisOutput.category,
    " severity: ",
    imageCategoriesAnalysisOutput.severity,
  );
}

管理文本阻止列表

创建或更新文本阻止列表

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, {
  CreateOrUpdateTextBlocklistParameters,
  isUnexpected,
} from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";
const blocklistDescription = "Test blocklist management.";
const createOrUpdateTextBlocklistParameters: CreateOrUpdateTextBlocklistParameters = {
  contentType: "application/merge-patch+json",
  body: {
    description: blocklistDescription,
  },
};

const result = await client
  .path("/text/blocklists/{blocklistName}", blocklistName)
  .patch(createOrUpdateTextBlocklistParameters);

if (isUnexpected(result)) {
  throw result;
}

console.log(
  "Blocklist created or updated: Name",
  result.body.blocklistName,
  ", Description: ",
  result.body.description,
);

列出文本阻止列表

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const result = await client.path("/text/blocklists").get();

if (isUnexpected(result)) {
  throw result;
}

console.log("List blocklists: ");
if (result.body.value) {
  for (const blocklist of result.body.value) {
    console.log(
      "BlocklistName: ",
      blocklist.blocklistName,
      ", Description: ",
      blocklist.description,
    );
  }
}

获取文本阻止列表

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client.path("/text/blocklists/{blocklistName}", blocklistName).get();

if (isUnexpected(result)) {
  throw result;
}

console.log("Get blocklist: ");
console.log("Name: ", result.body.blocklistName, ", Description: ", result.body.description);

删除文本阻止列表

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client.path("/text/blocklists/{blocklistName}", blocklistName).delete();

if (isUnexpected(result)) {
  throw result;
}

console.log("Deleted blocklist: ", blocklistName);

添加 blockItems

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";
const blockItemText1 = "sample";
const blockItemText2 = "text";
const addOrUpdateBlocklistItemsParameters = {
  body: {
    blocklistItems: [
      {
        description: "Test block item 1",
        text: blockItemText1,
      },
      {
        description: "Test block item 2",
        text: blockItemText2,
      },
    ],
  },
};

const result = await client
  .path("/text/blocklists/{blocklistName}:addOrUpdateBlocklistItems", blocklistName)
  .post(addOrUpdateBlocklistItemsParameters);

if (isUnexpected(result)) {
  throw result;
}

console.log("Block items added: ");
if (result.body.blocklistItems) {
  for (const blockItem of result.body.blocklistItems) {
    console.log(
      "BlockItemId: ",
      blockItem.blocklistItemId,
      ", Text: ",
      blockItem.text,
      ", Description: ",
      blockItem.description,
    );
  }
}

列出 blockItems

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blocklistName = "TestBlocklist";

const result = await client
  .path("/text/blocklists/{blocklistName}/blocklistItems", blocklistName)
  .get();

if (isUnexpected(result)) {
  throw result;
}

console.log("List block items: ");
if (result.body.value) {
  for (const blockItem of result.body.value) {
    console.log(
      "BlockItemId: ",
      blockItem.blocklistItemId,
      ", Text: ",
      blockItem.text,
      ", Description: ",
      blockItem.description,
    );
  }
}

获取 blockItem

TypeScript

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blockItemId = "<blockItemId>";
const blocklistName = "TestBlocklist";

const blockItem = await client
  .path(
    "/text/blocklists/{blocklistName}/blocklistItems/{blocklistItemId}",
    blocklistName,
    blockItemId,
  )
  .get();

if (isUnexpected(blockItem)) {
  throw blockItem;
}

console.log("Get blockitem: ");
console.log(
  "BlockItemId: ",
  blockItem.body.blocklistItemId,
  ", Text: ",
  blockItem.body.text,
  ", Description: ",
  blockItem.body.description,
);

删除 blockItems

import { DefaultAzureCredential } from "@azure/identity";
import ContentSafetyClient, { isUnexpected } from "@azure-rest/ai-content-safety";

const endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/";
const credential = new DefaultAzureCredential();
const client = ContentSafetyClient(endpoint, credential);

const blockItemId = "<blockItemId>";
const blocklistName = "TestBlocklist";
const blockItemText = "sample";

const removeBlocklistItemsParameters = {
  body: {
    blocklistItemIds: [blockItemId],
  },
};
const removeBlockItem = await client
  .path("/text/blocklists/{blocklistName}:removeBlocklistItems", blocklistName)
  .post(removeBlocklistItemsParameters);

if (isUnexpected(removeBlockItem)) {
  throw removeBlockItem;
}

console.log("Removed blockItem: ", blockItemText);

故障 排除

伐木

启用日志记录可能有助于发现有关故障的有用信息。 若要查看 HTTP 请求和响应的日志，请将 AZURE_LOG_LEVEL 环境变量设置为 info。 或者，可以通过在 @azure/logger中调用 setLogLevel 在运行时启用日志记录：

import { setLogLevel } from "@azure/logger";

setLogLevel("info");

有关如何启用日志的更详细说明，可以查看 @azure/记录器包文档。

后续步骤

其他文档

有关 Azure 内容安全的详细信息文档，请参阅有关 learn.microsoft.com Azure AI 内容安全。

贡献

若要参与此库，请阅读 贡献指南 了解有关如何生成和测试代码的详细信息。