FreeLLMAPI 使用教程：16 家免费大模型 API 聚合成一个端点，每月 17 亿 Token

小新软件平替发表于2026-06-24

你有没有算过，自己在各家大模型免费额度上浪费了多少 Token？Google Gemini 每天几百万、Groq 每分钟 30 次请求、Cerebras 送你 Qwen3 235B 的推理额度……单独用每一家都像玩具，但叠在一起，每月能凑出大约 17 亿 Token 的免费推理能力。

问题是——手动管理十几家厂商的 SDK、API Key、速率限制和故障切换，比写代码还累。

这就是 FreeLLMAPI 要解决的事。它把 16 家 LLM 厂商的免费额度聚合到一个 OpenAI 兼容的 /v1/chat/completions 端点后面，你只需要改一个 base_url，就能让任何 OpenAI 兼容的客户端自动在这些免费额度之间智能路由和故障转移。

FreeLLMAPI 是什么？ FreeLLMAPI 是由 tashfeenahmed 开发的开源 OpenAI 兼容代理服务器，将 16 家 LLM 提供商的免费额度聚合到单一端点，支持智能路由、自动故障转移和 AES-256-GCM 加密密钥存储。采用 MIT 许可证。

关键数据：

🌟 GitHub Stars: 11,998+（仓库链接）
🍴 Forks: 1,863+
📦 当前版本：v0.4.1
⚖️ 许可证：MIT
🔧 核心特性：16 家 LLM 提供商免费额度聚合，每月约 17 亿 Token
🧠 核心特性：智能路由 + 自动故障转移（最多 20 次重试）
🔒 核心特性：AES-256-GCM 加密密钥存储
🖥️ 核心特性：管理后台（React + Vite）+ 桌面应用（macOS / Windows）
🌐 核心特性：支持 OpenAI / Anthropic / Responses API 三种协议
💰 核心特性：免费版永久可用，Premium 版 $19/年获取实时模型目录更新

前提条件

在开始使用 FreeLLMAPI 之前，你需要准备：

Docker（推荐方式）或 **Node.js 20+**（本地开发方式）
至少一个 LLM 提供商的 API Key（Google、Groq 等均免费注册）
任意 OpenAI 兼容的客户端（Python openai 库、curl、LangChain、Continue 等）

💡 提示：不需要所有 16 家的 Key。有 2-3 家就能获得不错的故障转移效果，后续随时在管理后台添加更多。

概述

本教程将带你从零开始搭建 FreeLLMAPI，包括：

一键安装和配置
添加提供商密钥
使用 API 发送第一个请求
管理后台的使用
桌面应用安装
与现有 AI 工具集成

详细步骤

第一步：一键安装

FreeLLMAPI 提供了最简单的一行命令安装方式，自动完成目录创建、密钥生成、镜像拉取和容器启动：

1	curl -fsSL https://freellmapi.co/install.sh \| bash

这条命令会：

在 ~/freellmapi 创建工作目录
自动生成 AES-256 加密密钥
拉取最新的 Docker 镜像
启动容器并绑定到 localhost:3001

⚠️ 安全提示：安装脚本会自动保存 .env 文件中的加密密钥。重新运行脚本是安全的——你原有的 .env 和密钥会被保留，容器只会更新到最新版本。

如果你想先看脚本内容再执行，可以先访问 install.sh 阅读源码。

Windows 用户：最简单的方式是从 GitHub Releases 下载 .exe 桌面安装包。

第二步：手动安装（可选）

如果你更喜欢手动控制，可以使用 Docker Compose：

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

# 生成加密密钥
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env

docker compose up -d

环境变量说明：

变量	说明	默认值
`ENCRYPTION_KEY`	AES-256-GCM 加密密钥（必填）	无
`PORT`	服务端口	3001
`HOST_BIND`	绑定地址（`0.0.0.0` 可局域网访问）	127.0.0.1
`FREELLMAPI_CONTEXT_HANDOFF`	模型切换时注入上下文	空（关闭）
`DEV_MODE`	开发模式	false

使用 npm 本地直接启动（推荐非 Docker 开发者）

如果不想使用 Docker，可以直接使用 Node.js 运行项目。以下步骤已在本地验证可用，命令请保持原样：

git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

# 安装依赖
npm install

# 创建 .env 文件（必须有 ENCRYPTION_KEY）
cp .env.example .env

# 生成加密密钥并写入 .env
node -e '
  const key = require("crypto").randomBytes(32).toString("hex");
  console.log("ENCRYPTION_KEY=" + key);
' >> .env

然后根据你的需求选择运行模式：

开发模式（带热重载）： npm run dev
生产模式（构建后运行）：
  npm run build
  node server/dist/index.js

服务默认监听 http://localhost:3001(如果控制台打印的是其他端口直接使用该端口即可)，在浏览器打开即可进行密钥设置和管理。

第三步：添加提供商密钥

打开浏览器访问 http://localhost:3001，首次访问需要注册一个管理员账号（邮箱 + 密码）。

登录后进入 Keys 页面，逐个添加你的 API Key：

