Usar a capacidade de processamento provisionada

Esta página explica como a capacidade de processamento provisionada funciona, como controlar excedentes ou ignorar a capacidade de processamento provisionada e como monitorar o uso.

Como funciona a capacidade de processamento provisionada

Esta seção explica como a capacidade de processamento provisionada funciona usando a verificação de cota durante o período de aplicação da cota.

Verificação da cota de capacidade de processamento provisionada

Sua cota máxima de capacidade de processamento provisionada é um múltiplo do número de unidades de escalonamento de IA generativa (GSUs) compradas e da capacidade de processamento por GSU. Ele é verificado sempre que você faz uma solicitação no seu período de aplicação de cota, que é a frequência com que a cota máxima de capacidade de transferência provisionada é aplicada.

Quando uma solicitação é recebida, o tamanho real da resposta é desconhecido. Como priorizamos a velocidade de resposta para aplicativos em tempo real, a capacidade de processamento provisionada estima o tamanho do token de saída. Se a estimativa inicial exceder a cota máxima disponível de capacidade de processamento provisionada, a solicitação será processada como pagamento por uso. Caso contrário, ela será processada como capacidade de processamento provisionada. Para isso, compare a estimativa inicial com sua cota máxima de capacidade de processamento provisionada.

Quando a resposta é gerada e o tamanho real do token de saída é conhecido, o uso e a cota reais são reconciliados adicionando a diferença entre a estimativa e o uso real ao valor da cota de capacidade de transmissão provisionada disponível.

Período de aplicação da cota de capacidade de processamento provisionada

Para modelos do Gemini, o período de aplicação da cota pode levar até 30 segundos e está sujeito a mudanças. Isso significa que, em alguns casos, você pode ter um tráfego prioritário que excede sua cota por segundo, mas não por 30 segundos. Esses períodos são baseados no tempo do relógio interno da Vertex AI e são independentes de quando as solicitações são feitas.

Por exemplo, se você comprar uma GSU de gemini-2.0-flash-001, vai ter 3.360 tokens por segundo de capacidade de processamento sempre ativa. Em média, você não pode exceder 100.800 tokens a cada 30 segundos, o que é calculado usando a seguinte fórmula:

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

Se, em um dia, você enviou apenas uma solicitação que consumiu 8.000 tokens em um segundo, ela ainda poderá ser processada como uma solicitação de taxa de transferência provisionada, mesmo que você tenha excedido o limite de 3.360 tokens por segundo no momento da solicitação. Isso porque a solicitação não excedeu o limite de 100.800 tokens a cada 30 segundos.

Controlar excedentes ou ignorar a capacidade de processamento provisionada

Use a API para controlar excedentes quando você exceder a capacidade de processamento comprada ou para ignorar a capacidade de processamento provisionada por solicitação.

Leia cada opção para determinar o que você precisa fazer para atender ao seu caso de uso.

Comportamento padrão

Se uma solicitação exceder a cota restante de capacidade de processamento provisionada, ela será processada como uma solicitação sob demanda por padrão e será cobrada de acordo com a taxa de pagamento por uso. Quando isso acontece, o tráfego aparece como transbordamento nos painéis de monitoramento. Para mais informações sobre como monitorar o uso da capacidade de processamento provisionada, consulte Monitorar a capacidade de processamento provisionada.

Depois que o pedido de capacidade de processamento provisionada estiver ativo, o comportamento padrão vai ocorrer automaticamente. Não é preciso mudar o código para começar a consumir seu pedido, desde que ele seja consumido na região provisionada.

Usar apenas a capacidade de processamento provisionada

Se você estiver gerenciando custos evitando cobranças sob demanda, use apenas a capacidade de processamento provisionada. Solicitações que excedem o valor do pedido de capacidade de processamento provisionada retornam um erro 429.

Ao enviar solicitações para a API, defina o cabeçalho HTTP X-Vertex-AI-LLM-Request-Type como dedicated.

Usar apenas o pagamento por uso

Isso também é chamado de uso sob demanda. As solicitações ignoram o pedido de capacidade de processamento provisionada e são enviadas diretamente para o pagamento por uso. Isso pode ser útil para experimentos ou aplicativos que estão em desenvolvimento.

Ao enviar solicitações para a API, defina o cabeçalho HTTP X-Vertex-AI-LLM-Request-Type como shared.

