Etiquetas de metadatos personalizados

Puedes añadir metadatos personalizados a las llamadas a las APIs generateContent y streamGenerateContent mediante etiquetas. En esta página se explica qué son las etiquetas y cómo usarlas para desglosar los cargos facturados.

¿Qué son las etiquetas?

Una etiqueta es un par clave-valor que puedes asignar a las llamadas a las APIs generateContent y streamGenerateContent. Te ayudan a organizar estas llamadas y a gestionar tus costes a gran escala, con la granularidad que necesites. Puedes asignar una etiqueta a cada llamada y, después, filtrar las llamadas por etiquetas. La información relacionada con las etiquetas se reenvía al sistema de facturación para que puedas desglosar los cargos facturados por etiquetas. Con los informes de facturación integrados, puedes filtrar y agrupar los costes por etiquetas. También puedes usar etiquetas para consultar exportaciones de datos de facturación. Para obtener información sobre cómo usar las etiquetas después de crearlas, consulta un ejemplo de la descripción general de las etiquetas.

Requisitos de las etiquetas

Las etiquetas aplicadas a una llamada a la API deben cumplir los siguientes requisitos:

  • Cada llamada a la API puede tener hasta 64 etiquetas.
  • Cada etiqueta debe ser un par clave-valor.
  • Las claves deben tener como mínimo 1 carácter y como máximo 63 caracteres, y no pueden estar vacías. Los valores pueden estar vacíos y pueden tener hasta 63 caracteres.
  • Las claves y los valores solo pueden contener letras minúsculas, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar codificación UTF-8, y se pueden usar caracteres internacionales. Las claves deben empezar por una letra minúscula o un carácter internacional.
  • La parte de la clave de una etiqueta debe ser única en una sola llamada a la API. Sin embargo, puedes usar la misma clave con varias llamadas.

Estos límites se aplican a la clave y al valor de cada etiqueta, así como a la llamada a la API individual que tenga etiquetas. No hay límite en el número de etiquetas que puedes aplicar en todas las llamadas a la API de un proyecto.

Usos habituales de las etiquetas

A continuación se indican algunos de los usos más habituales de las etiquetas:

  • Etiquetas de equipo o centro de costes: añade etiquetas basadas en el equipo o el centro de costes para distinguir las llamadas a la API que pertenecen a diferentes equipos (por ejemplo, team:research y team:analytics). Puedes usar este tipo de etiqueta para la contabilidad de costes o la elaboración de presupuestos.

  • Etiquetas de componentes: por ejemplo, component:redis, component:frontend, component:ingest y component:dashboard.

  • Etiquetas de entorno o fase: por ejemplo, environment:production y environment:test.

  • Etiquetas de propiedad: se usan para identificar los equipos responsables de las operaciones. Por ejemplo, team:shopping-cart.

No recomendamos crear un gran número de etiquetas únicas, como las de marcas de tiempo o valores individuales para cada llamada a la API. El problema de este enfoque es que, cuando los valores cambian con frecuencia o con claves que saturan el catálogo, resulta difícil filtrar y generar informes sobre las llamadas a la API de forma eficaz.

Añadir una etiqueta a una llamada a la API

Para añadir una etiqueta a una llamada a la API generateContent o streamGenerateContent, haz lo siguiente:

REST

Antes de usar los datos de la solicitud, haz las siguientes sustituciones:

  • GENERATE_RESPONSE_METHOD: el tipo de respuesta que quieres que genere el modelo. Elige un método que genere la forma en que quieres que se devuelva la respuesta del modelo:
    • streamGenerateContent: la respuesta se transmite en tiempo real a medida que se genera para reducir la percepción de latencia de los usuarios.
    • generateContent: La respuesta se devuelve una vez que se ha generado por completo.
  • LOCATION: la región en la que se procesará la solicitud. Entre las opciones disponibles se incluyen las siguientes:

    Haz clic para ver una lista parcial de las regiones disponibles

    • us-central1
    • us-west4
    • northamerica-northeast1
    • us-east4
    • us-west1
    • asia-northeast3
    • asia-southeast1
    • asia-northeast1
  • PROJECT_ID: tu ID de proyecto.
  • MODEL_ID: el ID del modelo que quieres usar.
  • ROLE: el rol en una conversación asociado al contenido. Es obligatorio especificar un rol incluso en los casos prácticos de una sola interacción. Entre los valores aceptados se incluyen los siguientes:
    • USER: especifica el contenido que has enviado.
    • MODEL: especifica la respuesta del modelo.
  • PROMPT_TEXT
     Las instrucciones de texto que se deben incluir en la petición. JSON
  • LABEL_KEY: los metadatos de la etiqueta que quieras asociar a esta llamada a la API.
  • LABEL_VALUE: el valor de la etiqueta.

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual: 

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

A continuación, ejecuta el siguiente comando para enviar tu solicitud 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

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el siguiente comando en el terminal para crear o sobrescribir este archivo en el directorio actual: 

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

A continuación, ejecuta el siguiente comando para enviar tu solicitud 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

Deberías recibir una respuesta JSON similar a la siguiente.

Python

Antes de probar este ejemplo, sigue las Python instrucciones de configuración de la guía de inicio rápido de Vertex AI con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de Vertex AI.

Para autenticarte en Vertex AI, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación en un entorno de desarrollo 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.

Los productos deGoogle Cloud envían datos de uso y costes a los procesos de Facturación de Cloud a intervalos variables. Por lo tanto, es posible que haya un retraso entre el uso de los servicios deGoogle Cloud y la disponibilidad del uso y los costes en la facturación de Cloud. Por lo general, los costes están disponibles en un plazo de un día, pero a veces pueden tardar más de 24 horas.