推荐优先添加的免费提供商：

提供商	免费额度	注册难度	推荐模型
Google Gemini	每天数百万 Token	低	Gemini 2.5 Flash
Groq	每分钟 30 请求	低	Llama 3.3, Llama 4
Cerebras	高速推理	低	Qwen3 235B
Mistral	每月数百万 Token	低	Large 3, Codestral
OpenRouter	21 个免费模型	低	多种选择
GitHub Models	免费评估额度	低	GPT-4.1, GPT-4o
Cloudflare Workers AI	免费额度	中	Kimi K2, GLM-4.7
HuggingFace	免费推理 API	低	DeepSeek V4, Qwen3

添加密钥后，进入 Fallback Chain 页面调整优先级顺序。排在前面的提供商优先被使用，当它返回 429（速率限制）或 5xx 错误时，自动切换到下一个。

💡 提示：不需要一次添加所有提供商。先加 2-3 家，后续随时在管理后台补充。密钥在存储前会被 AES-256-GCM 加密。

第四步：获取统一 API Key

在 Keys 页面的顶部，你会看到一个 freellmapi-xxx 格式的统一 API Key。这个 Key 是你所有应用使用的唯一凭证——上游提供商的原始 Key 不会暴露给你的客户端。

复制这个 Key，接下来的所有请求都用它。

第五步：发送第一个请求

Python（推荐）：

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:3001/v1",
    api_key="freellmapi-你的统一Key",
)

resp = client.chat.completions.create(
    model="auto",  # 让路由器自动选择最佳模型
    messages=[{"role": "user", "content": "用一句话概括罗马帝国的衰落"}],
)
print(resp.choices[0].message.content)
print("路由到:", resp.headers.get("x-routed-via"))

curl：

curl http://localhost:3001/v1/chat/completions \
  -H "Authorization: Bearer freellmapi-你的统一Key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "auto",
    "messages": [{"role": "user", "content": "hi"}]
  }'

model 参数说明：

值	行为
`auto`	路由器自动选择最佳可用模型
`gemini-2.5-flash`	指定具体模型（路由器在提供该模型的厂商间故障转移）
`gpt-4.1`	指定具体模型

💡 提示：响应头 x-routed-via 会告诉你这次请求被路由到了哪个提供商，方便调试。

第六步：高级功能

流式输出：设置 stream: true 即可获得 SSE 流式响应，所有提供商适配器都支持。

工具调用（Tool Calling）：OpenAI 风格的 tools / tool_choice 请求会被透传，支持跨提供商的 tool_calls 消息往返。

Embeddings：/v1/embeddings 支持家庭路由——故障转移只在提供同一模型的厂商之间发生，不会跨模型切换（不同模型的向量不兼容）。

图片生成和 TTS：/v1/images/generations 和 /v1/audio/speech 也支持跨提供商路由，在管理后台的 Models → Image / Audio 标签页中管理。

Sticky Sessions：多轮对话会在 30 分钟内保持使用同一模型，避免中途切换模型导致的幻觉问题。

Context Handoff：可选功能，启用 FREELLMAPI_CONTEXT_HANDOFF=on_model_switch 后，当会话故障转移到不同模型时，会注入一条简短的系统消息让新模型了解上下文。

第七步：管理后台

FreeLLMAPI 内置了一个 React + Vite 的管理后台，功能包括：

Keys 管理：添加、删除、排序提供商密钥
Fallback Chain：拖拽调整故障转移优先级
Analytics：查看请求日志、延迟、Token 用量、成功率和提供商分布
Playground：直接在后台测试提示词
Models 浏览：查看所有可用模型，包括图片和音频模型
暗色模式：支持暗色主题

管理后台支持 6 种语言：English、中文（简体）、Français、Español、Português (Brasil)、Italiano。首次加载时自动检测浏览器语言。

第八步：桌面应用

FreeLLMAPI 还提供了原生桌面菜单栏应用，整个路由器和后台在本地运行：

macOS：从 Releases 下载 .dmg
Windows：从 Releases 下载 .exe 安装包

也可以从源码构建：

1
2
3

npm install
npm run desktop:dist        # macOS .dmg
npm run desktop:dist:win    # Windows .exe

💡 提示：本地构建的应用未签名，Windows SmartScreen 可能会弹出警告（点击”更多信息”→”仍要运行”即可），macOS 不会触发 Gatekeeper 警告。

第九步：接入你的 AI 工具

FreeLLMAPI 兼容所有支持 OpenAI API 的客户端。以下是在主流 AI 工具中的接入方式：

通用方式：将 base_url 改为 http://localhost:3001/v1，api_key 改为你的统一 Key。

Claude Code / Anthropic 客户端：

FreeLLMAPI 支持 Anthropic Messages API（/v1/messages），Claude Code 和官方 Anthropic SDK 可以直接使用：

1 2	export ANTHROPIC_BASE_URL=http://localhost:3001 export ANTHROPIC_API_KEY=freellmapi-你的统一Key

