Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

自定义元数据标签

您可以使用标签向 generateContent 和 rawPredict 等 API 调用添加自定义元数据。本页面介绍了什么是标签，并展示了如何使用标签来细分账单费用。

什么是标签？

标签是一种键值对，可分配给 generateContent 和 rawPredict 等 API 调用。它们可以帮助您按照所需的粒度大规模组织这些调用并管理用量和费用。您可以将标签附加到各个调用，然后根据其标签对调用进行过滤。标签的相关信息会转发到日志记录和结算系统，以便您按标签细分用量和结算费用。使用内置的结算报告，您可以按标签对费用进行过滤和分组。您还可以使用标签查询结算数据导出。如需了解如何在创建后使用标签，请参阅标签概览中的示例。

Agent Platform 支持两种标签：请求正文标签（会发送到 Cloud Billing）和标头标签（会显示在推理请求元数据日志中）。下一部分将对它们进行比较。

根据您的应用场景选择标签

Agent Platform 提供了两种标签机制。您可以通过不同的方式设置它们，它们会到达不同的目的地，并显示在推理请求元数据日志的不同字段中。您可以在同一请求中使用其中一个或同时使用这两个（如果支持）。

请求正文标签的工作原理如下：

您可以在请求正文的 labels 字段中设置这些参数。
它们会到达 Cloud Billing 和推理请求元数据日志。
它们会显示在日志条目的 labels 字段中。
支持随用随付流量。
对于 Claude 等合作伙伴模型，请求标签会在 X-Vertex-AI-Labels 标头（而非请求正文）中发送。它们会到达 Cloud Billing，但不会写入推理请求元数据日志。

标头标签的工作原理如下：

您可以在 x-goog-agent-platform-observability-label-KEY 请求标头中设置这些值。
它们只会访问推理请求元数据日志。
它们会显示在日志条目的 jsonPayload.httpHeaders 字段中。
支持的 API 方法：Gemini 模型支持 generateContent 和 streamGenerateContent，Claude 模型支持 rawPredict 和 streamRawPredict。支持的消费选项：预配吞吐量和模型提供的每个随用随付选项。

在日志条目中查找每个标签

单个请求可以同时包含这两者。以下请求会分别设置一个：

POST https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-pro:generateContent
x-goog-agent-platform-observability-label-team: payments

{
  "labels": {"cost_center": "cc-1234"},
  "contents": [{"role": "user", "parts": [{"text": "..."}]}]
}

这两个标签会出现在同一日志条目的不同字段中：

{
  "labels": {
    "gen_ai.operation.name": "generate_content",
    "cost_center": "cc-1234"
  },
  "jsonPayload": {
    "httpHeaders": {
      "x-goog-agent-platform-observability-label-team": {
        "values": ["payments"]
      }
    }
  }
}

这两种标签类型占用不同的字段，因此查询方式也不同。在 Logs Explorer 中：

labels.cost_center="cc-1234"
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"

在 Observability Analytics 中：

JSON_VALUE(labels.cost_center) AS cost_center,
JSON_VALUE(json_payload.httpHeaders
  ["x-goog-agent-platform-observability-label-team"].values[0]) AS team

标题标签的运作方式

标头标签是推理请求元数据日志记录的一部分。如需捕获这些元数据，请为项目开启推理请求元数据日志。

每个标签发送一个标头，并使用预留前缀。前缀不区分大小写：

x-goog-agent-platform-observability-label-KEY: VALUE

例如：

x-goog-agent-platform-observability-label-team: payments
x-goog-agent-platform-observability-label-application: invoice-ocr

每个标头都会显示在 jsonPayload.httpHeaders 下的日志条目中，以小写标头名称作为键，值位于 values 数组中，如在日志条目中查找每个标签所示。

Agent Platform 还会捕获一小部分自己的标头：x-vertex-ai-llm-request-type 和 x-vertex-ai-llm-shared-request-type。不会捕获任何其他标头。

标头标签在 Gemini 和 Claude 中的工作方式相同，您可以通过它们在推理请求元数据日志中为 Claude 请求添加标签。

标题标签的限制

