Rótulos de metadados personalizados

É possível adicionar metadados personalizados a chamadas de API, como generateContent, interactions.create e rawPredict, usando rótulos. Nesta página, explicamos o que são rótulos e mostramos como usá-los para detalhar as cobranças faturadas.

Sobre os rótulos

Um rótulo é um par de chave-valor que pode ser atribuído a chamadas de API, como generateContent, interactions.create e rawPredict. Eles ajudam a organizar essas chamadas e gerenciar seu uso e custos em escala, com a granularidade necessária. É possível anexar um rótulo a cada chamada e filtrar as chamadas com base nos rótulos. As informações sobre rótulos são encaminhadas ao sistema de geração de registros e sistema de faturamento, que permite detalhar o uso e as cobranças faturadas por rótulo. Com os relatórios de faturamento integrados, é possível filtrar e agrupar custos por rótulos. Também é possível usar rótulos para consultar as exportações de dados de faturamento. Para saber como usar rótulos após a criação, consulte um exemplo na visão geral de rótulos.

A Agent Platform aceita dois tipos de rótulos: os de corpo de solicitação, que chegam ao Cloud Billing, e os de cabeçalho, que aparecem nos registros de metadados de solicitações de inferência. A próxima seção compara as duas.

Escolha um rótulo com base no seu caso de uso

A Agent Platform oferece dois mecanismos de rótulo. Eles são definidos de maneira diferente, chegam a destinos diferentes e aparecem em campos diferentes do registro de metadados da solicitação de inferência. É possível usar um ou ambos na mesma solicitação, quando houver suporte.

Os rótulos do corpo da solicitação funcionam da seguinte maneira:

  • Defina-os no campo labels do corpo da solicitação.
  • Eles alcançam os registros de metadados de solicitações de inferência e do Cloud Billing.
  • Eles aparecem no campo labels da entrada de registro.
  • Compatível com o tráfego de pagamento por uso.
  • Para modelos de parceiros, como o Claude, os rótulos de solicitação são enviados no cabeçalho X-Vertex-AI-Labels em vez do corpo da solicitação. Eles chegam ao Cloud Billing, mas não são gravados no registro de metadados da solicitação de inferência.

Os rótulos de cabeçalho funcionam da seguinte maneira:

  • Você as define no cabeçalho da solicitação x-goog-agent-platform-observability-label-KEY.
  • Eles alcançam apenas os registros de metadados de solicitação de inferência.
  • Eles aparecem no campo jsonPayload.httpHeaders da entrada de registro.
  • Métodos de API compatíveis: generateContent e streamGenerateContent para modelos do Gemini e rawPredict e streamRawPredict para modelos do Claude. Opções de consumo compatíveis: capacidade de processamento provisionada e todas as opções de pagamento por uso oferecidas pelo modelo.

Encontrar cada rótulo na entrada de registro

Uma única solicitação pode conter os dois. A solicitação a seguir define um de cada:

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": "..."}]}]
}

Os dois rótulos vão para campos diferentes da mesma entrada de registro:

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

Os dois tipos de rótulo ocupam campos diferentes, então são consultados de maneira diferente. Na Análise de registros:

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

Na Análise de Observabilidade:

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

Como funcionam os rótulos de cabeçalho

Os rótulos de cabeçalho fazem parte do registro de metadados da solicitação de inferência. Para capturá-los, ative os registros de metadados de solicitação de inferência para o projeto.

Envie um cabeçalho por rótulo usando o prefixo reservado. O prefixo não diferencia maiúsculas de minúsculas:

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

Exemplo:

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

Cada cabeçalho aparece na entrada de registro em jsonPayload.httpHeaders, com chave pelo nome do cabeçalho em letras minúsculas, com o valor em uma matriz values, conforme mostrado em Encontrar cada rótulo na entrada de registro.

A Agent Platform também captura um pequeno conjunto de cabeçalhos próprios: x-vertex-ai-llm-request-type e x-vertex-ai-llm-shared-request-type. Nenhum outro cabeçalho é capturado.

Os rótulos de cabeçalho funcionam da mesma forma para o Gemini e o Claude, e é assim que você rotula as solicitações do Claude no registro de metadados de solicitações de inferência.

Limites para rótulos de cabeçalho

  • Uma única solicitação grava no máximo 32 cabeçalhos. Quando mais de um agente é qualificado, a Agent Platform os mantém em ordem alfabética crescente e descarta o restante. A queda é silenciosa.
  • Um valor de cabeçalho com mais de 1.024 bytes é truncado, e o truncamento é marcado no valor armazenado.
  • Cabeçalhos repetidos com o mesmo nome são combinados em uma única entrada com vários valores.

Para consultar rótulos de cabeçalho, consulte Uso por rótulo de cabeçalho personalizado.

Requisitos dos rótulos

