Limites de taxa, quotas e níveis
Nesta página
Limites de taxa, quotas e níveis
Os limites de taxa definem quantos pedidos pode enviar à API por minuto. Compreender e gerir estes limites é fundamental para evitar interrupções de serviço em produção. O cenário de pesadelo é sempre o mesmo: uma integração que funcionava perfeitamente em desenvolvimento, onde enviava três pedidos por minuto, entra em produção e subitamente processa uma fila de vários milhares de documentos. Os erros 429 chegam em cascata e metade do processamento perde-se porque o throughput não foi antecipado.
O sistema de níveis
A OpenAI organiza os limites em níveis (tiers) com base no seu histórico de faturação. Não escolhe o seu nível; desbloqueia-o acumulando despesas e aguardando o decurso de um intervalo de tempo. Esta progressão tem uma consequência prática importante: uma conta criada apenas para uma demonstração a um cliente não terá a mesma capacidade que a sua conta de produção, mesmo que o código seja idêntico.
# Os níveis determinam os seus limites
# Nível 1: Após o primeiro pagamento bem-sucedido
# Nível 2: Após $50 de gastos cumulativos + 7 dias
# Nível 3: Após $100 de gastos cumulativos + 7 dias
# Nível 4: Após $250 de gastos cumulativos + 14 dias
# Nível 5: Após $1000 de gastos cumulativos + 30 dias
# Os limites aumentam significativamente com cada nível
Tipos de limites de taxa
Três contadores são aplicados simultaneamente e o primeiro que atingir bloqueia-o. Processar textos curtos saturará o RPM muito antes do TPM; inversamente, analisar documentos longos esgotará o TPM mesmo que tenha enviado apenas algumas dezenas de pedidos. Verifique sempre a ordem de grandeza dos seus prompts antes de dimensionar o seu paralelismo.
# 1. RPM — Pedidos Por Minuto
# 2. TPM — Tokens Por Minuto
# 3. RPD — Pedidos Por Dia
# Ordem de grandeza para o Nível 3 (verifique os seus limites reais
# em platform.openai.com > Settings > Limits):
# RPM: 5.000 pedidos/minuto
# TPM: 2.000.000 tokens/minuto
# RPD: 10.000 pedidos/dia
Leitura dos cabeçalhos de limite de taxa
Não precisa de adivinhar o seu consumo: cada resposta transporta-o nos seus cabeçalhos HTTP. O SDK oculta-os por predefinição para devolver apenas o objeto analisado, mas with_raw_response dá-lhe acesso à resposta bruta e parse() reconstrói o objeto habitual. Um dashboard alimentado por estes valores avisa-o à medida que se aproxima do teto, em vez de o deixar descobri-lo através de um erro.
from openai import OpenAI
client = OpenAI()
response = client.responses.create(
model="gpt-5.6-terra",
input="Hello!"
)
# Aceda aos cabeçalhos através da resposta HTTP bruta
# Utilizando o modo with_raw_response
raw = client.responses.with_raw_response.create(
model="gpt-5.6-terra",
input="Hello!"
)
print(f"Limite RPM: {raw.headers.get('x-ratelimit-limit-requests')}")
print(f"RPM restante: {raw.headers.get('x-ratelimit-remaining-requests')}")
print(f"Limite TPM: {raw.headers.get('x-ratelimit-limit-tokens')}")
print(f"TPM restante: {raw.headers.get('x-ratelimit-remaining-tokens')}")
print(f"Reposição em: {raw.headers.get('x-ratelimit-reset-requests')}")
response = raw.parse()
print(f"Resposta: {response.output_text}")
Limitação de taxa no lado do cliente
É preferível abrandar voluntariamente do que ser rejeitado. Duas implementações cobrem a maioria das necessidades.
Limitação do throughput com um semáforo
A primeira combina um semáforo, que limita o número de chamadas simultâneas, com um atraso calculado a partir do throughput alvo. No exemplo, cinquenta resumos são lançados de uma vez, mas apenas cinco prosseguem em paralelo, espaçados pelo atraso correspondente a 100 pedidos por minuto. O código de chamada permanece um simples asyncio.gather: toda a disciplina está encapsulada na classe.
import asyncio
from openai import AsyncOpenAI
async_client = AsyncOpenAI()
class RateLimiter:
"""Limita o número de pedidos simultâneos."""
def __init__(self, max_concurrent: int = 10, rpm: int = 500):
self.semaphore = asyncio.Semaphore(max_concurrent)
self.rpm = rpm
self.delay = 60.0 / rpm # Atraso entre cada pedido
async def call(self, prompt: str) -> str:
async with self.semaphore:
await asyncio.sleep(self.delay)
response = await async_client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
return response.output_text
async def batch_processing():
limiter = RateLimiter(max_concurrent=5, rpm=100)
prompts = [f"Summarize concept {i}" for i in range(50)]
tasks = [limiter.call(p) for p in prompts]
results = await asyncio.gather(*tasks)
for i, r in enumerate(results):
print(f"Resultado {i}: {r[:50]}...")
# asyncio.run(batch_processing())
Token bucket simples
O token bucket é mais flexível porque permite picos de tráfego (bursts). O balde enche a uma taxa constante e esvazia-se a cada chamada: se a sua aplicação esteve inativa durante um minuto, pode reiniciar a toda a velocidade durante cinquenta pedidos, regressando depois naturalmente à taxa de enchimento. Este é exatamente o comportamento desejado para um serviço que alterna entre picos e períodos de calmaria, e funciona em ambientes multithread graças ao lock.
import time
import threading
class TokenBucket:
"""Limitador de taxa baseado no algoritmo token bucket."""
def __init__(self, tokens_per_second: float, max_capacity: int):
self.tokens_per_second = tokens_per_second
self.max_capacity = max_capacity
self.tokens = max_capacity
self.last_refill = time.monotonic()
self.lock = threading.Lock()
def wait(self, tokens_needed: int = 1):
"""Aguarda até haver tokens suficientes disponíveis."""
while True:
with self.lock:
now = time.monotonic()
elapsed = now - self.last_refill
self.tokens = min(
self.max_capacity,
self.tokens + elapsed * self.tokens_per_second
)
self.last_refill = now
if self.tokens >= tokens_needed:
self.tokens -= tokens_needed
return
time.sleep(0.1)
# Utilização: máx. 50 pedidos por minuto
bucket = TokenBucket(tokens_per_second=50/60, max_capacity=50)
def limited_call(prompt: str) -> str:
bucket.wait(1)
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
return response.output_text
Estratégias para grandes volumes
1. Distribuir por vários projetos
Cada projeto tem os seus próprios limites de taxa. Se atingir o seu teto enquanto já está num nível elevado, distribuir as chamadas por vários projetos multiplica mecanicamente a capacidade disponível. O round-robin abaixo ilustra o princípio; em produção, mova o ciclo para fora da função para que persista entre chamadas.
from openai import OpenAI
# Cada projeto tem os seus próprios limites de taxa
clients = [
OpenAI(project="proj-aaaa"), # Projeto 1
OpenAI(project="proj-bbbb"), # Projeto 2
OpenAI(project="proj-cccc"), # Projeto 3
]
def round_robin_call(prompt: str, clients: list) -> str:
"""Distribui as chamadas por vários projetos."""
import itertools
client_cycle = itertools.cycle(clients)
client = next(client_cycle)
return client.responses.create(
model="gpt-5.6-terra",
input=prompt
).output_text
2. Utilizar o modelo certo para o volume certo
A escolha do modelo é também uma decisão de capacidade, não apenas de qualidade. Reservar os modelos mais pesados para tarefas críticas e encaminhar o volume para um modelo com limites mais elevados liberta throughput onde realmente precisa dele.
# Modelos económicos (gpt-5.6-luna) têm os limites mais elevados
# Utilize-os para tarefas de alto volume
# O modelo principal (gpt-5.6-sol) tem os limites mais baixos
# Reserve-o para tarefas críticas
3. Filas de espera
Por fim, as filas de espera dissociam a produção de pedidos do seu consumo. Um único thread remove elementos da fila a um ritmo fixo enquanto o resto da aplicação submete livremente; o chamador bloqueia num evento até que o seu resultado chegue. Este padrão absorve picos sem nunca exceder o throughput configurado.
import queue
import threading
class APIQueue:
"""Fila para chamadas à API."""
def __init__(self, rpm: int = 100):
self.queue = queue.Queue()
self.delay = 60.0 / rpm
self.running = True
self.worker = threading.Thread(target=self._process, daemon=True)
self.worker.start()
def _process(self):
while self.running:
try:
prompt, future = self.queue.get(timeout=1)
response = client.responses.create(
model="gpt-5.6-terra",
input=prompt
)
future["result"] = response.output_text
future["event"].set()
time.sleep(self.delay)
except queue.Empty:
continue
def submit(self, prompt: str) -> str:
future = {"result": None, "event": threading.Event()}
self.queue.put((prompt, future))
future["event"].wait()
return future["result"]
Pontos-chave
- Os limites de taxa aplicam-se simultaneamente em RPM, TPM e RPD
- O seu nível determina os seus limites — aumenta com os seus gastos cumulativos
- Leia os cabeçalhos
x-ratelimit-*para conhecer o seu consumo em tempo real - Implemente um limitador de taxa no lado do cliente para evitar erros 429
- Distribua a carga por projetos para grandes volumes
- O Luna oferece os limites de taxa mais elevados para processamento em lote