Limite de requisições da API Groq e como funcionam os limites 429

A qual serviço pertencem os limites

Os nomes são fáceis de confundir. Groq é uma empresa que hospeda modelos em seu próprio hardware. Grok é a família de modelos da xAI. Este site não é nenhum dos dois: é uma API compatível com OpenAI para um único modelo de pesos abertos (ID do modelo uncensored), operada por um provedor independente. Então, para o próprio limite de taxa da API do Groq, como requisições ou tokens por minuto em um plano específico, abra o console ou a documentação do Groq e leia os números para a sua conta. Eles mudam, e eu não vou adivinhar.

O que segue é exato para a nossa API, e os hábitos se aplicam a qualquer provedor: respeite os cabeçalhos de limite, tente novamente apenas nos erros corretos e limite sua própria concorrência antes que o servidor faça isso por você. Se você veio aqui para uma configuração Grok NSFW, nosso guia de integração cobre os erros relacionados também.

Os limites em resumo

Dois desses são limites de taxa no sentido estrito, requisições por minuto e concorrência. Os outros dois são limites de tamanho em uma única requisição, e são independentes dos limites de taxa. Uma requisição com um prompt de 90.000 tokens conta como uma requisição contra as 300 por minuto, a mesma de um prompt de uma linha, embora demore mais e ocupe seu slot por mais tempo.

O crédito de teste de $0,50 é resgatado com um clique na página chave de API após o cadastro, e usa os limites de teste. Os limites de chave completa se aplicam depois que você fizer uma recarga.

Os três tipos de 429

Todos os erros de limite chegam como HTTP 429, mas significam coisas diferentes e exigem reações diferentes.

• rate_limited: você enviou mais requisições do que a sua cota por minuto. Diminua a velocidade; a janela é de um minuto, então espaçar as requisições uniformemente ajuda mais do que uma pausa longa.
• concurrency: muitas requisições estavam em andamento ao mesmo tempo. Aguarde uma anterior terminar. Isso é comum com streaming, onde cada requisição dura durante toda a geração.
• Sobrecarga temporária: também é um 429, com um cabeçalho Retry-After: 5. Não é culpa sua e não está ligado aos limites da sua chave. Aguarde os 5 segundos indicados e tente novamente.

Requisições falhas não são cobradas, então um loop de retry custa apenas a requisição que finalmente tem sucesso. As respostas também carregam X-RateLimit-Limit-Requests e X-RateLimit-Limit-Concurrency para que o seu cliente possa ler seus próprios tetos em vez de fixá-los no código, além de X-Balance-USD para o crédito restante e X-Request-Id, que você deve logar e citar se contatar suporte.

Matemática do throughput: por que 300 por minuto é difícil de alcançar

Os dois limites interagem. Com 8 slots de concorrência, o máximo que você pode concluir por minuto é 8 x 60 dividido pela duração média de uma requisição em segundos. Para realmente atingir 300 requisições por minuto você precisa de requisições que terminem em 8 x 60 / 300 = 1,6 segundos em média. Requisições mais lentas são limitadas primeiro pela concorrência.

Estes são tetos aritméticos para um tempo de requisição hipotético, não medições do nosso serviço; cronometre suas próprias requisições. A conclusão é que uma geração criativa longa de 20 segundos em uma chave completa limita-se a 24 requisições por minuto, muito abaixo das 300 permitidas. Se você precisa de mais throughput, encurte as respostas com max_tokens ou peça menos texto por chamada em vez de esperar por um limite de requisição maior.

Um cliente que trata todos os três casos

Este cliente Python limita sua própria concorrência com um semáforo, lê Retry-After quando presente, e faz backoff com um pequeno jitter caso contrário. Ele usa o pacote oficial openai.

Copyimport random
import threading
import time
from concurrent.futures import ThreadPoolExecutor

from openai import OpenAI, RateLimitError

client = OpenAI(
    base_url="https://api.groknsfw.top/v1",
    api_key="YOUR_KEY",
    max_retries=0,            # we handle retries ourselves
)

slots = threading.BoundedSemaphore(8)   # use 2 on the trial key

def ask(prompt, tries=6):
    for attempt in range(tries):
        with slots:
            try:
                r = client.chat.completions.create(
                    model="uncensored",
                    messages=[{"role": "user", "content": prompt}],
                    max_tokens=400,
                )
                return r.choices[0].message.content
            except RateLimitError as e:
                wait = e.response.headers.get("retry-after")
                body = e.response.text
        # sleep outside the slot so others can proceed
        delay = float(wait) if wait else min(2 ** attempt, 30)
        if "rate_limited" in body:
            delay = max(delay, 5)
        time.sleep(delay + random.random())
    raise RuntimeError("still rate limited after retries")

