FreeLLMAPI

O que é FreeLLMAPI?

FreeLLMAPI é um servidor proxy compatível com OpenAI que consolida acesso gratuito de múltiplos provedores de LLM por trás de uma única superfície de API. Em vez de configurar SDKs separados e gerenciar limites de taxa diferentes para cada provedor, você aponta um cliente compatível com OpenAI para o seu proxy e envia requisições para um único endpoint.

O projeto é projetado para experimentação pessoal. Ele agrega chaves de ~14 provedores (via adaptadores de provedor), roteia cada requisição para um modelo disponível e realiza failover automático quando um provedor está limitado por taxa ou apresenta erros.

Principais Recursos

• Endpoints compatíveis com OpenAI: Implementa POST /v1/chat/completions e GET /v1/models para que SDKs OpenAI e outros clientes compatíveis com OpenAI funcionem alterando apenas o base_url.
• Suporte a streaming: Quando stream: true, o servidor retorna respostas usando Server-Sent Events (SSE); caso contrário, retorna uma resposta JSON padrão.
• Pass-through de chamadas de ferramentas: Suporta requisições tools / tool_choice no estilo OpenAI e encaminha tool_calls do assistente mais mensagens subsequentes de função tool pelos adaptadores de provedor.
• Failover automático e retentativas: Se o provedor selecionado retornar 429, 5xx ou expirar o tempo, o roteador marca essa chave como temporariamente indisponível e tenta novamente com o próximo provedor na cadeia de fallback (até 20 tentativas).
• Rastreio de uso por chave contra limites do provedor: Monitora RPM, RPD, TPM e TPD por (platform, model, key) e seleciona chaves abaixo de seus limites gratuitos respectivos.
• Roteamento multi-turn persistente: Mantém uma conversa no mesmo modelo por 30 minutos para reduzir trocas no meio da conversa.
• Armazenamento criptografado de chaves: Criptografa chaves de provedores upstream com AES-256-GCM antes de armazená-las em SQLite; a descriptografia ocorre na memória logo antes do uso.
• Autenticação unificada do proxy: Seu cliente autentica no proxy com um único token bearer freellmapi-... em vez de usar chaves de provedores upstream.
• Verificações de saúde e controles admin: Sondas periódicas rotulam chaves como saudáveis/limitadas por taxa/inválidas/erro; o painel admin incluído (React + Vite) permite gerenciar chaves, reordenar prioridade de fallback, inspecionar análises e executar um playground de prompts.

Como Usar FreeLLMAPI

1. Instalar requisitos: Use Node.js 20+ e npm.
2. Clonar e instalar:
   • git clone https://github.com/tashfeenahmed/freellmapi.git
   • cd freellmapi
   • npm install
3. Configurar ambiente:
   • Copie o env de exemplo: cp .env.example .env
   • Gere uma ENCRYPTION_KEY e coloque em .env (o repositório fornece um comando que gera uma chave hex aleatória de 32 bytes).
4. Iniciar o proxy: Execute o servidor conforme descrito no quick start / README do repositório (o trecho de conteúdo da página inclui os passos de setup, e a documentação do repositório cobre o comando exato de inicialização).
5. Configurar seu cliente compatível com OpenAI:
   • Defina o base_url do cliente para o seu servidor local FreeLLMAPI.
   • Autentique com o token bearer do proxy (freellmapi-...) e chame POST /v1/chat/completions (opcionalmente com stream: true).

Casos de Uso

• Teste de chat em um único codebase entre provedores: Aponte um app ou biblioteca existente compatível com OpenAI para o proxy e experimente muitos modelos sem gerenciar SDKs separados de provedores.
• Reduzir falhas manuais por limite de taxa: Use o failover automático para pular provedores que respondem com 429/5xx/timeouts e continue a requisição pelo próximo modelo disponível na ordem de fallback configurada.
• Fluxos de chat com uso de ferramentas: Execute requisições de chamadas de ferramentas no estilo OpenAI onde tool_calls e mensagens de resultado de ferramentas são roteadas pelo mesmo fluxo de proxy subjacente.
• Consistência em conversas longas: Mantenha sessões de chat no mesmo modelo durante uso ativo (sessões persistentes por 30 minutos) enquanto ainda beneficia de fallback se o provedor ficar indisponível.
• Experimentação local com manuseio criptografado de chaves: Centralize chaves upstream dentro do proxy com armazenamento criptografado em repouso, para que seus apps cliente não precisem expor chaves de provedores.

FAQ

• FreeLLMAPI suporta a API completa do OpenAI? Não. O projeto foca em chat completions e lista de modelos (/v1/chat/completions, /v1/models). Embeddings, imagens, áudio/fala e entradas multimodais não são suportados, assim como /v1/completions legados, moderação e múltiplas completions por requisição.

• Como FreeLLMAPI lida com limites de taxa? Ele rastreia contadores de uso por chave (RPM/RPD/TPM/TPD) e seleciona chaves abaixo dos limites. Se um provedor ainda retornar 429 (ou 5xx/timeouts), o roteador tenta novamente usando o próximo provedor na cadeia de fallback.

• O streaming funciona com meu cliente? Sim. O proxy suporta streaming via SSE quando stream: true no endpoint de chat.

• Posso usar bibliotecas existentes compatíveis com OpenAI? O proxy é projetado para funcionar com SDKs oficiais OpenAI e outros clientes compatíveis com OpenAI apontando para o base_url do proxy.

• Isso é para uso em produção? O repositório afirma explicitamente que é “apenas para experimentação pessoal”.

Alternativas

• Usar um único provedor diretamente: Muitos serviços oferecem sua própria API com semântica consistente, mas você não obteria agregação multi-provedor, failover automático ou empilhamento de tiers gratuitos em um único endpoint.
• Construir seu próprio roteador/camada de fallback: Um proxy personalizado pode implementar failover e rotação de chaves, mas você precisaria gerenciar SDKs específicos de provedores, limites e tratamento de erros por conta própria.
• Usar um framework de orquestração que suporte múltiplos backends LLM: Algumas ferramentas roteiam requisições entre diferentes provedores de modelos, mas o fluxo de trabalho pode diferir (e pode não fornecer o mesmo comportamento de proxy /v1/chat/completions compatível com OpenAI descrito aqui).
• Troca manual de chaves e modelos: Você pode selecionar provedores manualmente em sua aplicação, mas perde o retry/failover automático e o rastreio de taxa por chave que o FreeLLMAPI fornece.