Etiquetas de metadatos personalizadas

Puedes agregar metadatos personalizados a las llamadas a la API, como generateContent y rawPredict, mediante el uso de etiquetas. En esta página, se explica qué son las etiquetas y se muestra cómo usarlas para desglosar los cargos facturados.

¿Qué son las etiquetas de recurso?

Una etiqueta es un par clave-valor que puedes asignar a las llamadas a la API, como generateContent y rawPredict. Te ayudan a organizar estas llamadas y administrar los costos a gran escala, con el nivel de detalle que necesitas. Puedes adjuntar una etiqueta a cada llamada y, luego, filtrar las llamadas según sus etiquetas. La información sobre las etiquetas se envía al sistema de facturación que te permite desglosar los cargos facturados por etiqueta. Con los informes de facturación integrados, puedes filtrar y agrupar costos por etiquetas. También puedes usar etiquetas para consultar las exportaciones de datos de facturación. Para obtener información sobre cómo usar etiquetas después de la creación, consulta un ejemplo de la descripción general de las etiquetas.

Requisitos para las etiquetas

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

  • Cada llamada a la API puede tener hasta 64 etiquetas para los modelos de Google y hasta 32 etiquetas para los modelos de socios.
  • Cada etiqueta debe ser un par clave-valor.
  • La longitud de las claves debe ser de entre 1 y 63 caracteres, y no pueden estar vacías. Los valores pueden estar vacíos y su longitud máxima es de 63 caracteres.
  • Las claves y los valores pueden contener solo letras en minúscula, caracteres numéricos, guiones bajos y guiones. Todos los caracteres deben usar la codificación UTF-8, además, se permiten los caracteres internacionales. Las claves deben comenzar con una letra en minúscula o un carácter internacional.
  • La parte clave de una etiqueta debe ser única dentro de 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, y a la llamada a la API individual que tiene etiquetas. No hay límite para la cantidad de claves de etiquetas que puedes crear en todas las llamadas a la API dentro de un proyecto. Cada clave de etiqueta puede tener hasta 1,000 valores únicos en todas las solicitudes durante la vida útil de la cuenta de facturación asociada. La clave de etiqueta se puede quitar sin previo aviso si se asocian más de 1,000 valores únicos.

Usos comunes de las etiquetas

Estos son algunos casos prácticos comunes de las etiquetas:

  • Etiquetas por equipo o centro de costos: Agrega etiquetas por equipo o centro de costos para distinguir las llamadas a la API pertenecientes a diferentes equipos (por ejemplo, team:research y team:analytics). Puedes usar este tipo de etiqueta para la contabilidad de costos o el presupuesto.

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

  • Etiquetas de entorno o etapa: Por ejemplo, environment:production y environment:test.

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

No recomendamos crear grandes cantidades de etiquetas únicas, como marcas de tiempo o valores individuales para cada llamada a la API. El problema con este enfoque es que las claves sobrecargan el catálogo, aumentan significativamente los tiempos de carga durante las consultas y dificultan el filtrado y la generación de informes eficaces para las llamadas a la API.

Modelos compatibles

La capacidad de agregar etiquetas a una solicitud es compatible con los modelos de Google y un subconjunto de modelos de socios. Si agregas etiquetas a una solicitud para un modelo no compatible, la solicitud generará un error.

Modelos de Google

Los modelos de Google admiten etiquetas en los siguientes métodos de API.

  • generateContent
  • streamGenerateContent

Modelos de socios

Los modelos de socios admiten etiquetas en los siguientes métodos de API.

  • rawPredict
  • streamRawPredict

Los siguientes modelos de socios admiten etiquetas.

Las etiquetas solo se reenvían a Facturación de Cloud cuando la solicitud usa la PayGo. Las solicitudes que usan la capacidad de procesamiento aprovisionada opción de consumo ignorarán de forma silenciosa las etiquetas enviadas en la solicitud.

Agrega una etiqueta a una llamada a la API de un modelo de Google

Para agregar una etiqueta a una llamada a la API de generateContent o streamGenerateContent, haz lo siguiente:

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • GENERATE_RESPONSE_METHOD: El tipo de respuesta que quieres que genere el modelo. Elige un método que genere cómo quieres que se muestre la respuesta del modelo:
    • streamGenerateContent: La respuesta se transmite a medida que se genera para reducir la percepción de latencia para un público humano.
    • generateContent: La respuesta se muestra después de que se genera por completo.
  • LOCATION: La región para procesar la solicitud.
  • PROJECT_ID: Tu [ID del proyecto](/resource-manager/docs/creating-managing-projects#identifiers). .
  • MODEL_ID: El ID del modelo que deseas usar.
  • ROLE: el rol en una conversación asociada con el contenido. Especificar un rol es obligatorio incluso en casos de uso de un solo turno. Los valores aceptables son los siguientes:
    • USER: especifica el contenido que envías.
    • MODEL: especifica la respuesta del modelo.
  • PROMPT_TEXT
    Las instrucciones de texto que se incluirán en el mensaje. JSON
  • LABEL_KEY: Los metadatos de la etiqueta que deseas asociar con 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 comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual: 

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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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 comando siguiente en la terminal para crear o reemplazar 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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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 que se muestra a continuación:

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración de Python que encontrarás en la guía de inicio rápido de Agent Platform sobre cómo usar las bibliotecas cliente.

Para autenticarte en Agent Platform, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo 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

Google Cloud Los productos informan los datos de costos y de uso a los procesos de la Facturación de Cloud en intervalos variables. Como resultado, es posible que haya una demora entre el uso que hagas de Google Cloud los servicios y la disponibilidad para ver el uso y los costos en Facturación de Cloud. Por lo general, tus costos están disponibles en un plazo de un día, aunque, a veces, pueden tardar más de 24 horas.

Agrega una etiqueta a una llamada a la API de un modelo de socio

Para agregar una etiqueta a una llamada a la API de rawPredict o streamRawPredict, haz lo siguiente:

REST

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Tu ID del proyecto.
  • MODEL_ID: El ID del modelo que deseas usar. Por ejemplo, claude-opus-4-6.

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

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

Luego, ejecuta el siguiente comando para enviar tu solicitud de 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 probar este ejemplo, sigue las instrucciones de configuración de Python que encontrarás en la guía de inicio rápido de Agent Platform sobre cómo usar las bibliotecas cliente.

Para autenticarte en Agent Platform, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configura la autenticación para un entorno de desarrollo local.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

  • PROJECT_ID: Tu ID del proyecto.
  • MODEL_ID: El ID del modelo que deseas usar. Por ejemplo, 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"))