共用方式為


快速入門:分析文字內容

開始使用 Content Safety Studio、REST API 或用戶端 SDK 來執行基本文字調節。 Azure AI 內容安全服務提供 AI 演算法來標記令人反感的內容。 請遵循下列步驟來試用。

如需有關文字審核的詳細資訊,請參閱有害類別概念頁面。 關於 API 輸入限制,請參閱概觀的輸入要求一節。

注意

樣本資料和程式碼可能包含冒犯性內容。 建議使用者斟酌使用。

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入您資源的唯一名稱,選取您的訂用帳戶,然後選取資源群組、支援的區域 (參閱區域可用性) 以及支援的定價層。 然後選取建立
    • 部署資源需要幾分鐘的時間。 完成後,選取 [移至資源]。 在左側窗格中,於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 端點和其中一個金鑰是用以呼叫 API。
  • 已安裝 cURL

分析文字內容

下一節會逐步解說 cURL 的範例要求。 將下列命令貼上至文字編輯器,並進行下列變更。

  1. <endpoint> 取代為與資源相關聯的端點 URL。
  2. <your_subscription_key> 取代為資源自帶的金鑰之一。
  3. 或者,將本文中的 "text" 欄位取代為您要分析的文字。

    提示

    文字大小和細微性

    如需文字長度上限,請參閱輸入需求

curl --location --request POST '<endpoint>/contentsafety/text:analyze?api-version=2024-09-01' \
--header 'Ocp-Apim-Subscription-Key: <your_subscription_key>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "text": "I hate you",
  "categories": ["Hate", "Sexual", "SelfHarm", "Violence"],
  "blocklistNames": ["string"],
  "haltOnBlocklistHit": true,
  "outputType": "FourSeverityLevels"
}'

下欄欄位必須包含在 URL 中:

名稱 必要 描述 類型
API 版本 必要 這是要檢查的 API 版本。 目前的版本為:api-version=2024-09-01。 範例: <endpoint>/contentsafety/text:analyze?api-version=2024-09-01 String

要求本文中的參數在此表中定義:

名稱 必要 描述 類型
text 必要 這是要檢查的原始文字。 可以包含其他非 ascii 字元。 String
categories 選擇性 假定這是類別名稱的陣列。 如需可用類別名稱的清單,請參閱危害類別指南。 如果未指定任何類別,則會使用這四個類別。 我們使用多個類別來取得單一要求中的分數。 String
blocklistNames 選擇性 文字區塊名稱。 僅支援下列字元:0-9 A-Z a-z - . _ ~。 您可以在這裡附加多個清單名稱。 Array
haltOnBlocklistHit 選擇性 當設定為 true 時,在封鎖清單被叫用的情況下,將不會針對有害內容執行進一步分析。 當設定為 false 時,無論在封鎖清單是否被叫用的情況下,將會針對所有有害內容的進一步執行分析。 布林值
outputType 選擇性 "FourSeverityLevels""EightSeverityLevels"。 四或八個層級的輸出嚴重性,此值可以是 0,2,4,60,1,2,3,4,5,6,7 String

請參閱下列範例要求本文:

{
  "text": "I hate you",
  "categories": ["Hate", "Sexual", "SelfHarm", "Violence"],
  "blocklistNames": ["array"],
  "haltOnBlocklistHit": false,
  "outputType": "FourSeverityLevels"
}

開啟命令提示視窗,貼上已編輯的 cURL 命令,然後執行它。

輸出

您應該會在主控台輸出中看到顯示為 JSON 資料的文字調節結果。 例如:

{
  "blocklistsMatch": [
    {
      "blocklistName": "string",
      "blocklistItemId": "string",
      "blocklistItemText": "string"
    }
  ],
  "categoriesAnalysis": [
    {
      "category": "Hate",
      "severity": 2
    },
    {
      "category": "SelfHarm",
      "severity": 0
    },
    {
      "category": "Sexual",
      "severity": 0
    },
    {
      "category": "Violence",
      "severity": 0
    }
  ]
}

輸出中的 JSON 欄位定義如下:

名稱 描述 類型
categoriesAnalysis API 預測的每個輸出類別。 分類可以為多標籤的。 例如,當文字範例透過文字調節模型執行時,可以同時分類為性內容和暴力內容。 傷害類別 String
嚴重性 輸入內容的嚴重性越高,這個值就越大。 整數

參考文件 | 程式庫來源程式碼 | 套件 (NuGet) | 範例

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 已啟用具有工作負載 .NET 桌面開發的 Visual Studio 整合式開發環境 (IDE)。 或者,如果您不打算使用 Visual Studio 整合式開發環境 (IDE),則您需要目前的 .NET Core 版本。
  • 擁有 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 金鑰,且切勿公開張貼金鑰。

