用途
use-freellmapi 指导用户把一个项目或编程智能体接到 FreeLLMAPI 上。FreeLLMAPI 是一个本地代理,把约 30 家 LLM 提供商的免费额度聚合到单一端点后面;代理内置路由器,按请求挑选可用模型,并在某模型被限流时自动故障转移。官方描述称其覆盖约 251 个模型家族 / 358 个端点、约每月 40 亿 token。
主要能力
- OpenAI 兼容:聊天、流式、工具调用、视觉、嵌入均走同一端点,现有 OpenAI 客户端库无需改动。
- 原生协议:同时支持 Anthropic Messages API(/v1/messages,Claude Code 与 Anthropic SDK)、Gemini API(/v1beta,Gemini CLI)和可选的 Ollama 接口(/api/*,Zed、JetBrains AI)。
- 模型选择:模型值可用 "auto" 让路由器自动选型并在失败时切换;"auto:fast" / "auto:smart" / "auto:reliable" / "auto:<profile-name>" 按请求临时调整策略;也可固定具体模型,或用 "fusion" 将一组模型融合为一个回答。
- 多客户端配置:代理提供配置生成器,可读取实时模型目录、合并现有配置并先写带时间戳的备份(如 npx freellmapi setup-claude)。
- 仪表盘:包含 Models、Playground、Keys、Agents、Analytics、Premium 等页面;支持每客户端密钥(sk-cp-…)、按密钥的模型范围与代理覆盖、命名路由配置、自动更新检查,界面支持 60 种语言。
- 分析:p50/p95 延迟、首 token 时间、成功率、估算节省、固定模型命中率,以及逐请求故障转移轨迹。
- 可选能力:提示压缩(默认关闭)、响应缓存、/mcp 服务器等。
使用方式
- 启动代理:先探测 http://localhost:3001/api/ping。若未运行,需经用户明确同意后执行官方安装脚本(需 Docker):curl -fsSL https://freellmapi.co/install.sh | bash。该脚本创建 ~/freellmapi、生成加密密钥、拉取镜像并在 3001 端口启动容器。也可使用桌面应用或源码安装。
- 获取密钥并启用提供商:优先在环境变量、项目 .env、同类项目或智能体记忆中查找已有密钥,只读取名称、不回显值;新密钥可在仪表盘 Keys 页或容器日志中获取。全新代理尚无提供商密钥,需在浏览器仪表盘启用至少一个提供商:无密钥快速验证可用 Kilo :free、OVH 或 AI Horde;正式使用可在 Keys 页添加各提供商的免费密钥并调整故障转移链。
- 区分目标:若是编程智能体/CLI,使用代理自带生成器改写配置(先 --dry-run 查看差异,应用时自动备份);若是应用代码,先检索项目现有的 LLM 客户端、库与 base_url/api_key 来源,再按对应技术栈(OpenAI Python/Node、LangChain、LlamaIndex、Vercel AI SDK、Continue、curl、Anthropic SDK 等)改写。
- 可逆改写:用环境变量驱动 base URL、密钥和模型,并把原提供商配置注释保留在其上方,便于切换;同步更新 .env.example;确认真实密钥不会被提交到 git。
- 验证:先直接请求 /v1/chat/completions(model 为 "auto"),正常响应为 200 且带 X-Routed-Via 头,再用项目自身代码路径验证。常见错误:401 为密钥错误,4xx 无模型为未启用提供商,429 为限流(可增加提供商密钥),连接被拒为端口或进程问题。
适用场景
适合希望在原型阶段免费调用真实模型的开发项目,以及需要统一接入多种免费模型、并保留切回付费提供商能力的编程智能体工作流。
限制
不支持内容审核(moderation)、n > 1、多租户认证;/v1/responses 与 fusion 的图像输入仍缺失。免费安装使用 30 天目录快照,新模型缺失或免费额度变化多为目录滞后。提示压缩默认关闭。若 /api/ping 有响应但仪表盘异常,可能是宿主机 npm run dev 占用了 3001 端口,应先检查端口占用,不要用 docker compose down -v 重置以免破坏密钥。