freellmapi 是什么?

FreeLLMAPI 是一个自托管、单用户的 OpenAI 兼容代理:把约 14 家 AI 提供商的免费额度 key 聚合到一个本地 /v1 端点,按健康状态和速率限制自动选路、失败自动回退。它的卖点是「单独看每家免费额度都是玩具,叠起来约每月 13 亿 token」,让任意 OpenAI 客户端只改 base_url 就能透明路由。它把项目边界划得很清——README 明确标注「仅供个人实验与学习、非生产用途」,并附了一份对各家 ToS 的逐条审查表。TypeScript 写,MIT 许可,作者 tashfeenahmed。

⭐ 5,400 Stars 🍴 800 Forks TypeScript MIT 作者: tashfeenahmed
来源:README Why this exists/Disclaimer/Terms of Service review;GitHub desc,license MIT 查看 GitHub 仓库 →

为什么值得关注

上线一个月即超过 3.7k 星,热度来自和 9router 类似的「免费薅 AI」诉求,但它走的是更克制、更诚实的路线:不吹「无限免费」,而是讲清楚叠加免费额度的真实收益(约 13 亿 token/月)与代价(没有前沿模型、智能度随当日额度耗尽下降、无 SLA),并罕见地给出逐家 ToS 审查与「一账户一家、不转售、不共享端点」的合规建议。这种透明 + 工程完整度(加密存 key、限额账本、Pi 可跑)让它显得靠谱,传播自然。

来源:GitHub 3,708 stars / 507 forks,created 2026-04-21;README Why/Limitations/ToS

核心功能

OpenAI 兼容统一端点 + 工具调用/流式

提供 POST /v1/chat/completions 与 GET /v1/models,兼容官方 OpenAI SDK 及 LangChain/LlamaIndex/Continue 等任意兼容客户端;支持 SSE 流式与非流式、OpenAI 风格 tools/tool_choice 工具调用且能跨 provider 往返。

来源:README Features(OpenAI-compatible/Streaming/Tool calling);Using the API
智能路由与自动回退

Router 每次请求挑「优先级最高、有健康 key、且未触各项限额」的模型;遇 429/5xx/超时则把该 key 短暂冷却并沿回退链重试下一个模型(最多 20 次),多轮对话用 30 分钟 sticky session 保持同一模型避免中途切换引发的幻觉。

来源:README Features/How it works;server/src/services/router.ts
按 key 限额账本与健康检查

对每个 (platform, model, key) 维护 RPM/RPD/TPM/TPD 计数(内存 + SQLite 落盘),保证只挑未超限的 key;周期性 health 探针把 key 标为 healthy/rate_limited/invalid/error,自动跳过失效项。

来源:README Features/How it works;server/src/services/{ratelimit,health}.ts
加密 key 存储 + 统一对外令牌

上游 provider key 用 AES-256-GCM 加密后存入 SQLite,仅在请求前于内存解密;客户端只用一个 freellmapi-… bearer 令牌认证,应用永远拿不到上游 key。

来源:README Features(Encrypted key storage/Unified API key)
管理面板 + 分析,可跑在树莓派

React + Vite + shadcn/ui 的管理面板可管 key、调整回退链顺序、看分析、在 playground 试 prompt(含暗色模式);按请求记录延迟/token/成功率与各 provider 分布;空载约 40MB RSS,可在 Pi 4 上用 PM2 + nginx 跑。

来源:README Features(Admin dashboard/Analytics/Raspberry Pi);client/

技术架构

前后端分离的 TypeScript monorepo(server / client / shared)。server 是 Express 代理(默认 :3001),核心是 server/src/services/router.ts(按健康度+限额选模型并失败回退)、ratelimit.ts(RPM/RPD/TPM/TPD 限额账本,SQLite 支撑 + 429 冷却)、health.ts(周期探针刷新 key 状态);每家提供商是 server/src/providers/ 下一个文件,继承 Provider 基类实现 chatCompletion() 与 streamChatCompletion(),新增 provider 只需照 openai-compat.ts 模板复制并在 index.ts 注册、在 db 里种模型;存储用 better-sqlite3,对 key 做 AES-256-GCM 信封加密。client 是 React + Vite + shadcn/ui 管理界面。模型目录可用 server/src/scripts/ 的 re-seed 脚本更新(应对免费额度变动)。整体是「统一 OpenAI 入口 → 路由/限额/健康 → 可插拔 provider 适配器」的清晰分层,单用户本地优先设计。

来源:tree(server/client/shared);README How it works/Contributing

项目知识图谱

知识图谱:项目核心节点(中心)+ 核心功能(内环六边形)+ 关键技术依赖(外环 chip) Express better-sqlite3 (SQLite)better-sqlite3 AES-256-GCM (key 加密)AES-256-GCM React + Vite + shadcn/uiReact + Vite +… 各 provider SDK (Google/Groq/Cerebras/Mistral/OpenRouter/Cloudflare 等)各 provider SDK OpenAI 兼容统一端点 + 工具调用/流式OpenAI 兼容统一端点… 智能路由与自动回退 按 key 限额账本与健康检查按 key 限额账本与健康… 加密 key 存储 + 统一对外令牌加密 key 存储 + 统一… 管理面板 + 分析,可跑在树莓派管理面板 + 分析,可跑… freellmapi 项目本体 核心功能 关键依赖

