talhasarit/llm-rate-limiting

Limitação de Taxa para LLMs

Implemente integrações resilientes com LLMs usando retentativas determinísticas, throttling, tratamento de cotas e controles de concorrência. Leia references/examples.md para entender os gatilhos esperados e não-gatilhos. Leia references/troubleshooting.md quando os sintomas não corresponderem ao caminho feliz.

Fluxo de Trabalho

1. Inspecione o código para encontrar o único ponto de fronteira onde as chamadas LLM saem da aplicação. Prefira modificar um gateway compartilhado, wrapper de cliente ou módulo de serviço em vez de espalhar retentativas por vários pontos de chamada.
2. Analise o código-fonte do projeto alvo para identificar o provedor de LLM específico em uso. Trate OpenAI e Groq como ramos de primeira classe com semânticas de cabeçalho e modelos de limite específicos de cada provedor.
3. Se o provedor for OpenAI, leia references/openai-rate-limits.md antes de escolher cotas, comportamento de retentativa ou suposições de ritmo.
4. Se o provedor for Groq, leia references/groq-rate-limits.md antes de escolher cotas, comportamento de retentativa ou suposições de ritmo.
5. Se o usuário disser "Estou no Tier 1" ou fornecer outro rótulo de plano, trate isso apenas como contexto de orçamento, a menos que a documentação do provedor diga que isso determina totalmente os limites operacionais.
6. Reutilize abstrações, logging, configuração e ajudantes de teste já existentes no projeto. Preserve o estilo do projeto em vez de introduzir uma pilha de cliente paralela.
7. Leia scripts/resilience_templates.py e adapte seus padrões de retentativa, janela de reset e circuit breaker ao modelo de cliente HTTP e exceções do projeto.
8. Adicione ou atualize a cobertura de regressão em torno da fronteira compartilhada de LLM quando o projeto tiver testes. Valide caminhos felizes, caminhos de throttling e análise de cabeçalhos específicos do provedor.

Tratamento Reativo

Implemente o Tratamento Reativo Baseado em Cabeçalhos. Use a biblioteca tenacity em Python para envolver todas as chamadas de rede LLM.

1. Parseie Retry-After primeiro quando estiver presente.
2. Se Retry-After estiver ausente, use os cabeçalhos de reset do provedor antes de cair em backoff exponencial com jitter.
3. Mantenha o jitter exponencial na faixa de 1s a 60s para evitar picos de "thundering herd".
4. Trate explicitamente erros HTTP 429 e 503.
5. Trate erros transitórios 5xx, timeout e reset de conexão como candidatos a retentativa apenas quando a chamada circundante for idempotente ou segura para repetir.
6. Evite retentar erros de cliente determinísticos, como requisições malformadas.
7. Emita logs estruturados que incluam provedor, modelo, código de status, tentativa de retentativa e atraso calculado.
8. Para OpenAI, parseie x-ratelimit-limit-requests, x-ratelimit-limit-tokens, x-ratelimit-remaining-requests, x-ratelimit-remaining-tokens, x-ratelimit-reset-requests e x-ratelimit-reset-tokens, e ajuste o ritmo pela dimensão mais restritiva.
9. Para Groq, parseie retry-after mais cabeçalhos x-ratelimit-*, lembrando que cabeçalhos de requisição se referem a RPD e cabeçalhos de token se referem a TPM.
10. Diferencie throttling retentável de exaustão de cota ou cobrança não retentável.

Circuit Breaker

Implemente o Padrão Circuit Breaker. Use a biblioteca pybreaker para abrir o circuito após 5 falhas consecutivas de throttling ou falhas transitórias de servidor.

1. Exclua erros de cliente 400 e 401 de acionar o disjuntor.
2. Mantenha o disjuntor na mesma fronteira compartilhada de LLM que a lógica de retentativa.
3. Levante ou mapeie uma exceção de fail-fast específica do projeto quando o disjuntor estiver aberto, para que o código upstream possa degradar graciosamente.
4. Para processamento flexível do Groq, trate o status 498 com capacity_exceeded como um sinal de capacidade retentável, não como um erro de aplicação permanente.

Throttling Proativo

Implemente Throttling Proativo.

1. Configure um limitador local de token bucket (ou equivalente) do lado do cliente que rastreie as dimensões do provedor realmente expostas pela API alvo.
2. Mantenha a taxa efetiva cerca de 10% abaixo dos limites conhecidos para preservar margem para jitter, skew de clock e workers concorrentes.
3. Enfileire, atrase ou rejeite localmente quando não houver orçamento suficiente de requisições ou tokens, em vez de deixar o provedor rejeitar a chamada.
4. Prefira estado compartilhado como Redis apenas quando a aplicação tiver múltiplos workers ou hosts que precisem coordenar o mesmo orçamento.
5. Para OpenAI, trate os limites como restrições de nível de organização e projeto, não de nível de usuário.
6. Para OpenAI, escopar o ritmo por família de modelo e grupos de limite compartilhados, em vez de assumir que cada modelo tem um orçamento independente.
7. Para OpenAI, considere limites de requisição de contexto longo separadamente quando o modelo alvo usar um bucket de contexto longo distinto.
8. Para Groq, trate os limites como restrições de nível de organização e lembre-se de que limites personalizados de nível de projeto só podem ser mais restritivos que o teto da organização.
9. Para Groq, lembre-se de que tokens em cache não contam para limites de taxa, mas o tráfego paralelo ainda pode esgotar a capacidade não cacheada.

Otimizações de Framework

Implemente Otimizações de Framework quando camadas de orquestração estiverem presentes.

1. Imponha limites explícitos de max_concurrency ou equivalentes de fan-out em todo caminho de execução paralela de LLM para evitar picos de rede.
2. Inspecione ajudantes assíncronos, pools de workers, executores de grafos e harnesses de avaliação em busca de chamadas LLM paralelas ocultas.
3. Apare ou limite o histórico de chat não limitado se a integração continuar anexando contexto antigo a toda chamada e queimar rapidamente os orçamentos de token.

Orientação de Cache

Recomende Cache Semântico e ajuste de taxa consciente do provedor.

1. Solicite ao usuário no console a integração de um cache semântico baseado em Redis ou GPTCache para evitar chamadas externas repetidas.
2. Enquadre o cache como um multiplicador direto de limite de taxa, não apenas uma otimização de latência.
3. Sugira inserção em cache apenas para prompts cujas saídas sejam estáveis o suficiente para reutilizar.
4. Para OpenAI, recomende reduzir max_tokens para o tamanho de saída realista mais próximo e agrupar workloads síncronas apenas quando RPM estiver saturado e houver margem de TPM.
5. Para Groq, recomende cache de prompt quando o modelo suportar e o workload reutilizar grandes prefixos compartilhados.

Regras de Implementação

1. Prefira bibliotecas testadas em batalha em vez de loops de retentativa personalizados ou implementações de disjuntor.
2. Mantenha caminhos de código determinísticos com baixa liberdade. Não invente novas fórmulas de backoff quando o template já se ajustar.
3. Use barras normais no estilo Unix em todo caminho de arquivo que você escrever ou referenciar.
4. Mantenha as semânticas do provedor explícitas. Não assuma que os significados de cabeçalho de um provedor se aplicam a outro.
5. Use cabeçalhos reais, páginas de limites autenticadas ou números fornecidos explicitamente pelo usuário quando o ritmo exato for importante.
6. Mantenha a pasta do skill limpa: sem README.md, sem docs apenas do repositório e sem capturas de tela dentro do skill instalável.