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

快速入门：自定义类别（标准模式）（预览版）

2025-10-11

遵循本指南，使用 Azure AI 内容安全自定义类别（标准）REST API 为用例创建自己的内容类别，并训练 Azure AI 内容安全，以在新文本内容中检测它们。

有关自定义类别的详细信息，请参阅自定义类别概念页。如需了解 API 输入限制，请参阅“概述”的输入要求部分。

重要说明

此功能仅在某些 Azure 区域中可用。请参阅区域可用性。

重要说明

留出足够的时间进行模型训练

自定义类别训练的端到端执行需要大约 5 到 10 小时。请相应地规划审核流程。

Prerequisites

一个 Azure 帐户。如果没有帐户，可以免费创建一个帐户。
Azure AI 资源。

设置

按照以下步骤使用内容安全试用页面：

转到 Azure AI Foundry 并导航到你的项目/中心。然后选择左侧导航栏上的 Guardrails + 控件 选项卡，然后选择“ 试用 ”选项卡。
在“试用”页面上，您可以尝试包括文本和图像内容在内的多种保护措施和控件功能，并使用可调整的阈值来筛选不当或有害内容。

Guardrails 和控件试用页面的屏幕截图。

使用自定义类别

通过此功能，可以创建和训练自己的自定义内容类别并扫描文本以查找匹配项。

选择“自定义类别”面板。
选择“添加新类别”以打开对话框。输入类别名称和文本说明，并使用文本训练数据连接 Blob 存储容器。选择“创建和训练”。
选择类别并输入示例输入文本，然后选择“运行测试”。该服务返回自定义类别结果。

有关详细信息，请参阅自定义类别概念指南。

Prerequisites

Azure 订阅 - 免费创建订阅
拥有 Azure 订阅后，请在 Azure 门户中创建内容安全资源，以获取密钥和终结点。输入资源的唯一名称，选择订阅，并选择资源组、支持的区域和支持的定价层。然后选择“创建”。
- 部署资源需要几分钟时间。完成后，选择“转到资源”。在左侧窗格中的“资源管理”下，选择“订阅密钥和终结点”。将终结点和其中一个密钥值复制到临时位置供以后使用。
此外，创建一个 Azure blob 存储容器，用于保存训练注释文件。
已安装以下项之一：
- REST API 调用的 cURL。
- 已安装 Python 3.x

准备训练数据

要训练自定义类别，需要可代表要检测的类别的示例文本数据。在本指南中，可以使用示例数据。提供的批注文件包含关于露营/荒野情况下生存建议的文本提示。经过训练的模型将学习如何检测新文本数据中的此类内容。

提示

有关创建自己的数据集的提示，请参阅操作指南。

从 GitHub 存储库下载示例文本数据文件。
将 .jsonl 文件上传到 Azure 存储帐户 blob 容器。然后将 blob URL 复制到临时位置以供将来使用。

重要说明

用户的存储帐户设置为分层命名空间帐户，自定义类别不支持该类帐户。请尝试改用常规存储帐户。 例如，Blob URL 不能拆分为两个层（如 example/example1/），而只能有一个层。有关更多详细信息，请参阅文档：Azure Data Lake Storage 分层命名空间 - Azure 存储。

授予存储访问权限

接下来，你需要为 Content Safety 资源授予从 Azure 存储资源中进行读取的访问权。为 Azure AI 内容安全实例启用系统分配的托管标识，并将“存储 Blob 数据参与者/所有者”角色分配到该标识：

重要说明

只有分配“存储 Blob 数据参与者”或“存储 Blob 数据所有者”角色才能继续。

为 Azure AI 内容安全实例启用托管标识。
将“存储 Blob 数据参与者/所有者”角色分配给托管标识。下面突出显示的任何角色均有效。

在以下命令中，用自己的值替换 <your_api_key>、<your_endpoint> 和其他必要参数。然后，在终端窗口中输入每个命令并运行它。

创建新类别版本

curl -X PUT "<your_endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
            \"categoryName\": \"survival-advice\",
            \"definition\": \"text prompts about survival advice in camping/wilderness situations\",
            \"sampleBlobUrl\": \"https://<your-azure-storage-url>/example-container/survival-advice.jsonl\"
        }"

提示

每次更改类别名称、定义或示例时，都会创建新版本。可以使用版本号来追溯以前的版本。请记住此版本号，因为下一步（训练自定义类别）需要将其输入到 URL 中。

