Google 會運用 AI 技術將內容翻譯成你偏好的語言，但可能會出錯。

自訂中繼資料標籤

您可以使用標籤，在 generateContent 和 rawPredict 等 API 呼叫中新增自訂中繼資料。本頁面說明標籤的定義，以及如何使用標籤細分帳單費用。

什麼是標籤？

標籤是一種鍵/值組合，可指派給 generateContent 和 rawPredict 等 API 呼叫。有助於在大規模環境下整理呼叫，並依所需精細程度管理用量和成本。您可以為每項呼叫加上標籤，並根據標籤篩選呼叫。標籤相關資訊會轉送到記錄和結帳系統，方便依照標籤詳細分析用量和帳單費用。使用內建的帳單報表，可依標籤篩選費用並加以分組。此外，亦可使用標籤查詢帳單資料匯出檔。如要瞭解如何在建立標籤後使用標籤，請參閱標籤總覽中的範例。

Agent Platform 支援兩種標籤：要求主體標籤 (會傳送至 Cloud Billing) 和標頭標籤 (會顯示在推論要求中繼資料記錄中)。下一節將比較這兩者。

根據用途選擇標籤

Agent Platform 提供兩種標籤機制。兩者的設定方式不同、目的地不同，且會顯示在推論要求中繼資料記錄的不同欄位中。您可以擇一使用，也可以在支援的情況下，在同一要求中同時使用兩者。

要求主體標籤的運作方式如下：

您可以在要求主體的 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。支援的用量選項：佈建輸送量，以及模型提供的所有即付即用選項。

找出記錄項目中的每個標籤

單一要求可以同時包含這兩者。下列要求會分別設定一個：

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": "..."}]}]
}

這兩個標籤會落在同一記錄項目的不同欄位中：

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

這兩種標籤類型會佔用不同的欄位，因此查詢方式也不同。在 Logs Explorer 中：

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

在 Observability Analytics 中：

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

標頭標籤的運作方式

標頭標籤是推論要求中繼資料記錄的一部分。如要擷取這些資料，請啟用專案的推論要求中繼資料記錄。

請使用保留前置字元，為每個標籤傳送一個標頭。前置字串不區分大小寫：

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 要求。

標頭標籤限制

單一要求最多可寫入 32 個標頭。如果符合條件的工具超過上限，Agent Platform 會依字母順序遞增排列，並捨棄其餘工具。水滴無聲。
超過 1,024 個位元組的標頭值會遭到截斷，並在儲存的值中標示截斷。
名稱相同的重複標頭會合併為單一項目，其中包含多個值。

如要查詢標頭標籤，請參閱「依自訂標頭標籤查看用量」。

標籤需求

套用至 API 呼叫的標籤必須符合下列規定：

Google 模型的每個 API 呼叫最多可有 64 個標籤，合作夥伴模型則最多可有 32 個標籤。
每個標籤都必須是鍵/值組合。
鍵的長度必須至少為 1 個字元，最多 63 個字元，且不能空白。值可以空白，長度上限為 63 個字元。
鍵和值只能使用小寫字母、數字字元、底線和連字號。所有字元都必須使用 UTF-8 編碼，允許國際字元。鍵的開頭必須是小寫字母或國際字元。
標籤中的鍵部分在單一 API 呼叫中不得重複。但可讓多個呼叫使用相同的鍵。

上述限制適用於各個標籤的鍵和值，以及帶有標籤的個別 API 呼叫。不過，在專案內的所有 API 呼叫中，可建立的標籤鍵數量並無上限。在相關帳單帳戶的生命週期內，每個標籤鍵在所有要求中最多可有 1000 個不重複的值。如果標籤鍵與超過 1,000 個不重複的值相關聯，系統可能會在不另行通知的情況下捨棄該標籤鍵。

標籤的常見用法

以下是一些常見的標籤用途：

團隊或成本中心標籤：依據團隊或成本中心來新增標籤，藉此區別不同團隊 (例如 team:research 和 team:analytics) 擁有的 API 呼叫，這類標籤可用於成本會計或預算編列作業。
元件標籤：例如 component:redis、component:frontend、component:ingest 和 component:dashboard。
環境或階段標籤：例如 environment:production 和 environment:test。
擁有權標籤：用於識別各項作業的責任團隊，例如：team:shopping-cart。

