カスタム メタデータ ラベル

ラベルを使用して、generateContent、interactions.create、rawPredict などの API 呼び出しにカスタム メタデータを追加できます。このページでは、ラベルの概要と、ラベルを使用して請求料金を分類する方法について説明します。

ラベルについて

ラベルは、generateContent、interactions.create、rawPredict などの API 呼び出しに割り当てることができる Key-Value ペアです。ラベルはこれらの呼び出しを整理し、必要な粒度に基づいて使用量とコストを大規模に管理する場合に役立ちます。各呼び出しにラベルを添付すると、ラベルに基づいて呼び出しをフィルタできます。ラベルに関する情報はロギング システムと課金システムに転送され、使用量と請求料金をラベル別に分類できます。組み込みの請求レポートにより、ラベルで費用をフィルタしてグループ化できます。また、ラベルを使用して請求データ エクスポートをクエリすることもできます。作成後のラベルの使用方法については、ラベルの概要の例をご覧ください。

Agent Platform は、Cloud Billing に到達するリクエスト本文ラベルと、推論リクエスト メタデータ ログに表示されるヘッダーラベルの 2 種類のラベルをサポートしています。次のセクションでは、これらを比較します。

ユースケースに基づいてラベルを選択する

Agent Platform には、2 つのラベル メカニズムが用意されています。これらは設定方法が異なり、到達する宛先も異なります。また、推論リクエストのメタデータ ログの異なるフィールドに表示されます。サポートされている場合は、同じリクエストで一方または両方を使用できます。

リクエスト本文のラベルは次のように機能します。

  • これらは、リクエスト本文の labels フィールドで設定します。
  • Cloud Billing と推論リクエストのメタデータ ログにアクセスします。
  • これらは、ログエントリの labels フィールドに表示されます。
  • 従量課金制のトラフィックでサポートされています。
  • Claude などのパートナー モデルの場合、リクエスト ラベルはリクエスト本文ではなく X-Vertex-AI-Labels ヘッダーで送信されます。Cloud Billing には到達しますが、推論リクエストのメタデータ ログには書き込まれません。

ヘッダーラベルは次のように機能します。

  • これらは x-goog-agent-platform-observability-label-KEY リクエスト ヘッダーで設定します。
  • 推論リクエストのメタデータログにのみアクセスします。
  • これらは、ログエントリの jsonPayload.httpHeaders フィールドに表示されます。
  • サポートされている API メソッド: Gemini モデルの場合は generateContent と streamGenerateContent、Claude モデルの場合は rawPredict と streamRawPredict。サポートされている使用オプション: プロビジョンド スループットと、モデルが提供するすべての従量課金制オプション。

ログエントリで各ラベルを見つける

1 つのリクエストで両方を送信できます。次のリクエストでは、それぞれ 1 つずつ設定します。

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-pro:generateContent
x-goog-agent-platform-observability-label-team: payments

{
  "labels": {"cost_center": "cc-1234"},
  "contents": [{"role": "user", "parts": [{"text": "..."}]}]
}

2 つのラベルは、同じログエントリの異なるフィールドに配置されます。

{
  "labels": {
    "gen_ai.operation.name": "generate_content",
    "cost_center": "cc-1234"
  },
  "jsonPayload": {
    "httpHeaders": {
      "x-goog-agent-platform-observability-label-team": {
        "values": ["payments"]
      }
    }
  }
}

2 つのラベルタイプは異なるフィールドを占有するため、クエリの方法が異なります。ログ エクスプローラで次の操作を行います。

labels.cost_center="cc-1234"
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"

オブザーバビリティ分析:

JSON_VALUE(labels.cost_center) AS cost_center,
JSON_VALUE(json_payload.httpHeaders
  ["x-goog-agent-platform-observability-label-team"].values[0]) AS team

ヘッダーラベルの仕組み

ヘッダーラベルは、推論リクエストのメタデータ ロギングの一部です。これらをキャプチャするには、プロジェクトの推論リクエスト メタデータ ログを有効にします。

予約済みのプレフィックスを使用して、ラベルごとに 1 つのヘッダーを送信します。接頭辞では大文字と小文字が区別されません。

x-goog-agent-platform-observability-label-KEY: VALUE

次に例を示します。

x-goog-agent-platform-observability-label-team: payments
x-goog-agent-platform-observability-label-application: invoice-ocr

