FreeLLMAPI

Qu'est-ce que FreeLLMAPI ?

FreeLLMAPI est un serveur proxy compatible OpenAI qui consolide l'accès free-tier de plusieurs fournisseurs LLM derrière une seule surface d'API. Au lieu de configurer des SDK séparés et de gérer des limites de taux différentes pour chaque fournisseur, vous pointez un client compatible OpenAI vers votre proxy et envoyez des requêtes à un seul endpoint.

Le projet est conçu pour l'expérimentation personnelle. Il agrège des clés de ~14 fournisseurs (via des adaptateurs fournisseurs), route chaque requête vers un modèle disponible et effectue un basculement automatique quand un fournisseur est limité en taux ou en erreur.

Fonctionnalités principales

• Endpoints compatibles OpenAI : Implémente POST /v1/chat/completions et GET /v1/models pour que les SDK OpenAI et autres clients compatibles OpenAI fonctionnent en changeant base_url.
• Support du streaming : Quand stream: true, le serveur renvoie les réponses via Server-Sent Events (SSE) ; sinon il renvoie une réponse JSON standard.
• Pass-through des appels d'outils : Prend en charge les requêtes tools / tool_choice style OpenAI et transfère les tool_calls de l'assistant plus les messages de rôle tool suivants via les adaptateurs fournisseurs.
• Basculement automatique et réessais : Si le fournisseur sélectionné renvoie 429, 5xx, ou expire, le routeur marque cette clé comme temporairement indisponible et réessaie avec le fournisseur suivant dans la chaîne de fallback (jusqu'à 20 tentatives).
• Suivi d'usage par clé contre les limites fournisseurs : Suit RPM, RPD, TPM, et TPD par (platform, model, key) et sélectionne les clés sous leurs limites free-tier respectives.
• Routage multi-tour collant : Garde une conversation sur le même modèle pendant 30 minutes pour réduire les changements en milieu de conversation.
• Stockage chiffré des clés : Chiffre les clés fournisseurs en amont avec AES-256-GCM avant de les stocker en SQLite ; déchiffrement en mémoire juste avant utilisation.
• Authentification proxy unifiée : Votre client s'authentifie au proxy avec un seul token bearer freellmapi-... plutôt qu'avec les clés fournisseurs en amont.
• Vérifications de santé et contrôles admin : Sondes périodiques étiquettent les clés comme saines/limitée/invalide/erreur ; le tableau de bord admin inclus (React + Vite) permet de gérer les clés, réordonner les priorités de fallback, inspecter les analyses et exécuter un playground de prompts.

Comment utiliser FreeLLMAPI

1. Installer les prérequis : Utilisez Node.js 20+ et npm.
2. Cloner et installer :
   • git clone https://github.com/tashfeenahmed/freellmapi.git
   • cd freellmapi
   • npm install
3. Configurer l'environnement :
   • Copier l'exemple env : cp .env.example .env
   • Générer une ENCRYPTION_KEY et la placer dans .env (le repo fournit une commande qui sort une clé hex aléatoire de 32 octets).
4. Démarrer le proxy : Lancez le serveur comme décrit dans le quick start / README du repo (le contenu de la page inclut les étapes de setup, et la doc du repo couvre la commande de démarrage exacte).
5. Configurer votre client compatible OpenAI :
   • Définir base_url du client vers votre serveur FreeLLMAPI local.
   • Authentifier avec le token bearer du proxy (freellmapi-...) et appeler POST /v1/chat/completions (optionnellement avec stream: true).

Cas d'usage

• Tests de chat mono-codebase sur fournisseurs : Pointez une app (ou lib) compatible OpenAI existante vers le proxy pour expérimenter de nombreux modèles sans gérer des SDK fournisseurs séparés.
• Réduction des échecs manuels de limites de taux : Utilisez le basculement automatique pour sauter les fournisseurs qui répondent 429/5xx/timeouts et continuer via le modèle suivant disponible dans votre ordre de fallback configuré.
• Flux de chat avec outils : Exécutez des requêtes d'appels d'outils style OpenAI où tool_calls et messages de résultats d'outils sont routés via le même flux proxy sous-jacent.
• Cohérence des conversations longues : Gardez les sessions de chat sur le même modèle pendant l'usage actif (sessions collantes 30 min) tout en bénéficiant du fallback si le fournisseur devient indisponible.
• Expérimentation locale avec gestion chiffrée des clés : Centralisez les clés en amont dans le proxy avec stockage chiffré au repos, pour que vos apps client n'exposent pas les clés fournisseurs.

FAQ

• FreeLLMAPI supporte-t-il l'API OpenAI complète ? Non. Le projet se concentre sur les complétions de chat et la liste des modèles (/v1/chat/completions, /v1/models). Embeddings, images, audio/parole, et entrées multimodales ne sont pas supportés, pas plus que /v1/completions legacy, modération, et multiples complétions par requête.

• Comment FreeLLMAPI gère-t-il les limites de taux ? Il suit les compteurs d'usage par clé (RPM/RPD/TPM/TPD) et sélectionne les clés sous les caps. Si un fournisseur renvoie encore un 429 (ou 5xx/timeouts), le routeur réessaie avec le fournisseur suivant dans la chaîne de fallback.

• Le streaming fonctionne-t-il avec mon client ? Oui. Le proxy supporte le streaming via SSE quand stream: true pour l'endpoint chat.

• Puis-je utiliser des libs compatibles OpenAI existantes ? Le proxy est conçu pour fonctionner avec les SDK OpenAI officiels et autres clients compatibles OpenAI en les pointant vers base_url du proxy.

• Est-ce destiné à un usage en production ? Le repo indique explicitement qu'il est « pour expérimentation personnelle uniquement ».

Alternatives

• Utiliser un seul fournisseur directement : De nombreux services proposent leur propre API avec une sémantique cohérente, mais vous n'obtiendriez pas l'agrégation multi-fournisseurs, le basculement automatique ou l'empilement des free-tiers sur un seul endpoint.
• Construire votre propre routeur/couche de fallback : Un proxy personnalisé peut implémenter le basculement et la rotation des clés, mais vous devriez gérer vous-même les SDK spécifiques aux fournisseurs, les limites et la gestion des erreurs.
• Utiliser un framework d'orchestration compatible avec plusieurs backends LLM : Certains outils routent les requêtes vers différents fournisseurs de modèles, mais le workflow peut différer (et ne pas offrir le même comportement de proxy /v1/chat/completions compatible OpenAI décrit ici).
• Changement manuel de clés et de modèles : Vous pouvez sélectionner les fournisseurs manuellement dans votre application, mais vous perdez la tentative automatique/rétablissement et le suivi par clé que fournit FreeLLMAPI.