# freellmapiPro
**Repository Path**: web/freellmapi-pro
## Basic Information
- **Project Name**: freellmapiPro
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MIT
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No
## Statistics
- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-05-07
- **Last Updated**: 2026-05-12
## Categories & Tags
**Categories**: Uncategorized
**Tags**: None
## README
# FreeLLMAPI-Pro
**一个 OpenAI 兼容的端点。十四个免费 LLM 提供商。每月约 13 亿+ token。**
**改自原开源项目:** [https://github.com/tashfeenahmed/freellmapi.git](https://github.com/tashfeenahmed/freellmapi.git)
将 Google、Groq、Cerebras、SambaNova、NVIDIA、Mistral、OpenRouter、GitHub Models、Hugging Face、Cohere、Cloudflare、智谱、Moonshot（Kimi）和 MiniMax 的免费层聚合到一个 `/v1/chat/completions` 端点后面。密钥加密存储。路由器为每个请求选择最佳可用模型，当某个提供商被限流时自动故障转移到下一个，并跟踪每个密钥的使用情况，确保您保持在每个免费层限额内。
[](https://github.com/tashfeenahmed/freellmapi/actions/workflows/ci.yml)
[](./LICENSE)
[](#contributing)
---
## 目录
- [为什么需要这个项目](#为什么需要这个项目)
- [支持的提供商](#支持的提供商)
- [功能特性](#功能特性)
- [自定义 API 支持](#自定义-api支持)
- [暂不支持的功能](#暂不支持的功能)
- [快速开始](#快速开始)
- [使用 API](#使用-api)
- [截图](#截图)
- [工作原理](#工作原理)
- [限制](#限制)
- [贡献](#贡献)
- [服务条款审查](#服务条款审查)
- [免责声明](#免责声明)
## 为什么需要这个项目
每个严肃的 AI 实验室现在都提供免费层——每月几百万 token，每天几千次请求。单独使用时，每个免费层都只是个玩具。但将它们堆叠在一起，总共可以达到大约 **每月 13 亿 token** 的推理能力，涵盖从小型快速模型到功能强大的模型等数十种模型。
问题在于手动堆叠它们非常痛苦：十四个不同的 SDK、十四个不同的速率限制、十四个可能失败的地方。FreeLLMAPI 将这些简化为一个 OpenAI 兼容的端点。将任何 OpenAI 客户端库指向您的本地服务器，它会透明地路由到您添加了密钥的任何提供商。
## 支持的提供商
## 功能特性
- **OpenAI 兼容** — `POST /v1/chat/completions` 和 `GET /v1/models` 可与官方 OpenAI SDK 以及任何 OpenAI 兼容客户端（LangChain、LlamaIndex、Continue、Hermes 等）一起使用。只需更改 `base_url`。
- **流式和非流式** — 当 `stream: true` 时使用 Server-Sent Events，否则返回 JSON 响应。每个提供商适配器都实现了这两种模式。
- **工具调用** — OpenAI 风格的 `tools` / `tool_choice` 请求会被传递，assistant 的 `tool_calls` + `tool` 角色的后续消息会跨提供商往返。
- **自动故障转移** — 如果所选提供商返回 429、5xx 或超时，路由器会跳过它，将密钥置于短暂冷却状态，并在回退链中的下一个模型上重试（最多 20 次尝试）。
- **每密钥速率跟踪** — 每个 `(平台, 模型, 密钥)` 的 RPM、RPD、TPM 和 TPD 计数器，因此路由器始终选择处于限额内的密钥。
- **粘性会话** — 多轮对话在 30 分钟内保持与同一模型对话，以避免中途切换模型导致的幻觉激增。
- **加密密钥存储** — API 密钥在存入 SQLite 之前使用 AES-256-GCM 加密；解密仅在请求前在内存中进行。
- **统一 API 密钥** — 客户端使用单个 `freellmapi-…` bearer token 认证到您的代理。您永远不会向上游提供商暴露密钥。
- **健康检查** — 定期探测将密钥标记为 `healthy`、`rate_limited`、`invalid` 或 `error`，因此路由器会自动跳过失效的密钥。
- **管理仪表板** — React + Vite UI 用于管理密钥、重新排序回退链、查看分析和在 playground 中运行提示。支持深色模式。
- **分析** — 每请求日志记录，包含延迟、token 计数、成功率和每个提供商的细分。
- **部署到树莓派** — 在树莓派 4 上通过 PM2 在 nginx 后面愉快运行。空闲时约 40 MB RSS。
- **管理密码保护** — 可选的管理密码（通过 `.env` 中的 `ADMIN_PASSWORD` 设置）保护仪表板。API 请求不受影响。
- **错误日志** — 可选的错误日志记录（通过 `.env` 中的 `ERROR_LOGGING=true` 启用）。
### 新增功能 (Pro)
- **管理平台密码验证** — 为管理仪表板添加密码保护，防止未授权访问。
- **兼容 OpenClaw 调用** — 支持 OpenClaw 调用，实现无缝集成。
- **新增通用 OpenAPI 模型添加** — 通过通用 OpenAPI 端点添加自定义 OpenAI 兼容模型。
- **直接获取所有可用模型** — 从 `/v1/models` 端点直接获取所有可用模型。
- **一键校验所有模型是否可用** — 一次性验证所有模型是否正常工作。
## 自定义 API 支持
FreeLLMAPI 支持添加自定义 OpenAI 兼容的 API 端点。这允许您：
1. **连接到任何 OpenAI 兼容的 API** — 添加您自己的 API 端点和自定义 URL
2. **与任何模型一起使用** — 自定义 API 密钥可用于访问目录中的任何模型
3. **扩展到支持的提供商之外** — 连接到未在支持提供商列表中列出的 API
### 添加自定义 API 密钥
1. 转到仪表板中的 **Keys** 页面
2. 从平台下拉菜单中选择 **Custom OpenAI-compatible API**
3. 输入您的 API 密钥和 API 基础 URL（例如 `https://api.example.com/v1`）
4. 点击 **Add key**
自定义 API 密钥具有优先级，可用于访问回退链中的任何模型。当有自定义密钥可用时，它将优先于平台特定的密钥使用。
## 暂不支持的功能
范围故意收窄。如果某个功能不在此列表中且不在下面，请认为它尚未实现。
- **嵌入** (`/v1/embeddings`)
- **图像生成** (`/v1/images/*`)
- **音频/语音** (`/v1/audio/*`)
- **视觉/多模态输入** — 消息内容仅限文本
- **传统补全** (`/v1/completions`) — 仅实现了聊天端点
- **内容审核** (`/v1/moderations`)
- **`n > 1`**（每个请求多个补全）
- **每用户计费/多租户认证** — 设计为单用户
添加任何这些功能的 PR 非常受欢迎。请参阅 [贡献](#贡献)。
## 快速开始
**前提条件：** Node.js 20+，npm。
```bash
git clone https://gitee.com/web/freellmapi-pro.git
cd freellmapi
npm install
# 更新
git pull
# 生成用于密钥存储的加密密钥
cp .env.example .env
echo "ENCRYPTION_KEY=$(node -e "console.log(require('crypto').randomBytes(32).toString('hex'))")" >> .env
# 一起启动服务器和仪表板
npm run dev
```
打开 http://localhost:5173（Vite 开发 UI），在 **Keys** 页面添加您的提供商密钥，按喜好重新排序 **Fallback Chain**，并从 **Keys** 页面头部获取您的统一 API 密钥。这个统一密钥就是您要指向 OpenAI SDK 的密钥。
生产构建：
```bash
npm run build
node server/dist/index.js # 服务器和仪表板都在 :3001 上提供服务
```
## 使用 API
任何 OpenAI 兼容的客户端都可以使用。示例：
**Python**
```python
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:3001/v1",
api_key="freellmapi-your-unified-key",
)
resp = client.chat.completions.create(
model="auto", # 让路由器选择；或指定例如 "gemini-2.5-flash"
messages=[{"role": "user", "content": "用一句话概括罗马的衰落。"}],
)
print(resp.choices[0].message.content)
print("路由通过:", resp.headers.get("x-routed-via"))
```
**curl**
```bash
curl http://localhost:3001/v1/chat/completions \
-H "Authorization: Bearer freellmapi-your-unified-key" \
-H "Content-Type: application/json" \
-d '{
"model": "auto",
"messages": [{"role": "user", "content": "hi"}]
}'
```
**流式传输**
```python
stream = client.chat.completions.create(
model="auto",
messages=[{"role": "user", "content": "给我一首关于 SQLite 的俳句。"}],
stream=True,
)
for chunk in stream:
print(chunk.choices[0].delta.content or "", end="", flush=True)
```
**工具调用**
传递 OpenAI 风格的 `tools` 和 `tool_choice`；assistant 响应通过代理往返，与 OpenAI API 完全相同。多步骤流程（assistant `tool_calls` → `tool` 角色后续 → 最终答案）可以在路由器可访问的每个提供商上工作。
```python
tools = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "获取城市的当前天气。",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
# 1. 模型请求工具调用
first = client.chat.completions.create(
model="auto",
messages=[{"role": "user", "content": "卡拉奇的天气怎么样？"}],
tools=tools,
tool_choice="required",
)
call = first.choices[0].message.tool_calls[0]
# 2. 您执行工具，将结果反馈回去
final = client.chat.completions.create(
model="auto",
messages=[
{"role": "user", "content": "卡拉奇的天气怎么样？"},
first.choices[0].message,
{"role": "tool", "tool_call_id": call.id, "content": '{"temp_c": 32, "cond": "sunny"}'},
],
tools=tools,
)
print(final.choices[0].message.content)
```
也支持 `stream=True` — 您会得到 `delta.tool_calls` 块，然后是 `finish_reason: "tool_calls"` 结束。在底层，OpenAI 兼容提供商（Groq、Cerebras、SambaNova、Mistral、OpenRouter、GitHub Models、HuggingFace、Cloudflare、Cohere compat）的请求直接传递；Gemini 请求被转换为 Google 的 `functionDeclarations` / `functionResponse` 格式，响应再转换回来。
每个响应都带有 `X-Routed-Via: /` 头，因此您可以看到哪个提供商实际服务了每个调用。如果请求在提供商之间发生故障转移，您还会看到 `X-Fallback-Attempts: N`。
## 截图
### Keys
管理提供商凭证并获取您的应用连接的统一 API 密钥。每个密钥显示状态点和上次健康检查的时间。
### Playground
通过路由器发送聊天补全，查看哪个提供商服务了它，模型 ID 和延迟直接显示在消息上。
### Analytics
请求量、成功率、输入输出 token、平均延迟以及 24h / 7d / 30d 窗口内每个提供商的细分。
## 工作原理
```
┌──────────────────┐ Bearer freellmapi-… ┌─────────────────────────┐
│ OpenAI SDK / │ ──────────────────────▶ │ Express proxy (:3001) │
│ curl / any │ ◀────────────────────── │ /v1/chat/completions │
│ OpenAI client │ streamed tokens └────────────┬────────────┘
└──────────────────┘ │
▼
┌────────────────────────────────────────────────┐
│ Router │
│ 1. 选择优先级最高的模型，要求： │
│ (a) 有健康的密钥，并且 │
│ (b) 在所有速率限制之下。 │
│ 2. 解密密钥，调用提供商 SDK。 │
│ 3. 如果遇到 429/5xx → 冷却 + 重试下一个模型。 │
└────────────────────────────────────────────────┘
│
┌──────────────┬────────────┬──────────┴─────────┬─────────────┬──────────┐
▼ ▼ ▼ ▼ ▼ ▼
Google Groq Cerebras OpenRouter HF …10 more
```
- **Router** (`server/src/services/router.ts`) — 为每个请求选择模型。
- **速率限制分类账** (`server/src/services/ratelimit.ts`) — 内存中的 RPM/RPD/TPM/TPD 计数器，由 SQLite 支持，429 时有冷却机制。
- **提供商适配器** (`server/src/providers/*.ts`) — 每个提供商一个文件，实现 `Provider` 基类：`chatCompletion()` 和 `streamChatCompletion()`。
- **健康服务** (`server/src/services/health.ts`) — 定期探测保持密钥状态新鲜。
- **仪表板** (`client/`) — React + Vite + shadcn/ui 管理界面。
- **存储** — SQLite (`better-sqlite3`)，密钥使用 AES-256-GCM 信封加密。
## 限制
堆叠免费层有实际的权衡。请诚实地看待它们：
- **没有前沿模型。** 免费层目录最高达到 Llama 3.3 70B、GLM-4.5、Qwen 3 Coder 和 Gemini 2.5 Pro。您不会通过这个获得 GPT-5 或 Claude Opus 级别的推理能力。对于难题，请付费使用真正的 API。
- **智能程度随时间下降。** 您排名最高的模型（通常是 Gemini 2.5 Pro、通过 GitHub Models 的 GPT-4o）每日限额最低。一旦达到限额，路由器会在您的优先级链中降级到更小/更弱的模型。预计端点的有效智能程度在每天晚些时候会下降——然后在 UTC 午夜重置。
- **延迟高度可变。** Cerebras 和 Groq 非常快；其他则不然。您得到的是可用的那个。
- **免费层可能随时更改。** 提供商定期收紧、放宽或取消免费层。发生这种情况时，您会看到 429 或认证错误，直到您更新目录。重新播种脚本位于 `server/src/scripts/` 中。
- **没有 SLA，根据定义。** 如果您需要可靠性，请使用有合同的付费提供商。
- **本地优先。** 没有多租户认证。自己运行；不要暴露到互联网。
## 贡献
非常欢迎贡献者！好的首次 PR：
- **添加提供商** — 复制 `server/src/providers/openai-compat.ts` 作为模板，将其连接到 `server/src/providers/index.ts`，在 `server/src/db/index.ts` 中播种其模型，在 `server/src/__tests__/providers/` 中添加测试。
- **添加端点** — 嵌入、图像、审核。提供商基类可以添加新方法；适配器声明它们支持的方法。
- **改进路由器** — 成本感知路由（最便宜-健康-最快权衡）、更好的延迟加权优先级、区域固定。
- **仪表板改进** — 分析页面上的图表、密钥轮换 UX、从 `.env` 批量导入密钥。
- **文档** — 更多示例、Go/Rust 等客户端库代码片段、Docker 或 Fly 的部署方案。
**开发循环：**
```bash
npm install
npm run dev # 服务器在 :3001，仪表板在 :5173，都有 HMR
npm test # vitest — 提供商、路由、路由器、速率限制共 75 个测试
```
PR 应包含测试，保持现有测试套件通过，并符合仓库中已有的 `.editorconfig` / tsconfig 默认值。问题和讨论是开放的。
### 贡献者
感谢所有帮助改进 FreeLLMAPI 的人：
- [@moaaz12-web](https://github.com/moaaz12-web) — 跨提供商的工具调用支持 (#3)
## 服务条款审查
针对每个提供商的 ToS（2026 年 4 月）审查了自托管、单用户、个人使用设置。摘要：
| 提供商 | 结论 | 备注 |
|---|---|---|
| Google Gemini | ✅ 可能 OK | 无不利条款；个人使用代理未被禁止。 |
| Groq | ✅ 可能 OK | 明确允许集成到"客户应用程序"中。 |
| Cerebras | ✅ 可能 OK | 允许；不要转售密钥。 |
| Mistral | ✅ 可能 OK | API 允许个人/内部商业使用。 |
| OpenRouter | ✅ 可能 OK | 仅限私人使用；不要公开暴露代理。 |
| Hugging Face | ✅ 可能 OK | BYO-key 代理是文档化的模式。 |
| 智谱 | ✅ 可能 OK | 明确的"个人、非商业研究"例外。 |
| Moonshot / Kimi | ✅ 可能 OK | 竞争产品条款广泛但不针对单用户代理。 |
| SambaNova | ⚠️ 模糊 | 公开条款对 API 保持沉默。 |
| MiniMax | ⚠️ 模糊 | 公开条款沉默。 |
| Cloudflare Workers AI | ⚠️ 模糊 | 未发现不利条款。 |
| NVIDIA NIM | ⚠️ 谨慎 | 免费层是"仅评估，非生产"。 |
| GitHub Models | ⚠️ 谨慎 | 免费层范围为"实验"。 |
| Cohere | ❌ 避免 | 试用 ToS §14 明确禁止个人/家庭使用。 |
让大多数提供商满意的经验法则：**每个提供商一个账户**、**不转售**、**不与其他人共享您的端点**、**不要将免费层作为付费生产后端滥用**。这是信息性的，不是法律建议——阅读每个提供商的 ToS 并自行决定。
## 免责声明
**本项目仅供个人实验和学习，不适用于生产环境。** 免费层存在是为了让开发人员可以针对它们进行原型设计；它们不是稳定的、受支持的推理基础架构，不应被视为这样的基础架构。如果您在 FreeLLMAPI 之上构建了真正的东西，请在发布前换入付费 API。您与每个上游提供商的关系受您创建账户时接受的条款管辖——当流量通过此项目代理时，这些条款仍然适用，您有责任遵守它们。
## 许可证
[MIT](./LICENSE)