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

[アーティクル]
11/05/2024

このガイドに従って、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 がインストールされていること

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

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

ヒント

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

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

重要

ユーザーのストレージアカウントは階層型名前空間アカウントとして設定されています。これはカスタムカテゴリではサポートできません。代わりに、通常のストレージアカウントを使用してみてください。たとえば、BLOB URL は example/example1/ のように 2 つのレイヤーに分割することはできず、1 つのレイヤーのみにする必要があります。詳細については、ドキュメント「Azure Data Lake Storage 階層型名前空間 - Azure Storage」を参照してください。

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

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

重要

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

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

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

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
Python

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

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

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

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)

次の方法で共有

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

前提条件

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

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

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

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

API 要求

API 応答

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

API 応答

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

API 応答

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

API 要求

API 応答

新しいカテゴリを作成します

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

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

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

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

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

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

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

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

フィードバック

その他のリソース

次の方法で共有

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

前提条件

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

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

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

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

API 要求

API 応答

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

API 応答

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

API 応答

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

API 要求

API 応答

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

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

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

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

関連するコンテンツ

フィードバック

その他のリソース

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

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

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

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

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

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

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