Usa la capacidad de procesamiento aprovisionada

En esta página, se explica cómo funciona la capacidad de procesamiento aprovisionada, cómo controlar los excedentes u omitir la capacidad de procesamiento aprovisionada y cómo supervisar el uso.

Cómo funciona la capacidad de procesamiento aprovisionada

En esta sección, se explica cómo funciona la capacidad de procesamiento aprovisionada a través de la verificación de cuotas durante el período de aplicación de cuotas.

Verificación de la cuota de capacidad de procesamiento aprovisionada

Tu cuota máxima de capacidad de procesamiento aprovisionada es un múltiplo de la cantidad de unidades de escalamiento de IA generativa (GSU) compradas y la capacidad de procesamiento por GSU. Se verifica cada vez que realizas una solicitud dentro de tu período de aplicación de la cuota, que es la frecuencia con la que se aplica la cuota máxima de capacidad de procesamiento aprovisionada.

En el momento en que se recibe una solicitud, se desconoce el tamaño real de la respuesta. Dado que priorizamos la velocidad de respuesta para las aplicaciones en tiempo real, la capacidad de procesamiento aprovisionada estima el tamaño del token de salida. Si la estimación inicial supera la cuota máxima disponible de capacidad de procesamiento aprovisionada, la solicitud se procesa como pago por uso. De lo contrario, se procesa como capacidad de procesamiento aprovisionada. Para ello, se compara la estimación inicial con tu cuota máxima de capacidad de procesamiento aprovisionada.

Cuando se genera la respuesta y se conoce el tamaño real del token de salida, el uso y la cuota reales se concilian agregando la diferencia entre la estimación y el uso real a la cantidad de cuota de capacidad de procesamiento aprovisionada disponible.

Período de aplicación de la cuota de capacidad de procesamiento aprovisionada

En el caso de los modelos de Gemini, el período de aplicación de la cuota puede tardar hasta 30 segundos y está sujeto a cambios. Esto significa que, en algunos casos, es posible que experimentes temporalmente tráfico prioritario que supere tu cuota por segundo, pero no deberías superar tu cuota por cada 30 segundos. Estos períodos se basan en el tiempo interno de Vertex AI y son independientes del momento en que se realizan las solicitudes.

Por ejemplo, si compras una GSU de gemini-2.0-flash-001, deberías esperar 3,360 tokens por segundo de capacidad de procesamiento siempre activa. En promedio, no puedes superar los 100,800 tokens en un período de 30 segundos, lo que se calcula con la siguiente fórmula:

3,360 tokens per second * 30 seconds = 100,800 tokens

Si, en un día, enviaste solo una solicitud que consumió 8,000 tokens en un segundo, es posible que se procese como una solicitud de capacidad de procesamiento aprovisionada, aunque hayas superado el límite de 3,360 tokens por segundo en el momento de la solicitud. Esto se debe a que la solicitud no superó el umbral de 100,800 tokens por 30 segundos.

Controla los excesos o evita la capacidad de procesamiento aprovisionada

Usa la API para controlar los excedentes cuando superes la capacidad de procesamiento que compraste o para omitir la capacidad de procesamiento aprovisionada por solicitud.

Lee cada opción para determinar qué debes hacer para cumplir con tu caso de uso.

Comportamiento predeterminado

Si una solicitud supera la cuota restante de capacidad de procesamiento aprovisionada, de forma predeterminada, toda la solicitud se procesa como una solicitud a pedido y se factura según la tarifa de pago por uso. Cuando esto sucede, el tráfico aparece como desbordamiento en los paneles de supervisión. Para obtener más información sobre cómo supervisar el uso de la capacidad de procesamiento aprovisionada, consulta Supervisa la capacidad de procesamiento aprovisionada.

Una vez que tu pedido de capacidad de procesamiento aprovisionada esté activo, el comportamiento predeterminado se producirá automáticamente. No es necesario que cambies tu código para comenzar a consumir tu pedido, siempre y cuando lo hagas en la región aprovisionada.

