クイック スタート: カスタム カテゴリ (標準モード)

このガイドに従って、Azure AI Content Safety カスタム カテゴリ REST API を使用して、ユース ケースに応じた独自のコンテンツ カテゴリを作成し、新しいテキスト コンテンツでそれらを検出するよう Azure AI Content Safety をトレーニングします。

カスタム カテゴリの詳細については、カスタム カテゴリの概念に関するページを参照してください。 API 入力の制限については、「概要」の「入力の要件」セクションを参照してください。

重要

この機能は、特定の Azure リージョンでのみ使用できます。 利用可能なリージョンに関するページを参照してください。

重要

モデルのトレーニングには十分な時間を取ってください

カスタム カテゴリ トレーニングのエンド ツー エンドの実行には、5 時間から 10 時間程度かかる場合があります。 これを踏まえた上でモデレーション パイプラインを計画してください。

前提条件

• Azure サブスクリプション - 無料アカウントを作成します
• Azure サブスクリプションを入手したら、Azure portal で Content Safety リソースを作成し、キーとエンドポイントを取得します。 リソースの一意の名前を入力し、サブスクリプションを選択して、リソース グループ、サポートされているリージョン、サポートされている価格レベルを選択します。 [作成] を選択します。
  • リソースのデプロイには数分かかります。 完了したら、[リソースに移動] を選びます。 左ペインの [リソース管理] で、[サブスクリプション キーとエンドポイント] を選びます。 後で使用するために、エンドポイントといずれかのキー値を一時的な場所にコピーします。
• また、トレーニング注釈ファイルを保存する Azure Blob Storage コンテナーを作成します。
• 次のいずれかがインストールされていること。
  • REST API 呼び出し用の cURL。
  • Python 3.x がインストールされていること

トレーニング データを準備する

カスタム カテゴリをトレーニングするには、検出したいカテゴリを表したテキスト データの例が必要です。 このガイドでは、サンプル データを使用できます。 提供される注釈ファイルには、キャンプや野外といった状況でのサバイバル アドバイスに関するテキスト プロンプトが含まれています。 トレーニングされたモデルは、新しいテキスト データからこの種のコンテンツを検出するよう学習します。

ヒント

独自のデータ セットの作成に関するヒントについては、攻略ガイドを参照してください。

1. GitHub リポジトリからテキスト データのサンプル ファイルをダウンロードします。
2. .jsonl ファイルを Azure Storage アカウントの BLOB コンテナーにアップロードします。 後で使用するために、BLOB の URL を一時的な場所にコピーします。

ストレージ アクセスを許可する

次に、Azure Storage リソースからの読み取りアクセス権を Content Safety リソースに付与する必要があります。 Azure AI Content Safety インスタンスのシステム割り当てマネージド ID を有効にし、ストレージ BLOB データ共同作成者/所有者/閲覧者のロールをその ID に割り当てます。

1. Azure AI Content Safety インスタンスのマネージド ID を有効にします。

   

2. ストレージ BLOB データ共同作成者/所有者のロールをマネージド ID に割り当てます。 以下で強調表示されているロールはすべて機能するはずです。

   

   

   

カスタム モデルを作成してトレーニングする

cURL

以下のコマンドでは、<your_api_key>、<your_endpoint>、およびその他の必要なパラメーターを独自の値に置き換えます。 次に、各コマンドをターミナル ウィンドウに入力して実行します。

新しいカテゴリ バージョンを作成する

curl -X PUT "<your_endpoint>/contentsafety/text/categories/survival-advice?api-version=2024-02-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\"
        }"

カテゴリのビルド プロセスを開始する

<your_api_key> と <your_endpoint> を独自の値に置き換えます。 モデル トレーニングには十分な時間を取ってください。カスタム カテゴリ トレーニングのエンド ツー エンドの実行には、5 時間から 10 時間程度かかる場合があります。 これを踏まえた上でモデレーション パイプラインを計画してください。 応答を受信したら、操作 ID (id と呼ばれる) を一時的な場所に保存します。 この ID は、次のセクションで Get status API を使用してビルドの状態を取得するために必要になります。

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

カテゴリのビルド状態を取得する

状態を取得するには、前回の API 応答から取得した id を使用し、以下の API のパスに配置します。

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

カスタマイズしたカテゴリを使用してテキストを分析する

以下のコマンドを実行して、カスタマイズしたカテゴリでテキストを分析します。 <your_api_key> と <your_endpoint> を独自の値に置き換えます。

curl -X POST "<your_endpoint>/contentsafety/text:analyzeCustomCategory?api-version=2024-02-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
        }"

Python

まず、必須の 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-02-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 と呼ばれる) をノートブックなどに保存してください。 この ID は、次のセクションで 'get_build_status' 関数を使用してビルドの状態を取得するために必要になります。

def trigger_category_build_process(category_name, version):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}:build?api-version=2024-02-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-02-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-02-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)

関連するコンテンツ

• その他のカスタム カテゴリ操作の詳細については、攻略ガイドを参照してください。
• カスタム カテゴリの概念
• Content Safety を使ってコンテンツをモデレートする