Rótulos de metadados personalizados

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

O que são rótulos?

Um rótulo é um par de chave-valor que pode ser atribuído a chamadas de API generateContent e streamGenerateContent. Eles ajudam a organizar essas chamadas e gerenciar seus 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 faturamento, que permite detalhar 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.

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.
  • 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 rótulos que podem ser aplicados a todas as chamadas de API em um projeto.

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.

Não recomendamos a criação de 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. O problema com essa abordagem é que, quando os valores mudam com frequência ou com chaves que desordenam o catálogo, isso dificulta a filtragem e a geração de relatórios sobre as chamadas de API.

Adicionar um rótulo a uma chamada de API

Para adicionar um rótulo a uma chamada de API generateContent ou streamGenerateContent, 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. As opções disponíveis incluem:

    Clicar para abrir uma lista parcial das regiões disponíveis

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: o ID do projeto.
  • MODEL_ID: o ID do modelo multimodal que você quer usar. Algumas opções incluem:
    • gemini-1.0-pro-002
    • gemini-1.0-pro-vision-001
    • gemini-1.5-pro-002
    • gemini-1.5-flash
  • 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.

Os produtos do Google 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 do Google 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.