Exemplo

Python

Instalar

pip install --upgrade google-genai

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a 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

Saiba como instalar ou atualizar o Go.

Para saber mais, consulte a documentação de referência do SDK.

Defina variáveis de ambiente para usar o SDK de IA generativa com a 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

Depois de configurou seu ambiente use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao publisher endpoint do modelo. 

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."}]}]}'

Usar a capacidade de processamento provisionada com uma chave de API

Se você comprou a taxa de transferência provisionada para um projeto, modelo do Google e região específicos e quer usá-la para enviar uma solicitação com uma chave de API, inclua o ID do projeto, o modelo, o local e a chave de API como parâmetros na solicitação.

Para informações sobre como criar uma Google Cloud chave de API vinculada a uma conta de serviço, consulte Receber uma Google Cloud chave de API. Para saber como enviar solicitações à API Gemini usando uma chave de API, consulte o Guia de início rápido da API Gemini na Vertex AI.

Por exemplo, o exemplo a seguir mostra como enviar uma solicitação com uma chave de API ao usar a capacidade de transmissão provisionada:

REST

Depois de configurou seu ambiente use REST para testar uma solicitação de texto. O exemplo a seguir envia uma solicitação ao publisher endpoint do modelo. 

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"
        }
      ]
    }
  ]
}'

Monitorar a capacidade de processamento provisionada

É possível monitorar o uso da capacidade de processamento provisionada usando um conjunto de métricas medidas no tipo de recurso aiplatform.googleapis.com/PublisherModel.

O monitoramento de tráfego de capacidade de processamento provisionada é um recurso de pré-lançamento público.

Dimensões

É possível filtrar as métricas usando as seguintes dimensões:

Dimensão Valores
type input
output
request_type

dedicated: o tráfego é processado usando a capacidade de processamento provisionada.

spillover: o tráfego é processado como cota de pagamento conforme o uso depois que você excede a cota de taxa de transferência provisionada.

shared: se a capacidade de transferência provisionada estiver ativa, o tráfego será processado como uma cota de pagamento por uso usando o cabeçalho HTTP compartilhado. Se a capacidade de processamento provisionada não estiver ativa, o tráfego será processado como pagamento por uso, por padrão.

Prefixo do caminho

O prefixo do caminho de uma métrica é aiplatform.googleapis.com/publisher/online_serving.

Por exemplo, o caminho completo da métrica /consumed_throughput é aiplatform.googleapis.com/publisher/online_serving/consumed_throughput.

Métricas

As seguintes métricas do Cloud Monitoring estão disponíveis no recurso aiplatform.googleapis.com/PublisherModel para os modelos do Gemini. Use os tipos de solicitação dedicated para filtrar o uso da capacidade de processamento provisionada.

Métrica Nome de exibição Descrição
/dedicated_gsu_limit Limite (GSU) Limite dedicado em GSUs. Use essa métrica para entender sua cota máxima de capacidade de processamento provisionada em GSUs.
/tokens Tokens Distribuição da contagem de tokens de entrada e saída.
/token_count Contagem de tokens Contagem acumulada de tokens de entrada e saída.
/consumed_token_throughput Capacidade de processamento de tokens Uso da capacidade de processamento, que considera a taxa de burndown em tokens e incorpora a conciliação de cotas. Consulte Verificação da cota de capacidade de processamento provisionada.

Use essa métrica para entender como sua cota de capacidade de processamento provisionada foi usada.
/dedicated_token_limit Limite (tokens por segundo) Limite dedicado em tokens por segundo. Use essa métrica para entender sua cota máxima de capacidade de processamento provisionada para modelos baseados em tokens.
/characters Caracteres Distribuição de contagem de caracteres de entrada e saída.
/character_count Contagem de caracteres Contagem de caracteres de entrada e saída acumulados.
/consumed_throughput Capacidade de processamento de caracteres Uso da capacidade de processamento, que considera a taxa de burndown em caracteres e incorpora a reconciliação de cota Verificação de cota de capacidade de processamento provisionada.

Use essa métrica para entender como sua cota de capacidade de processamento provisionada foi usada.