Usar solo la capacidad de procesamiento aprovisionada

Si administras los costos evitando los cargos según demanda, usa solo la capacidad de procesamiento aprovisionada. Las solicitudes que excedan el importe del pedido de capacidad de procesamiento aprovisionada devolverán un error 429.

Cuando envíes solicitudes a la API, configura el encabezado HTTP X-Vertex-AI-LLM-Request-Type en dedicated.

Usar solo el modelo de pago por uso

Esto también se conoce como uso a pedido. Las solicitudes omiten el pedido de capacidad de procesamiento aprovisionada y se envían directamente al pago por uso. Esto puede ser útil para experimentos o aplicaciones en desarrollo.

Cuando envíes solicitudes a la API, configura el encabezado HTTP X-Vertex-AI-LLM-Request-Type en shared.

Ejemplo

Python

Instalar

pip install --upgrade google-genai

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(
    http_options=HttpOptions(
        api_version="v1",
        headers={
            # Options:
            # - "dedicated": Use Provisioned Throughput
            # - "shared": Use pay-as-you-go
            # https://cloud.google.com/vertex-ai/generative-ai/docs/use-provisioned-throughput
            "X-Vertex-AI-LLM-Request-Type": "shared"
        },
    )
)
response = client.models.generate_content(
    model="gemini-2.5-flash",
    contents="How does AI work?",
)
print(response.text)
# Example response:
# Okay, let's break down how AI works. It's a broad field, so I'll focus on the ...
#
# Here's a simplified overview:
# ...

Go

Obtén información para instalar o actualizar Go.

Para obtener más información, consulta la documentación de referencia del SDK.

Establece variables de entorno para usar el SDK de IA generativa con Vertex AI:

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_VERTEXAI=True

import (
	"context"
	"fmt"
	"io"
	"net/http"

	"google.golang.org/genai"
)

// generateText shows how to generate text Provisioned Throughput.
func generateText(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{
			APIVersion: "v1",
			Headers: http.Header{
				// Options:
				// - "dedicated": Use Provisioned Throughput
				// - "shared": Use pay-as-you-go
				// https://cloud.google.com/vertex-ai/generative-ai/docs/use-provisioned-throughput
				"X-Vertex-AI-LLM-Request-Type": []string{"shared"},
			},
		},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	modelName := "gemini-2.5-flash"
	contents := genai.Text("How does AI work?")

	resp, err := client.Models.GenerateContent(ctx, modelName, contents, nil)
	if err != nil {
		return fmt.Errorf("failed to generate content: %w", err)
	}

	respText := resp.Text()

	fmt.Fprintln(w, respText)

	// Example response:
	// Artificial Intelligence (AI) isn't magic, nor is it a single "thing." Instead, it's a broad field of computer science focused on creating machines that can perform tasks that typically require human intelligence.
	// .....
	// In Summary:
	// ...

	return nil
}

REST

Después de configurar tu entorno, puedes usar REST para probar una instrucción de texto. En el siguiente ejemplo, se envía una solicitud al extremo del modelo de publicador.

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -H "X-Vertex-AI-LLM-Request-Type: dedicated" \ # Options: dedicated, shared
  $URL \
  -d '{"contents": [{"role": "user", "parts": [{"text": "Hello."}]}]}'

Usa el procesamiento aprovisionado con una clave de API

Si compraste capacidad de procesamiento aprovisionada para un proyecto, un modelo de Google y una región específicos, y quieres usarla para enviar una solicitud con una clave de API, debes incluir el ID del proyecto, el modelo, la ubicación y la clave de API como parámetros en tu solicitud.

Para obtener información sobre cómo crear una Google Cloud clave de API vinculada a una cuenta de servicio, consulta Obtén una Google Cloud clave de API. Para obtener información sobre cómo enviar solicitudes a la API de Gemini con una clave de API, consulta la guía de inicio rápido de GeminiAPI en Vertex AI.

Por ejemplo, en la siguiente muestra, se muestra cómo enviar una solicitud con una clave de API mientras se usa el procesamiento aprovisionado:

REST

Después de configurar tu entorno, puedes usar REST para probar una instrucción de texto. En el siguiente ejemplo, se envía una solicitud al extremo del modelo de publicador.

curl \
-X POST \
-H "Content-Type: application/json" \
"https://aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/publishers/google/models/MODEL_ID:generateContent?key=YOUR_API_KEY" \
-d $'{
  "contents": [
    {
      "role": "user",
      "parts": [
        {
          "text": "Explain how AI works in a few words"
        }
      ]
    }
  ]
}'

Supervisa la capacidad de procesamiento aprovisionada

Versión preliminar

Esta función está sujeta a las “Condiciones de la Oferta de la Fase Previa a la DG” en la sección Condiciones del Servicio Generales de las Condiciones Específicas del Servicio. Las funciones de la fase previa a la DG están disponibles sin modificaciones y pueden tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Puedes supervisar por tu cuenta el uso de la capacidad de procesamiento aprovisionada con un conjunto de métricas que se miden en el tipo de recurso aiplatform.googleapis.com/PublisherModel.

El monitoreo del tráfico de la capacidad de procesamiento aprovisionada es una función de versión preliminar pública.

Dimensiones

Puedes filtrar las métricas con las siguientes dimensiones:

Dimensión	Valores
type	input output
request_type	dedicated: El tráfico se procesa con la capacidad de procesamiento aprovisionada. spillover: El tráfico se procesa como cuota de pago por uso después de que superas tu cuota de capacidad de procesamiento aprovisionada. Ten en cuenta que la métrica spillover no es compatible con el rendimiento aprovisionado para los modelos de Gemini 2.0 si está habilitado el almacenamiento en caché explícito, ya que estos modelos no admiten el almacenamiento en caché explícito. En este caso, el tráfico aparece como shared. shared: Si el rendimiento aprovisionado está activo, el tráfico se procesa como una cuota de pago por uso con el encabezado HTTP compartido. Si la capacidad de procesamiento aprovisionada no está activa, el tráfico se procesa como pago por uso de forma predeterminada.

Prefijo de ruta de acceso

El prefijo de ruta de acceso para una métrica es aiplatform.googleapis.com/publisher/online_serving.

Por ejemplo, la ruta completa de la métrica /consumed_throughput es aiplatform.googleapis.com/publisher/online_serving/consumed_throughput.

Métricas

Las siguientes métricas de Cloud Monitoring están disponibles en el recurso aiplatform.googleapis.com/PublisherModel para los modelos de Gemini. Usa los tipos de solicitudes dedicated para filtrar el uso de la capacidad de procesamiento aprovisionada.

Métrica	Nombre visible	Descripción
/dedicated_gsu_limit	Límite (GSU)	Límite dedicado en GSU. Usa esta métrica para comprender tu cuota máxima de capacidad de procesamiento aprovisionada en GSU.
/tokens	Tokens	Distribución del recuento de tokens de entrada y salida.
/token_count	Recuento de tokens	Cantidad acumulada de tokens de entrada y salida.
/consumed_token_throughput	Capacidad de procesamiento de tokens	Uso de la capacidad de procesamiento, que tiene en cuenta la tasa de consumo en tokens y que incorpora la conciliación de cuotas. Consulta Verificación de la cuota de capacidad de procesamiento aprovisionada. Usa esta métrica para comprender cómo se usó tu cuota de capacidad de procesamiento aprovisionada.
/dedicated_token_limit	Límite (tokens por segundo)	Límite dedicado en tokens por segundo. Usa esta métrica para comprender tu cuota máxima de capacidad de procesamiento aprovisionada para los modelos basados en tokens.
/characters	Caracteres	Distribución del recuento de caracteres de entrada y salida.
/character_count	Recuento de caracteres	Es el recuento acumulado de caracteres de entrada y salida.
/consumed_throughput	Capacidad de procesamiento de caracteres	Uso de la capacidad de procesamiento, que tiene en cuenta la tasa de consumo en caracteres y la conciliación de la cuota verificación de la cuota de capacidad de procesamiento aprovisionada. Usa esta métrica para comprender cómo se usó tu cuota de capacidad de procesamiento aprovisionada. En el caso de los modelos basados en tokens, esta métrica equivale al rendimiento consumido en tokens multiplicado por 4.
/dedicated_character_limit	Límite (caracteres por segundo)	Límite dedicado en caracteres por segundo. Usa esta métrica para comprender tu cuota máxima de capacidad de procesamiento aprovisionada para los modelos basados en caracteres.
/model_invocation_count	Recuento de invocaciones de modelos	Cantidad de invocaciones de modelos (solicitudes de predicción).
/model_invocation_latencies	Latencias de invocación de modelos	Latencias de invocación del modelo (latencia de predicción)
/first_token_latencies	Latencias del primer token	Es la duración desde que se recibe la solicitud hasta que se muestra el primer token.