单个请求最多可写入 32 个标头。如果符合条件的数量超过此限制，智能体平台会按字母顺序保留前 10 个，并舍弃其余的。该丢弃操作不会发出任何提示。
长度超过 1,024 字节的标头值会被截断，并且截断会在存储的值中标记。
名称相同的重复标头会合并为具有多个值的单个条目。

如需查询标头标签，请参阅按自定义标头标签划分的使用情况。

标签要求

应用于 API 调用的标签必须符合以下要求：

对于 Google 模型，每个 API 调用最多可以有 64 个标签；对于合作伙伴模型，每个 API 调用最多可以有 32 个标签。
每个标签都必须采用键值对形式。
键至少包含 1 个字符，最多包含 63 个字符，且不能为空。值可以为空，且最多包含 63 个字符。
键和值只能包含小写字母、数字字符、下划线和短划线。所有字符必须使用 UTF-8 编码，允许使用国际字符。键必须以小写字母或国际字符开头。
标签的键部分在单个 API 调用中必须是唯一的。不过，您可以将同一个键用于多个调用。

这些限制适用于每个标签的键和值，以及带有标签的各个 API 调用。您可以对一个项目的所有 API 调用创建任意数量的标签键。在关联的结算账号的生命周期内，每个标签键在所有请求中最多可以有 1,000 个唯一值。如果标签键关联了超过 1,000 个唯一值，则可能会在不通知的情况下被丢弃。

标签的常见用途

以下是标签的一些常见使用场景：

团队或成本中心标签：根据团队或成本中心添加标签，以区分不同团队所拥有的API 调用（例如 team:research 和 team:analytics）。您可以在核算成本或制定预算时使用此类标签。
组件标签：例如 component:redis、component:frontend、component:ingest、component:dashboard。
环境或阶段标签：例如 environment:production 和 environment:test。
所有权标签：用于标识负责运营的团队，例如：team:shopping-cart。

我们不建议创建大量唯一标签，例如为每个 API 调用的时间戳或个别值创建标签。这种方法的问题在于，键会导致目录杂乱，在查询期间显著增加加载时间，并且很难有效地过滤和报告 API 调用。

支持请求标签的模型

不同模型支持请求标签和标头标签。Google 模型和部分合作伙伴模型支持向请求添加请求标签。如果您向不受支持的模型请求添加请求标签，则请求会导致错误。Google 模型在请求正文的 labels 字段中接受请求标签。合作伙伴模型在 X-Vertex-AI-Labels 标头中接受这些令牌。

Google 模型

Google 模型支持在以下 API 方法中使用标签。

generateContent
streamGenerateContent

合作伙伴模型

合作伙伴模型支持在以下 API 方法中使用标签。

rawPredict
streamRawPredict

以下合作伙伴模型支持标签。

只有当请求使用 PayGo 使用选项时，标签才会转发到 Cloud Billing。使用预配吞吐量消耗选项的请求将静默忽略请求中发送的标签。

支持标题标签的模型

标头标签仅写入推理请求元数据日志，因此它们适用于日志记录的模型和方法。

Gemini 模型：generateContent 和 streamGenerateContent。
Claude 模型：rawPredict 和 streamRawPredict。
使用选项：预配吞吐量和模型提供的每个随用随付选项。
不支持其他合作伙伴模型，包括 Mistral AI。向其发送带有标头标签的请求仍然会成功，但不会写入日志条目，因此标签不会记录在任何位置。
标头标签绝不会到达 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

注意：以下命令假定您已使用您的用户账号通过运行 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

在尝试此示例之前，请按照《Agent Platform 快速入门：使用客户端库》中的 Python 设置说明执行操作。

如需向 Agent Platform 进行身份验证，请设置应用默认凭据。如需了解详情，请参阅为本地开发环境设置身份验证。


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

Google Cloud 产品会按不同的时间间隔向 Cloud Billing 流程报告用量和费用数据。因此，您可能会在使用Google Cloud 服务与可在 Cloud Billing 中查看的使用量和费用之间看到延迟现象。通常一天之内即可获得您的费用信息，但有时可能需要 24 小时以上。

向合作伙伴模型 API 调用添加请求标签

如需向 rawPredict 或 streamRawPredict API 调用添加标签，请执行以下操作：

