FreeLLMAPI

Cos'è FreeLLMAPI?

FreeLLMAPI è un server proxy compatibile con OpenAI che consolida l'accesso free-tier da più provider LLM dietro a un'unica superficie API. Invece di configurare SDK separati e gestire limiti di rate diversi per ogni provider, punti un client compatibile con OpenAI al tuo proxy e invii richieste a un unico endpoint.

Il progetto è progettato per sperimentazioni personali. Aggrega chiavi da ~14 provider (tramite adapter provider), instrada ogni richiesta a un modello disponibile e esegue failover automatico quando un provider è limitato dal rate o genera errori.

Caratteristiche Principali

• Endpoint compatibili con OpenAI: Implementa POST /v1/chat/completions e GET /v1/models così che gli SDK OpenAI e altri client compatibili con OpenAI funzionino cambiando solo base_url.
• Supporto allo streaming: Quando stream: true, il server restituisce risposte usando Server-Sent Events (SSE); altrimenti restituisce una risposta JSON standard.
• Pass-through per tool calling: Supporta richieste tools / tool_choice in stile OpenAI e inoltra tool_calls dell'assistente più messaggi successivi con ruolo tool attraverso gli adapter provider.
• Failover automatico e retry: Se il provider selezionato restituisce 429, 5xx o scade il timeout, il router segna quella chiave come temporaneamente non disponibile e ritenta con il provider successivo nella catena di fallback (fino a 20 tentativi).
• Tracciamento utilizzo per chiave contro i limiti provider: Traccia RPM, RPD, TPM e TPD per (platform, model, key) e seleziona chiavi sotto i rispettivi limiti free-tier.
• Routing multi-turn sticky: Mantiene una conversazione sullo stesso modello per 30 minuti per ridurre switch a metà conversazione.
• Storage chiavi cifrato: Cifra le chiavi upstream con AES-256-GCM prima di salvarle in SQLite; la decifratura avviene in memoria subito prima dell'uso.
• Autenticazione proxy unificata: Il tuo client si autentica al proxy con un singolo token bearer freellmapi-... invece di usare chiavi upstream provider.
• Controlli salute e admin: Probe periodiche etichettano le chiavi come sane/limitate/invalide/errore; il dashboard admin incluso (React + Vite) permette di gestire chiavi, riordinare priorità fallback, ispezionare analytics e usare un playground per prompt.

Come Usare FreeLLMAPI

1. Installa i requisiti: Usa Node.js 20+ e npm.
2. Clona e installa:
   • git clone https://github.com/tashfeenahmed/freellmapi.git
   • cd freellmapi
   • npm install
3. Imposta configurazione ambiente:
   • Copia l'env esempio: cp .env.example .env
   • Genera una ENCRYPTION_KEY e inseriscila in .env (il repo fornisce un comando che genera una chiave hex casuale da 32 byte).
4. Avvia il proxy: Esegui il server come descritto nel quick start / README del repository (il contenuto della pagina include i passi setup, e la documentazione del repo copre il comando di avvio esatto).
5. Configura il tuo client compatibile con OpenAI:
   • Imposta base_url del client al tuo server FreeLLMAPI locale.
   • Autentica con il token bearer del proxy (freellmapi-...) e chiama POST /v1/chat/completions (opzionalmente con stream: true).

Casi d'Uso

• Test chat con un unico codebase su provider multipli: Punta un'app esistente compatibile con OpenAI (o libreria) al proxy per sperimentare con molti modelli senza gestire SDK provider separati.
• Ridurre fallimenti manuali rate-limit: Usa il failover automatico per saltare provider che rispondono con 429/5xx/timeout e continua la richiesta con il modello successivo disponibile nel tuo ordine fallback configurato.
• Flussi chat con tool: Esegui richieste tool calling in stile OpenAI dove tool_calls e messaggi tool-result sono instradati attraverso lo stesso flusso proxy sottostante.
• Consistenza conversazioni lunghe: Mantieni sessioni chat sullo stesso modello durante l'uso attivo (sessioni sticky per 30 minuti) beneficiando comunque di fallback se il provider diventa non disponibile.
• Sperimentazione locale con gestione chiavi cifrate: Centralizza chiavi upstream nel proxy con storage cifrato a riposo, così le tue app client non devono esporre chiavi provider.

FAQ

• FreeLLMAPI supporta l'intera API OpenAI? No. Il progetto si concentra su chat completions e lista modelli (/v1/chat/completions, /v1/models). Embeddings, immagini, audio/speech e input multimodali non sono supportati, così come /v1/completions legacy, moderazione e multiple completions per richiesta.

• Come gestisce FreeLLMAPI i rate limit? Traccia contatori utilizzo per chiave (RPM/RPD/TPM/TPD) e seleziona chiavi sotto i limiti. Se un provider restituisce comunque 429 (o 5xx/timeout), il router ritenta con il provider successivo nella catena fallback.

• Lo streaming funziona con il mio client? Sì. Il proxy supporta streaming via SSE quando stream: true per l'endpoint chat.

• Posso usare librerie esistenti compatibili con OpenAI? Il proxy è progettato per funzionare con SDK OpenAI ufficiali e altri client compatibili con OpenAI puntandoli alla base_url del proxy.

• È adatto per uso in produzione? Il repository specifica esplicitamente che è “solo per sperimentazioni personali”.

Alternative

• Usa un singolo provider direttamente: Molti servizi offrono la propria API con semantiche consistenti, ma non otterresti l'aggregazione multi-provider, il failover automatico o lo stacking free-tier in un unico endpoint.
• Costruisci il tuo router/strato di fallback: Un proxy personalizzato può implementare failover e rotazione chiavi, ma dovresti gestire SDK specifici del provider, limiti e gestione errori da solo.
• Usa un framework di orchestrazione che supporta più backend LLM: Alcuni tool instradano le richieste su diversi provider di modelli, ma il workflow potrebbe differire (e potrebbe non fornire lo stesso comportamento proxy /v1/chat/completions compatibile con OpenAI descritto qui).
• Commutazione manuale di chiavi e modelli: Puoi selezionare i provider manualmente nella tua applicazione, ma perdi il retry/failover automatico e il rate tracking per chiave fornito da FreeLLMAPI.