Use o débito aprovisionado

Esta página explica como funciona o débito processado, como controlar os excedentes ou ignorar o débito processado e como monitorizar a utilização.

Como funciona o débito aprovisionado

Esta secção explica como o débito processado funciona através da verificação de quotas durante o período de aplicação de quotas.

Verificação da quota de débito aprovisionado

A sua quota máxima de débito aprovisionado é um múltiplo do número de unidades de escalabilidade de IA generativa (GSUs) compradas e do débito por GSU. É verificado sempre que faz um pedido no seu período de aplicação de quotas, que é a frequência com que a quota de débito processado máxima é aplicada.

No momento em que é recebido um pedido, o tamanho real da resposta é desconhecido. Uma vez que damos prioridade à velocidade de resposta para aplicações em tempo real, o débito aprovisionado estima o tamanho dos tokens de saída. Se a estimativa inicial exceder a quota máxima de débito processado disponível, o pedido é processado como pagamento conforme o uso. Caso contrário, é processado como débito processado. Isto é feito comparando a estimativa inicial com a quota máxima de débito processado.

Quando a resposta é gerada e o tamanho real do token de saída é conhecido, a utilização e a quota reais são reconciliadas adicionando a diferença entre a estimativa e a utilização real ao valor da quota de débito processado disponível.

Período de aplicação da quota de débito aprovisionado

Para os modelos Gemini, o período de aplicação de quotas pode demorar até 30 segundos e está sujeito a alterações. Isto significa que pode ter temporariamente tráfego prioritário que excede a quantidade da sua quota por segundo em alguns casos, mas não deve exceder a quota por 30 segundos. Estes períodos baseiam-se na hora do relógio interno do Vertex AI e são independentes do momento em que os pedidos são feitos.

Por exemplo, se comprar uma GSU de gemini-2.0-flash-001, deve esperar 3360 tokens por segundo de débito sempre ativo. Em média, não pode exceder 100 800 tokens num período de 30 segundos, o que é calculado através da seguinte fórmula:

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

Se, num dia, tiver enviado apenas um pedido que consumiu 8000 tokens num segundo, este pode continuar a ser processado como um pedido de débito processado, mesmo que tenha excedido o limite de 3360 tokens por segundo no momento do pedido. Isto deve-se ao facto de o pedido não ter excedido o limite de 100 800 tokens por 30 segundos.

Controle os excessos ou ignore o débito aprovisionado

Use a API para controlar os excessos quando excede o débito comprado ou para ignorar o débito aprovisionado por pedido.

Leia cada opção para determinar o que tem de fazer para satisfazer o seu exemplo de utilização.

Comportamento predefinido

Se exceder a quantidade de débito comprada, os excessos passam a ser a pedido e são faturados à taxa de pagamento conforme o uso. Depois de a encomenda de débito processado estar ativa, o comportamento predefinido ocorre automaticamente. Não tem de alterar o seu código para começar a consumir a sua encomenda, desde que a consuma na região aprovisionada.

Use apenas o débito aprovisionado

Se estiver a gerir os custos evitando encargos a pedido, use apenas o débito processado. Os pedidos que excedem o valor do débito processado devolvem um erro 429.

Quando enviar pedidos para a API, defina o cabeçalho HTTP X-Vertex-AI-LLM-Request-Type como dedicated.

Use apenas o pagamento mediante utilização

Isto também é conhecido como usar a pedido. Os pedidos ignoram a ordem de débito de capacidade de processamento provisionada e são enviados diretamente para o pagamento conforme o uso. Isto pode ser útil para experiências ou aplicações em desenvolvimento.

Quando enviar pedidos para a API, defina o cabeçalho HTTP X-Vertex-AI-LLM-Request-Type como shared.

Exemplo

Python

Instalação

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 gen com o 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 gen com o 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 configurar o seu ambiente, pode usar a API REST para testar um comando de texto. O exemplo seguinte envia um pedido para o ponto final do modelo do 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."}]}]}'

Monitorize o débito aprovisionado

Pré-visualização

Esta funcionalidade está sujeita aos "Termos das Ofertas de Pré-DG" na secção Termos Gerais de Serviço dos Termos Específicos do Serviço. As funcionalidades de pré-DG estão disponíveis "tal como estão" e podem ter apoio técnico limitado. Para mais informações, consulte as descrições das fases de lançamento.

Pode monitorizar autonomamente a utilização do débito processado através de um conjunto de métricas que são medidas no tipo de recurso aiplatform.googleapis.com/PublisherModel.

A monitorização do tráfego de débito aprovisionado é uma funcionalidade de pré-visualização pública.

Dimensões

Pode filtrar por métricas através das seguintes dimensões:

Dimensão	Valores
type	input output
request_type	dedicated: o tráfego é processado através do débito processado. spillover: o tráfego é processado como quota de pagamento conforme o uso depois de exceder a quota de débito processado. shared: se o débito processado estiver ativo, o tráfego é processado como quota de pagamento conforme o uso através do cabeçalho HTTP partilhado. Se o débito processado não estiver ativo, o tráfego é processado como pagamento conforme o uso, por predefinição.

Prefixo do caminho

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

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

Métrica

As seguintes métricas do Cloud Monitoring estão disponíveis no recurso aiplatform.googleapis.com/PublisherModel para os modelos Gemini. Use os dedicated tipos de pedidos para filtrar a utilização do débito processado.

