Share via


快速入門:分析文字內容

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

注意

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

必要條件

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

分析文字內容

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

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

    提示

    文字大小和細微性

    文字提交的預設長度上限為 10K 個字元。

curl --location --request POST '<endpoint>/contentsafety/text:analyze?api-version=2023-10-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=2023-10-01。 範例: <endpoint>/contentsafety/text:analyze?api-version=2023-10-01 String

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

名稱 必要 描述 類型
text 必要 這是要檢查的原始文字。 可以包含其他非 ascii 字元。 String
categories 選擇性 假定這是類別名稱的陣列。 如需可用類別名稱的清單,請參閱危害類別指南。 如果未指定任何類別,則會使用這四個類別。 我們會使用多個類別來取得單一要求中的分數。 String
blocklistNames 選擇性 文字區塊名稱。 僅支援下列字元:0-9 A-Z a-z - . _ ~。 您可以在這裡附加多個清單名稱。 陣列
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 命令。

解譯 API 回應

您應該會在主控台輸出中看到顯示為 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。 選取 [安裝]。

建立環境變數

在此範例中,您會在執行應用程式的本機電腦上將認證寫入環境變數。

提示

請勿將金鑰直接包含在您的程式代碼中,且絕不會公開發佈。 如需更多驗證選項 (例如 Azure Key Vault),請參閱 Azure AI 服務安全性文章。

若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。

  1. 若要設定 CONTENT_SAFETY_KEY 環境變數,請將 取代 YOUR_CONTENT_SAFETY_KEY 為您資源的其中一個密鑰。
  2. 若要設定 CONTENT_SAFETY_ENDPOINT 環境變數,請將 取代 YOUR_CONTENT_SAFETY_ENDPOINT 為您資源的端點。
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" 取代為您想要使用的文字內容。

提示

文字大小和細微性

文字提交的預設長度上限為 10K 個字元。

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

參考文件 | 庫原始程式碼 | 套件 (PyPI)範例 | |

必要條件

  • Azure 訂用帳戶 - 建立免費帳戶
  • 擁有 Azure 訂用帳戶之後,在 Azure 入口網站中建立 Content Safety 資源,以取得您的金鑰和端點。 輸入資源的唯一名稱、選取您的訂用帳戶,然後選取資源群組、支援的區域(美國東部或西歐),以及支持的定價層。 然後選取建立
    • 部署資源需要幾分鐘的時間。 完成後,選取 [移至資源]。 在左側窗格中,於 [資源管理] 下選取 [訂用帳戶金鑰和端點]。 端點和其中一個金鑰是用以呼叫 API。
  • Python 3.x
    • 您的 Python 安裝應該包含 pip。 您可以藉由在命令列上執行 pip --version 來檢查您是否已安裝 pip。 安裝最新版本的 Python 以取得 pip。

建立環境變數

在此範例中,您會在執行應用程式的本機電腦上將認證寫入環境變數。

提示

請勿將金鑰直接包含在您的程式代碼中,且絕不會公開發佈。 如需更多驗證選項 (例如 Azure Key Vault),請參閱 Azure AI 服務安全性文章。

若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。

  1. 若要設定 CONTENT_SAFETY_KEY 環境變數,請將 取代 YOUR_CONTENT_SAFETY_KEY 為您資源的其中一個密鑰。
  2. 若要設定 CONTENT_SAFETY_ENDPOINT 環境變數,請將 取代 YOUR_CONTENT_SAFETY_ENDPOINT 為您資源的端點。
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" 取代為您想要使用的文字內容。

    提示

    文字大小和細微性

    文字提交的預設長度上限為 10K 個字元。

  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

流覽至新的資料夾,並建立名為 Content 保管庫 tyQuickstart.java 的檔案。

安裝用戶端 SDK

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

找出 build.gradle.kts ,並使用您慣用的 IDE 或文本編輯器加以開啟。 然後複製下列組建組態。 此組態會將項目定義為 Java 應用程式,其進入點為 Content 保管庫 tyQuickstart 類別。 它會匯入 Azure AI 視覺連結庫。

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

建立環境變數

在此範例中,您會在執行應用程式的本機電腦上將認證寫入環境變數。

提示

請勿將金鑰直接包含在您的程式代碼中,且絕不會公開發佈。 如需更多驗證選項 (例如 Azure Key Vault),請參閱 Azure AI 服務安全性文章。

若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。

  1. 若要設定 CONTENT_SAFETY_KEY 環境變數,請將 取代 YOUR_CONTENT_SAFETY_KEY 為您資源的其中一個密鑰。
  2. 若要設定 CONTENT_SAFETY_ENDPOINT 環境變數,請將 取代 YOUR_CONTENT_SAFETY_ENDPOINT 為您資源的端點。
setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

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

分析文字內容

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

提示

文字大小和細微性

文字提交的預設長度上限為 10K 個字元。

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 將會隨著相依性更新。

建立環境變數

在此範例中,您會在執行應用程式的本機電腦上將認證寫入環境變數。

提示

請勿將金鑰直接包含在您的程式代碼中,且絕不會公開發佈。 如需更多驗證選項 (例如 Azure Key Vault),請參閱 Azure AI 服務安全性文章。

若要設定金鑰和端點的環境變數,請開啟主控台視窗,然後遵循作業系統和開發環境的指示進行。

  1. 若要設定 CONTENT_SAFETY_KEY 環境變數,請將 取代 YOUR_CONTENT_SAFETY_KEY 為您資源的其中一個密鑰。
  2. 若要設定 CONTENT_SAFETY_ENDPOINT 環境變數,請將 取代 YOUR_CONTENT_SAFETY_ENDPOINT 為您資源的端點。
setx CONTENT_SAFETY_KEY 'YOUR_CONTENT_SAFETY_KEY'
setx CONTENT_SAFETY_ENDPOINT 'YOUR_CONTENT_SAFETY_ENDPOINT'

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

分析文字內容

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

提示

文字大小和細微性

文字提交的預設長度上限為 10K 個字元。

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 服務訂用帳戶,則可以刪除資源或資源群組。 刪除資源群組也會刪除與其相關聯的任何其他資源。

下一步

使用 Content Safety Studio 設定每個類別和測試資料集的篩選,匯出程式碼並部署。