MajidAsghariTabrizi/free-best-router

Free Best Router

一个兼容 OpenAI 的端点，可自动查找并将请求路由到最佳的可用免费 AI 模型。

License: MIT
Node >= 22
Tests
PRs welcome

Your App
↓
Free Best Router
↓
┌───────────────┬───────────────┬───────────────┐
│ OpenRouter    │ OpenCode/Zen  │ Other Free    │
│ Free Models   │ Free Models   │ Providers     │
└───────────────┴───────────────┴───────────────┘

这是什么？

Free Best Router 是一个开源、自托管、兼容 OpenAI 的智能路由器，专为免费 AI 模型而设计。你将它指向你拥有 API 密钥的提供商的免费层级（或者完全不使用密钥运行，它会使用无需身份验证的提供商），它会自动：

1. 发现每个提供商提供的所有免费模型
2. 规范化这些目录（不同提供商对模型的描述方式各不相同）
3. 健康检查每个模型，在启动时进行预热探测
4. 评分每个模型的能力、可靠性、延迟和上下文匹配度
5. 排序目录，最佳者优先
6. 路由每个传入请求到当前最佳的健康模型
7. 故障转移当最佳模型触发速率限制、超时或返回完成错误时
8. 冷却不健康的路由，避免同样的故障重复发生
9. 探索采样不足的候选模型，定期轮换，避免优胜者固化

你的应用程序看到的是一个单一的兼容 OpenAI 的端点，它始终能从免费模型中返回尽可能最佳的答案——无需逐提供商配置，无需手动故障转移逻辑，没有意外的速率限制。

为什么？

免费 AI 模型很棒，但也很混乱。它们：

- 不可靠——免费层推理队列会停滞 30–120 秒
- 有速率限制——激进的每分钟限制，且会无预警地变化
- 经常不可用——模型会逐小时地在 429/404/传输错误状态之间循环
- 分散在众多提供商中——OpenRouter、OpenCode/Zen、Groq、Cerebras、Mistral、DeepSeek、本地 Ollama 等等
- 不断变化——每周都有新的免费模型出现；旧的消失
- 难以比较——每个提供商暴露的能力元数据都不同
- 难以集成——每个提供商的 API 契约都略有不同
- 难以手动配置——维护一份可用的免费模型列表是一份全职工作

Free Best Router 将这一团乱麻变成一个稳定的端点。

特性

- ✅ 兼容 OpenAI——可直接替换任何 openai-python / openai-node 客户端
- ✅ 多提供商——OpenRouter、OpenCode/Zen、Groq、Cerebras、Mistral、DeepSeek、本地 Ollama/LM Studio
- ✅ 自动发现 — 每个提供商在启动时都会获取其模型目录
- ✅ 默认仅使用免费模型 — 除非你主动选择，否则付费模型会被排除
- ✅ 能力感知排序 — 编码、推理、工具调用、视觉、长上下文
- ✅ 运行时学习 — 基于成功率的 Wilson 下界，时间衰减惩罚
- ✅ 智能探索 — 定期探测采样不足的健康候选模型
- ✅ 自动回退 — 每个请求最多尝试 4 个模型，墙钟时间有上限
- ✅ 按失败类型冷却 — 指数退避，并按类型设置上限（404 为 1 小时，429 为 8 分钟）
- ✅ 有界失败 — 当模型池为空时返回 502/429 + Retry-After + next_eligible_model
- ✅ 流式传输 — 完整的 SSE 透传，捕获 finish_reason + tool_calls
- ✅ DeepSeek Harness 集成 — 可直接替换的 OpenAI 兼容提供商配置
- ✅ 自托管且隐私优先 — 你的提供商密钥永远不会离开你的机器
- ✅ 零遥测 — 路由器不会向外发送数据

快速开始（60 秒）

1. Install
git clone https://github.com/MajidAsghariTabrizi/free-best-router.git
cd free-best-router
npm install

2. (Optional) Add provider keys — the router works without any keys, but having
at least one OpenRouter key dramatically improves the free model pool.
cp .env.example .env
edit .env and set at least OPENROUTER_API_KEY=

3. Start
npm start

就是这样。你现在已经在 http://127.0.0.1:4098/v1 上运行了一个 OpenAI 兼容的路由器。

Health check
curl http://127.0.0.1:4098/health
→ {"status":"ok","route":"free-best"}

List models (always returns the single route)
curl http://127.0.0.1:4098/v1/models
→ {"object":"list","data":[{"id":"free-best","object":"model","owned_by":"free-router"}]}

Live chat completion
curl -X POST http://127.0.0.1:4098/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "free-best",
"messages": [{"role":"user","content":"Reply with OK"}],
"max_tokens": 8
}'

每次你请求时，路由器都会选择一个不同的模型——这正是它的意义所在。查看响应头中的 x-free-router-model，即可了解它选择了哪一个。

DeepSeek Harness

Free Best Router 作为一流的 OpenAI 兼容提供商与 DeepSeek Harness 集成。将以下内容添加到你的 DSH settings.yaml 中：

