通过

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

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

  • 项目

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

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

重要

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

重要

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

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

先决条件

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

准备训练数据

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

提示

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

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

重要

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

授予存储访问权限

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

重要

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

  1. 为 Azure AI Content Safety 实例启用托管标识。

    启用托管标识的 Azure 门户的屏幕截图。

  2. 将“存储 Blob 数据参与者/所有者”角色分配给托管标识。 下面突出显示的任何角色均有效。

    Azure 门户中“添加角色分配”屏幕的屏幕截图。

    Azure 门户中分配的角色的屏幕截图。

    托管标识角色的屏幕截图。

创建和训练自定义类别

在以下命令中，用自己的值替换 <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 请求关联到的类别或主题的名称。 survival-advice
definition 类别的内容类型的简短说明。 关于露营/荒野情况下生存建议的文本提示
sampleBlobUrl 用于访问包含类别数据示例的示例 JSONL 文件的 URL。 链接。

API 响应

字段 说明 示例值
categoryName 响应关联到的类别或主题的名称。 survival-advice
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

其他自定义类别操作

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

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

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

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"

相关内容