azure-ai-contentsafety-py

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Azure AI Content Safety SDK for Python

适用于Python的Azure AI Content Safety SDK

Detect harmful user-generated and AI-generated content in applications.

检测应用程序中用户生成和AI生成的有害内容。

Installation

安装

bash

pip install azure-ai-contentsafety

bash

pip install azure-ai-contentsafety

Environment Variables

环境变量

bash

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

bash

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

Authentication

认证

API Key

API密钥

python

from azure.ai.contentsafety import ContentSafetyClient
from azure.core.credentials import AzureKeyCredential
import os

client = ContentSafetyClient(
    endpoint=os.environ["CONTENT_SAFETY_ENDPOINT"],
    credential=AzureKeyCredential(os.environ["CONTENT_SAFETY_KEY"])
)

python

from azure.ai.contentsafety import ContentSafetyClient
from azure.core.credentials import AzureKeyCredential
import os

client = ContentSafetyClient(
    endpoint=os.environ["CONTENT_SAFETY_ENDPOINT"],
    credential=AzureKeyCredential(os.environ["CONTENT_SAFETY_KEY"])
)

Entra ID

Entra ID认证

python

from azure.ai.contentsafety import ContentSafetyClient
from azure.identity import DefaultAzureCredential

client = ContentSafetyClient(
    endpoint=os.environ["CONTENT_SAFETY_ENDPOINT"],
    credential=DefaultAzureCredential()
)

python

from azure.ai.contentsafety import ContentSafetyClient
from azure.identity import DefaultAzureCredential

client = ContentSafetyClient(
    endpoint=os.environ["CONTENT_SAFETY_ENDPOINT"],
    credential=DefaultAzureCredential()
)

Analyze Text

文本分析

python

from azure.ai.contentsafety import ContentSafetyClient
from azure.ai.contentsafety.models import AnalyzeTextOptions, TextCategory
from azure.core.credentials import AzureKeyCredential

client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

request = AnalyzeTextOptions(text="Your text content to analyze")
response = client.analyze_text(request)

python

from azure.ai.contentsafety import ContentSafetyClient
from azure.ai.contentsafety.models import AnalyzeTextOptions, TextCategory
from azure.core.credentials import AzureKeyCredential

client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

request = AnalyzeTextOptions(text="Your text content to analyze")
response = client.analyze_text(request)

Check each category

检查每个分类

for category in [TextCategory.HATE, TextCategory.SELF_HARM, TextCategory.SEXUAL, TextCategory.VIOLENCE]: result = next((r for r in response.categories_analysis if r.category == category), None) if result: print(f"{category}: severity {result.severity}")

undefined

undefined

Analyze Image

图像分析

python

from azure.ai.contentsafety import ContentSafetyClient
from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData
from azure.core.credentials import AzureKeyCredential
import base64

client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

python

from azure.ai.contentsafety import ContentSafetyClient
from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData
from azure.core.credentials import AzureKeyCredential
import base64

client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

From file

从文件读取

with open("image.jpg", "rb") as f: image_data = base64.b64encode(f.read()).decode("utf-8")

request = AnalyzeImageOptions( image=ImageData(content=image_data) )

response = client.analyze_image(request)

for result in response.categories_analysis: print(f"{result.category}: severity {result.severity}")

undefined

with open("image.jpg", "rb") as f: image_data = base64.b64encode(f.read()).decode("utf-8")

request = AnalyzeImageOptions( image=ImageData(content=image_data) )

response = client.analyze_image(request)

for result in response.categories_analysis: print(f"{result.category}: severity {result.severity}")

undefined

Image from URL

从URL读取图像

python

from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData

request = AnalyzeImageOptions(
    image=ImageData(blob_url="https://example.com/image.jpg")
)

response = client.analyze_image(request)

python

from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData

request = AnalyzeImageOptions(
    image=ImageData(blob_url="https://example.com/image.jpg")
)

response = client.analyze_image(request)

Text Blocklist Management

文本黑名单管理

Create Blocklist

创建黑名单

python

from azure.ai.contentsafety import BlocklistClient
from azure.ai.contentsafety.models import TextBlocklist
from azure.core.credentials import AzureKeyCredential

blocklist_client = BlocklistClient(endpoint, AzureKeyCredential(key))

blocklist = TextBlocklist(
    blocklist_name="my-blocklist",
    description="Custom terms to block"
)

result = blocklist_client.create_or_update_text_blocklist(
    blocklist_name="my-blocklist",
    options=blocklist
)

python

from azure.ai.contentsafety import BlocklistClient
from azure.ai.contentsafety.models import TextBlocklist
from azure.core.credentials import AzureKeyCredential