Los modelos de Anthropic también tienen un filtro para la capacidad de procesamiento aprovisionada, pero solo para tokens y token_count.

Paneles

Los paneles de supervisión predeterminados para la capacidad de procesamiento aprovisionada proporcionan métricas que te permiten comprender mejor tu uso y la utilización de la capacidad de procesamiento aprovisionada. Para acceder a los paneles, haz lo siguiente:

1. En la consola de Google Cloud , ve a la página Capacidad de procesamiento aprovisionada.

   Ir a Capacidad de procesamiento aprovisionada

2. Para ver el uso de la capacidad de procesamiento aprovisionada de cada modelo en todos tus pedidos, selecciona la pestaña Resumen de uso.

   En la tabla Uso de la capacidad de procesamiento aprovisionada por modelo, puedes ver lo siguiente para el período seleccionado:

   • Cantidad total de GSU que tenías.

   • Uso máximo de capacidad de procesamiento en términos de GSU.

   • Es el uso promedio de GSU.

   • Es la cantidad de veces que alcanzaste tu límite de capacidad de procesamiento aprovisionada.

3. Selecciona un modelo en la tabla Utilización de la capacidad de procesamiento aprovisionada por modelo para ver más métricas específicas del modelo seleccionado.

Cómo interpretar los paneles de supervisión

El rendimiento aprovisionado verifica la cuota disponible en tiempo real a nivel de milisegundos para las solicitudes a medida que se realizan, pero compara estos datos con un período de aplicación de la cuota continuo de 30 segundos, según la hora del reloj interno de Vertex AI. Esta comparación es independiente del momento en que se realizan las solicitudes. Los paneles de supervisión informan las métricas de uso después de que se realiza la conciliación de la cuota. Sin embargo, estas métricas se agregan para proporcionar promedios de los períodos de alineación del panel, según el intervalo de tiempo seleccionado. El nivel de detalle más bajo posible que admiten los paneles de supervisión es el nivel de minutos. Además, la hora del reloj de los paneles de supervisión es diferente de la de Vertex AI.

En ocasiones, estas diferencias en los tiempos pueden generar discrepancias entre los datos de los paneles de supervisión y el rendimiento en tiempo real. Esto puede deberse a cualquiera de los siguientes motivos:

• La cuota se aplica en tiempo real, pero los gráficos de supervisión agregan datos en períodos de alineación del panel de 1 minuto o más, según el período especificado en los paneles de supervisión.

• Vertex AI y los paneles de supervisión se ejecutan en diferentes relojes del sistema.

• Si un aumento repentino de tráfico durante un período de 1 segundo supera tu cuota de capacidad de procesamiento aprovisionada, toda la solicitud se procesará como tráfico de desbordamiento. Sin embargo, la utilización general del rendimiento aprovisionado puede parecer baja cuando los datos de supervisión de ese segundo se promedian dentro del período de alineación de 1 minuto, ya que la utilización promedio en todo el período de alineación podría no superar el 100%. Si ves tráfico de desbordamiento, se confirma que tu cuota de capacidad de procesamiento aprovisionada se utilizó por completo durante el período de aplicación de la cuota en el que se realizaron esas solicitudes específicas. Esto se aplica independientemente del uso promedio que se muestra en los paneles de supervisión.

