您可以使用标签向 generateContent 和 rawPredict 等 API 调用添加自定义元数据。本页介绍了标签的含义，并展示了如何使用标签细分账单费用。
什么是标签？
标签是一种键值对，可分配给 generateContent 和 rawPredict 等 API 调用。它们可以帮助您按照所需的粒度大规模组织这些调用并管理费用。您可以将标签附加到各个调用，然后根据其标签对调用进行过滤。标签的相关信息会转发到结算系统，以便您按标签细分结算费用。使用内置的结算报告，您可以按标签对费用进行过滤和分组。您还可以使用标签查询结算数据导出。如需了解如何在创建标签后使用标签，请参阅标签概览中的示例。
标签要求
应用于 API 调用的标签必须满足以下要求：
- 每次 API 调用最多可以包含 64 个 Google 模型标签和 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 模型
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 设置说明进行操作。
如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
Google Cloud 产品会按不同的时间间隔向 Cloud Billing 流程报告用量和费用数据。因此，您可能会在使用Google Cloud 服务与可在 Cloud Billing 中查看的使用量和费用之间看到延迟现象。通常一天之内即可获得您的费用信息，但有时可能需要 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 设置说明进行操作。
如需向代理平台进行身份验证，请设置应用默认凭据。 如需了解详情，请参阅为本地开发环境设置身份验证。
在使用任何请求数据之前，请先进行以下替换：
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"))