Azure AI 内容安全 TypeScript SDK

azure-ai-contentsafety-ts
分类通用
作者Agentic Awesome Skills 社区
许可MIT
评分4.20/5
使用8.0K

Azure AI Content Safety TypeScript REST SDK

通过可自定义的阻止列表分析文本和图像中的有害内容。

安装

bash
npm install @azure-rest/ai-content-safety @azure/identity @azure/core-auth

环境变量

bash
CONTENT_SAFETY_ENDPOINT=https://<resource>.cognitiveservices.azure.com
CONTENT_SAFETY_KEY=<api-key>

身份验证

重要提示：这是一个 REST 客户端。ContentSafetyClient 是一个函数，而非类。

API 密钥

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

const client = ContentSafetyClient(
  process.env.CONTENT_SAFETY_ENDPOINT!,
  new AzureKeyCredential(process.env.CONTENT_SAFETY_KEY!)
);

DefaultAzureCredential

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

const client = ContentSafetyClient(
  process.env.CONTENT_SAFETY_ENDPOINT!,
  new DefaultAzureCredential()
);

分析文本

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

const result = await client.path("/text:analyze").post({
  body: {
    text: "待分析的文本内容",
    categories: ["Hate", "Sexual", "Violence", "SelfHarm"],
    outputType: "FourSeverityLevels"  // 或 "EightSeverityLevels"
  }
});


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


for (const analysis of result.body.categoriesAnalysis) {
  console.log(${analysis.category}: severity ${analysis.severity});
}

分析图像

Base64 内容

typescript
import { readFileSync } from "node:fs";

const imageBuffer = readFileSync("./image.png");
const base64Image = imageBuffer.toString("base64");


const result = await client.path("/image:analyze").post({
  body: {
    image: { content: base64Image }
  }
});


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


for (const analysis of result.body.categoriesAnalysis) {
  console.log(${analysis.category}: severity ${analysis.severity});
}

Blob URL

typescript
const result = await client.path("/image:analyze").post({
  body: {
    image: { blobUrl: "https://storage.blob.core.windows.net/container/image.png" }
  }
});

阻止列表管理

创建阻止列表

typescript
const result = await client
  .path("/text/blocklists/{blocklistName}", "my-blocklist")
  .patch({
    contentType: "application/merge-patch+json",
    body: {
      description: "禁止术语的自定义阻止列表"
    }
  });

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


console.log(已创建: ${result.body.blocklistName});

向阻止列表添加项

typescript
const result = await client
  .path("/text/blocklists/{blocklistName}:addOrUpdateBlocklistItems", "my-blocklist")
  .post({
    body: {
      blocklistItems: [
        { text: "prohibited-term-1", description: "第一个被阻止的术语" },
        { text: "prohibited-term-2", description: "第二个被阻止的术语" }
      ]
    }
  });

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


for (const item of result.body.blocklistItems ?? []) {
  console.log(已添加: ${item.blocklistItemId});
}

使用阻止列表进行分析

typescript
const result = await client.path("/text:analyze").po
typescript
st({
  body: {
    text: "可能包含屏蔽词的文本",
    blocklistNames: ["my-blocklist"],
    haltOnBlocklistHit: false
  }
});

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


// 检查屏蔽词匹配情况
if (result.body.blocklistsMatch) {
  for (const match of result.body.blocklistsMatch) {
    console.log(屏蔽词: "${match.blocklistItemText}" 来自 ${match.blocklistName});
  }
}

列出屏蔽列表

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

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


for (const blocklist of result.body.value ?? []) {
  console.log(${blocklist.blocklistName}: ${blocklist.description});
}

删除屏蔽列表

typescript
await client.path("/text/blocklists/{blocklistName}", "my-blocklist").delete();

危害类别

| 类别 | API 术语 | 描述 |
|----------|----------|-------------|
| 仇恨与公平性 | Hate | 针对身份群体的歧视性语言 |
| 性内容 | Sexual | 性内容、裸露、色情 |
| 暴力 | Violence | 身体伤害、武器、恐怖主义 |
| 自残 | SelfHarm | 自伤、自杀、饮食失调 |

严重程度级别

| 级别 | 风险 | 建议操作 |
|-------|------|-------------------|
| 0 | 安全 | 允许 |
| 2 | 低 | 审核或带警告允许 |
| 4 | 中 | 屏蔽或需要人工审核 |
| 6 | 高 | 立即屏蔽 |

输出类型:

  • FourSeverityLevels (默认): 返回 0, 2, 4, 6

  • EightSeverityLevels: 返回 0-7

内容审核辅助函数

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

interface ModerationResult {
  isAllowed: boolean;
  flaggedCategories: string[];
  maxSeverity: number;
  blocklistMatches: string[];
}


async function moderateContent(
  client: ReturnType<typeof ContentSafetyClient>,
  text: string,
  maxAllowedSeverity = 2,
  blocklistNames: string[] = []
): Promise<ModerationResult> {
  const result = await client.path("/text:analyze").post({
    body: { text, blocklistNames, haltOnBlocklistHit: false }
  });


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


const flaggedCategories = result.body.categoriesAnalysis
    .filter(c => (c.severity ?? 0) > maxAllowedSeverity)
    .map(c => c.category!);


const maxSeverity = Math.max(
    ...result.body.categoriesAnalysis.map(c => c.severity ?? 0)
  );


const blocklistMatches = (result.body.blocklistsMatch ?? [])
    .map(m => m.blocklistItemText!);


return {
    isAllowed: flaggedCategories.length === 0 && blocklistMatches.length === 0,
    flaggedCategories,
    maxSeverity,
    blocklistMatches
  };
}

API 终结点

| 操作 | 方法 | 路径 |
|-----------|--------|------|
| 分析文本 | POST | /text:analyze |
| 分析图像 | POST | /image:analyze |
| 创建/更新屏蔽列表 | PATCH | /text/blocklists/{blocklistName} |
| 列出屏蔽列表 | GET | /text/blocklists |
| 删除屏蔽列表 | DELETE | /text/blocklists/{blocklistName} |
| 添加屏蔽项 | POST | /text/blocklists/{blocklistName}:addOrUpdateBlocklistItems |
| 列出屏蔽项 | GET | /text/blocklists/{blocklistName}/blocklistItems |
| 移除屏蔽项 | POST | /text/blocklists/{blocklistName}:removeBlocklistItems |

关键类型

typescript
import ContentSafetyClient, {
  isUnexpected,
  AnalyzeTextParameters,
  AnalyzeImageParameters,
  TextCategoriesAnalysisOutput,
  ImageCat
typescript
egoriesAnalysisOutput,
  TextBlocklist,
  TextBlocklistItem
} from "@azure-rest/ai-content-safety";

最佳实践

1. 始终使用 isUnexpected() —— 用于错误处理的类型守卫。
2. 设置合适的阈值 —— 不同类别可能需要不同的严重程度阈值。
3. 针对特定领域术语使用屏蔽列表 —— 用自定义规则补充 AI 检测。
4. 记录审核决策 —— 为合规性保留审计追踪。
5. 处理边缘情况 —— 如空文本、超长文本或不支持的图像格式。

适用场景

本技能适用于执行概览中所描述的工作流或操作。

局限性

  • 仅在任务明确符合上述范围时使用此技能。
  • 不要将输出结果视为环境特定验证、测试或专家评审的替代方案。
  • 如果缺少必要的输入、权限、安全边界或成功标准，请停止操作并请求澄清。