自訂中繼資料標籤

您可以使用標籤,在 generateContentstreamGenerateContent API 呼叫中新增自訂中繼資料。本頁面說明標籤的用途,以及如何使用標籤細分帳單費用。

什麼是標籤?

標籤是可指派給 generateContentstreamGenerateContent API 呼叫的鍵/值組合。這些工具可協助您整理這些呼叫,並以所需的精細程度大規模管理費用。您可以為每通電話加上標籤,並根據標籤篩選電話。標籤相關資訊會轉送到帳單系統,方便您依據標籤查看帳單費用明細。您可以使用內建的帳單報表,依標籤篩選及分組費用。您也可以使用標籤查詢帳單資料匯出內容。如要瞭解如何使用標籤,請參閱標籤總覽中的範例

標籤需求

套用於 API 呼叫的標籤必須符合下列需求條件:

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

這些限制適用於每個標籤的鍵和值,以及含有標籤的個別 API 呼叫。專案中所有 API 呼叫可套用的標籤數量沒有上限。

標籤的常見用法

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

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

  • 元件標籤:例如 component:rediscomponent:frontendcomponent:ingestcomponent:dashboard

  • 環境或階段標籤:例如 environment:productionenvironment:test

  • 擁有權標籤:用來識別負責作業的團隊,例如:team:shopping-cart

我們不建議您建立大量的不重複標籤,例如幫時間戳記或每個 API 呼叫的個別值建立標籤。這種做法的問題在於,如果值經常變更,或是使用會讓目錄雜亂無章的鍵,就難以有效篩選及回報 API 呼叫。

為 API 呼叫加上標籤

如要為 generateContentstreamGenerateContent 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。
  • 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

在試用這個範例之前,請先按照Python使用用戶端程式庫的 Vertex AI 快速入門中的操作說明進行設定。 詳情請參閱 Vertex AI Python API 參考說明文件

如要向 Vertex AI 進行驗證,請設定應用程式預設憑證。 詳情請參閱「為本機開發環境設定驗證」。

import vertexai

from vertexai.generative_models import GenerativeModel

# TODO(developer): Update and un-comment below line
# PROJECT_ID = "your-project-id"
vertexai.init(project=PROJECT_ID, location="us-central1")

model = GenerativeModel("gemini-2.0-flash-001")

prompt = "What is Generative AI?"
response = model.generate_content(
    prompt,
    # Example Labels
    labels={
        "team": "research",
        "component": "frontend",
        "environment": "production",
    },
)

print(response.text)
# Example response:
# Generative AI is a type of Artificial Intelligence focused on **creating new content** based on existing data.

Google Cloud 產品會依不同時間間隔,將用量和費用資料回報給 Cloud Billing 程序。因此,您可能需要等待一段時間,才能在 Cloud Billing 中查看Google Cloud 服務的用量和費用。費用通常會在一天內提供,但有時可能需要超過 24 小時。