REST

在使用任何请求数据之前，请先进行以下替换：

PROJECT_ID：您的项目 ID。
MODEL_ID：您要使用的模型的模型 ID。例如 claude-opus-4-6。

注意：以下命令假定您已使用您的用户账号通过运行 gcloud init 或 gcloud auth login 登录 gcloud CLI，或者使用了 Cloud Shell，这会使您自动登录 gcloud CLI。您可以运行 gcloud auth list 来检查当前活跃的账号。

将请求正文保存在名为 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"))

向 API 调用添加标头标签

标头标签不需要更改请求正文。为每个标签向任何受支持的请求添加一个 x-goog-agent-platform-observability-label-KEY 标头。以下示例展示了 2026 年 10 月 14 日的测试请求中的请求和推理请求元数据日志条目的结果字段。

向 Gemini 模型 API 调用添加标头标签

使用 generateContent 或 streamGenerateContent 发送标头标签。请将 PROJECT_ID 替换为您的项目 ID。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-agent-platform-observability-label-team: payments" \
  -H "x-goog-agent-platform-observability-label-application: invoice-ocr" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/google/models/gemini-2.5-flash:generateContent" \
  -d '{"contents": [{"role": "user", "parts": [{"text": "What is Generative AI?"}]}]}'

日志条目会在 jsonPayload.httpHeaders 下记录每个标签。标头标签也会记录在预配吞吐量流量中，而请求标签不支持此功能：

{
  "method": "GENERATE_CONTENT",
  "trafficType": "PROVISIONED_THROUGHPUT",
  "httpHeaders": {
    "x-goog-agent-platform-observability-label-application": {"values": ["invoice-ocr"]},
    "x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
  },
  "generateContentDetails": {"usageMetadata": {"promptTokenCount": 6, "candidatesTokenCount": 1, "totalTokenCount": 7}},
  "provisionedThroughput": {"accountingResource": "projects/PROJECT_NUMBER", "ptChargedInputTokenCount": "6", "ptChargedOutputTokenCount": "9"}
}

向 Claude 模型 API 调用添加标头标签

使用 rawPredict 或 streamRawPredict 发送标头标签。替换 PROJECT_ID 和 MODEL_ID，例如 claude-opus-4-6。

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "x-goog-agent-platform-observability-label-team: payments" \
  "https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/global/publishers/anthropic/models/MODEL_ID:rawPredict" \
  -d '{"anthropic_version": "vertex-2023-10-16", "messages": [{"role": "user", "content": "What is Generative AI?"}], "max_tokens": 256}'

日志条目会在 jsonPayload.httpHeaders 下记录该标签，紧邻 Claude 的 token 计数：

{
  "method": "RAW_PREDICT",
  "trafficType": "ON_DEMAND",
  "httpHeaders": {
    "x-goog-agent-platform-observability-label-team": {"values": ["payments"]}
  },
  "rawPredictDetails": {"usageMetadata": {"input_tokens": 17, "output_tokens": 16, "cache_read_input_tokens": 0, "cache_creation_input_tokens": 0}}
}

Claude 请求还可以在 X-Vertex-AI-Labels 标头中携带请求标签，如向合作伙伴模型 API 调用添加请求标签中所示。这些数据会到达 Cloud Billing，但不会写入日志条目。

查询标头标签

在 Logs Explorer 中，按一个标头标签值进行过滤：

jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"

在可观测性分析中，使用记录推理请求元数据页面上的按自定义标头标签划分的用量查询，按标头标签进行分组。

自定义元数据标签 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

什么是标签？

根据您的应用场景选择标签

在日志条目中查找每个标签

标题标签的运作方式

标题标签的限制

标签要求

标签的常见用途

支持请求标签的模型

Google 模型

合作伙伴模型

支持标题标签的模型

向 Google 模型 API 调用添加请求标签

REST

curl

PowerShell

响应

Python

向合作伙伴模型 API 调用添加请求标签

REST

Python

向 API 调用添加标头标签

向 Gemini 模型 API 调用添加标头标签

向 Claude 模型 API 调用添加标头标签

查询标头标签

自定义元数据标签