如需 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 ContentSafetySampleAnalyzeText
  {
    public static void AnalyzeText()
    {
      // 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));

      string text = "Your input text";

      var request = new AnalyzeTextOptions(text);

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

      Console.WriteLine("\nAnalyze text succeeded:");
      Console.WriteLine("Hate severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == TextCategory.Hate)?.Severity ?? 0);
      Console.WriteLine("SelfHarm severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == TextCategory.SelfHarm)?.Severity ?? 0);
      Console.WriteLine("Sexual severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == TextCategory.Sexual)?.Severity ?? 0);
      Console.WriteLine("Violence severity: {0}", response.Value.CategoriesAnalysis.FirstOrDefault(a => a.Category == TextCategory.Violence)?.Severity ?? 0);

    }
    static void Main()
    {
        AnalyzeText();
    }
  }
}

"Your input text" 取代為您想要使用的文字內容。

提示

文字大小和細微性

如需文字長度上限,請參閱輸入需求

從 IDE 視窗頂端的 [偵錯] 功能表選取 [開始偵錯] (或按 F5) 來建置並執行應用程式。

參考文件 | 程式庫來源程式碼 | 套件 (PyPI) | 範例 |

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入您資源的唯一名稱,選取您的訂用帳戶,然後選取資源群組、支援的區域 (參閱區域可用性) 以及支援的定價層。 然後選取建立
    • 部署資源需要幾分鐘的時間。 完成後,選取 [移至資源]。 在左側窗格中,於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 端點和其中一個金鑰是用以呼叫 API。
  • Python 3.x
    • 您安裝的 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 金鑰,且切勿公開張貼金鑰。

如需 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 程式庫:

    pip install azure-ai-contentsafety
    
  3. 將下列程式碼複製到 quickstart.py

    import os
    from azure.ai.contentsafety import ContentSafetyClient
    from azure.core.credentials import AzureKeyCredential
    from azure.core.exceptions import HttpResponseError
    from azure.ai.contentsafety.models import AnalyzeTextOptions, TextCategory
    
    def analyze_text():
        # analyze text
        key = os.environ["CONTENT_SAFETY_KEY"]
        endpoint = os.environ["CONTENT_SAFETY_ENDPOINT"]
    
        # Create an Azure AI Content Safety client
        client = ContentSafetyClient(endpoint, AzureKeyCredential(key))
    
        # Contruct request
        request = AnalyzeTextOptions(text="Your input text")
    
        # 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}")
    
    if __name__ == "__main__":
        analyze_text()
    
  4. "Your input text" 取代為您想要使用的文字內容。

    提示

    文字大小和細微性

    如需文字長度上限,請參閱輸入需求

  5. 然後使用快速入門檔案上的 python 命令執行應用程式。

    python quickstart.py
    

參考文件 | 程式庫原始程式碼 | 成品 (Maven) | 範例

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 最新版的 Java Development Kit (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 的檔案。

安裝用戶端 SDK

本快速入門會使用 Gradle 相依性管理員。 您可以在 Maven 中央存放庫中找到用戶端程式庫和其他相依性管理員的資訊。

找出 build.gradle.kts,並使用您慣用的 IDE 或文字編輯器加以開啟。 然後,在其中複製下列組建組態。 此組態會將專案定義為進入點為 ContentSafetyQuickstart 類別的 Java 應用程式。 它會匯入 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 金鑰,且切勿公開張貼金鑰。

如需 AI 服務安全性的詳細資訊,請參閱驗證對 Azure AI 服務的要求 (英文)。

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。

分析文字內容

在慣用的編輯器或 IDE 中開啟 ContentSafetyQuickstart.java,並貼上下列程式碼。 將 <your text sample> 取代為您想要使用的文字內容。

提示

文字大小和細微性

如需文字長度上限,請參閱輸入需求

import com.azure.ai.contentsafety.ContentSafetyClient;
import com.azure.ai.contentsafety.ContentSafetyClientBuilder;
import com.azure.ai.contentsafety.models.AnalyzeTextOptions;
import com.azure.ai.contentsafety.models.AnalyzeTextResult;
import com.azure.ai.contentsafety.models.TextCategoriesAnalysis;
import com.azure.core.credential.KeyCredential;
import com.azure.core.util.Configuration;


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

        // 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();

        AnalyzeTextResult response = contentSafetyClient.analyzeText(new AnalyzeTextOptions("<your text sample>"));

        for (TextCategoriesAnalysis 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 檔案建立節點應用程式。

npm init

安裝用戶端 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 金鑰,且切勿公開張貼金鑰。

如需 AI 服務安全性的詳細資訊,請參閱驗證對 Azure AI 服務的要求 (英文)。

setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

新增環境變數之後,您可能需要重新啟動任何將讀取環境變數的執行中程式,包括主控台視窗。

分析文字內容

在目錄建立新的檔案 index.js。 在您慣用的編輯器或 IDE 中開啟該檔案,並貼上下列程式碼。 將 <your text sample> 取代為您想要使用的文字內容。

提示

文字大小和細微性

如需文字長度上限,請參閱輸入需求

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

// 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 text string 
    const text = "<your sample text>";
    const analyzeTextOption = { text: text };
    const analyzeTextParameters = { body: analyzeTextOption };
    
    const result = await client.path("/text:analyze").post(analyzeTextParameters);
    
    if (isUnexpected(result)) {
        throw result;
    }
    
    for (let i = 0; i < result.body.categoriesAnalysis.length; i++) {
    const textCategoriesAnalysisOutput = result.body.categoriesAnalysis[i];
    console.log(
      textCategoriesAnalysisOutput.category,
      " severity: ",
      textCategoriesAnalysisOutput.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 服務訂用帳戶,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。