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

快速入门:分析图像内容

开始使用 Content Studio、REST API 或客户端 SDK 来执行基本的文本审查。 Azure AI 内容安全服务为你提供用于标记不良内容的 AI 算法。 请按照以下步骤试用该环境。

有关图像审查的详细信息,请参阅危害类别概念页。 如需了解 API 输入限制,请参阅“概述”的输入要求部分。

注意

示例数据和代码可能包含冒犯性内容。 建议用户自行决定。

先决条件

  • Azure 订阅 - 免费创建订阅
  • 拥有 Azure 订阅后,请在 Azure 门户中创建 Content Safety 资源 ,以获取密钥和终结点。 输入资源的唯一名称,选择订阅,并选择资源组、支持的区域(请参阅上市区域)和支持的定价层。 然后选择“创建”。
    • 部署资源需要几分钟时间。 完成后,选择“转到资源”。 在左侧窗格中的“资源管理”下,选择“订阅密钥和终结点”。 终结点和任一密钥都用于调用 API。
  • 已安装 cURL

分析图像内容

下一部分介绍使用 cURL 进行图像审查的示例。

准备图像示例

选择要分析的示例图像,并将其下载到设备。

有关图像限制,请参阅输入要求。 如果格式已进行动画处理,服务将提取第一帧执行分析。

可以通过以下两种方法之一输入图像:本地文件流或 Blob 存储 URL。

  • 本地文件流(推荐):将图像编码为 Base64。 可以使用 codebeautify 等网站来执行编码。 然后将编码的字符串保存到临时位置。

  • Blob 存储 URL:将图像上传到 Azure Blob 存储帐户。 点击 Blob 存储快速入门了解如何执行此操作。 然后打开 Azure 存储资源管理器并获取图像的 URL。 将其保存到临时位置。

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

    重要

    只有存储 Blob 数据参与者或存储 Blob 数据所有者是可以继续操作的有效角色

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

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

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

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

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

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

分析图像内容

将以下命令粘贴到文本编辑器,并进行以下更改。

  1. <endpoint> 替换为资源终结点 URL。
  2. <your_subscription_key> 替换为你的密钥。
  3. 使用 "content" 字段或 "blobUrl" 字段填充正文中的 "image" 字段。 例如 {"image": {"content": "<base_64_string>"}{"image": {"blobUrl": "<your_storage_url>"}
curl --location --request POST '<endpoint>/contentsafety/image:analyze?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "image": {
    "content": "<base_64_string>"
  },
  "categories": ["Hate", "SelfHarm", "Sexual", "Violence"],
  "outputType": "FourSeverityLevels"
}'

注意

如果使用的是 Blob 存储 URL,则请求主体应如下所示:

{
  "image": {
    "blobUrl": "<your_storage_url>"
  }
}

URL 中必须包含以下字段:

名称 必需? 说明 类型
API 版本 必需 这是要检查的 API 版本。 当前版本为:api-version=2024-09-01。 示例: <endpoint>/contentsafety/image:analyze?api-version=2024-09-01 字符串

请求正文中的参数在此表中定义:

名称 必需? 说明 类型
content 必须 图像的内容或 Blob URL。 可以是 Base64 编码的字节或 Blob URL。 如果同时提供两者,则会拒绝该请求。 图像允许的最大大小为 7200x7200 像素,最大文件大小为 4MB。 图像的最小大小为 50 像素 x 50 像素。 字符串
categories 可选 假定这是类别名称的数组。 有关可用categories名称的列表,请参阅危害类别指南。 如果未指定categories,则使用所有四个categories。 我们使用多个类别在单个请求中获取分数。 字符串
outputType 可选 图像审查 API 仅支持 "FourSeverityLevels"。 输出严重性分为四个级别。 该值可以为 0,2,4,6 字符串

打开命令提示符窗口并运行 cURL 命令。

输出

应会在控制台中看到显示为 JSON 数据的图像审查结果。 例如:

{
  "categoriesAnalysis": [
    {
      "category": "Hate",
      "severity": 2
    },
    {
      "category": "SelfHarm",
      "severity": 0
    },
    {
      "category": "Sexual",
      "severity": 0
    },
    {
      "category": "Violence",
      "severity": 0
    }
  ]
}