Para modelos baseados em tokens, essa métrica é equivalente à taxa de transferência consumida em tokens multiplicada por 4.
/dedicated_character_limit Limite (caracteres por segundo) Limite dedicado em caracteres por segundo. Use essa métrica para entender sua cota máxima de capacidade de processamento provisionada para modelos baseados em caracteres.
/model_invocation_count Contagem de invocações de modelo Número de invocações de modelo (solicitações de previsão).
/model_invocation_latencies Latências de invocação de modelo Latências de invocação de modelo (latências de previsão).
/first_token_latencies Latências do primeiro token Duração da solicitação recebida até o primeiro token retornado.

Os modelos da Anthropic também têm um filtro para capacidade de processamento provisionada, mas apenas para tokens e token_count.

Painéis

Os painéis de monitoramento padrão para capacidade de processamento provisionada fornecem métricas que ajudam a entender melhor o uso e a utilização da capacidade de processamento provisionada. Para acessar os painéis, faça o seguinte:

  1. No console Google Cloud , acesse a página Capacidade de processamento provisionada.

    Acessar a capacidade de processamento provisionada

  2. Para conferir o uso da capacidade de processamento provisionada de cada modelo em todos os pedidos, selecione a guia Resumo de uso.

    Na tabela Utilização da capacidade de processamento provisionada por modelo, é possível conferir o seguinte para o período selecionado:

    • Número total de GSUs que você tinha.

    • Pico de uso da capacidade de processamento em termos de GSUs.

    • O uso médio da GSU.

    • O número de vezes que você atingiu o limite de capacidade de transferência provisionada.

  3. Selecione um modelo na tabela Utilização da capacidade de processamento provisionada por modelo para conferir mais métricas específicas dele.

Limitações do painel

O painel pode mostrar resultados inesperados, principalmente para tráfego instável, com picos ou infrequente (por exemplo, menos de uma consulta por segundo). Os seguintes motivos podem contribuir para esses resultados:

  • Intervalos maiores que 12 horas podem resultar em uma representação menos precisa do período de aplicação da cota. As métricas de capacidade de processamento e seus derivados, como utilização, mostram médias em períodos de alinhamento com base no período selecionado. Quando o período aumenta, cada período de alinhamento também aumenta. O período de alinhamento se estende pelo cálculo do uso médio. Como a aplicação de cotas é calculada em um nível inferior a um minuto, definir o período para 12 horas ou menos resulta em dados no nível de minutos mais comparáveis ao período real de aplicação de cotas. Para mais informações sobre períodos de alinhamento, consulte Alinhamento: regularização em série. Para mais informações sobre intervalos de tempo, consulte Regularização de intervalos de tempo.
  • Se várias solicitações forem enviadas ao mesmo tempo, as agregações de monitoramento poderão afetar sua capacidade de filtrar solicitações específicas.
  • A capacidade de processamento provisionada limita o tráfego quando uma solicitação é feita, mas informa as métricas de uso depois que a cota é conciliada.
  • Os períodos de aplicação da cota de capacidade provisionada são independentes e podem não estar alinhados com os períodos de agregação de monitoramento ou de solicitação/resposta.
  • Se não houver erros, talvez apareça uma mensagem no gráfico de taxa de erros. Por exemplo, Ocorreu um erro durante a solicitação dos dados. Um ou mais recursos não foram encontrados.

Monitorar modelos de Genmedia

O monitoramento da capacidade de processamento provisionada não está disponível nos modelos Veo 3 e Imagen.

Alertas

Depois de ativar os alertas, defina os padrões para ajudar a gerenciar o uso do tráfego.

Ativar alertas

Para ativar os alertas no painel, faça o seguinte:

  1. No console Google Cloud , acesse a página Capacidade de processamento provisionada.

    Acessar a capacidade de processamento provisionada

  2. Para conferir o uso da capacidade de processamento provisionada de cada modelo em todos os pedidos, selecione a guia Resumo de uso.

  3. Selecione Alertas recomendados. Os seguintes alertas vão aparecer:

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

  4. Confira os alertas que ajudam você a gerenciar seu tráfego.

Ver mais detalhes do alerta

Para mais informações sobre os alertas, faça o seguinte:

  1. Acesse a página Integrações.

    Acessar "Integrações"

  2. Digite vertex no campo Filtro e pressione Enter. A opção Google Vertex AI aparece.

  3. Para mais informações, clique em Ver detalhes. O painel Detalhes da Vertex AI do Google é exibido.

  4. Selecione a guia Alertas e escolha um modelo de Política de alertas.

A seguir