ラベルを使用して、generateContent や rawPredict などの API 呼び出しにカスタム メタデータを追加できます。このページでは、ラベルの概要と、ラベルを使用して請求料金を分類する方法について説明します。
ラベルとは
ラベルは、generateContent や rawPredict などの API 呼び出しに割り当てることができる Key-Value ペアです。ラベルはこれらの呼び出しを整理し、必要な粒度に基づいてコストを大規模に管理する場合に役立ちます。各呼び出しにラベルを添付すると、ラベルに基づいて呼び出しをフィルタできます。ラベルに関する情報は課金システムに転送され、請求料金をラベル別に分類できます。組み込みの請求レポートにより、ラベルで費用をフィルタしてグループ化できます。また、ラベルを使用して請求データ エクスポートをクエリすることもできます。作成後のラベルの使用方法については、ラベルの概要の例をご覧ください。
ラベルの要件
API 呼び出しに適用するラベルは、次の要件を満たす必要があります。
- 各 API 呼び出しには、Google モデルの場合は最大 64 個、パートナー モデルの場合は最大 32 個のラベルを付けることができます。
- ラベルは、Key-Value ペアでなければなりません。
- キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
- キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。キーは、小文字または国際文字で始める必要があります。
- ラベルのキー部分は、単一の API 呼び出し内では一意である必要があります。ただし、複数の呼び出しで同じキーを使用できます
これらの上限は、各ラベルのキーと値、およびラベルが付けられる個々の API 呼び出しに適用されます。1 つのプロジェクト内で、API 呼び出しに作成できるラベルキーの数の合計に上限はありません。各ラベルキーには、関連付けられた請求先アカウントの有効期間にわたるすべてのリクエストで、最大 1,000 個の固有値を設定できます。1,000 個を超える一意の値がラベルキーに関連付けられている場合、ラベルキーは予告なく削除されることがあります。
ラベルの一般的な用途
次に、ラベルの一般的なユースケースを示します。
チームまたはコストセンターのラベル: チームやコストセンターに基づいてラベルを追加し、各チームが所有する API 呼び出しを区別します（例:
team:research、team:analytics）。この種類のラベルは、アカウンティングまたは予算作成に使用できます。コンポーネント ラベル:
component:redis、component:frontend、component:ingest、component:dashboardなど。環境ラベルまたはステージのラベル:
environment:production、environment:testなど。オーナー権限ラベル: 運用担当チームの識別に使用されます（例:
team:shopping-cart）。
すべての API 呼び出しにタイムスタンプや個別の値を設定するなど、一意のラベルを多数作成することはおすすめしません。このアプローチの問題は、キーがカタログを混乱させ、クエリの読み込み時間が大幅に増加し、API 呼び出しを効果的にフィルタして報告することが困難になることです。
サポートされているモデル
リクエストにラベルを追加する機能は、Google モデルと一部のパートナー モデルでサポートされています。サポートされていないモデルのリクエストにラベルを追加すると、リクエストでエラーが発生します。
Google モデル
Google モデルは、次の API メソッドでラベルをサポートしています。
generateContentstreamGenerateContent
パートナーのモデル
パートナー モデルは、次の API メソッドのラベルをサポートしています。
rawPredictstreamRawPredict
次のパートナー モデルはラベルをサポートしています。
ラベルは、リクエストで PayGo 使用オプションが使用されている場合にのみ、Cloud Billing に転送されます。プロビジョンド スループットの消費オプションを使用するリクエストでは、リクエストで送信されたラベルは無視されます。
Google モデルの API 呼び出しにラベルを追加する
generateContent API 呼び出しまたは streamGenerateContent API 呼び出しにラベルを追加するには、次の手順を行ってください。
REST
リクエストのデータを使用する前に、次のように置き換えます。
GENERATE_RESPONSE_METHOD: モデルに生成させるレスポンスのタイプ。モデルのレスポンスを返す方法を生成するメソッドを選択します。streamGenerateContent: レスポンスは生成時にストリーミングされます。ユーザーが遅延を感じることは少なくなります。generateContent: レスポンスは、完全に生成された後に返されます。
LOCATION: リクエストを処理するリージョン。使用できる選択肢は以下のとおりです。クリックして、利用可能なリージョンの一部を開く
us-central1us-west4northamerica-northeast1us-east4us-west1asia-northeast3asia-southeast1asia-northeast1
PROJECT_ID: [プロジェクト ID](/resource-manager/docs/creating-managing-projects#identifiers)。.MODEL_ID: 使用するモデルのモデル ID。ROLE: コンテンツに関連付けられた会話におけるロール。単一ターンのユースケースでも、ロールの指定が必要です。指定できる値は以下のとおりです。USER: 送信するコンテンツを指定します。MODEL: モデルのレスポンスを指定します。
PROMPT_TEXT
LABEL_KEY: この API 呼び出しに関連付けるラベル メタデータ。LABEL_VALUE: ラベルの値。
リクエストを送信するには、次のいずれかのオプションを選択します。
curl
リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。
cat > request.json << 'EOF'
{
"contents": {
"role": "ROLE",
"parts": { "text": "PROMPT_TEXT" }
},
"labels": {
"LABEL_KEY": "LABEL_VALUE"
},
}
EOFその後、次のコマンドを実行して REST リクエストを送信します。
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD"
PowerShell
リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。
@'
{
"contents": {
"role": "ROLE",
"parts": { "text": "PROMPT_TEXT" }
},
"labels": {
"LABEL_KEY": "LABEL_VALUE"
},
}
'@ | Out-File -FilePath request.json -Encoding utf8その後、次のコマンドを実行して REST リクエストを送信します。
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }
Invoke-WebRequest `
-Method POST `
-Headers $headers `
-ContentType: "application/json; charset=utf-8" `
-InFile request.json `
-Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:GENERATE_RESPONSE_METHOD" | Select-Object -Expand Content
次のような JSON レスポンスが返されます。
Python
このサンプルを試す前に、クライアント ライブラリを使用した Agent Platform クイックスタートの Python の手順に沿って設定を行ってください。
Agent Platform で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
Google Cloud プロダクトは、Cloud Billing プロセスに使用量データと費用データについてさまざまな間隔で報告します。その結果、Google Cloud プロダクトの使用と、Cloud Billing に表示される使用量や費用との間に遅延が生じる場合があります。通常、費用は 1 日以内に利用可能になりますが、24 時間以上かかる場合もあります。
パートナー モデルの API 呼び出しにラベルを追加する
rawPredict API 呼び出しまたは streamRawPredict API 呼び出しにラベルを追加するには、次の手順を行ってください。
REST
リクエストのデータを使用する前に、次のように置き換えます。
PROJECT_ID: プロジェクト ID。MODEL_ID: 使用するモデルのモデル ID。例:claude-opus-4-6
リクエスト本文を request.json という名前のファイルに保存します。ターミナルで次のコマンドを実行して、このファイルを現在のディレクトリに作成または上書きします。
cat > request.json << 'EOF'
{
"anthropic_version": "vertex-2023-10-16",
"messages": [
{
"role": "user",
"content": "What is Generative AI?"
}
],
"max_tokens": 1024,
"stream": false
}
EOF
その後、次のコマンドを実行して REST リクエストを送信します。
REQUEST_LABELS=$(echo -n '{"team": "research", "component": "frontend"}' | base64 --wrap 0)
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "X-Vertex-AI-Labels: ${REQUEST_LABELS}" \
-H "Content-Type: application/json; charset=utf-8" \
-d @request.json \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL_ID:rawPredict"
Python
このサンプルを試す前に、クライアント ライブラリを使用した Agent Platform クイックスタートの Python の手順に沿って設定を行ってください。
Agent Platform で認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。
リクエストのデータを使用する前に、次のように置き換えます。
PROJECT_ID: プロジェクト ID。MODEL_ID: 使用するモデルのモデル ID。例:claude-opus-4-6
import base64 import json from google.cloud.aiplatform import aiplatform_v1 from google.api import httpbody_pb2 project_id = "PROJECT_ID" model_id = "MODEL_ID" request_body = { "anthropic_version": "vertex-2023-10-16", "messages": [{ "role": "user", "content": [{"type": "text", "text": "What is Generative AI?"}] }], "max_tokens": 256, "stream": True, } # Encode labels to base64 for the X-Vertex-AI-Labels header labels = { "team": "research", "component": "frontend", "environment": "production", } labels_json = json.dumps(labels).encode("utf-8") vertex_header_value = base64.b64encode(labels_json) endpoint_id=f"projects/{project_id}/locations/global/publishers/anthropic/models/{model_id}" client = aiplatform_v1.PredictionServiceClient() responses = client.stream_raw_predict( request=aiplatform_v1.StreamRawPredictRequest( endpoint=endpoint_id, http_body=httpbody_pb2.HttpBody( data=json.dumps(request_body).encode("utf-8"), content_type="application/json", ), ), metadata=[("x-vertex-ai-labels", vertex_header_value)], ) for response in responses: print(response.data.decode("utf-8"))