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

ラベルを使用して、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 呼び出しを効果的にフィルタして報告することが困難になることです。

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

generateContent または 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: ラベルの値。

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

curl

注: 次のコマンドは、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"

PowerShell

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

リクエスト本文を 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 レスポンスが返されます。

レスポンス

{
  "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 時間以上かかる場合もあります。