自訂中繼資料標籤

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

什麼是標籤？

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

標籤需求

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

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

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

標籤的常見用法

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

  • 團隊或成本中心標籤：依據團隊或成本中心來新增標籤，藉此區別不同團隊 (例如 team:research 和 team:analytics) 擁有的 API 呼叫。這類標籤可用於成本會計或預算編列作業。

  • 元件標籤：例如 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 或 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

將要求主體儲存在名為 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 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證機制」。

執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。


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

Cloud de Confiance by S3NS 產品會按照不同間隔，將用量和費用資料回報給 Cloud Billing 程序。因此，您可能需要等待一段時間，才能在 Cloud Billing 中查看Cloud de Confiance by S3NS 服務的用量和費用。這些資訊通常會在一天內顯示，但有時可能超過 24 小時。

為合作夥伴模型 API 呼叫新增標籤

如要為 rawPredict 或 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 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證機制」。

執行程式碼範例前，請將 GOOGLE_CLOUD_UNIVERSE_DOMAIN 環境變數設為 s3nsapis.fr。

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

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