中心为项目本体,内环 = 核心功能模块,外环 = 关键技术依赖;按 deep.json 中的 core_features 与 tech_stack.key_deps 自动生成

技术栈

语言TypeScript框架Express (后端) + React/Vite (前端)
Expressbetter-sqlite3 (SQLite)AES-256-GCM (key 加密)React + Vite + shadcn/ui各 provider SDK (Google/Groq/Cerebras…vitest (75 测试)
本地单用户自托管(Node 20+);可在树莓派 Pi4 上用 PM2 + nginx 跑,空载约 40MB;依赖各家免费额度账号
来源:README Quick start/How it works/Contributing;package.json

快速上手

需 Node.js 20+。`git clone https://github.com/tashfeenahmed/freellmapi.git && cd freellmapi && npm install`,先生成用于静态加密 key 的密钥(README 给出命令),再启动 server + dashboard(dev 模式 `npm run dev`:server :3001、dashboard :5173,均带 HMR;`npm test` 跑 75 个 vitest)。在面板里添加各家免费额度 key、排回退链顺序,然后把你的 OpenAI 客户端 base_url 指向本地服务、用 freellmapi-… 令牌认证即可。注意:单用户本地用,别暴露到公网;只支持 chat 端点(无 embeddings/images/audio/vision/n>1)。
来源:README Quick start/Using the API/Not yet supported

使用场景

适合:①个人开发者把多家免费额度叠成一个本地 OpenAI 端点,用来做原型、实验、跑非生产小项目;②想统一管理多家 key、要加密存储和限额/健康自动选路的人;③想在树莓派等低配机上常驻一个轻量聚合代理的玩家。不适合:需要前沿模型(GPT-5/Claude Opus 级,免费档拿不到)、需要稳定 SLA、做生产后端、或需要 embeddings/图像/多模态/多租户的场景——这些项目都明确说了不支持或不建议,要换付费 API。

来源:README Why/Limitations/Not yet supported/Disclaimer

优势与局限

优势

  • 诚实克制:不吹无限免费,讲清真实收益与代价,并给出逐家 ToS 审查和合规建议,态度难得
  • 工程完整:路由/限额账本/健康检查/失败回退/sticky session 都做了,且 75 个测试、provider 适配器可插拔
  • 安全细节到位:上游 key AES-256-GCM 加密存储、对外只暴露统一令牌、应用拿不到真实 key
  • OpenAI 兼容彻底:改 base_url 即用,支持流式与工具调用,接入成本极低
  • 轻量可自托管:空载约 40MB、能跑在树莓派,单用户本地优先,部署门槛低

局限

  • 天花板低:免费档最多到 Llama 3.3 70B / GLM-4.5 / Gemini 2.5 Pro 一级,拿不到前沿模型,难题仍需付费 API
  • 智能度随当日高配额度耗尽而下降,UTC 午夜才重置;不同 provider 延迟差异大,体验不稳定
  • 本质是叠加免费额度,可持续性受各家政策影响(README 自述 HF/Moonshot/MiniMax 已被移除/转付费)
  • 合规仍是灰色地带:尽管做了 ToS 审查,部分 provider 标注 ⚠️ 谨慎甚至 ❌ 避免(如 Cohere),最终责任在使用者
  • 刻意窄范围:不支持 embeddings/图像/音频/视觉/n>1/多租户,单用户本地用、不可暴露公网
来源:README Limitations/ToS review/Not yet supported/Disclaimer

最新版本

仓库无正式 GitHub Release,以主分支持续维护,提交活跃(最近 push 2026-05-22)。模型目录随免费额度变动用 re-seed 脚本更新,README 记录了 2026-05 的 ToS 复审与已移除/调整的 provider(HF、Moonshot、MiniMax)。

来源:GitHub 无 releases;pushed_at 2026-05-22;README ToS review 更新说明

总结评价

FreeLLMAPI 和市面上一堆「免费薅 AI」项目最大的不同是诚实:它把叠加免费额度能拿到什么、拿不到什么、以及各家 ToS 的风险都摊开讲,工程上也把路由、限额、加密、健康检查做得相当扎实,单用户本地、能跑树莓派的定位很克制。作为个人实验/原型的本地聚合代理,它是同类里更靠谱、更值得用的一个。但要守住它自己划的边界:拿不到前沿模型、智能度随额度波动、无 SLA、合规责任自负,真要上线请换付费 API。把它当「个人玩具级推理底座」用很合适,别当生产用。

来源:综合 README 定位/限制/ToS、tree 工程结构的事实判断
透明度声明
本页内容由 AI(大语言模型)基于以下公开材料自动生成:GitHub README、代码目录结构、依赖文件、Release 信息。 分析时间: 2026-05-22 18:06. 质量评分: 100/100.

数据来源:README、GitHub API、依赖文件