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

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

ラベルとは

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

ラベルの要件

API 呼び出しに適用するラベルは、次の要件を満たす必要があります。

各 API 呼び出しには最大 64 個のラベルを付けることができます。
ラベルは、Key-Value ペアでなければなりません。
キーは 1 文字以上、63 文字までにする必要があります。空にすることはできません。値は 63 文字以下にします。空にすることもできます。
キーと値には、小文字、数字、アンダースコア、ダッシュのみを使用できます。すべての文字は UTF-8 でエンコードする必要があります。国際文字も使用できます。キーは、小文字または国際文字で始める必要があります。
ラベルのキー部分は、単一の API 呼び出し内では一意である必要があります。ただし、複数の呼び出しで同じキーを使用できます

これらの上限は、各ラベルのキーと値、およびラベルが付けられる個々の API 呼び出しに適用されます。1 つのプロジェクト内で、API 呼び出しに適用できるラベルの数の合計に上限はありません。

ラベルの一般的な用途

次に、ラベルの一般的なユースケースを示します。

チームまたはコストセンターのラベル: チームやコストセンターに基づいてラベルを追加し、各チームが所有する API 呼び出しを区別します（例: team:research、team:analytics）。この種類のラベルは、アカウンティングまたは予算作成に使用できます。
コンポーネントラベル: component:redis、component:frontend、component:ingest、component:dashboard など。
環境ラベルまたはステージのラベル: environment:production、environment:test など。
オーナー権限ラベル: 運用担当チームの識別に使用されます（例: team:shopping-cart）。

すべての API 呼び出しにタイムスタンプや個別の値を設定するなど、一意のラベルを多数作成することはおすすめしません。このアプローチには、値が頻繁に変更された場合やカタログを混乱させるキーが使用された場合に、リソースを効果的にフィルタして報告することが困難になるという問題があります。

API 呼び出しにラベルを追加する

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

REST

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

GENERATE_RESPONSE_METHOD: モデルに生成させるレスポンスのタイプ。モデルのレスポンスを返す方法を生成するメソッドを選択します。
- streamGenerateContent: レスポンスは生成時にストリーミングされます。ユーザーが遅延を感じることは少なくなります。
- generateContent: レスポンスは、完全に生成された後に返されます。
LOCATION: リクエストを処理するリージョン。使用できる選択肢は以下のとおりです。
クリックして、利用可能なリージョンの一部を開く
- us-central1
- us-west4
- northamerica-northeast1
- us-east4
- us-west1
- asia-northeast3
- asia-southeast1
- asia-northeast1
PROJECT_ID: 実際のプロジェクト ID。
MODEL_ID: 使用するマルチモーダルモデルのモデル ID。選択できるオプションには次のものがあります。
- gemini-1.0-pro-002
- gemini-1.0-pro-vision-001
- gemini-1.5-pro-002
- gemini-1.5-flash
ROLE: コンテンツに関連付けられた会話におけるロール。単一ターンのユースケースでも、ロールの指定が必要です。指定できる値は以下のとおりです。
- USER: 送信するコンテンツを指定します。
- MODEL: モデルのレスポンスを指定します。
```
PROMPT_TEXT
```
プロンプトに配置する指示のテキスト。JSON
LABEL_KEY: この API 呼び出しに関連付けるラベルメタデータ。
LABEL_VALUE: ラベルの値。

リクエストを送信するには、次のいずれかのオプションを選択します。

curlPowerShell

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ユーザーアカウントで gcloud CLI にログインしているか、Cloud Shell を使用して自動的に gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

リクエスト本文を 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"

注: 次のコマンドは、gcloud init または gcloud auth login を実行して、ご自分のユーザーアカウントで gcloud CLI にログインしていることを前提としています。gcloud auth list を実行すると、現在アクティブなアカウントを確認できます。

@'
{
  "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 レスポンスが返されます。

レスポンス

{
  "candidates": [
    {
      "content": {
        "role": "model",
        "parts": [
          {
            "text": Generative AI is a type of artificial intelligence (AI) that can **create new
            content**, like text, images, audio, video, and even code.
          }
        ]
      },
      "finishReason": "STOP",
      "safetyRatings": [
        {
          "category": "HARM_CATEGORY_HATE_SPEECH",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.037841797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.06347656
        },
        {
          "category": "HARM_CATEGORY_DANGEROUS_CONTENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.053466797,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.08496094
        },
        {
          "category": "HARM_CATEGORY_HARASSMENT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.08154297,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.033203125
        },
        {
          "category": "HARM_CATEGORY_SEXUALLY_EXPLICIT",
          "probability": "NEGLIGIBLE",
          "probabilityScore": 0.071777344,
          "severity": "HARM_SEVERITY_NEGLIGIBLE",
          "severityScore": 0.083984375
        }
      ],
      "avgLogprobs": -0.40486351219383448
    }
  ],
  "usageMetadata": {
    "promptTokenCount": 5,
    "candidatesTokenCount": 555,
    "totalTokenCount": 560
  }
}

Google Cloud サービスは、Cloud Billing プロセスに使用量データと費用データについてさまざまな間隔で報告します。その結果、Google Cloud プロダクトの使用と、Cloud Billing に表示される使用量や費用との間に遅延が生じる場合があります。通常、費用は 1 日以内に利用可能になりますが、24 時間以上かかる場合もあります。

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

ラベルとは

ラベルの要件

ラベルの一般的な用途

API 呼び出しにラベルを追加する

レスポンス

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