自定义元数据标签

您可以使用标签向 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。一些选项包括：
  • gemini-1.0-pro-002
  • gemini-1.0-pro-vision-001
  • gemini-1.5-pro-002
  • gemini-1.5-flash
• 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
  }
}

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