Os rótulos aplicados a uma chamada de API precisam atender aos seguintes requisitos:

  • Cada chamada de API pode ter até 64 rótulos para modelos do Google e até 32 rótulos para modelos de parceiros.
  • Cada rótulo precisa ser um par de chave-valor.
  • As chaves têm comprimento mínimo de 1 e máximo de 63 caracteres. Além disso, elas não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 caracteres.
  • As chaves e os valores contêm apenas letras minúsculas, caracteres numéricos, sublinhados e traços. Todos os caracteres precisam usar a codificação UTF-8, e os caracteres internacionais são permitidos. As chaves precisam começar com uma letra minúscula ou um caractere internacional.
  • A parte principal de um rótulo precisa ser exclusiva em uma única chamada de API. No entanto, é possível usar a mesma chave com várias chamadas.

Esses limites se aplicam à chave e ao valor de cada rótulo e à chamada de API individual que tem rótulos. Não há limite para a quantidade de chaves de rótulo que podem ser criadas em todas as chamadas de API em um projeto. Cada chave de rótulo pode ter até 1.000 valores exclusivos em todas as solicitações durante a vida útil da conta de faturamento associada. A chave do rótulo poderá ser descartada sem aviso se mais de 1.000 valores exclusivos forem associados a ela.

Usos comuns dos rótulos

Veja alguns casos de uso comum para rótulos:

  • Rótulos de centro de custo ou de equipe: adicione rótulos com base na equipe ou no centro de custo para distinguir as chamadas de API pertencentes a equipes diferentes (por exemplo, team:research e team:analytics). É possível usar esse tipo de rótulo para contabilização de custos ou definição de orçamento.

  • Rótulos de componentes: por exemplo, component:redis, component:frontend, component:ingest e component:dashboard.

  • Rótulos de ambientes ou de estágios: por exemplo, environment:production e environment:test.

  • Rótulos de propriedade: usados para identificar as equipes responsáveis pelas operações, por exemplo: team:shopping-cart.

  • Atribuição de abuso do usuário final (safety_identifier): anexe um ID anônimo por usuário (por exemplo, safety_identifier:user_session_001) nas chamadas do Gemini e do Veo para que o feedback da política seja direcionado a usuários finais específicos, em vez de todo o projeto. Para ver regras e exemplos de formatação, consulte Transmitir um identificador de segurança do usuário final em chamadas de API.

Evite criar um grande número de rótulos exclusivos, como aqueles relacionados a carimbos de data/hora ou valores individuais, para todas as chamadas de API. Criar um grande número de chaves exclusivas desorganiza o catálogo, aumenta significativamente os tempos de carregamento durante as consultas e dificulta a filtragem e a geração de relatórios sobre as chamadas de API.

Modelos compatíveis com rótulos de solicitação

Os rótulos de solicitação e de cabeçalho são compatíveis com modelos diferentes. A capacidade de adicionar rótulos a uma solicitação é compatível com os modelos do Google e um subconjunto de modelos de parceiros. Se você adicionar rótulos de solicitação a uma solicitação de um modelo não compatível, ela vai resultar em um erro. Os modelos do Google usam rótulos de solicitação no campo labels do corpo da solicitação. Os modelos de parceiros os recebem no cabeçalho X-Vertex-AI-Labels.

Modelos do Google

Os modelos do Google aceitam rótulos nos seguintes métodos de API:

  • generateContent
  • streamGenerateContent
  • predictLongRunning (geração de vídeos do Veo)
  • interactions.create

Modelos de parceiros

Os modelos de parceiros aceitam rótulos nos seguintes métodos de API:

  • rawPredict
  • streamRawPredict

Os seguintes modelos de parceiros são compatíveis com rótulos:

Os rótulos só são encaminhados para o Cloud Billing quando a solicitação usa a opção de consumo PayGo. As solicitações que usam a opção de consumo de capacidade de processamento provisionada ignoram silenciosamente os rótulos enviados na solicitação.

Modelos compatíveis com rótulos de cabeçalho

Os rótulos de cabeçalho são gravados apenas no registro de metadados da solicitação de inferência, portanto, funcionam nos modelos e métodos que o registro grava.

  • Modelos do Gemini: generateContent e streamGenerateContent.
  • Modelos Claude: rawPredict e streamRawPredict.
  • Opções de consumo: capacidade de processamento provisionada e todas as opções de pagamento por uso oferecidas pelo modelo.
  • Outros modelos de parceiros, incluindo o Mistral AI, não são compatíveis. Uma solicitação para eles com rótulos de cabeçalho ainda é bem-sucedida, mas nenhuma entrada de registro é gravada, então os rótulos não são registrados em nenhum lugar.
  • Os rótulos de cabeçalho nunca chegam ao Cloud Billing. Para detalhar as cobranças faturadas, use rótulos de solicitação.

Adicionar um rótulo de solicitação a uma chamada de API de modelo do Google

Para adicionar um rótulo a uma chamada de API generateContent, streamGenerateContent ou interactions.create, faça isto:

REST

