您可以使用標籤，在 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 方法的標籤。
generateContentstreamGenerateContent
合作夥伴模型
合作夥伴模型支援下列 API 方法的標籤。
rawPredictstreamRawPredict
下列合作夥伴機型支援標籤。
只有在要求使用「隨用隨付」PayGo消耗量選項時，標籤才會轉送至 Cloud Billing。如果要求使用「透過佈建的輸送量」消耗選項，系統會自動忽略要求中傳送的標籤。
為 Google 模型 API 呼叫加上標籤
如要為 generateContent 或 streamGenerateContent API 呼叫新增標籤，請按照下列步驟操作：
REST
使用任何要求資料之前，請先修改下列項目的值：
GENERATE_RESPONSE_METHOD：您希望模型生成的回覆類型。 選擇生成模型回覆傳回方式的方法：streamGenerateContent：在生成回覆時串流傳輸，減少人類觀眾的延遲感。generateContent：系統會在完整生成回應後傳回。
LOCATION：處理要求的區域。可用選項包括：按一下即可展開可用區域的部分清單
us-central1us-west4northamerica-northeast1us-east4us-west1asia-northeast3asia-southeast1asia-northeast1
PROJECT_ID： 您的 [專案 ID](/resource-manager/docs/creating-managing-projects#identifiers)。 。MODEL_ID：要使用的模型 ID。ROLE： 與內容相關聯的對話角色。即使是單輪對話，也必須指定角色。 可接受的值包括：USER：指定您傳送的內容。MODEL：指定模型的回覆。
PROMPT_TEXT
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 產品會按照不同間隔，將用量和費用資料回報給 Cloud Billing 程序。因此，您可能需要等待一段時間，才能在 Cloud Billing 查看Google Cloud 服務的用量和費用。費用通常會在一天內提供，不過有時可能會超過 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 進行驗證，請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證機制」。
使用任何要求資料之前，請先替換以下項目：
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"))