输出中的 JSON 字段定义如下:

名称 说明 类型
categoriesAnalysis API 预测的每个输出类。 分类可以是多标记的。 例如,将图像上传到图像审查模型时,可以将其归类为性内容和暴力。 有害categories 字符串
严重性 每个危害类别中标志的严重性级别。 有害categories Integer

参考文档 | 库源代码 | 包 (NuGet) | 示例

先决条件

  • Azure 订阅 - 免费创建订阅
  • 启用了“.NET 桌面开发”工作负载的 Visual Studio IDE。 或者,如果你不打算使用 Visual Studio IDE,则需要当前版本的 .NET Core
  • 已安装 .NET 运行时
  • 拥有 Azure 订阅后,请在 Azure 门户中创建 Content Safety 资源 ,以获取密钥和终结点。 输入资源的唯一名称,选择订阅,并选择资源组、支持的区域(请参阅上市区域)和支持的定价层。 然后选择“创建”。
    • 部署资源需要几分钟时间。 完成后,选择“转到资源”。 在左侧窗格中的“资源管理”下,选择“订阅密钥和终结点”。 终结点和任一密钥都用于调用 API。

设置应用程序

创建一个新的 C# 应用程序。

打开 Visual Studio,在“开始”下选择“创建新项目”。 将模板筛选器设置为 C#/所有平台/控制台。 选择“控制台应用”(可在 Windows、Linux 和 macOS 版 .NET 上运行的命令行应用程序),然后选择“下一步”。 将项目名称更新为 ContentSafetyQuickstart,然后选择“下一步”。 选择“.NET 6.0”或更高版本,然后选择“创建”以创建项目。

安装客户端 SDK

创建新项目后,右键单击“解决方案资源管理器”中的项目解决方案,然后选择“管理 NuGet 包”,以安装客户端 SDK。 在打开的包管理器中选择“浏览”,搜索 Azure.AI.ContentSafety。 选择“安装” 。

创建环境变量

在此示例中,你将凭据写入运行应用程序的本地计算机上的环境变量。

若要为密钥和终结点设置环境变量,请打开控制台窗口,并按照操作系统和开发环境的说明进行操作。

  • 若要设置 CONTENT_SAFETY_KEY 环境变量,请将 YOUR_CONTENT_SAFETY_KEY 替换为资源的其中一个密钥。
  • 若要设置 CONTENT_SAFETY_ENDPOINT 环境变量,请将 YOUR_CONTENT_SAFETY_ENDPOINT 替换为资源的终结点。

重要

如果使用 API 密钥,请将其安全地存储在某个其他位置,例如 Azure Key Vault 中。 请不要直接在代码中包含 API 密钥,并且切勿公开发布该密钥。

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

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后,可能需要重启任何正在运行的、将读取环境变量的程序(包括控制台窗口)。

分析图像内容

从项目目录中,打开以前创建的 Program.cs 文件。 粘贴到以下代码中。

using System;
using Azure.AI.ContentSafety;

