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

ラベルを使用して、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 メソッドでラベルをサポートしています。

  • generateContent
  • streamGenerateContent

パートナーのモデル

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

  • rawPredict
  • streamRawPredict

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

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

Google モデルの API 呼び出しにラベルを追加する

generateContent API 呼び出しまたは streamGenerateContent API 呼び出しにラベルを追加するには、次の手順を行ってください。

REST

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

  • GENERATE_RESPONSE_METHOD: モデルに生成させるレスポンスのタイプ。モデルのレスポンスを返す方法を生成するメソッドを選択します。
    • streamGenerateContent: レスポンスは生成時にストリーミングされます。ユーザーが遅延を感じることは少なくなります。
    • generateContent: レスポンスは、完全に生成された後に返されます。
  • LOCATION: リクエストを処理するリージョン。
  • PROJECT_ID: [プロジェクト ID](/resource-manager/docs/creating-managing-projects#identifiers)。 。
  • 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

このサンプルを試す前に、クライアント ライブラリを使用したPython Agent Platform クイックスタートの手順に沿って設定を行ってください。

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

このサンプルを試す前に、クライアント ライブラリを使用したPython Agent Platform クイックスタートの手順に沿って設定を行ってください。

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