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

このガイドに従って、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 に割り当てます。

重要

次に進むことができるロールは、ストレージ BLOB データ共同作成者またはストレージ BLOB データ所有者のみです。

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

   

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

   

   

   

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

cURL

以下のコマンドでは、<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	カテゴリ データ処理の現在の状態。	Succeeded

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

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

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	要求の現在の状態	Succeeded

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

状態を取得するには、前回の 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	要求の現在の状態	Succeeded

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

以下のコマンドを実行して、カスタマイズしたカテゴリでテキストを分析します。 <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

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-09-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-09-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-09-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-09-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)

その他のカスタム カテゴリ操作

以下のプレースホルダーは、API キー、エンドポイント、および特定のコンテンツ (カテゴリ名、定義など) の実際の値に置き換えてください。 これらの例は、アカウントでカスタマイズされたカテゴリを管理するのに役立ちます。

cURL

カスタマイズされたカテゴリまたはその特定のバージョンを取得する

ターミナル ウィンドウでプレースホルダーを独自の値に置き換えて、次のコマンドを実行します。

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"

Python

まず、必須の Python ライブラリがインストールされていることを確認します。

pip install requests

次に、独自の AI リソースの詳細を使用して、必要な構成を設定します。

import requests

API_KEY = '<your_api_key>'
ENDPOINT = '<your_endpoint>'

headers = {
    'Ocp-Apim-Subscription-Key': API_KEY,
    'Content-Type': 'application/json'
}

カスタマイズされたカテゴリまたはその特定のバージョンを取得する

Python スクリプトでプレースホルダーを独自の値に置き換えて、次のコードを実行します。

def get_customized_category(category_name, version=None):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
    if version:
        url += f"&version={version}"
    
    response = requests.get(url, headers=headers)
    return response.json()

# Replace the parameters with your own values
category_name = "DrugAbuse"
version = 1

result = get_customized_category(category_name, version)
print(result)

最新バージョンのカテゴリを一覧表示する

def list_categories_latest_versions():
    url = f"{ENDPOINT}/contentsafety/text/categories?api-version=2024-09-15-preview"
    response = requests.get(url, headers=headers)
    return response.json()

result = list_categories_latest_versions()
print(result)

カスタマイズされたカテゴリまたはその特定のバージョンを削除する

Python スクリプトでプレースホルダーを独自の値に置き換えて、次のコードを実行します。

def delete_customized_category(category_name, version=None):
    url = f"{ENDPOINT}/contentsafety/text/categories/{category_name}?api-version=2024-09-15-preview"
    if version:
        url += f"&version={version}"
    
    response = requests.delete(url, headers=headers)
    return response.status_code

# Replace the parameters with your own values
category_name = "<your_category_name>"
version = 1

result = delete_customized_category(category_name, version)
print(result)

関連するコンテンツ

• カスタム カテゴリの概念
• Content Safety を使ってコンテンツをモデレートする