Puedes agregar metadatos personalizados a las llamadas a la API, como generateContent,
interactions.create y rawPredict, con etiquetas. En esta página, se explica qué son las etiquetas y se muestra cómo usarlas para desglosar los cargos facturados.
Acerca de las etiquetas
Una etiqueta es un par clave-valor que puedes asignar a llamadas a la API, como
generateContent, interactions.create y rawPredict. Te ayudan a
organizar estas llamadas y
administrar el uso y los costos a gran escala, con el nivel de detalle que necesitas. Puedes adjuntar una
etiqueta a cada llamada y, luego, usarlas para filtrarlas. La información
sobre las etiquetas se envía al sistema de registro y facturación, que te permite desglosar el
uso y 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 las etiquetas después de la creación, consulta un ejemplo de la
descripción general de las etiquetas.
Agent Platform admite dos tipos de etiquetas: las etiquetas del cuerpo de la solicitud, que llegan a la Facturación de Cloud, y las etiquetas de encabezado, que aparecen en los registros de metadatos de las solicitudes de inferencia. En la siguiente sección, se comparan.
Elige una etiqueta según tu caso de uso
Agent Platform ofrece dos mecanismos de etiquetado. Se configuran de manera diferente, llegan a destinos distintos y aparecen en campos diferentes del registro de metadatos de la solicitud de inferencia. Puedes usar cualquiera de los dos o ambos en la misma solicitud cuando sea posible.
Las etiquetas del cuerpo de la solicitud funcionan de la siguiente manera:
- Los configuras en el campo
labelsdel cuerpo de la solicitud. - Llegan a los registros de metadatos de solicitudes de inferencia y de Facturación de Cloud.
- Aparecen en el campo
labelsde la entrada de registro. - Se admite en el tráfico de pago por uso.
- En el caso de los modelos de socios, como Claude, las etiquetas de solicitud se envían en el
encabezado
X-Vertex-AI-Labelsen lugar del cuerpo de la solicitud. Llegan a la Facturación de Cloud, pero no se escriben en el registro de metadatos de la solicitud de inferencia.
Las etiquetas de encabezado funcionan de la siguiente manera:
- Los configuras en el encabezado de la solicitud
x-goog-agent-platform-observability-label-KEY. - Solo llegan a los registros de metadatos de las solicitudes de inferencia.
- Aparecen en el campo
jsonPayload.httpHeadersde la entrada de registro. - Métodos de API admitidos:
generateContentystreamGenerateContentpara modelos de Gemini, yrawPredictystreamRawPredictpara modelos de Claude. Opciones de consumo admitidas: capacidad de procesamiento aprovisionada y todas las opciones de pago por uso que ofrece el modelo.
Busca cada etiqueta en la entrada de registro
Una sola solicitud puede contener ambos. En la siguiente solicitud, se establece uno de cada uno:
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": "..."}]}]
}
Las dos etiquetas se ubican en campos diferentes de la misma 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"]
}
}
}
}
Los dos tipos de etiquetas ocupan campos diferentes, por lo que se consultan de manera diferente. En el Explorador de registros:
labels.cost_center="cc-1234"
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"
En Estadísticas de observabilidad:
JSON_VALUE(labels.cost_center) AS cost_center,
JSON_VALUE(json_payload.httpHeaders
["x-goog-agent-platform-observability-label-team"].values[0]) AS team
Cómo funcionan las etiquetas de encabezado
Las etiquetas de encabezado forman parte del registro de metadatos de la solicitud de inferencia. Para capturarlos, activa los registros de metadatos de solicitudes de inferencia para el proyecto.
Envía un encabezado por etiqueta con el prefijo reservado. El prefijo no distingue mayúsculas de minúsculas:
x-goog-agent-platform-observability-label-KEY: VALUE
Por ejemplo:
x-goog-agent-platform-observability-label-team: payments
x-goog-agent-platform-observability-label-application: invoice-ocr
Cada encabezado aparece en la entrada de registro en jsonPayload.httpHeaders, con la clave del
nombre del encabezado en minúsculas, con el valor en un array values, como se muestra en
Busca cada etiqueta en la entrada de registro.
Agent Platform también captura un pequeño conjunto de sus propios encabezados:
x-vertex-ai-llm-request-type y x-vertex-ai-llm-shared-request-type. No
se capturan otros encabezados.
Las etiquetas de encabezado funcionan de la misma manera para Gemini y Claude, y son la forma en que etiquetas las solicitudes de Claude en el registro de metadatos de solicitudes de inferencia.
Límites de las etiquetas de encabezado
- Una sola solicitud escribe como máximo 32 encabezados. Cuando hay más agentes aptos, Agent Platform los mantiene en orden alfabético ascendente y descarta el resto. La caída es silenciosa.
- Un valor de encabezado de más de 1,024 bytes se trunca, y la reducción se marca en el valor almacenado.
- Los encabezados repetidos con el mismo nombre se combinan en una sola entrada con varios valores.
Para consultar las etiquetas de encabezado, consulta Uso por etiqueta de encabezado personalizada.
Requisitos para las etiquetas
Las etiquetas que se aplican 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 porción de clave de una etiqueta debe ser única para una sola llamada a la API. Sin embargo, puedes usar la misma clave en 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 etiqueta 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 podría quitarse sin previo aviso si se asocian más de 1,000 valores únicos con ella.
Usos comunes de las etiquetas
Estos son algunos casos prácticos comunes de las etiquetas:
Etiquetas de equipo o del centro de costos: Agrega etiquetas por equipo o centro de costos para distinguir las llamadas a la API que pertenecen a distintos equipos (por ejemplo,
team:researchyteam:analytics). Puedes usar este tipo de etiquetas para la contabilidad de costos o la creación de presupuestos.Etiquetas de componentes: por ejemplo,
component:redis,component:frontend,component:ingestycomponent:dashboard.Etiquetas de entorno o etapa: por ejemplo,
environment:productionyenvironment:test.Etiquetas de propiedad: Se usan para identificar a los equipos responsables de las operaciones, por ejemplo:
team:shopping-cart.Atribución de abuso de usuarios finales (
safety_identifier): Adjunta un ID de usuario anonimizado por usuario (por ejemplo,safety_identifier:user_session_001) en las llamadas a Gemini y Veo para que los comentarios sobre las políticas se dirijan a usuarios finales específicos en lugar de a todo tu proyecto. Para conocer las reglas y los ejemplos de formato, consulta Pasa un identificador de seguridad del usuario final en las llamadas a la API.
No recomendamos crear grandes cantidades de etiquetas únicas, como marcas de tiempo o valores individuales para cada llamada a la API. La creación de grandes cantidades de claves únicas sobrecarga el catálogo, aumenta los tiempos de carga de forma significativa durante las consultas y dificulta el filtrado y la generación de informes eficaces para las llamadas a la API.
Modelos compatibles con las etiquetas de solicitud
Las etiquetas de solicitud y de encabezado se admiten en diferentes modelos. La capacidad
de agregar etiquetas de solicitud de anuncio a una solicitud es compatible con los modelos de Google y un subconjunto
de modelos de socios. Si agregas etiquetas de solicitud a una solicitud de un modelo no compatible, la solicitud generará un error. Los modelos de Google toman etiquetas de solicitud en el
campo labels del cuerpo de la solicitud. Los modelos de socios los toman en el encabezado X-Vertex-AI-Labels.
Modelos de Google
Los modelos de Google admiten etiquetas en los siguientes métodos de la API:
generateContentstreamGenerateContentpredictLongRunning(generación de video de Veo)interactions.create
Modelos de socios
Los modelos de socios admiten etiquetas en los siguientes métodos de la API:
rawPredictstreamRawPredict
Los siguientes modelos de socios admiten etiquetas:
Las etiquetas solo se reenvían a la Facturación de Cloud cuando la solicitud usa la opción de consumo PayGo. Las solicitudes que usan la opción de consumo de capacidad de procesamiento aprovisionada ignoran de forma silenciosa las etiquetas enviadas en la solicitud.
Modelos compatibles con las etiquetas de encabezado
Las etiquetas de encabezado solo se escriben en el registro de metadatos de la solicitud de inferencia, por lo que funcionan en los modelos y métodos que registra el registro.
- Modelos de Gemini:
generateContentystreamGenerateContent. - Modelos de Claude:
rawPredictystreamRawPredict. - Opciones de consumo: Capacidad de procesamiento aprovisionada y todas las opciones de pago por uso que ofrece el modelo.
- No se admiten otros modelos de socios, incluido Mistral AI. Una solicitud a ellos con etiquetas de encabezado aún se realiza correctamente, pero no se escribe ninguna entrada de registro, por lo que las etiquetas no se registran en ningún lugar.
- Las etiquetas de encabezado nunca llegan a la Facturación de Cloud. Para desglosar los cargos facturados, usa etiquetas de solicitud.
Agrega una etiqueta de solicitud a una llamada a la API de un modelo de Google
Para agregar una etiqueta a una llamada a la API de generateContent, streamGenerateContent o
interactions.create, 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: Es el ID del proyecto. .MODEL_ID: Es 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.
Las instrucciones de texto que se incluirán en el mensaje. JSONPROMPT_TEXT
LABEL_KEY: Son los metadatos de la etiqueta que deseas asociar con esta llamada a la API.LABEL_VALUE: Es 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"
},
}
EOFLuego, 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 utf8Luego, 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 para Python incluidas en la guía de inicio rápido de Agent Platform sobre cómo usar 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.
Los productos deGoogle Cloud 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 los servicios de Google Cloud 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 de solicitud 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: ID del proyectoMODEL_ID: Es 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 para Python incluidas en la guía de inicio rápido de Agent Platform sobre cómo usar 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: ID del proyectoMODEL_ID: Es 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"))
Agrega etiquetas de encabezado a las llamadas a la API
Las etiquetas de encabezado no necesitan cambios en el cuerpo de la solicitud. Agrega un
encabezado x-goog-agent-platform-observability-label-KEY por etiqueta a cualquier
solicitud compatible. En los siguientes ejemplos, se muestran la solicitud y los campos resultantes
de la entrada de registro de metadatos de la solicitud de inferencia, a partir de las solicitudes de prueba del 14 de octubre de 2026.
Agrega etiquetas de encabezado a una llamada a la API del modelo de Gemini
Envía etiquetas de encabezado con generateContent o streamGenerateContent. Reemplaza PROJECT_ID con el ID del proyecto.
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?"}]}]}'
La entrada de registro registra cada etiqueta en jsonPayload.httpHeaders. Las etiquetas de encabezado
también se registran en el tráfico de capacidad de procesamiento aprovisionada, que las etiquetas de solicitud
no admiten:
{
"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"}
}
Agrega etiquetas de encabezado a una llamada a la API del modelo de Claude
Envía etiquetas de encabezado con rawPredict o streamRawPredict. Reemplaza
PROJECT_ID y MODEL_ID, por
ejemplo, 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}'
La entrada de registro registra la etiqueta en jsonPayload.httpHeaders, junto a
los recuentos de tokens de 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}}
}
Una solicitud de Claude también puede llevar etiquetas de solicitud en el encabezado X-Vertex-AI-Labels,
como se muestra en
Agrega una etiqueta de solicitud a una llamada a la API del modelo de socio.
Estos llegan a la Facturación de Cloud, pero no se escriben en la entrada de registro.
Etiquetas de encabezado de consulta
En el Explorador de registros, filtra por un valor de etiqueta de encabezado:
jsonPayload.httpHeaders."x-goog-agent-platform-observability-label-team".values="payments"
En Estadísticas de observabilidad, agrupa por una etiqueta de encabezado con la consulta Uso por etiqueta de encabezado personalizada en la página Registra los metadatos de la solicitud de inferencia.