Antes de usar os dados da solicitação abaixo, faça as substituições a seguir:

  • GENERATE_RESPONSE_METHOD: o tipo de resposta que você quer que o modelo gere. Escolha um método que gere como você quer que a resposta do modelo seja retornada:
    • streamGenerateContent: a resposta é transmitida conforme é gerada para reduzir a percepção de latência para o público humano.
    • generateContent: a resposta será retornada depois de ser totalmente gerada.
  • LOCATION: a região para processar a solicitação.
  • PROJECT_ID: o ID do projeto. .
  • MODEL_ID: o ID do modelo que você quer usar.
  • ROLE: o papel em uma conversa associada ao conteúdo. É necessário especificar um papel mesmo em casos de uso de turno único. Os valores aceitáveis são os seguintes:
    • USER: especifica o conteúdo que é enviado por você.
    • MODEL: especifica a resposta do modelo.
  • PROMPT_TEXT
    As instruções de texto a serem incluídas no comando. JSON
  • LABEL_KEY: os metadados do rótulo que você quer associar a essa chamada de API.
  • LABEL_VALUE: o valor do rótulo.

Para enviar a solicitação, escolha uma destas opções:

curl

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "contents": {
    "role": "ROLE",
    "parts": { "text": "PROMPT_TEXT" }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
}
EOF

Depois execute o comando a seguir para enviar a solicitação 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

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

@'
{
  "contents": {
    "role": "ROLE",
    "parts": { "text": "PROMPT_TEXT" }
  },
  "labels": {
    "LABEL_KEY": "LABEL_VALUE"
  },
}
'@  | Out-File -FilePath request.json -Encoding utf8

Depois execute o comando a seguir para enviar a solicitação 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

Você receberá uma resposta JSON semelhante a seguinte.

Python

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na plataforma de agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.


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

Os produtos doGoogle Cloud informam dados de uso e custo para processos do Cloud Billing em intervalos variados. Como resultado, pode haver um atraso entre o uso dos serviços doGoogle Cloud e a disponibilização do uso e dos custos para visualização no Cloud Billing. Normalmente, os custos ficam disponíveis em um dia, mas às vezes podem demorar mais de 24 horas.

Adicionar um rótulo de solicitação a uma chamada de API de modelo de parceiro

Para adicionar um rótulo a uma chamada de API rawPredict ou streamRawPredict, faça isto:

REST

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • MODEL_ID: o ID do modelo que você quer usar. Por exemplo, claude-opus-4-6.

Salve o corpo da solicitação em um arquivo chamado request.json. Execute o comando a seguir no terminal para criar ou substituir esse arquivo no diretório atual:

cat > request.json << 'EOF'
{
  "anthropic_version": "vertex-2023-10-16",
  "messages": [
    {
      "role": "user",
      "content": "What is Generative AI?"
    }
  ],
  "max_tokens": 1024,
  "stream": false
}
EOF

Depois execute o comando a seguir para enviar a solicitação 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

Antes de testar este exemplo, siga as instruções de configuração do Python no guia de início rápido da plataforma de agentes: como usar bibliotecas de cliente.

Para autenticar na plataforma de agentes, configure o Application Default Credentials. Para mais informações, consulte Configurar a autenticação para um ambiente de desenvolvimento local.

Antes de usar os dados da solicitação, faça as substituições a seguir:

  • PROJECT_ID: o ID do projeto.
  • MODEL_ID: o ID do modelo que você quer usar. Por exemplo, 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"))

Adicionar rótulos de cabeçalho às chamadas de API

Os rótulos de cabeçalho não precisam de mudanças no corpo da solicitação. Adicione um cabeçalho x-goog-agent-platform-observability-label-KEY por rótulo a qualquer solicitação compatível. Os exemplos a seguir mostram a solicitação e os campos resultantes da entrada de registro de metadados da solicitação de inferência, de solicitações de teste em 14/10/2026.

Adicionar rótulos de cabeçalho a uma chamada de API do modelo do Gemini

Envie rótulos de cabeçalho com generateContent ou streamGenerateContent. Substitua PROJECT_ID pelo ID do projeto.

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?"}]}]}'

A entrada de registro registra cada rótulo em jsonPayload.httpHeaders. Os rótulos de cabeçalho também são registrados no tráfego da Capacidade de Processamento Provisionada, o que não é compatível com os rótulos de solicitação:

{
  "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"}
}

Adicionar rótulos de cabeçalho a uma chamada de API do modelo Claude

Envie rótulos de cabeçalho com rawPredict ou streamRawPredict. Substitua PROJECT_ID e MODEL_ID, por exemplo, 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}'

A entrada de registro registra o rótulo em jsonPayload.httpHeaders, ao lado das contagens de tokens do Claude:

{
  "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}}
}

Uma solicitação do Claude também pode conter rótulos de solicitação no cabeçalho X-Vertex-AI-Labels, conforme mostrado em Adicionar um rótulo de solicitação a uma chamada de API de modelo de parceiro. Eles chegam ao Cloud Billing, mas não são gravados na entrada de registro.

Rótulos de cabeçalho de consulta

Na Análise de Registros, filtre por um valor de rótulo de cabeçalho:

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

Na Análise de Observabilidade, agrupe por um rótulo de cabeçalho com a consulta Uso por rótulo de cabeçalho personalizado na página Metadados de solicitação de inferência de registro.