自訂中繼資料標籤

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

什麼是標籤？

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

標籤需求

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

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

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

標籤的常見用法

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

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

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