Etiquetas de metadados personalizados

Pode adicionar metadados personalizados a chamadas da API generateContent e streamGenerateContent usando etiquetas. Esta página explica o que são as etiquetas e mostra como as usar para discriminar os encargos faturados.

O que são etiquetas?

Uma etiqueta é um par de chave-valor que pode atribuir a chamadas da API generateContent e streamGenerateContent. Ajudam a organizar estas chamadas e a gerir os custos em grande escala, com o nível de detalhe de que precisa. Pode anexar uma etiqueta a cada chamada e, em seguida, filtrar as chamadas com base nas respetivas etiquetas. As informações sobre as etiquetas são encaminhadas para o sistema de faturação que lhe permite discriminar os encargos faturados por etiqueta. Com os relatórios de faturação integrados, pode filtrar e agrupar os custos por etiquetas. Também pode usar etiquetas para consultar exportações de dados de faturação. Para ver informações sobre como usar etiquetas após a criação, consulte um exemplo da vista geral das etiquetas.

Requisitos para etiquetas

As etiquetas aplicadas a uma chamada API têm de cumprir os seguintes requisitos:

  • Cada chamada API pode ter até 64 etiquetas.
  • Cada etiqueta tem de ser um par chave-valor.
  • As chaves têm um comprimento mínimo de 1 caráter e um comprimento máximo de 63 carateres, e não podem estar vazias. Os valores podem estar vazios e ter um comprimento máximo de 63 carateres.
  • As chaves e os valores só podem conter letras minúsculas, carateres numéricos, sublinhados e travessões. Todos os carateres têm de usar a codificação UTF-8, e são permitidos carateres internacionais. As chaves têm de começar com uma letra minúscula ou um caráter internacional.
  • A parte da chave de uma etiqueta tem de ser exclusiva numa única chamada API. No entanto, pode usar a mesma chave com várias chamadas.

Estes limites aplicam-se à chave e ao valor de cada etiqueta, bem como à chamada API individual que tem etiquetas. Não existe limite para o número de etiquetas que pode aplicar a todas as chamadas API num projeto.

Utilizações comuns das etiquetas

Seguem-se alguns exemplos de utilização comuns das etiquetas:

  • Etiquetas de equipa ou centro de custos: adicione etiquetas com base na equipa ou no centro de custos para distinguir as chamadas à API pertencentes a diferentes equipas (por exemplo, team:research e team:analytics). Pode usar este tipo de etiqueta para contabilidade de custos ou orçamentação.

  • Etiquetas de componentes: por exemplo, component:redis, component:frontend, component:ingest e component:dashboard.

  • Etiquetas de ambiente ou fase: por exemplo, environment:production e environment:test.

  • Etiquetas de propriedade: usadas para identificar as equipas responsáveis pelas operações, por exemplo: team:shopping-cart.

Não recomendamos a criação de um grande número de etiquetas únicas, como para indicações de tempo ou valores individuais para cada chamada da API. O problema desta abordagem é que, quando os valores mudam frequentemente ou com chaves que desorganizam o catálogo, torna-se difícil filtrar e criar relatórios de forma eficaz sobre as chamadas da API.

Adicione uma etiqueta a uma chamada da API

Para adicionar uma etiqueta a uma chamada de API generateContent ou streamGenerateContent, faça o seguinte:

REST

Antes de usar qualquer um dos dados do pedido, faça as seguintes substituições:

  • GENERATE_RESPONSE_METHOD: o tipo de resposta que quer que o modelo gere. Escolha um método que gere a forma como quer que a resposta do modelo seja devolvida:
    • streamGenerateContent: a resposta é transmitida à medida que é gerada para reduzir a perceção de latência para um público humano.
    • generateContent: a resposta é devolvida depois de ser totalmente gerada.
  • LOCATION: a região para processar o pedido. As opções disponíveis incluem o seguinte:

    Clique para expandir 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 seu ID do projeto.
  • MODEL_ID: o ID do modelo que quer usar.
  • ROLE: A função numa conversa associada ao conteúdo. É necessário especificar uma função, mesmo em exemplos de utilização de uma única interação. Os valores aceitáveis incluem o seguinte:
    • USER: especifica o conteúdo enviado por si.
    • MODEL: especifica a resposta do modelo.
  • PROMPT_TEXT
     As instruções de texto a incluir no comando. JSON
  • LABEL_KEY: os metadados da etiqueta que quer associar a esta chamada API.
  • LABEL_VALUE: o valor da etiqueta.

Para enviar o seu pedido, escolha uma destas opções:

curl

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Guarde o corpo do pedido num ficheiro denominado request.json. Execute o seguinte comando no terminal para criar ou substituir este ficheiro no diretório atual: 

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

Em seguida, execute o seguinte comando para enviar o seu pedido 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

Deve receber uma resposta JSON semelhante à seguinte.

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do Vertex AI com bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API Python Vertex AI.

Para se autenticar no Vertex AI, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para um ambiente de desenvolvimento local. 

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 Os produtos comunicam os dados de utilização e custos aos processos do Cloud Billing a intervalos variáveis. Como resultado, pode haver um atraso entre a sua utilização dos Google Cloud serviços e a disponibilidade da utilização e dos custos para visualização na faturação do Google Cloud. Normalmente, os custos estão disponíveis no prazo de um dia, mas, por vezes, podem demorar mais de 24 horas.