FreeLLMAPI

FreeLLMAPI 是什麼？

FreeLLMAPI 是一個 OpenAI 相容的代理伺服器，將多個 LLM 供應商的免費階層存取整合在單一 API 介面後方。您無需配置各別 SDK 或處理每個供應商的不同速率限制，只需將 OpenAI 相容客戶端指向您的代理，並發送請求至單一端點。

此專案設計用於個人實驗。它彙整約 14 家供應商的金鑰（透過供應商適配器），將每個請求路由至可用模型，並在供應商遇速率限制或錯誤時自動故障切換。

OpenAI 相容端點：實作 POST /v1/chat/completions 和 GET /v1/models，讓 OpenAI SDK 及其他 OpenAI 相容客戶端僅需變更 base_url 即可運作。
串流支援：當 stream: true 時，伺服器使用 Server-Sent Events (SSE) 回傳回應；否則回傳標準 JSON 回應。
工具呼叫直通：支援 OpenAI 風格的 tools / tool_choice 請求，並將助理的 tool_calls 及後續 tool 角色訊息轉發至供應商適配器。
自動故障切換與重試：若選定供應商回傳 429、5xx 或逾時，路由器將該金鑰標記為暫時不可用，並使用後備鏈中的下一個供應商重試（最多 20 次）。
每金鑰使用量追蹤對供應商上限：針對每個 (platform, model, key) 追蹤 RPM, RPD, TPM, and TPD，並選擇未達免費階層限制的金鑰。
黏性多輪路由：對話維持在相同模型 30 分鐘，減少對話中途切換。
加密金鑰儲存：使用 AES-256-GCM 加密上游供應商金鑰後儲存至 SQLite；使用前在記憶體中解密。
統一代理認證：您的客戶端使用單一 freellmapi-... bearer token 向代理認證，而非使用上游供應商金鑰。
健康檢查與管理控制：定期探測將金鑰標記為健康/速率限制/無效/錯誤；內含管理儀表板（React + Vite）可管理金鑰、重新排序後備優先順序、檢視分析及執行提示遊樂場。

安裝需求：使用 Node.js 20+ 和 npm。
複製與安裝：
- git clone https://github.com/tashfeenahmed/freellmapi.git
- cd freellmapi
- npm install
設定環境配置：
- 複製範例 env：cp .env.example .env
- 產生 ENCRYPTION_KEY 並置入 .env（儲存庫提供指令輸出隨機 32 位元組十六進位金鑰）。
啟動代理：依儲存庫快速入門 / README 所述執行伺服器（頁面內容摘錄包含設定步驟，儲存庫文件涵蓋確切啟動指令）。
配置您的 OpenAI 相容客戶端：
- 將客戶端的 base_url 設為本機 FreeLLMAPI 伺服器。
- 使用代理的 bearer token (freellmapi-...) 認證並呼叫 POST /v1/chat/completions（可選 stream: true）。

FreeLLMAPI 是否支援完整 OpenAI API？ 不支援。此專案聚焦聊天完成及模型清單（/v1/chat/completions、/v1/models）。嵌入、圖像、音訊/語音及多模態輸入不支援，舊版 /v1/completions、審核及多重完成亦然。
FreeLLMAPI 如何處理速率限制？ 追蹤每金鑰使用計數器（RPM/RPD/TPM/TPD）並選擇未達上限的金鑰。若供應商仍回傳 429（或 5xx/逾時），路由器使用後備鏈中下一個供應商重試。
串流是否與我的客戶端相容？ 是。代理支援聊天端點 stream: true 時的 SSE 串流。
能否使用現有 OpenAI 相容函式庫？ 代理設計用於與官方 OpenAI SDK 及其他 OpenAI 相容客戶端搭配，僅需指向代理的 base_url。
這適合生產環境使用嗎？ 儲存庫明確表示僅供「個人實驗」。

直接使用單一供應商：許多服務提供自家 API 具一致語意，但無法獲得多供應商聚合、自動故障切換或單一端點免費額度疊加。
自行建置路由/備援層：自訂代理可實現故障切換與金鑰輪替，但需自行管理供應商專屬 SDK、限制與錯誤處理。
使用支援多 LLM 後端的協調框架：某些工具可在不同模型供應商間路由請求，但工作流程可能不同（且未必提供本文所述相同 OpenAI 相容 /v1/chat/completions 代理行為）。
手動切換金鑰與模型：可在應用程式中手動選擇供應商，但會失去 FreeLLMAPI 提供的自動重試/故障切換與每把金鑰速率追蹤。