API 请求

字段	说明	示例值
`categoryName`	请求关联到的类别或主题的名称。	生存建议
`definition`	类别的内容类型的简短说明。	关于露营/荒野情况下生存建议的文本提示
`sampleBlobUrl`	用于访问包含类别数据示例的示例 JSONL 文件的 URL。	链接

API 响应

字段	说明	示例值
`categoryName`	响应关联到的类别或主题的名称。	生存建议
`definition`	类别的内容类型的简短说明。	关于露营/荒野情况下生存建议的文本提示
`sampleBlobUrl`	用于访问包含类别数据示例的示例 JSONL 文件的 URL。	链接
`sampleBlobSnapshotUrl`	示例 JSONL 文件的快照 URL，用于访问特定数据版本。	快照 URL
`version`	类别数据的版本号。	1
`createdTime`	创建类别数据时的时间戳。	2024-10-28T22：06：59.4626988Z
`status`	类别数据处理的当前状态。	已成功

启动类别生成过程

将 <your_api_key> 和 <your_endpoint> 替换为自己的值，并追加在上一步骤中获取的 URL 中的版本号。为模型训练留出足够的时间：自定义类别训练的端到端执行需要大约 5 到 10 小时。请相应地规划审核流程。收到响应后，将操作 ID（称为 id）存储在临时位置中。在下一部分中，使用获取状态 API 检索生成状态时，需要此 ID。

curl -X POST "<your_endpoint>/contentsafety/text/categories/survival-advice:build?api-version=2024-09-15-preview&version={version}" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

API 响应

字段	说明	示例值
`operation id`	用于检索生成状态的唯一标识符	b6c69dc1-2338-484e-85a5b-xxxxxxxxxxxx
`status`	请求的当前状态	已成功

获取类别生成状态

要检索状态，请使用从前一个 API 响应获取的 id，并将其置于以下 API 的路径中。

curl -X GET "<your_endpoint>/contentsafety/text/categories/operations/<id>?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

API 响应

字段	说明	示例值
`operation id`	用于检索生成状态的唯一标识符	b6c69dc1-2338-484e-855b-xxxxxxxxxxxx
`status`	请求的当前状态	已成功

使用自定义类别分析文本

运行以下命令，使用自定义类别分析文本。将 <your_api_key> 和 <your_endpoint> 替换为自己的值。

curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
            \"text\": \"<Example text to analyze>\",
            \"categoryName\": \"survival-advice\", 
            \"version\": 1
        }"

API 请求

字段	说明
`text`	用于类别检测的文本内容或消息
`categoryName`	要在其下检测到文本的类别的名称
`version`	类别的版本号

API 响应

字段	说明	示例值
`customCategoryAnalysis`	包含类别分析结果的对象。	—
`detected`	指示是否检测到指定的类别。	false

首先，需要安装所需的 Python 库：

pip install requests

然后，打开一个新的 Python 脚本，并使用自己的 Azure 资源详细信息定义必要的变量：

import requests

API_KEY = '<your_api_key>'
ENDPOINT = '<your_endpoint>'

headers = {
    'Ocp-Apim-Subscription-Key': API_KEY,
    'Content-Type': 'application/json'
}

创建新类别

可以使用类别名称、定义和 sample_blob_url 创建新类别，然后即可获得此类别的自动生成的版本号。

def create_new_category_version(category_name, definition, sample_blob_url):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
    data = {
        "categoryName": category_name,
        "definition": definition,
        "sampleBlobUrl": sample_blob_url
    }
    response = requests.put(url, headers=headers, json=data)
    return response.json()

# Replace the parameters with your own values
category_name = "survival-advice"
definition = "text prompts about survival advice in camping/wilderness situations"
sample_blob_url = "https://<your-azure-storage-url>/example-container/survival-advice.jsonl"

result = create_new_category_version(category_name, definition, sample_blob_url)
print(result)

启动类别生成过程

可以使用类别名称和版本号启动类别生成过程。为模型训练留出足够的时间：自定义类别训练的端到端执行需要大约 5 到 10 小时。请相应地规划审核流程。收到响应后，请确保将操作 ID（称为 id）存储在笔记本等位置。在下一部分中，使用 get_build_status 函数检索生成状态时，需要此 ID。

