本頁面由 Cloud Translation API 翻譯而成。

自訂中繼資料標籤

您可以使用標籤，在 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

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

在試用這個範例之前，請先按照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 小時。