with ThreadPoolExecutor(max_workers=8) as pool:
    results = list(pool.map(ask, ["Write one line about the sea."] * 20))
print(len(results))

A mesma ideia em Node é uma pequena fila que permite no máximo 8 promises pendentes, e a verificação curl abaixo imprime os cabeçalhos de limite para que você possa confirmar os tetos da sua chave:

Copycurl -s -D - -o /dev/null https://api.groknsfw.top/v1/models \
  -H "Authorization: Bearer YOUR_KEY" | grep -i "x-"

Streaming, prompts longos e contexto

Uma requisição streamed com stream: true mantém o seu slot de concorrência até o último evento chegar. Isso significa que um leitor lento prejudica você: se o seu código pausa ao lidar com cada trecho, o slot fica ocupado. Consuma o stream prontamente.

Prompts longos interagem com os limites de duas formas. Primeiro, eles levam mais tempo para processar, então eles baixam o seu throughput pela fórmula acima. Segundo, eles devem caber na janela de 100.000 tokens junto com a resposta, então mantenha uma margem. Cortar os turnos antigos do chat ajuda ambos os problemas, e o mesmo corte reduz sua conta: a $0,15 por 1M de tokens de entrada, um histórico de 20.000 tokens custa $0,003 cada vez que você reenviá-lo.

Detalhes do formato da requisição estão no quickstart, e as taxas estão na página de preços.

Mostrando limites para seus próprios usuários

Um limite de taxa também é uma decisão de produto. Se o seu app fica entre usuários finais e a API, um 429 bruto nunca deve alcançá-los. Decida antecipadamente o que eles veem.

• Para apps de chat, mostre um estado curto de "escrevendo" e enfileire a mensagem. Uma espera de alguns segundos é invisível para a maioria dos usuários se algo estiver acontecendo na tela.
• Para ferramentas em lote, mostre o progresso como uma contagem de itens concluídos e deixe a tarefa rodar em segundo plano. As novas tentativas são internos e não devem aparecer como erros.
• Para implantações compartilhadas, dê a cada usuário uma pequena cota individual no seu próprio código para que um usuário intensivo não ocupe todos os 8 slots dos outros.

Logue três coisas para cada falha: o X-Request-Id, o código de erro e quantas requisições o seu app tinha em andamento naquele momento. Com isso, você pode distinguir um cliente mal-comportado de carga real em poucos minutos. Se um problema parece estar no lado do servidor, o request ID é o que suporte pedirá primeiro.

Finalmente, teste de propósito o caminho de falha. Execute seu cliente com um semáforo deliberadamente baixo e depois com um alto, e veja o que os logs mostram. Um loop de retry que nunca disparou é um loop de retry em que você não pode confiar. A chave de teste é um lugar conveniente para isso, já que com apenas 2 requisições simultâneas é fácil provocar o erro concurrency com um script curto e ver como seu código reage, por um custo de uma fração de centavo de dólar por requisição.

Erros comuns

Alguns padrões causam a maioria dos problemas de 429 que as pessoas relatam.

1. Tentar novamente instantaneamente. Um loop que reenvia a cada falha transforma um momento de limite excedido em uma tempestade. Aguarde, adicione jitter e limite o número de tentativas.
2. Tentar novamente tudo. Apenas 429 e erros transientes de servidor merecem um retry. Uma requisição malformada ou uma chave errada vai falhar da mesma forma todas as vezes.
3. Esquecendo streams na contagem. Dez janelas de chat abertas em uma chave completa podem ser dez streams, e isso são dois a mais do que os 8 slots.
4. Sem tempo limite. Uma conexão pendente mantém um slot ocupado. Defina um tempo limite razoável para cada requisição no seu cliente HTTP.
5. Dimensionamento para a média. O tráfego vem em rajadas. Planeje para o seu minuto mais intenso, não para a média diária.

Planejando capacidade antes do lançamento

Trabalhe de trás para frente a partir do seu pico. Se você espera 30 usuários conversando ao mesmo tempo e cada resposta faz streaming por cerca de 15 segundos, você precisa de 30 slots no instante em que todos enviam, e uma chave completa tem 8. Coloque o restante na fila no seu próprio app, mostre uma espera curta e processe-os conforme os slots ficam livres. Com 8 slots e respostas de 15 segundos, você pode concluir 8 x 60 / 15 = 32 respostas por minuto.

Para tarefas em lote, execute um pool de workers fixo igual ao seu limite de concorrência e deixe a lógica de retry lidar com a sobrecarga ocasional. Em vez de contornar os limites, construa a fila: isso oferece comportamento previsível e permite mostrar tempos de espera reais para seus usuários.

Mais guias

• API Grok sem censura: Guia de integração de LLM NSFW