Ejemplo de posible discrepancia en los datos de supervisión

En este ejemplo, se ilustran algunas de las discrepancias que surgen debido a la desalineación de la ventana. En la figura 1, se representa el uso de la capacidad de procesamiento durante un período específico. En esta figura, se muestra lo siguiente:

• Las barras azules representan el tráfico admitido como capacidad de procesamiento aprovisionada.

• La barra naranja representa el tráfico que supera el límite de GSU y se procesa como desbordamiento.

Figura 1. Uso de la capacidad de procesamiento en períodos

Según el uso del rendimiento, la figura 2 representa posibles discrepancias visuales debido a la falta de alineación de las ventanas. En esta figura, se muestra lo siguiente:

• La línea azul representa el tráfico de capacidad de procesamiento aprovisionada.

• La línea naranja representa el tráfico indirecto.

Figura 2. Posibles discrepancias visuales en los paneles de supervisión

En este caso, los datos de supervisión pueden mostrar el uso del procesamiento aprovisionado sin desbordamiento para un período de agregación de supervisión, mientras que, simultáneamente, se observa el uso del procesamiento aprovisionado por debajo del límite de la GSU que coincide con un desbordamiento en otro período de agregación de supervisión.

Soluciona problemas de paneles de supervisión

Para solucionar problemas de desbordamiento inesperado en tus paneles o errores 429, sigue estos pasos:

1. Acercar: Establece el intervalo del panel en 12 horas o menos para proporcionar el período de alineación más detallado de 1 minuto. Los rangos de tiempo grandes suavizan los picos que causan la limitación y aumentan los promedios del período de alineación.

2. Verifica el tráfico total: Tus paneles específicos del modelo muestran el tráfico dedicado y el tráfico de desbordamiento como dos líneas separadas, lo que podría llevar a la conclusión incorrecta de que la cuota de capacidad de procesamiento aprovisionada no se utiliza por completo y se desborda de forma prematura. Si tu tráfico supera la cuota disponible, toda la solicitud se procesa como desbordamiento. Para obtener otra visualización útil, agrega una consulta al panel con el Explorador de métricas y, luego, incluye el rendimiento de tokens para el modelo y la región específicos. No incluyas agregaciones ni filtros adicionales para ver el tráfico total en todos los tipos de tráfico (dedicado, desbordamiento y compartido).

Supervisa los modelos de Genmedia

La supervisión de la capacidad de procesamiento aprovisionada no está disponible en los modelos de Imagen y Veo 3.

Alertas

Después de habilitar las alertas, configura las alertas predeterminadas para ayudarte a administrar el uso del tráfico.

Habilitar alertas

Para habilitar las alertas en el panel, haz lo siguiente:

1. En la consola de Google Cloud , ve a la página Capacidad de procesamiento aprovisionada.

   Ir a Capacidad de procesamiento aprovisionada

2. Para ver el uso de la capacidad de procesamiento aprovisionada de cada modelo en todos tus pedidos, selecciona la pestaña Resumen de uso.

3. Selecciona Alertas recomendadas y se mostrarán las siguientes alertas:

   • Provisioned Throughput Usage Reached Limit
   • Provisioned Throughput Utilization Exceeded 80%
   • Provisioned Throughput Utilization Exceeded 90%

4. Consulta las alertas que te ayudan a administrar tu tráfico.

Ver más detalles de la alerta

Para ver más información sobre las alertas, sigue estos pasos:

1. Ve a la página Integraciones.

   Ir a Integraciones

2. Ingresa vertex en el campo Filter y presiona Intro. Aparecerá Google Vertex AI.

3. Para ver más información, haz clic en Ver detalles. Se muestra el panel Detalles de Google Vertex AI.

4. Selecciona la pestaña Alertas y, luego, podrás seleccionar una plantilla de Política de alertas.

¿Qué sigue?

• Soluciona el problema del código de error 429.