各ヘッダーは、ログエントリで各ラベルを見つけるに示すように、jsonPayload.httpHeaders の下のログエントリに表示されます。ヘッダー名は小文字で、値は values 配列にあります。

Agent Platform は、独自のヘッダー(x-vertex-ai-llm-request-type と x-vertex-ai-llm-shared-request-type)の小さなセットもキャプチャします。他のヘッダーはキャプチャされません。

ヘッダーラベルは Gemini と Claude で同じように機能します。推論リクエスト メタデータ ログで Claude リクエストにラベルを付ける方法です。

ヘッダーラベルの上限

  • 1 つのリクエストで書き込まれるヘッダーは最大 32 個です。対象となるエージェントがさらに多い場合、Agent Platform はアルファベット順にエージェントを保持し、残りを削除します。ドロップはサイレントです。
  • 1,024 バイトを超えるヘッダー値は切り捨てられ、切り捨てられたことが保存された値にマークされます。
  • 同じ名前のヘッダーが繰り返される場合、複数の値を持つ 1 つのエントリに結合されます。

ヘッダーラベルをクエリするには、カスタム ヘッダーラベル別の使用状況をご覧ください。

ラベルの要件

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)。

  • エンドユーザーの不正行為の帰属(safety_identifier): Gemini と Veo の呼び出しに匿名化されたユーザーごとの ID(safety_identifier:user_session_001 など)を添付して、ポリシー フィードバックがプロジェクト全体ではなく特定のエンドユーザーを対象とするようにします。形式のルールとサンプルについては、API 呼び出しでエンドユーザーの安全識別子を渡すをご覧ください。

すべての API 呼び出しにタイムスタンプや個別の値を設定するなど、一意のラベルを多数作成することは避けてください。一意のキーを多数作成すると、カタログが乱雑になり、クエリ中の読み込み時間が大幅に増加し、API 呼び出しを効果的にフィルタして報告することが困難になります。

リクエスト ラベルでサポートされているモデル

リクエスト ラベルとヘッダーラベルは、異なるモデルでサポートされています。リクエストにリクエスト ラベルを追加する機能は、Google モデルと一部のパートナー モデルでサポートされています。サポートされていないモデルのリクエストにリクエスト ラベルを追加すると、リクエストはエラーになります。Google モデルは、リクエスト本文の labels フィールドでリクエスト ラベルを受け取ります。パートナー モデルは、X-Vertex-AI-Labels ヘッダーでそれらを受け取ります。

Google モデル

Google モデルは、次の API メソッドでラベルをサポートしています。

  • generateContent
  • streamGenerateContent
  • predictLongRunning(Veo による動画生成)
  • interactions.create

パートナーのモデル

パートナー モデルは、次の API メソッドでラベルをサポートしています。

  • rawPredict
  • streamRawPredict

次のパートナー モデルはラベルをサポートしています。

ラベルは、リクエストで PayGo 使用オプションが使用されている場合にのみ Cloud Billing に転送されます。プロビジョンド スループットの使用オプションを使用するリクエストでは、リクエストで送信されたラベルがサイレントに無視されます。

ヘッダーラベルでサポートされているモデル

ヘッダーラベルは推論リクエストのメタデータログにのみ書き込まれるため、ログに記録されるモデルとメソッドで機能します。

  • Gemini モデル: generateContent、streamGenerateContent。
  • Claude モデル: rawPredict、streamRawPredict。
  • 使用オプション: プロビジョンド スループットと、モデルが提供するすべての従量課金制オプション。
  • Mistral AI などの他のパートナー モデルはサポートされていません。ヘッダーラベルを含むリクエストは引き続き成功しますが、ログエントリは書き込まれないため、ラベルはどこにも記録されません。
  • ヘッダーラベルが Cloud Billing に到達することはありません。請求額の内訳を確認するには、リクエスト ラベルを使用します。

Google モデル API 呼び出しにリクエスト ラベルを追加する

generateContent、streamGenerateContent、interactions.create の API 呼び出しにラベルを追加するには、次の操作を行います。

REST