namespace Azure.AI.ContentSafety.Dotnet.Sample
{
  class ContentSafetySampleAnalyzeImage
  {
    public static void AnalyzeImage()
    {
      // retrieve the endpoint and key from the environment variables created earlier
      string endpoint = Environment.GetEnvironmentVariable("CONTENT_SAFETY_ENDPOINT");
      string key = Environment.GetEnvironmentVariable("CONTENT_SAFETY_KEY");

      ContentSafetyClient client = new ContentSafetyClient(new Uri(endpoint), new AzureKeyCredential(key));

      // Example: analyze image

      string imagePath = @"sample_data\image.png";
      ContentSafetyImageData image = new ContentSafetyImageData(BinaryData.FromBytes(File.ReadAllBytes(imagePath)));

      var request = new AnalyzeImageOptions(image);

      Response<AnalyzeImageResult> response;
      try
      {
          response = client.AnalyzeImage(request);
      }
      catch (RequestFailedException ex)
      {
          Console.WriteLine("Analyze image failed.\nStatus code: {0}, Error code: {1}, Error message: {2}", ex.Status, ex.ErrorCode, ex.Message);
          throw;
      }

      Console.WriteLine("Hate severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == ImageCategory.Hate)?.Severity ?? 0);
      Console.WriteLine("SelfHarm severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == ImageCategory.SelfHarm)?.Severity ?? 0);
      Console.WriteLine("Sexual severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == ImageCategory.Sexual)?.Severity ?? 0);
      Console.WriteLine("Violence severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == ImageCategory.Violence)?.Severity ?? 0);
    }
    static void Main()
    {
      AnalyzeImage();
    }
  }
}

在项目目录中创建 sample_data 文件夹,并将 image.png 文件添加到其中。

从 IDE 窗口顶部的“调试”菜单中选择“开始调试”(或按 F5),以生成并运行应用程序。

参考文档 | 库源代码 | 包 (PyPI) | 示例 |

先决条件

  • Azure 订阅 - 免费创建订阅
  • 拥有 Azure 订阅后,请在 Azure 门户中创建 Content Safety 资源 ,以获取密钥和终结点。 输入资源的唯一名称,选择订阅,并选择资源组、支持的区域(请参阅上市区域)和支持的定价层。 然后选择“创建”。
    • 部署资源需要几分钟时间。 完成后,选择“转到资源”。 在左侧窗格中的“资源管理”下,选择“订阅密钥和终结点”。 终结点和任一密钥都用于调用 API。
  • Python 3.8 或更高版本
    • 你的 Python 安装应包含 pip。 可以通过在命令行上运行 pip --version 来检查是否安装了 pip。 通过安装最新版本的 Python 获取 pip。

创建环境变量

在此示例中,你将凭据写入运行应用程序的本地计算机上的环境变量。

若要为密钥和终结点设置环境变量,请打开控制台窗口,并按照操作系统和开发环境的说明进行操作。

  • 若要设置 CONTENT_SAFETY_KEY 环境变量,请将 YOUR_CONTENT_SAFETY_KEY 替换为资源的其中一个密钥。
  • 若要设置 CONTENT_SAFETY_ENDPOINT 环境变量,请将 YOUR_CONTENT_SAFETY_ENDPOINT 替换为资源的终结点。

重要

如果使用 API 密钥,请将其安全地存储在某个其他位置,例如 Azure Key Vault 中。 请不要直接在代码中包含 API 密钥,并且切勿公开发布该密钥。

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

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后,可能需要重启任何正在运行的、将读取环境变量的程序(包括控制台窗口)。

分析图像内容

下一部分介绍使用 Python SDK 进行请求的示例。

  1. 打开命令提示符,导航到项目文件夹,并创建一个名为 quickstart.py 的新文件。

  2. 运行以下命令以安装 Azure AI Content Safety 客户端库:

    python -m pip install azure-ai-contentsafety
    
  3. 将以下代码复制到 quickstart.py 中:

    import os
    
    from azure.ai.contentsafety import ContentSafetyClient
    from azure.ai.contentsafety.models import AnalyzeImageOptions, ImageData, ImageCategory
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError
    
    def analyze_image():
        endpoint = os.environ.get('CONTENT_SAFETY_ENDPOINT')
        key = os.environ.get('CONTENT_SAFETY_KEY')
        image_path = os.path.join("sample_data", "image.jpg")
    
        # Create an Azure AI 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}")
    
    if __name__ == "__main__":
        analyze_image()
    
  4. "sample_data""image.jpg" 替换为要使用的本地文件的路径和文件名。

  5. 然后,使用快速入门文件中的 python 命令运行应用程序。

    python quickstart.py
    

参考文档 | 库源代码 | 项目 (Maven) | 示例

先决条件

  • Azure 订阅 - 免费创建订阅
  • 最新版的 Java 开发工具包 (JDK)
  • Gradle 生成工具,或其他依赖项管理器。
  • 拥有 Azure 订阅后,请在 Azure 门户中创建 Content Safety 资源 ,以获取密钥和终结点。 输入资源的唯一名称,选择订阅,并选择资源组、支持的区域(请参阅上市区域)和支持的定价层。 然后选择“创建”。
    • 部署资源需要几分钟时间。 完成后,选择“转到资源”。 在左侧窗格中的“资源管理”下,选择“订阅密钥和终结点”。 终结点和任一密钥都用于调用 API。

设置应用程序

创建一个新的 Gradle 项目。

在控制台窗口(例如 cmd、PowerShell 或 Bash)中,为应用创建一个新目录并导航到该目录。

mkdir myapp && cd myapp

从工作目录运行 gradle init 命令。 此命令将创建 Gradle 的基本生成文件,包括 build.gradle.kts,在运行时将使用该文件创建并配置应用程序。

gradle init --type basic

当提示你选择一个 DSL 时,选择 Kotlin

从工作目录运行以下命令,以创建项目源文件夹:

mkdir -p src/main/java

导航到新文件夹,创建名为 ContentSafetyQuickstart.java 的文件

此外,在项目的根目录中创建 src/resources 文件夹,并向其添加示例图像。

安装客户端 SDK

本快速入门使用 Gradle 依赖项管理器。 可以在 Maven 中央存储库中找到客户端库以及其他依赖项管理器的信息。

找到 build.gradle.kts,并使用喜好的 IDE 或文本编辑器将其打开。 然后在该文件中复制以下生成配置。 此配置将项目定义一个 Java 应用程序,其入口点为 ContentSafetyQuickstart 类。 它会导入 Azure AI 视觉库。

plugins {
    java
    application
}
application { 
    mainClass.set("ContentSafetyQuickstart")
}
repositories {
    mavenCentral()
}
dependencies {
    implementation(group = "com.azure", name = "azure-ai-contentsafety", version = "1.0.0")
}

创建环境变量

在此示例中,你将凭据写入运行应用程序的本地计算机上的环境变量。

若要为密钥和终结点设置环境变量,请打开控制台窗口,并按照操作系统和开发环境的说明进行操作。

  • 若要设置 CONTENT_SAFETY_KEY 环境变量,请将 YOUR_CONTENT_SAFETY_KEY 替换为资源的其中一个密钥。
  • 若要设置 CONTENT_SAFETY_ENDPOINT 环境变量,请将 YOUR_CONTENT_SAFETY_ENDPOINT 替换为资源的终结点。

重要

如果使用 API 密钥,请将其安全地存储在某个其他位置,例如 Azure Key Vault 中。 请不要直接在代码中包含 API 密钥,并且切勿公开发布该密钥。

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

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后,可能需要重启任何正在运行的、将读取环境变量的程序(包括控制台窗口)。

分析图像内容

在首选编辑器或 IDE 中打开 ContentSafetyQuickstart.java,并粘贴以下代码。source 变量替换为示例图像的路径。

import com.azure.ai.contentsafety.ContentSafetyClient;
import com.azure.ai.contentsafety.ContentSafetyClientBuilder;
import com.azure.ai.contentsafety.models.AnalyzeImageOptions;
import com.azure.ai.contentsafety.models.AnalyzeImageResult;
import com.azure.ai.contentsafety.models.ContentSafetyImageData;
import com.azure.ai.contentsafety.models.ImageCategoriesAnalysis;
import com.azure.core.credential.KeyCredential;
import com.azure.core.util.BinaryData;
import com.azure.core.util.Configuration;

import java.io.IOException;
import java.nio.file.Files;
import java.nio.file.Paths;


public class ContentSafetyQuickstart {
    public static void main(String[] args) throws IOException {

        // get endpoint and key from environment variables
        String endpoint = System.getenv("CONTENT_SAFETY_ENDPOINT");
        String key = System.getenv("CONTENT_SAFETY_KEY");

        ContentSafetyClient contentSafetyClient = new ContentSafetyClientBuilder()
            .credential(new KeyCredential(key))
            .endpoint(endpoint).buildClient();

        ContentSafetyImageData image = new ContentSafetyImageData();
        String cwd = System.getProperty("user.dir");
        String source = "/src/samples/resources/image.png";

        image.setContent(BinaryData.fromBytes(Files.readAllBytes(Paths.get(cwd, source))));

        AnalyzeImageResult response =
                contentSafetyClient.analyzeImage(new AnalyzeImageOptions(image));

        for (ImageCategoriesAnalysis result : response.getCategoriesAnalysis()) {
            System.out.println(result.getCategory() + " severity: " + result.getSeverity());
        }
    }
}

导航回项目根文件夹,并通过以下内容生成应用:

gradle build

然后,使用 gradle run 命令运行应用:

gradle run

输出

Hate severity: 0
SelfHarm severity: 0
Sexual severity: 0
Violence severity: 0

参考文档 | 库源代码 | 包 (npm) | 示例 |

先决条件

  • Azure 订阅 - 免费创建订阅
  • 最新版本的 Node.js
  • 拥有 Azure 订阅后,请在 Azure 门户中创建 Content Safety 资源 ,以获取密钥和终结点。 输入资源的唯一名称,选择订阅,并选择资源组、支持的区域(请参阅上市区域)和支持的定价层。 然后选择“创建”。
    • 部署资源需要几分钟时间。 完成后,选择“转到资源”。 在左侧窗格中的“资源管理”下,选择“订阅密钥和终结点”。 终结点和任一密钥都用于调用 API。

设置应用程序

创建新的 Node.js 应用程序。 在控制台窗口(例如 cmd、PowerShell 或 Bash)中,为应用创建一个新目录并导航到该目录。

mkdir myapp && cd myapp

运行 npm init 命令以使用 package.json 文件创建一个 node 应用程序。

npm init

此外,在项目的根目录中创建 /resources 文件夹,并向其添加示例图像。

安装客户端 SDK

安装 @azure-rest/ai-content-safety npm 包:

npm install @azure-rest/ai-content-safety

另请安装 dotenv 模块以使用环境变量:

npm install dotenv

应用的 package.json 文件将使用依赖项进行更新。

创建环境变量

在此示例中,你将凭据写入运行应用程序的本地计算机上的环境变量。

若要为密钥和终结点设置环境变量,请打开控制台窗口,并按照操作系统和开发环境的说明进行操作。

  • 若要设置 CONTENT_SAFETY_KEY 环境变量,请将 YOUR_CONTENT_SAFETY_KEY 替换为资源的其中一个密钥。
  • 若要设置 CONTENT_SAFETY_ENDPOINT 环境变量,请将 YOUR_CONTENT_SAFETY_ENDPOINT 替换为资源的终结点。

重要

如果使用 API 密钥,请将其安全地存储在某个其他位置,例如 Azure Key Vault 中。 请不要直接在代码中包含 API 密钥,并且切勿公开发布该密钥。

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

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

添加环境变量后,可能需要重启任何正在运行的、将读取环境变量的程序(包括控制台窗口)。

分析图像内容

在目录中创建新文件 index.js。 在偏好的编辑器或 IDE 中打开它,并粘贴以下代码。 将 image_path 变量替换为示例图像的路径。

const ContentSafetyClient = require("@azure-rest/ai-content-safety").default,
  { isUnexpected } = require("@azure-rest/ai-content-safety");
const { AzureKeyCredential } = require("@azure/core-auth");
const fs = require("fs");
const path = require("path");

// Load the .env file if it exists
require("dotenv").config();

async function main() {
    // get endpoint and key from environment variables
    const endpoint = process.env["CONTENT_SAFETY_ENDPOINT"];
    const key = process.env["CONTENT_SAFETY_KEY"];
    
    const credential = new AzureKeyCredential(key);
    const client = ContentSafetyClient(endpoint, credential);
    
    // replace with your own sample image file path 
    const image_path = path.resolve(__dirname, "./resources/image.jpg");
    
    const imageBuffer = fs.readFileSync(image_path);
    const base64Image = imageBuffer.toString("base64");
    const analyzeImageOption = { image: { content: base64Image } };
    const analyzeImageParameters = { body: analyzeImageOption };
    
    const result = await client.path("/image:analyze").post(analyzeImageParameters);
    
    if (isUnexpected(result)) {
        throw result;
    }
    for (let i = 0; i < result.body.categoriesAnalysis.length; i++) {
    const imageCategoriesAnalysisOutput = result.body.categoriesAnalysis[i];
    console.log(
      imageCategoriesAnalysisOutput.category,
      " severity: ",
      imageCategoriesAnalysisOutput.severity
    );
  }
}

main().catch((err) => {
    console.error("The sample encountered an error:", err);
});

在快速入门文件中使用 node 命令运行应用程序。

node index.js

输出

Hate severity:  0
SelfHarm severity:  0
Sexual severity:  0
Violence severity:  0

清理资源

如果想要清理并移除 Azure AI 服务订阅,可以删除资源或资源组。 删除资源组同时也会删除与之相关联的任何其他资源。