通过

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

适用于 Python 的 Azure AI 内容安全 客户端库 - 版本 1.0.0

  • 项目

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

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

文档

提供了各种文档来帮助你入门

入门

先决条件

安装包

pip install azure-ai-contentsafety

验证客户端

获取终结点

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

使用 API 密钥作为 credential 参数。

  • 步骤 1：获取 API 密钥。 可以在 Azure 门户中 或通过运行以下 Azure CLI 命令找到 API 密钥：

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

  • 步骤 2：将密钥作为字符串传递到 的 AzureKeyCredential实例中。

    from azure.core.credentials import AzureKeyCredential
from azure.ai.contentsafety import ContentSafetyClient, BlocklistClient

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = AzureKeyCredential("<api_key>")
content_safety_client = ContentSafetyClient(endpoint, credential)
blocklist_client = BlocklistClient(endpoint, credential)

使用 Microsoft Entra ID 令牌凭据创建 ContentSafetyClient/BlocklistClient

  • 步骤 1：为资源启用Microsoft Entra ID。 有关为资源启用Microsoft Entra ID 的步骤，请参阅本文档使用Microsoft Entra ID 进行身份验证。

    主要步骤包括：

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

  • 步骤 2：将Microsoft Entra应用程序的客户端 ID、租户 ID 和客户端密码的值设置为环境变量：AZURE_CLIENT_ID、、AZURE_TENANT_IDAZURE_CLIENT_SECRET。

    DefaultAzureCredential 将使用这些环境变量中的值。

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

endpoint = "https://<my-custom-subdomain>.cognitiveservices.azure.com/"
credential = DefaultAzureCredential()
content_safety_client = ContentSafetyClient(endpoint, credential)
blocklist_client = BlocklistClient(endpoint, credential)

关键概念

可用功能

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

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

有害类别

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

类别 说明
仇恨 仇恨和公平相关的伤害是指基于这些群体的某些不同属性（包括但不限于种族、种族、国籍、性别认同和表达、性取向、宗教、移民身份、能力地位、个人外貌和身体大小）攻击或使用贬损性或歧视性语言的任何内容。
性 性描述与解剖器官和生殖器、浪漫关系、色情或深情词语所描绘的行为、怀孕、身体性行为（包括被描绘为违反个人意志的攻击或强迫性暴力行为、卖淫、色情和虐待）相关的语言。
暴力 暴力是指与旨在伤害、伤害、伤害或杀死某人或某物的身体行为相关的语言;描述武器、枪支和相关实体，如制造商、协会、立法等。
自残 自残描述与故意伤害、伤害、伤害身体或自杀的身体行为相关的语言。

分类可以是多标记的。 例如，通过文本审查模型运行文本示例时，可以将其归类为性内容和暴力。

严重性级别

该服务适用的每种伤害类别还带有严重性评级。 严重性级别旨在表明，如果显示了已标记的内容，则造成的后果的严重性有多高。

文本：当前版本的文本模型支持完整的 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 获取阻止列表
  • 将 blocklistItems 添加到阻止列表
  • 从阻止列表中删除 blocklistItems
  • 按 blocklistName 列出阻止列表中的所有 blocklistItems
  • 按 blocklistItemId 和 blocklistName 获取阻止列表中的 blocklistItem
  • 删除阻止列表及其所有 blocklistItems

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

示例

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

有关此处使用 的数据，请参阅示例 数据。 有关更多示例，请参阅 示例。

分析文本

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


    import os
    from azure.ai.contentsafety import ContentSafetyClient
    from azure.ai.contentsafety.models import TextCategory
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError
    from azure.ai.contentsafety.models import AnalyzeTextOptions

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Content Safety client
    client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

    # Construct a request
    request = AnalyzeTextOptions(text="You are an idiot")

    # 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}")