リクエストのデータを使用する前に、次のように置き換えます。

  • GENERATE_RESPONSE_METHOD: モデルに生成させるレスポンスのタイプ。モデルのレスポンスを返す方法を生成するメソッドを選択します。
    • streamGenerateContent: レスポンスは生成時にストリーミングされます。ユーザーが遅延を感じることは少なくなります。
    • generateContent: レスポンスは、完全に生成された後に返されます。
  • LOCATION: リクエストを処理するリージョン。
  • PROJECT_ID: 実際のプロジェクト ID。.
  • MODEL_ID: 使用するモデルのモデル ID。
  • ROLE: コンテンツに関連付けられた会話における役割。単一ターンのユースケースでも、ロールの指定が必要です。指定できる値は以下のとおりです。
    • USER: 送信するコンテンツを指定します。
    • MODEL: モデルのレスポンスを指定します。
  • PROMPT_TEXT
    プロンプトに含める指示のテキスト。JSON
  • 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 への認証を行うには、アプリケーションのデフォルト認証情報を設定します。詳細については、ローカル開発環境の認証の設定をご覧ください。


import os

from google import genai

PROJECT_ID = os.getenv("GOOGLE_CLOUD_PROJECT")
LOCATION = os.getenv("LOCATION_ID")
GEMINI_MODEL = os.getenv("GEMINI_MODEL_ID", "gemini-2.5-flash")


def generate_content() -> genai.types.GenerateContentResponse:

    genai_client = genai.Client(enterprise=True, project=PROJECT_ID, location=LOCATION)

    labels = {
        "environment": "testing",
        "feature": "genai",
        "model": "gemini",
    }

    config = genai.types.GenerateContentConfig(temperature=0.4, labels=labels)

    response = genai_client.models.generate_content(
        model=GEMINI_MODEL, contents="What is Generative AI?", config=config
    )

    print(response.text)
    return response

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"))

API 呼び出しにヘッダーラベルを追加する

ヘッダーラベルでは、リクエスト本文を変更する必要はありません。サポートされているリクエストに、ラベルごとに 1 つの x-goog-agent-platform-observability-label-KEY ヘッダーを追加します。次の例は、2026 年 10 月 14 日のテスト リクエストから、推論リクエストのメタデータ ログエントリのリクエストと結果のフィールドを示しています。

Gemini モデルの API 呼び出しにヘッダーラベルを追加する

generateContent または streamGenerateContent を含むヘッダーラベルを送信します。PROJECT_ID は実際のプロジェクト ID に置き換えます。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-agent-platform-observability-label-team: payments" \
  -H "x-goog-agent-platform-observability-label-application: invoice-ocr" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "What is Generative AI?"}]}]}'

ログエントリには、jsonPayload.httpHeaders の各ラベルが記録されます。ヘッダーラベルは、プロビジョンド スループット トラフィックにも記録されます。リクエストラベルはこれをサポートしていません。

{
  "method": "GENERATE_CONTENT",
  "trafficType": "PROVISIONED_THROUGHPUT",
  "httpHeaders": {
    "x-goog-agent-platform-observability-label-application": {"values": ["invoice-ocr"]},
    "x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
  },
  "generateContentDetails": {"usageMetadata": {"promptTokenCount": 6, "candidatesTokenCount": 1, "totalTokenCount": 7}},
  "provisionedThroughput": {"accountingResource": "projects/PROJECT_NUMBER", "ptChargedInputTokenCount": "6", "ptChargedOutputTokenCount": "9"}
}

Claude モデルの API 呼び出しにヘッダーラベルを追加する

rawPredict または streamRawPredict を含むヘッダーラベルを送信します。PROJECT_ID と MODEL_ID を置き換えます(例: claude-opus-4-6)。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-agent-platform-observability-label-team: payments" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL_ID:rawPredict" \
  -d '{"anthropic_version": "vertex-2023-10-16", "messages": [{"role": "user", "content": "What is Generative AI?"}], "max_tokens": 256}'

ログエントリには、jsonPayload.httpHeaders の下に、Claude のトークン数の横にラベルが記録されます。

{
  "method": "RAW_PREDICT",
  "trafficType": "ON_DEMAND",
  "httpHeaders": {
    "x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
  },
  "rawPredictDetails": {"usageMetadata": {"input_tokens": 17, "output_tokens": 16, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}
}

パートナー モデル API 呼び出しにリクエスト ラベルを追加するに示されているように、Claude リクエストは X-Vertex-AI-Labels ヘッダーにリクエスト ラベルを付けることもできます。これらは Cloud Billing に到達しますが、ログエントリには書き込まれません。

クエリヘッダー ラベル

ログ エクスプローラで、1 つのヘッダーラベル値でフィルタします。

jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"

オブザーバビリティ分析で、[ログ推論リクエストのメタデータ] ページの [カスタム ヘッダーラベル別の使用量] クエリを使用して、ヘッダーラベルでグループ化します。