Ir para o conteúdo principal
Português— Escolher um idioma
Menu

Limites de taxa, quotas e níveis

Aula 13 de 22 Atualizada a 29 de julho de 2026 Programador
Nesta página
  1. Limites de taxa, quotas e níveis
  2. O sistema de níveis
  3. Tipos de limites de taxa
  4. Leitura dos cabeçalhos de limite de taxa
  5. Limitação de taxa no lado do cliente
  6. Estratégias para grandes volumes
  7. Pontos-chave

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