我們不建議建立大量的不重複標籤，例如幫時間戳記或每個 API 呼叫的個別值建立標籤。這種做法的問題在於，標籤鍵會使目錄變得雜亂，大幅增加查詢時的載入時間，並難以有效篩選 API 呼叫及製作報表。

要求標籤支援的模型

不同模型支援的要求標籤和標頭標籤也不同。Google 模型和部分合作夥伴模型支援在要求中新增要求標籤。如果對不支援的模型新增要求標籤，要求會導致錯誤。Google 模型會採用要求主體 labels 欄位中的要求標籤。合作夥伴模型則會透過 X-Vertex-AI-Labels 標頭接收。

Google 模型

Google 模型支援下列 API 方法的標籤。

generateContent
streamGenerateContent

合作夥伴模型

合作夥伴模型支援下列 API 方法的標籤。

rawPredict
streamRawPredict

下列合作夥伴模型支援標籤。

只有在要求使用 PayGo 用量選項時，標籤才會轉送至 Cloud Billing。如果要求使用佈建輸送量消耗選項，系統會忽略要求中傳送的標籤，且不會顯示任何訊息。

支援標頭標籤的模型

標頭標籤只會寫入推論要求中繼資料記錄，因此適用於記錄中的模型和方法。

Gemini 模型：generateContent和streamGenerateContent。
Claude 模型：rawPredict和streamRawPredict。
用量選項：佈建輸送量和模型提供的所有即付即用選項。
不支援其他合作夥伴模型，包括 Mistral AI。向這些端點傳送含有標頭標籤的要求仍會成功，但不會寫入記錄項目，因此標籤不會記錄在任何地方。
標頭標籤不會傳送至 Cloud Billing。如要細分已結算費用，請使用要求標籤。

在 Google 模型 API 呼叫中加入要求標籤

如要為 generateContent 或 streamGenerateContent 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

注意：下列指令假設您已執行 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
  }
}

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 程序。因此，您可能需要等待一段時間，才能在 Cloud Billing 查看Google Cloud 服務的用量和費用。費用通常會在一天內提供，但有時可能需要超過 24 小時。

在合作夥伴模型 API 呼叫中加入要求標籤

如要為 rawPredict 或 streamRawPredict API 呼叫新增標籤，請按照下列步驟操作：

REST

使用任何要求資料之前，請先替換下列項目：

PROJECT_ID：專案 ID。
MODEL_ID：要使用的模型 ID。例如：claude-opus-4-6。

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 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 呼叫中加入標頭標籤

標頭標籤不需要變更要求主體。請在任何支援的要求中，為每個標籤新增一個 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}}
}

Claude 要求也可以在 X-Vertex-AI-Labels 標頭中攜帶要求標籤，如「在合作夥伴模型 API 呼叫中新增要求標籤」一節所示。這些資訊會傳送至 Cloud Billing，但不會寫入記錄項目。

查詢標頭標籤

在 Logs Explorer 中，依據一個標頭標籤值篩選：

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

在 Observability Analytics 中，前往「Log inference request metadata」(記錄推論要求中繼資料) 頁面，使用「Usage by custom header label」(依自訂標頭標籤區分用量) 查詢，依標頭標籤分組。

自訂中繼資料標籤 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

什麼是標籤？

根據用途選擇標籤

找出記錄項目中的每個標籤

標頭標籤的運作方式

標頭標籤限制

標籤需求

標籤的常見用法

要求標籤支援的模型

Google 模型

合作夥伴模型

支援標頭標籤的模型

在 Google 模型 API 呼叫中加入要求標籤

REST

curl

PowerShell

回應

Python

在合作夥伴模型 API 呼叫中加入要求標籤

REST

Python

在 API 呼叫中加入標頭標籤

在 Gemini 模型 API 呼叫中新增標頭標籤

在 Claude 模型 API 呼叫中新增標頭標籤

查詢標頭標籤

自訂中繼資料標籤