カスタムカテゴリ (標準) API を使用する (プレビュー)

[アーティクル]
09/03/2024

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

重要

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

注意事項

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

前提条件

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

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

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

サンプルデータを収集するか書き込みます。
- トレーニングによって効果的なモデルを作成するには、サンプルデータの品質が重要です。特定したいコンテンツを正確に表す正のサンプルを少なくとも 50 個収集することを目指します。これらのサンプルは、明確かつ多様で、カテゴリ定義に直接関連している必要があります。
- 負のサンプルは必須ではありませんが、関連するコンテンツと、関連のないコンテンツを区別するモデルの能力を向上させることができます。パフォーマンスを向上させるには、正のケース定義に関連しないサンプルを 50 個集めることを目指します。これらは多様である必要がありますが、モデルが遭遇するコンテンツのコンテキストに沿ったものでなければなりません。負のサンプルを慎重に選択して、正のカテゴリと誤って重複しないようにします。
- 正と負のサンプル数のバランスを取るようにします。データセットが不均一だとモデルに偏りが出てくることがあるため、ある種類の分類が別の種類よりも優先され、擬陽性や偽陰性の割合が高くなる可能性があります。
テキストエディターを使用して、.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}
```
.jsonl ファイルを Azure Storage アカウントの BLOB コンテナーにアップロードします。後で使用するために、BLOB の URL を一時的な場所にコピーします。

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

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

重要

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

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

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

重要

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

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

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

cURL
Python

次のコマンドでは、<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 ライブラリをインストールする必要があります。

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
Python

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

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

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 ライブラリがインストールされていることを確認します。

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)

次の方法で共有

カスタムカテゴリ (標準) API を使用する (プレビュー)

前提条件

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

フィードバック

その他のリソース

次の方法で共有

カスタム カテゴリ (標準) API を使用する (プレビュー)

前提条件

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

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

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

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

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

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

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

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

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

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

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

関連するコンテンツ

フィードバック

その他のリソース

カスタムカテゴリ (標準) API を使用する (プレビュー)

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

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

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

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

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

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