llm-pi-ai:
providers:
free-router:
displayName: Free Best Router
api: openai-completions
baseURL: http://127.0.0.1:4098/v1
apiKeyEnv: FREE_ROUTER_API_KEY
models:
- id: free-best
DSH 会像对待任何其他 OpenAI 兼容的提供商一样对待该路由器。在 DSH 的环境变量中设置 FREE_ROUTER_API_KEY=any-value（路由器不会验证入站的 bearer——它使用来自 .env 的自己的提供商密钥）。路由器实际选择的模型记录在 x-free-router-model 响应头中，并保留在上游响应的 model 字段中，因此 DSH 的 responseModel 就是真实的模型 id。

完整示例请参见 examples/deepseek-harness/settings.yaml。

OpenAI 兼容 API

端点

| 方法   | 路径                     | 用途                                                                     |
|--------|--------------------------|-------------------------------------------------------------------------|
| GET  | /health                | 存活探针。返回 {"status":"ok","route":"free-best"}。                   |
| GET  | /v1/models             | OpenAI 兼容的模型列表。返回单个 free-best 路由。                       |
| POST | /v1/chat/completions   | OpenAI 兼容的聊天补全。当 stream: true 时进行流式传输。                |
| GET  | /diagnostics           | 当前胜出者、前 10 名、提供商/模型健康状况、统计信息。JSON 或文本。       |
| POST | /_refresh              | 强制从所有提供商刷新目录。                                               |

响应头（每次补全）

| 响应头                        | 含义                                                                                     |
|------------------------------|------------------------------------------------------------------------------------------|
| x-free-router-model        | 被选中的实际 provider/model id（例如 openrouter/llama-3.3-70b:free）。               |
| x-free-router-route        | 你请求的路由（对于此路由器始终为 free-best）。                                          |
| x-free-router-explored     | 如果此请求作为探索被发送到非现任候选者，则为 true。                                     |
| x-free-router-next-eligible| 在 502/429 时：将最快恢复的模型 id。                                                      |
| Retry-After                | 在 502/429 时：直到至少一个候选者再次健康所需的秒数。                                     |

Python

from openai import OpenAI

client = OpenAI(
base_url="http://127.0.0.1:4098/v1",
api_key="any-value-not-validated",
)

response = client.chat.completions.create(
model="free-best",
messages=[{"role": "user", "content": "What is the capital of France?"}],
)

print(response.choices[0].message.content)
print("picked model:", response._raw_response.headers.get("x-free-router-model"))

JavaScript / TypeScript

import OpenAI from "openai";

const client = new OpenAI({
baseURL: "http://127.0.0.1:4098/v1",
apiKey: "any-value-not-validated",
});

const response = await client.chat.completions.create({
model: "free-best",
messages: [{ role: "user", content: "法国的首都是什么？" }],
});

console.log(response.choices[0].message.content);

流式传输

stream = client.chat.completions.create(
model="free-best",
messages=[{"role": "user", "content": "写一首俳句"}],
stream=True,
)
for chunk in stream:
if chunk.choices[0].delta.content:
print(chunk.choices[0].delta.content, end="")

支持的提供商

| 提供商              | 免费额度             | 是否需要认证  | 备注                                             |
|---------------------|----------------------|---------------|--------------------------------------------------|
| OpenRouter      | 许多 :free 模型    | 是（免费密钥） | 免费前沿级模型的主要来源。                       |
| OpenCode / Zen  | 若干 -free id      | 是（免费密钥） | 需要本地安装（代理位于 127.0.0.1:4097）。      |
| Groq            | Llama 3.1/3.3 免费   | 是（免费密钥） | 延迟极低。                                       |
| Cerebras        | Llama / Qwen 免费    | 是（免费密钥） | 晶圆级芯片，延迟极低。                           |
| Mistral         | Small/Nemo/Codestral | 是（免费密钥） | 欧洲提供商。                                     |
| DeepSeek        | （付费）             | 是（付费密钥） | 已接入，但被仅免费策略排除。                     |
| 本地（Ollama / LM Studio / llama.cpp） | 你自行提供的任意模型 | 否            | 在常见本地端口上自动发现。                       |

添加一个新的 OpenAI 兼容提供商只需在 providers/ 中写一个 30 行的文件。参见 docs/providers.md。

路由算法

DISCOVER → NORMALIZE → FREE FILTER → CAPABILITY FILTER → HEALTH FILTER
→ QUALITY RANK → TASK RANK → SELECT → ATTEMPT → RECORD OUTCOME
↓ on failure
FALLBACK (next candidate)
↓ all candidates bad
502 + Retry-After

总分（mission #11）

total = capability_fit0.25 + agentic_quality0.20 + reliability0.20
+ coding_quality0.15 + context_fit0.08 + tool_quality0.07 + latency0.05

硬性要求（必须全部满足）：free、提供商可达、code_generation、tool_calling；当存在图像时需要 vision；对于仓库级任务需要 long_context。探索比例为 5%（可配置）——5% 的请求会发送给一个非现任的前半部分候选者，该候选者仍需满足所有硬性要求。

完整设计参见 docs/architecture.md。

配置