Métrica	Nome a apresentar	Descrição
/dedicated_gsu_limit	Limite (GSU)	Limite dedicado em GSUs. Use esta métrica para compreender a sua quota máxima de débito aprovisionado em GSUs.
/tokens	Tokens	Distribuição da contagem de tokens de entrada e saída.
/token_count	Contagem de tokens	Contagem de tokens de entrada e saída acumulados.
/consumed_token_throughput	Débito de tokens	Utilização da taxa de transferência, que tem em conta a taxa de redução em tokens e incorpora a conciliação de quotas. Consulte a verificação da quota de débito processado. Use esta métrica para compreender como foi usada a sua quota de débito processado.
/dedicated_token_limit	Limite (tokens por segundo)	Limite dedicado em tokens por segundo. Use esta métrica para compreender a sua quota máxima de débito processado para modelos baseados em tokens.
/characters	Carateres	Distribuição da contagem de carateres de entrada e saída.
/character_count	Número de carateres	Número de carateres de entrada e saída acumulados.
/consumed_throughput	Débito de carateres	Utilização do débito, que tem em conta a taxa de redução em carateres e incorpora a conciliação de quotas Verificação de quotas de débito aprovisionado. Use esta métrica para compreender como foi usada a sua quota de débito processado provisionado. Para modelos baseados em tokens, esta métrica é equivalente ao débito consumido em tokens multiplicado por 4.
/dedicated_character_limit	Limite (carateres por segundo)	Limite dedicado em carateres por segundo. Use esta métrica para compreender a sua quota máxima de débito processado para modelos baseados em carateres.
/model_invocation_count	Contagem de invocações do modelo	Número de invocações de modelos (pedidos de previsão).
/model_invocation_latencies	Latências de invocação de modelos	Latências de invocação de modelos (latências de previsão).
/first_token_latencies	Latências do primeiro token	Duração desde o pedido recebido até à devolução do primeiro token.

Os modelos da Anthropic também têm um filtro para o débito processado, mas apenas para tokens e token_count.

Painéis de controlo

Os painéis de controlo de monitorização predefinidos para o débito aprovisionado fornecem métricas que lhe permitem compreender melhor a sua utilização e a utilização do débito aprovisionado. Para aceder aos painéis de controlo, faça o seguinte:

1. Na Google Cloud consola, aceda à página Provisioned Throughput.

   Aceda a Débito processado

2. Para ver a utilização do débito processado de cada modelo em todas as suas encomendas, selecione o separador Resumo da utilização.

   Na tabela Utilização do débito aprovisionado por modelo, pode ver o seguinte para o intervalo de tempo selecionado:

   • Número total de GSUs que tinha.

   • Utilização do débito de pico em termos de GSUs.

   • A utilização média do GSU.

   • O número de vezes que atingiu o limite de débito processado provisionado.

3. Selecione um modelo na tabela Utilização do débito aprovisionado por modelo para ver mais métricas específicas do modelo selecionado.

Limitações do painel de controlo

O painel de controlo pode apresentar resultados inesperados, especialmente para tráfego flutuante que seja irregular ou pouco frequente (por exemplo, menos de 1 consulta por segundo). Os seguintes motivos podem contribuir para esses resultados:

• Os intervalos de tempo superiores a 12 horas podem originar uma representação menos precisa do período de aplicação da quota. As métricas de débito e os respetivos derivados, como a utilização, apresentam médias em períodos de alinhamento com base no intervalo de tempo selecionado. Quando o intervalo de tempo se expande, cada período de alinhamento também se expande. O período de alinhamento expande-se ao longo do cálculo da utilização média. Uma vez que a aplicação de quotas é calculada ao nível de um subminuto, a definição do intervalo de tempo para um período de 12 horas ou menos resulta em dados ao nível do minuto que são mais comparáveis com o período de aplicação de quotas real. Para mais informações sobre os períodos de alinhamento, consulte o artigo Alinhamento: regularização dentro da série. Para mais informações sobre intervalos de tempo, consulte o artigo Regularizar intervalos de tempo.
• Se foram enviados vários pedidos ao mesmo tempo, as agregações de monitorização podem afetar a sua capacidade de filtrar pedidos específicos.
• O débito processado limita o tráfego quando é feito um pedido, mas comunica as métricas de utilização após a conciliação da quota.
• Os períodos de aplicação da quota de débito processado aprovisionado são independentes dos períodos de agregação de monitorização ou dos períodos de pedido ou resposta e podem não estar alinhados com estes.
• Se não ocorrerem erros, pode ver uma mensagem de erro no gráfico da taxa de erro. Por exemplo, Ocorreu um erro ao pedir os dados. Não foi possível encontrar um ou mais recursos.

Monitorize modelos Genmedia

A monitorização do débito aprovisionado não está disponível nos modelos Veo 3 e Imagen.

Alertas

Depois de ativar os alertas, defina alertas predefinidos para ajudar a gerir a sua utilização do tráfego.

Ative os alertas

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

1. Na Google Cloud consola, aceda à página Provisioned Throughput.

   Aceda a Débito processado

2. Para ver a utilização do débito processado de cada modelo em todas as suas encomendas, selecione o separador Resumo da utilização.

3. Selecione Alertas recomendados. São apresentados os seguintes alertas:

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

4. Verifique os alertas que ajudam a gerir o seu tráfego.

Veja mais detalhes do alerta

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

1. Aceda à página Integrações.

   Aceda a Integrações

2. Introduza vertex no campo Filtro e prima Enter. É apresentado o Google Vertex AI.

3. Para ver mais informações, clique em Ver detalhes. É apresentado o painel Detalhes do Google Vertex AI.

4. Selecione o separador Alertas e pode selecionar um modelo de Política de alertas.

O que se segue?

• Resolva problemas do código de erro 429.