自定义元数据标签

您可以使用标签向 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

在尝试此示例之前，请按照《Vertex AI 快速入门：使用客户端库》中的 Python 设置说明执行操作。 如需了解详情，请参阅 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 进程报告使用情况和费用数据。因此，您可能会在使用Google Cloud 服务与可在 Cloud Billing 中查看的使用量和费用之间看到延迟现象。通常一天之内即可获得您的费用信息，但有时可能需要 24 小时以上。