カスタム カテゴリ (標準) API を使用する

カスタム カテゴリ (標準) API を使用すると、ユース ケース用に独自のコンテンツ カテゴリを作成し、新しいコンテンツでそれを検出できるように Azure AI Content Safety をトレーニングできます。

重要

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

注意事項

このガイドのサンプル データには、不快なコンテンツが含まれている可能性があります。 ユーザーの裁量が推奨されます。

前提条件

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

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

カスタム カテゴリをトレーニングするには、検出したいカテゴリを表すテキスト データの例が必要です。 サンプル データを準備するには、次の手順に従います。

1. サンプル データを収集するか書き込みます。

   • トレーニングによって効果的なモデルを作成するには、サンプル データの品質が重要です。 特定したいコンテンツを正確に表す正のサンプルを少なくとも 50 個収集することを目指します。 これらのサンプルは、明確かつ多様で、カテゴリ定義に直接関連している必要があります。
   • 負のサンプルは必須ではありませんが、関連するコンテンツと、関連のないコンテンツを区別するモデルの能力を向上させることができます。 パフォーマンスを向上させるには、正のケース定義に関連しないサンプルを 50 個集めることを目指します。 これらは多様である必要がありますが、モデルが遭遇するコンテンツのコンテキストに沿ったものでなければなりません。 負のサンプルを慎重に選択して、正のカテゴリと誤って重複しないようにします。
   • 正と負のサンプル数のバランスを取るようにします。 データセットが不均一だとモデルに偏りが出てくることがあるため、ある種類の分類が別の種類よりも優先され、擬陽性や偽陰性の割合が高くなる可能性があります。

2. テキスト エディターを使用して、.jsonl ファイル内のデータを書式設定します。 以下に、適切な書式設定の例を示します。 カテゴリの例では、isPositive を true に設定する必要があります。 負の例は省略可能ですが、パフォーマンスを向上させることができます。

   {"text": "This is the 1st sample.", "isPositive": true}
   {"text": "This is the 2nd sample.", "isPositive": true}
   {"text": "This is the 3rd sample (negative).", "isPositive": false}
   

3. .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 に割り当てます。 以下で強調表示されているロールはすべて機能するはずです。

   

   

   

カスタム カテゴリを作成してトレーニングする

重要

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

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

• サンプル データの収集と準備
• トレーニング プロセス
• モデルの評価と調整

cURL

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

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

curl -X PUT "<your_endpoint>/contentsafety/text/categories/<your_category_name>?api-version=2024-02-15-preview" \
     -H "Ocp-Apim-Subscription-Key: <your_api_key>" \
     -H "Content-Type: application/json" \
     -d "{
        \"categoryName\": \"<your_category_name>\",
        \"definition\": \"<your_category_definition>\",
        \"sampleBlobUrl\": \"https://example.blob.core.windows.net/example-container/sample.jsonl\"
     }"

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

応答を受信したら、操作 ID (id と呼ばれる) を一時的な場所に保存します。 この ID は、Get status API を使用してビルド状態を取得するために必要です。

curl -X POST "<your_endpoint>/contentsafety/text/categories/<your_category_name>:build?api-version=2024-02-15-preview&version={version}" \
     -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_category_name> は、実際の値に置き換えてください。

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\": \"<your_category_name>\", 
        \"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 = "DrugAbuse"
definition = "This category is related to Drug Abuse."
sample_blob_url = "https://<your-azure-storage-url>/example-container/drugsample.jsonl"

result = create_new_category_version(category_name, definition, sample_blob_url)
print(result)

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

カテゴリのビルド プロセスは、"カテゴリ名" と "バージョン番号" を使って開始できます。

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 = "<your_category_name>"
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 = "<your_category_name>"
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-02-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-02-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-02-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-02-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-02-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-02-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 を使ってコンテンツをモデレートする