FreeLLMAPI

Was ist FreeLLMAPI?

FreeLLMAPI ist ein OpenAI-kompatibler Proxy-Server, der kostenlosen Zugriff von mehreren LLM-Anbietern hinter einer einzigen API-Oberfläche bündelt. Statt separater SDKs zu konfigurieren und unterschiedliche Ratenlimits pro Anbieter zu handhaben, richten Sie einen OpenAI-kompatiblen Client auf Ihren Proxy aus und senden Anfragen an einen Endpunkt.

Das Projekt ist für persönliche Experimente konzipiert. Es aggregiert Keys von ~14 Anbietern (über Provider-Adapter), leitet jede Anfrage an ein verfügbares Modell weiter und führt automatisches Failover durch, wenn ein Anbieter rate-limitiert ist oder Fehler meldet.

Wichtige Funktionen

• OpenAI-kompatible Endpunkte: Implementiert POST /v1/chat/completions und GET /v1/models, sodass OpenAI-SDKs und andere OpenAI-kompatible Clients durch Ändern der base_url funktionieren.
• Streaming-Unterstützung: Bei stream: true liefert der Server Antworten über Server-Sent Events (SSE); sonst eine standard JSON-Antwort.
• Tool-Calling-Passthrough: Unterstützt OpenAI-ähnliche tools / tool_choice-Anfragen und leitet Assistenten-tool_calls plus nachfolgende tool-Role-Nachrichten über Provider-Adapter weiter.
• Automatisches Failover und Retries: Bei 429, 5xx oder Timeout markiert der Router den Key als vorübergehend nicht verfügbar und versucht es mit dem nächsten Anbieter in der Fallback-Kette (bis zu 20 Versuche).
• Nutzungs-Tracking pro Key gegen Provider-Limits: Verfolgt RPM, RPD, TPM und TPD pro (platform, model, key) und wählt Keys unter ihren kostenlosen Limits aus.
• Sticky Multi-Turn-Routing: Hält ein Gespräch 30 Minuten am selben Modell, um Wechsel mitten im Gespräch zu reduzieren.
• Verschlüsselter Key-Storage: Verschlüsselt Upstream-Provider-Keys mit AES-256-GCM, bevor sie in SQLite gespeichert werden; Entschlüsselung erfolgt im Speicher kurz vor der Nutzung.
• Einheitliche Proxy-Authentifizierung: Ihr Client authentifiziert sich beim Proxy mit einem einzigen freellmapi-...-Bearer-Token statt Upstream-Provider-Keys zu nutzen.
• Health-Checks und Admin-Steuerung: Periodische Tests markieren Keys als healthy/rate-limited/invalid/error; das inkludierte Admin-Dashboard (React + Vite) ermöglicht Key-Management, Neuordnung der Fallback-Priorität, Analytics-Einblick und einen Prompt-Playground.

So verwenden Sie FreeLLMAPI

1. Voraussetzungen installieren: Verwenden Sie Node.js 20+ und npm.
2. Klonen und installieren:
   • git clone https://github.com/tashfeenahmed/freellmapi.git
   • cd freellmapi
   • npm install
3. Umgebungskonfiguration setzen:
   • Beispiel-Env kopieren: cp .env.example .env
   • Einen ENCRYPTION_KEY generieren und in .env einfügen (das Repo bietet einen Befehl für einen zufälligen 32-Byte-Hex-Key).
4. Proxy starten: Server wie im Repository-Quick-Start/README beschrieben ausführen (die Seiteninhalte enthalten Setup-Schritte, Repo-Doku den genauen Start-Befehl).
5. OpenAI-kompatiblen Client konfigurieren:
   • base_url des Clients auf Ihren lokalen FreeLLMAPI-Server setzen.
   • Mit Proxy-Bearer-Token (freellmapi-...) authentifizieren und POST /v1/chat/completions aufrufen (optional mit stream: true).

Anwendungsfälle

• Chat-Tests mit einem Codebase über Provider: Bestehende OpenAI-kompatible App (oder Library) auf Proxy richten, um viele Modelle ohne separate Provider-SDKs zu testen.
• Manuelle Rate-Limit-Fehler reduzieren: Automatisches Failover nutzen, um 429/5xx/Timeouts überspringende Provider zu skippen und Anfrage über nächsten verfügbaren Modell fortzusetzen.
• Tool-nutzende Chat-Flows: OpenAI-ähnliche Tool-Calling-Anfragen ausführen, bei denen tool_calls und Tool-Ergebnis-Nachrichten denselben Proxy-Flow durchlaufen.
• Konsistenz bei langen Gesprächen: Chat-Sessions während aktiver Nutzung am selben Modell halten (sticky für 30 Minuten), mit Fallback bei Provider-Ausfall.
• Lokale Experimente mit verschlüsselter Key-Handhabung: Upstream-Keys zentral im Proxy mit verschlüsselter-at-rest-Speicherung, damit Client-Apps keine Provider-Keys exponieren müssen.

FAQ

• Unterstützt FreeLLMAPI die volle OpenAI-API? Nein. Das Projekt fokussiert auf Chat-Completions und Modell-Liste (/v1/chat/completions, /v1/models). Embeddings, Bilder, Audio/Speech, multimodale Inputs sowie legacy /v1/completions, Moderation und multiple Completions pro Anfrage werden nicht unterstützt.

• Wie handhabt FreeLLMAPI Rate-Limits? Es verfolgt Nutzungszähler pro Key (RPM/RPD/TPM/TPD) und wählt Keys unter Limits aus. Bei 429 (oder 5xx/Timeouts) retryt der Router mit nächstem Provider in der Fallback-Kette.

• Funktioniert Streaming mit meinem Client? Ja. Der Proxy unterstützt Streaming via SSE bei stream: true für den Chat-Endpunkt.

• Kann ich bestehende OpenAI-kompatible Libraries nutzen? Der Proxy ist für offizielle OpenAI-SDKs und andere OpenAI-kompatible Clients gedacht, indem man sie auf die Proxy-base_url richtet.

• Ist das für Produktionseinsatz gedacht? Das Repository betont explizit „nur für persönliche Experimente“.

Alternativen

• Direkte Nutzung eines einzelnen Anbieters: Viele Dienste bieten eigene APIs mit konsistenter Semantik, aber Sie erhalten keine Multi-Provider-Aggregation, automatischen Failover oder Free-Tier-Stacking in einem Endpoint.
• Eigener Router/Fallback-Layer erstellen: Ein benutzerdefinierter Proxy kann Failover und Key-Rotation umsetzen, aber Sie müssen provider-spezifische SDKs, Limits und Fehlerbehandlung selbst managen.
• Orchestrierungs-Framework mit Unterstützung mehrerer LLM-Backends nutzen: Einige Tools leiten Anfragen an verschiedene Model-Anbieter weiter, aber der Workflow kann abweichen (und bietet möglicherweise nicht dasselbe OpenAI-kompatible /v1/chat/completions-Proxy-Verhalten wie hier beschrieben).
• Manuelles Umschalten von Keys und Modellen: Sie können Anbieter manuell in Ihrer Anwendung auswählen, verlieren aber den automatischen Retry/Failover und das per-Key-Rate-Tracking, das FreeLLMAPI bietet.