def trigger_category_build_process(category_name, version):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}:build?api-version=2024-09-15-preview&version={version}"
    response = requests.post(url, headers=headers)
    return response.status_code

# Replace the parameters with your own values
category_name = "survival-advice"
version = 1

result = trigger_category_build_process(category_name, version)
print(result)

获取类别生成状态：

要检索状态，请使用从前一个响应获取的 id。

def get_build_status(id):
    url = f"{ENDPOINT}/contentsafety/text/categories/operations/{id}?api-version=2024-09-15-preview"
    response = requests.get(url, headers=headers)
    return response.status_code

# Replace the parameter with your own value
id = "your-operation-id"

result = get_build_status(id)
print(result)

使用自定义类别分析文本

需要在推理过程中指定类别名称和版本号（可选；服务默认使用最新版本）。可以指定多个类别（如果已定义这些类别）。

def analyze_text_with_customized_category(text, category_name, version):
    url = f"{ENDPOINT}/contentsafety/text:analyzeCustomCategory?api-version=2024-09-15-preview"
    data = {
        "text": text,
        "categoryName": category_name,
        "version": version
    }
    response = requests.post(url, headers=headers, json=data)
    return response.json()

# Replace the parameters with your own values
text = "<Example text to analyze>"
category_name = "survival-advice"
version = 1

result = analyze_text_with_customized_category(text, category_name, version)
print(result)

其他自定义类别操作

请记住将下面的占位符替换为 API 密钥、终结点和特定内容（类别名称、定义等）的实际值。这些示例可帮助管理帐户中的自定义类别。

重要说明

请谨慎使用 API 密钥。请不要直接在代码中包含 API 密钥，并且切勿公开发布该密钥。如果使用 API 密钥，请将其安全地存储在 Azure Key Vault 中。若要详细了解如何在应用中安全地使用 API 密钥，请参阅 API 密钥与 Azure 密钥保管库。

有关 AI 服务安全性的详细信息，请参阅对 Azure AI 服务的请求进行身份验证。

cURL
Python

获取自定义类别或其特定版本

将占位符替换为自己的值，并在终端窗口中运行以下命令：

curl -X GET "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

将占位符替换为自己的值，并在终端窗口中运行以下命令：

curl -X GET "<endpoint>/contentsafety/text/categories?api-version=2024-09-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

删除自定义类别或其特定版本

将占位符替换为自己的值，并在终端窗口中运行以下命令：

curl -X DELETE "<endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-09-15-preview&version=1" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json"

首先，确保已安装所需的 Python 库：

pip install requests

然后，用自己的 AI 资源详细信息设置必要的配置：

import requests

API_KEY = '<your_api_key>'
ENDPOINT = '<your_endpoint>'

headers = {
    'Ocp-Apim-Subscription-Key': API_KEY,
    'Content-Type': 'application/json'
}

获取自定义类别或其特定版本

将占位符替换为自己的值，然后在 Python 脚本中运行以下代码：

def get_customized_category(category_name, version=None):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
    if version:
        url += f"&version={version}"
    
    response = requests.get(url, headers=headers)
    return response.json()

# Replace the parameters with your own values
category_name = "DrugAbuse"
version = 1

result = get_customized_category(category_name, version)
print(result)

def list_categories_latest_versions():
    url = f"{ENDPOINT}/contentsafety/text/categories?api-version=2024-09-15-preview"
    response = requests.get(url, headers=headers)
    return response.json()

result = list_categories_latest_versions()
print(result)

删除自定义类别或其特定版本

将占位符替换为自己的值，然后在 Python 脚本中运行以下代码：

def delete_customized_category(category_name, version=None):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
    if version:
        url += f"&version={version}"
    
    response = requests.delete(url, headers=headers)
    return response.status_code

# Replace the parameters with your own values
category_name = "<your_category_name>"
version = 1

result = delete_customized_category(category_name, version)
print(result)

反馈

此页面是否有帮助？

通过

快速入门：自定义类别（标准模式）（预览版）

Prerequisites

设置

使用自定义类别

Prerequisites

准备训练数据

授予存储访问权限

创建和训练自定义类别

创建新类别版本

API 请求

API 响应

启动类别生成过程

API 响应

获取类别生成状态

API 响应

使用自定义类别分析文本

API 请求

API 响应

其他自定义类别操作

获取自定义类别或其特定版本

列出其最新版本的类别

删除自定义类别或其特定版本

相关内容

反馈

其他资源