所有运行时配置都位于 config.json 中。默认值对大多数用户来说都是合理的。常见调整项：

| 参数                              | 默认值  | 作用                                                                    |
|-----------------------------------|---------|-------------------------------------------------------------------------|
| routing.strategy.explorationRate| 0.05  | 探测非当前候选者的请求比例。              |
| routing.fallback.maxDepth       | 4     | 每个请求的最大模型尝试次数。                                     |
| routing.fallback.attemptTimeoutMs| 45000 | 每次尝试的墙钟时间。越低 = 故障转移越快，越高 = 容忍缓慢的上游。 |
| routing.health.warmUpTopN       | 40    | 启动时探测的顶级候选者数量。                             |
| routing.health.maxCooldownSec   | 480   | 默认冷却上限。model_not_found/client_error 为 3600。        |
| server.port                     | 4098  | 绑定端口。使用 FREE_ROUTER_PORT 环境变量覆盖。                        |

诊断

curl http://127.0.0.1:4098/diagnostics | jq

返回当前获胜者、排名前 10 的候选者、每个提供商的健康状态、每个模型的运行时统计信息以及全局计数器。使用 Accept: text/plain 获取人类可读的仪表板。

故障排除

未选择任何免费模型。
- 检查 /diagnostics 中的 providerHealth 映射。未设置 API 密钥的提供商将显示为 NOT_CONFIGURED。
- 在 .env 中至少设置一个密钥：OPENROUTER_API_KEY、GROQ_API_KEY、CEREBRAS_API_KEY、MISTRAL_API_KEY 或 OPENCODE_ZEN_API_KEY。
- 无需身份验证的免费模型并不存在（每个免费层级仍然需要一个免费账户）。至少需要一个提供商密钥。

每个请求都返回 429 / NO_FREE_AGENT_MODEL_AVAILABLE。
- 所有免费候选者都受到速率限制或处于冷却状态。路由器会返回 Retry-After 头——请等待该时长。
- 添加更多提供商密钥以扩大池。
- 如果你希望当前候选者占据更多主导地位，请降低 routing.strategy.explorationRate。

首次请求非常慢（5–30 秒）。
- 对于免费模型的首次调用来说，这是正常的。免费层级会排队推理并冷加载权重。路由器本身很快。
- 将客户端超时增加到 120 秒以上。路由器专为免费层级延迟而设计。

Cannot find module '../providers/index.mjs'
- 你从仓库根目录之外运行了测试。请从项目根目录运行 npm test。

EADDRINUSE: address already in use :::4098
- 另一个进程占用了端口 4098。设置 FREE_ROUTER_PORT=4099（或其他空闲端口）并启动路由器。

文档

- docs/architecture.md — 完整系统设计、评分数学、状态机
- docs/providers.md — 如何添加新的提供商适配器
- SECURITY.md — 漏洞报告、安全模型
- CONTRIBUTING.md — 贡献工作流、开发设置、代码风格
- CHANGELOG.md — 发布历史

示例

- examples/curl/ — 原始 curl 请求
- examples/openai-python/ — Python openai SDK
- examples/javascript/ — Node.js openai SDK
- examples/deepseek-harness/ — DSH settings.yaml + .env

路线图

已实现（v0.1.0）
- 上述功能特性部分中的所有功能。

计划中
- 持久化的磁盘状态（重启后仍能保留，不会丢失冷却状态）
- 按提供商配置的 HTTP 代理支持（目前仅支持环境变量）
- gpt-oss、o3、o4 系列检测器
- 自适应能力推断（引导 → 观测）
- 可选的 Prometheus /metrics 端点

想法（未承诺）
- 托管版本（将作为独立产品）
- 社区提供商注册表
- 跨付费层级的成本感知路由
- 排名权重的 A/B 测试

贡献

我们欢迎提供商适配器、排名实验、测试和文档。请从 CONTRIBUTING.md 开始。最简单的“适合首次贡献”的任务是向 providers/ 中的 MISTRAL_FREE_IDS / GROQ_FREE_IDS / CEREBRAS_FREE_IDS 允许列表添加一个已知的免费模型 id。

安全

Free Best Router 的设计目标是在受信任的本地网络上安全暴露。它不会验证入站的 Authorization 头（它使用自己的提供商密钥）。如果你将其绑定到公共地址，请在前面添加一个身份验证代理。参见 SECURITY.md。

相关项目

| 项目 | 它解决的问题 |
|---|---|
| universal-engineering-agent | 工程代理操作内核。 任何编码代理都应执行的 9 阶段循环：检查 → 规划 → 实现 → 验证 → 分类 → 恢复 → 测试 → 泛化。UEA 是这个路由器所位于其下的技术栈*。 |
| DeepSeek Harness | 代理框架。这个路由器是 DSH 的一个可直接替换的 OpenAI 兼容提供商块。 |

UEA = 工程协调。 Free Best Router = 模型路由。 它们是兄弟项目。

许可证

MIT — 参见 LICENSE。

致谢

灵感来自每一位曾因免费模型的速率限制而浪费掉一个下午的开发者。

— 由 Majid Asghari Tabrizi 构建