Claude 模型族（opus / sonnet / haiku / default）会自动映射到 auto 或你在 Keys 页面指定的模型。

Codex CLI：

FreeLLMAPI 支持 Responses API（/v1/responses），当前版本的 Codex CLI 所需的协议格式完全兼容：

1 2	export OPENAI_BASE_URL=http://localhost:3001/v1 export OPENAI_API_KEY=freellmapi-你的统一Key

LangChain / LlamaIndex：

1 2	from openai import OpenAI client = OpenAI(base_url="http://localhost:3001/v1", api_key="freellmapi-...")

**Continue (VS Code)**：

在 Continue 设置中将 apiBase 改为 http://localhost:3001/v1。

与同类工具的对比

特性	FreeLLMAPI	LiteLLM	OpenRouter
部署方式	自托管	自托管 / 云	云服务
免费使用	✅ 完全免费	✅ 开源版免费	部分免费模型
聚合厂商数	16+	100+	聚合多个提供商
免费额度聚合	✅ 核心功能	❌ 需手动配置	❌ 按量付费为主
Anthropic API	✅ 原生支持	✅	✅
Responses API	✅	❌	❌
桌面应用	✅	❌	❌
加密密钥存储	✅ AES-256-GCM	❌	N/A（云托管）
管理后台	✅ 内置	✅	✅
许可证	MIT	MIT	专有

常见问题（FAQ）

Q: FreeLLMAPI 怎么安装？
A: 最简单的方式是使用 Docker 一键安装脚本：curl -fsSL https://freellmapi.co/install.sh | bash。也可以手动 clone 仓库后用 docker compose up -d 启动。Windows 用户可以直接下载 .exe 安装包。

Q: FreeLLMAPI 支持哪些大模型提供商？
A: 目前支持 16 家：Google Gemini、Groq、Cerebras、OpenCode Zen、Mistral、OpenRouter、GitHub Models、Cloudflare、Cohere、Z.ai（智谱）、NVIDIA、HuggingFace、Ollama Cloud、Kilo Gateway、Pollinations、LLM7、OVH AI Endpoints。还可以添加任意自定义 OpenAI 兼容端点。

Q: 每月 17 亿 Token 是真的吗？
A: 这是将所有支持的提供商免费额度叠加后的理论上限。实际可用量取决于你注册了多少家提供商、各家的免费政策变化以及你的使用模式。

Q: FreeLLMAPI 和 LiteLLM 有什么区别？
A: FreeLLMAPI 专注于”免费额度聚合”这个核心场景，内置了速率追踪、故障转移和加密存储。LiteLLM 更通用，支持 100+ 提供商但需要手动配置每个提供商的路由逻辑。FreeLLMAPI 还提供桌面应用和原生 Anthropic/Responses API 支持。

Q: API Key 安全吗？
A: 所有提供商的 API Key 在存储前使用 AES-256-GCM 加密，仅在发送请求时在内存中解密。管理后台使用邮箱+密码认证（scrypt 哈希），API 端点使用独立的统一 Key 认证。

Q: 可以在局域网内给多台设备用吗？
A: 可以。启动时设置 HOST_BIND=0.0.0.0 即可在局域网内访问。注意仅在可信网络中使用，因为代理是单用户的。

Q: FreeLLMAPI 的使用教程在哪里？
A: 本文就是 FreeLLMAPI 的完整使用教程和安装指南，涵盖了从安装到接入 AI 工具的全流程。官方文档请访问 freellmapi.co。

进阶技巧

自定义提供商

除了内置的 16 家提供商，你还可以在 Keys 页面添加任意 OpenAI 兼容端点，比如本地的 llama.cpp、LM Studio、vLLM 或远程网关。

Premium 模型目录

免费版使用每月快照的模型目录。升级到 Premium（$19/年或 $49 终身）可以获取每 2-3 天更新的实时模型目录，新免费模型上线后立即可用。在管理后台的 Premium 页面激活。

Docker 运维

# 查看日志
docker compose logs -f freellmapi

# 更新到最新版本
docker compose pull && docker compose up -d

# 数据持久化
# SQLite 数据存储在 freellmapi-data 卷中
# 升级时保留 .env 中的 ENCRYPTION_KEY 和数据卷

请求分析

默认保留 90 天或 100,000 条请求日志（以先到者为准）。在 .env 中设置 REQUEST_ANALYTICS_RETENTION_DAYS=0 或 REQUEST_ANALYTICS_MAX_ROWS=0 可禁用保留限制。

总结

以上就是 FreeLLMAPI 的完整使用教程和安装指南。从一行命令安装到接入 AI 工具，FreeLLMAPI 让你可以零成本地将 16 家大模型厂商的免费额度整合到一起，获得每月约 17 亿 Token 的推理能力。它的智能路由和自动故障转移确保你的应用不会因为某一家提供商的速率限制而中断服务。

如果你正在寻找一个免费的大模型 API 代理方案，或者想最大化利用各家的免费额度，FreeLLMAPI 值得一试。更多详情请访问 GitHub 仓库和官方网站。