blocklist_client = BlocklistClient(endpoint, AzureKeyCredential(key))

blocklist = TextBlocklist(
    blocklist_name="my-blocklist",
    description="Custom terms to block"
)

result = blocklist_client.create_or_update_text_blocklist(
    blocklist_name="my-blocklist",
    options=blocklist
)

Add Block Items

添加黑名单条目

python

from azure.ai.contentsafety.models import AddOrUpdateTextBlocklistItemsOptions, TextBlocklistItem

items = AddOrUpdateTextBlocklistItemsOptions(
    blocklist_items=[
        TextBlocklistItem(text="blocked-term-1"),
        TextBlocklistItem(text="blocked-term-2")
    ]
)

result = blocklist_client.add_or_update_blocklist_items(
    blocklist_name="my-blocklist",
    options=items
)

python

from azure.ai.contentsafety.models import AddOrUpdateTextBlocklistItemsOptions, TextBlocklistItem

items = AddOrUpdateTextBlocklistItemsOptions(
    blocklist_items=[
        TextBlocklistItem(text="blocked-term-1"),
        TextBlocklistItem(text="blocked-term-2")
    ]
)

result = blocklist_client.add_or_update_blocklist_items(
    blocklist_name="my-blocklist",
    options=items
)

Analyze with Blocklist

结合黑名单分析文本

python

from azure.ai.contentsafety.models import AnalyzeTextOptions

request = AnalyzeTextOptions(
    text="Text containing blocked-term-1",
    blocklist_names=["my-blocklist"],
    halt_on_blocklist_hit=True
)

response = client.analyze_text(request)

if response.blocklists_match:
    for match in response.blocklists_match:
        print(f"Blocked: {match.blocklist_item_text}")

python

from azure.ai.contentsafety.models import AnalyzeTextOptions

request = AnalyzeTextOptions(
    text="Text containing blocked-term-1",
    blocklist_names=["my-blocklist"],
    halt_on_blocklist_hit=True
)

response = client.analyze_text(request)

if response.blocklists_match:
    for match in response.blocklists_match:
        print(f"Blocked: {match.blocklist_item_text}")

Severity Levels

严重程度等级

Text analysis returns 4 severity levels (0, 2, 4, 6) by default. For 8 levels (0-7):

python

from azure.ai.contentsafety.models import AnalyzeTextOptions, AnalyzeTextOutputType

request = AnalyzeTextOptions(
    text="Your text",
    output_type=AnalyzeTextOutputType.EIGHT_SEVERITY_LEVELS
)

文本分析默认返回4个严重程度等级（0、2、4、6）。若需8个等级（0-7）：

python

from azure.ai.contentsafety.models import AnalyzeTextOptions, AnalyzeTextOutputType

request = AnalyzeTextOptions(
    text="Your text",
    output_type=AnalyzeTextOutputType.EIGHT_SEVERITY_LEVELS
)

Harm Categories

有害内容分类

Category	Description
`Hate`	Attacks based on identity (race, religion, gender, etc.)
`Sexual`	Sexual content, relationships, anatomy
`Violence`	Physical harm, weapons, injury
`SelfHarm`	Self-injury, suicide, eating disorders

分类	描述
`Hate`	基于身份（种族、宗教、性别等）的攻击
`Sexual`	性内容、性关系、人体解剖
`Violence`	人身伤害、武器、受伤
`SelfHarm`	自我伤害、自杀、饮食失调

Severity Scale

严重程度量表

Level	Text Range	Image Range	Meaning
0	Safe	Safe	No harmful content
2	Low	Low	Mild references
4	Medium	Medium	Moderate content
6	High	High	Severe content

等级	文本范围	图像范围	含义
0	安全	安全	无有害内容
2	低	低	轻微提及
4	中	中	中等程度内容
6	高	高	严重内容

Client Types

客户端类型

Client	Purpose
`ContentSafetyClient`	Analyze text and images
`BlocklistClient`	Manage custom blocklists

客户端	用途
`ContentSafetyClient`	分析文本和图像
`BlocklistClient`	管理自定义黑名单

Best Practices

最佳实践

Use blocklists for domain-specific terms
Set severity thresholds appropriate for your use case
Handle multiple categories — content can be harmful in multiple ways
Use halt_on_blocklist_hit for immediate rejection
Log analysis results for audit and improvement
Consider 8-severity mode for finer-grained control
Pre-moderate AI outputs before showing to users

使用黑名单处理特定领域的术语
设置严重程度阈值以适配你的使用场景
处理多分类情况——内容可能存在多种有害类型
启用halt_on_blocklist_hit实现即时拒绝
记录分析结果用于审计和优化
考虑使用8级严重程度模式以获得更精细的控制
预审核AI输出再展示给用户