カスタム カテゴリ (標準) API を使用する
カスタム カテゴリ (標準) 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 に割り当てます。
Azure AI Content Safety インスタンスのマネージド ID を有効にします。
ストレージ BLOB データ共同作成者/所有者のロールをマネージド ID に割り当てます。 以下で強調表示されているロールはすべて機能するはずです。
カスタム カテゴリを作成してトレーニングする
重要
モデルのトレーニングには十分な時間を取ってください
カスタム カテゴリ トレーニングのエンド ツー エンドの実行には、5 時間から 10 時間程度かかる場合があります。 これを踏まえたうえでモデレーション パイプラインを計画し、以下のための時間をとります。
- サンプル データの収集と準備
- トレーニング プロセス
- モデルの評価と調整
次のコマンドでは、<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
}"
その他のカスタム カテゴリ操作
以下のプレースホルダーは、API キー、エンドポイント、および特定のコンテンツ (カテゴリ名、定義など) の実際の値に置き換えてください。 これらの例は、アカウントでカスタマイズされたカテゴリを管理するのに役立ちます。
カスタマイズされたカテゴリまたはその特定のバージョンを取得する
ターミナル ウィンドウでプレースホルダーを独自の値に置き換えて、次のコマンドを実行します。
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"