使用阻止列表分析文本


    import os
    from azure.ai.contentsafety import ContentSafetyClient
    from azure.core.credentials import AzureKeyCredential
    from azure.ai.contentsafety.models import AnalyzeTextOptions
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Content Safety client
    client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    input_text = "I h*te you and I want to k*ll you."

    try:
        # After you edit your blocklist, it usually takes effect in 5 minutes, please wait some time before analyzing with blocklist after editing.
        analysis_result = client.analyze_text(
            AnalyzeTextOptions(text=input_text, blocklist_names=[blocklist_name], halt_on_blocklist_hit=False)
        )
        if analysis_result and analysis_result.blocklists_match:
            print("\nBlocklist match results: ")
            for match_result in analysis_result.blocklists_match:
                print(
                    f"BlocklistName: {match_result.blocklist_name}, BlockItemId: {match_result.blocklist_item_id}, "
                    f"BlockItemText: {match_result.blocklist_item_text}"
                )
    except HttpResponseError as e:
        print("\nAnalyze text failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

分析图像


    import os
    from azure.ai.contentsafety import ContentSafetyClient
    from azure.ai.contentsafety.models import ImageCategory
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError
    from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]
    image_path = os.path.abspath(os.path.join(os.path.abspath(__file__), "..", "./sample_data/image.jpg"))

    # Create a Content Safety client
    client = ContentSafetyClient(endpoint, AzureKeyCredential(key))

    # Build request
    with open(image_path, "rb") as file:
        request = AnalyzeImageOptions(image=ImageData(content=file.read()))

    # Analyze image
    try:
        response = client.analyze_image(request)
    except HttpResponseError as e:
        print("Analyze image 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 == ImageCategory.HATE)
    self_harm_result = next(item for item in response.categories_analysis if item.category == ImageCategory.SELF_HARM)
    sexual_result = next(item for item in response.categories_analysis if item.category == ImageCategory.SEXUAL)
    violence_result = next(item for item in response.categories_analysis if item.category == ImageCategory.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}")

管理文本阻止列表

创建或更新文本阻止列表


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

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    blocklist_description = "Test blocklist management."

    try:
        blocklist = client.create_or_update_text_blocklist(
            blocklist_name=blocklist_name,
            options=TextBlocklist(blocklist_name=blocklist_name, description=blocklist_description),
        )
        if blocklist:
            print("\nBlocklist created or updated: ")
            print(f"Name: {blocklist.blocklist_name}, Description: {blocklist.description}")
    except HttpResponseError as e:
        print("\nCreate or update text blocklist failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

列出文本阻止列表


    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    try:
        blocklists = client.list_text_blocklists()
        if blocklists:
            print("\nList blocklists: ")
            for blocklist in blocklists:
                print(f"Name: {blocklist.blocklist_name}, Description: {blocklist.description}")
    except HttpResponseError as e:
        print("\nList text blocklists failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

获取文本阻止列表


    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"

    try:
        blocklist = client.get_text_blocklist(blocklist_name=blocklist_name)
        if blocklist:
            print("\nGet blocklist: ")
            print(f"Name: {blocklist.blocklist_name}, Description: {blocklist.description}")
    except HttpResponseError as e:
        print("\nGet text blocklist failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

删除文本阻止列表


    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"

    try:
        client.delete_text_blocklist(blocklist_name=blocklist_name)
        print(f"\nDeleted blocklist: {blocklist_name}")
    except HttpResponseError as e:
        print("\nDelete blocklist failed:")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

添加 blockItems


    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.ai.contentsafety.models import AddOrUpdateTextBlocklistItemsOptions, TextBlocklistItem
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    block_item_text_1 = "k*ll"
    block_item_text_2 = "h*te"

    block_items = [TextBlocklistItem(text=block_item_text_1), TextBlocklistItem(text=block_item_text_2)]
    try:
        result = client.add_or_update_blocklist_items(
            blocklist_name=blocklist_name, options=AddOrUpdateTextBlocklistItemsOptions(blocklist_items=block_items)
        )
        for block_item in result.blocklist_items:
            print(
                f"BlockItemId: {block_item.blocklist_item_id}, Text: {block_item.text}, Description: {block_item.description}"
            )
    except HttpResponseError as e:
        print("\nAdd block items failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

List blockItems


    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"

    try:
        block_items = client.list_text_blocklist_items(blocklist_name=blocklist_name)
        if block_items:
            print("\nList block items: ")
            for block_item in block_items:
                print(
                    f"BlockItemId: {block_item.blocklist_item_id}, Text: {block_item.text}, "
                    f"Description: {block_item.description}"
                )
    except HttpResponseError as e:
        print("\nList block items failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

获取 blockItem


    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.ai.contentsafety.models import TextBlocklistItem, AddOrUpdateTextBlocklistItemsOptions
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    block_item_text_1 = "k*ll"

    try:
        # Add a blockItem
        add_result = client.add_or_update_blocklist_items(
            blocklist_name=blocklist_name,
            options=AddOrUpdateTextBlocklistItemsOptions(blocklist_items=[TextBlocklistItem(text=block_item_text_1)]),
        )
        if not add_result or not add_result.blocklist_items or len(add_result.blocklist_items) <= 0:
            raise RuntimeError("BlockItem not created.")
        block_item_id = add_result.blocklist_items[0].blocklist_item_id

        # Get this blockItem by blockItemId
        block_item = client.get_text_blocklist_item(blocklist_name=blocklist_name, blocklist_item_id=block_item_id)
        print("\nGet blockitem: ")
        print(
            f"BlockItemId: {block_item.blocklist_item_id}, Text: {block_item.text}, Description: {block_item.description}"
        )
    except HttpResponseError as e:
        print("\nGet block item failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

删除 blockItems


    import os
    from azure.ai.contentsafety import BlocklistClient
    from azure.core.credentials import AzureKeyCredential
    from azure.ai.contentsafety.models import (
        TextBlocklistItem,
        AddOrUpdateTextBlocklistItemsOptions,
        RemoveTextBlocklistItemsOptions,
    )
    from azure.core.exceptions import HttpResponseError

    key = os.environ["CONTENT_SAFETY_KEY"]
    endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]

    # Create a Blocklist client
    client = BlocklistClient(endpoint, AzureKeyCredential(key))

    blocklist_name = "TestBlocklist"
    block_item_text_1 = "k*ll"

    try:
        # Add a blockItem
        add_result = client.add_or_update_blocklist_items(
            blocklist_name=blocklist_name,
            options=AddOrUpdateTextBlocklistItemsOptions(blocklist_items=[TextBlocklistItem(text=block_item_text_1)]),
        )
        if not add_result or not add_result.blocklist_items or len(add_result.blocklist_items) <= 0:
            raise RuntimeError("BlockItem not created.")
        block_item_id = add_result.blocklist_items[0].blocklist_item_id

        # Remove this blockItem by blockItemId
        client.remove_blocklist_items(
            blocklist_name=blocklist_name, options=RemoveTextBlocklistItemsOptions(blocklist_item_ids=[block_item_id])
        )
        print(f"\nRemoved blockItem: {add_result.blocklist_items[0].blocklist_item_id}")
    except HttpResponseError as e:
        print("\nRemove block item failed: ")
        if e.error:
            print(f"Error code: {e.error.code}")
            print(f"Error message: {e.error.message}")
            raise
        print(e)
        raise

疑难解答

常规

Azure AI 内容安全客户端库将引发 Azure Core 中定义的异常。 错误代码定义如下：

错误代码 可能的原因 建议
InvalidRequestBody 请求正文中的一个或多个字段与 API 定义不匹配。 1. 检查 API 调用中指定的 API 版本。
2. 检查所选 API 版本的相应 API 定义。
InvalidResourceName 在 URL 中指定的资源名称不符合要求，例如阻止列表名称、阻止列表术语 ID 等。 1. 检查 API 调用中指定的 API 版本。
2. 根据 API 定义检查给定的名称是否包含无效字符。
ResourceNotFound URL 中指定的资源（例如阻止列表名称）可能不存在。 1. 检查 API 调用中指定的 API 版本。
2. 反复检查 URL 中指定的资源是否存在。
InternalError 已在服务器端触发一些意外情况。 1. 建议在等待片刻时间后重试几次，看看问题是否再次发生。
2. 如果问题仍然存在，请联系 Azure 支持部门。
ServerBusy 服务器端暂时无法处理请求。 1. 建议在等待片刻时间后重试几次，看看问题是否再次发生。
2. 如果问题仍然存在，请联系 Azure 支持部门。
TooManyRequests 当前 RPS 已超出当前 SKU 的配额。 1. 查看定价表了解 RPS 配额。
2. 如需提高 QPS，请联系 Azure 支持部门。

日志记录

此库使用标准 日志记录 库进行日志记录。

有关 HTTP 会话 (URL、标头等的基本信息，) 是在级别记录的 INFO 。

可以使用 关键字 (keyword) 参数在客户端上或按操作logging_enable启用详细DEBUG级别日志记录，包括请求/响应正文和未实现的标头。

请参阅此处提供示例的完整 SDK 日志记录文档。

可选配置

可选关键字 (keyword) 参数可以在客户端和按操作级别传入。 azure-core 参考文档 介绍了重试、日志记录、传输协议等的可用配置。

后续步骤

其他文档

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

贡献

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

提交拉取请求时，CLA 机器人将自动确定你是否需要提供 CLA，并相应地修饰 PR（例如标签、注释）。 直接按机器人提供的说明操作。 只需使用 CLA 对所有存储库执行一次这样的操作。

本项目采用 Microsoft 开源行为准则。 有关详细信息，请参阅“行为准则常见问题解答”，如有其他任何问题或意见，请联系 opencode@microsoft.com。