FreeLLMAPI：聚合16个LLM免费层级的统一代理FreeLLMAPI** 是一个OpenAI兼容的代理服务，它将

项目简介

FreeLLMAPI 是一个OpenAI兼容的代理服务，它将来自16家LLM提供商的免费层级聚合到一个统一的 /v1/chat/completions 端点后面。通过这个工具，开发者可以使用任何OpenAI客户端库，无缝访问总计约每月17亿Token的免费推理容量。

该项目的核心理念很简单：单独看，每家提供的免费额度都像是个“玩具”；但把它们堆叠在一起，就构成了一个相当可观的、包含100多个模型的推理资源池。FreeLLMAPI解决的核心痛点，就是让你不用再手动处理16种不同的SDK、速率限制和错误处理。

支持的提供商

该项目目前聚合了以下提供商的免费层级（截至2026年5月）：

提供商	部分代表性模型
Google	Gemini 2.5 Flash, 3.x 预览版
Groq	Llama 3.3, Llama 4, GPT-OSS, Qwen3
Cerebras	Qwen3 235B
SambaNova	DeepSeek V3.x, Llama 4, Gemma 3
Mistral	Large 3, Medium 3.5, Codestral, Devstral
OpenRouter	21个免费模型
GitHub Models	GPT-4.1, GPT-4o
Cloudflare	Kimi K2, GLM-4.7, GPT-OSS
Cohere	Command R+, Command-A (试用)
Z.ai (Zhipu)	GLM-4.5, GLM-4.7 Flash
NVIDIA (NIM)	默认禁用，需谨慎使用
HuggingFace	路由至DeepSeek V4, Kimi K2.6等
Ollama Cloud	GLM-4.7, Kimi K2, Qwen3
Kilo Gateway	免费路由（可匿名）
Pollinations	GPT-OSS 20B（可匿名）
LLM7	GPT-OSS, Llama 3.1（可匿名）

此外，还支持自定义提供商，可以指向任何OpenAI兼容的端点（如llama.cpp、LM Studio、本地Ollama）。

核心特性

1. OpenAI兼容的API

支持 POST /v1/chat/completions 和 GET /v1/models
可直接使用官方OpenAI SDK、LangChain、LlamaIndex等任何兼容客户端
仅需修改 base_url 指向你的本地FreeLLMAPI服务

2. 智能请求路由与自动故障转移

路由器会为每个请求选择最佳可用模型
当某个提供商返回429（速率限制）、5xx错误或超时时，自动跳过并冷却该密钥
在备用链上重试，最多尝试20次
粘性会话：多轮对话在30分钟内持续使用同一模型，避免中途切换导致的“幻觉”飙升

3. 全功能支持

流式与非流式响应：支持Server-Sent Events
工具调用（Tool Calling） ：完全支持OpenAI风格的 tools / tool_choice，支持多轮对话中的工具调用往返
图像输入（Vision） ：支持标准OpenAI image_url 格式，路由器会自动筛选支持视觉的模型

4. 密钥管理与安全

加密存储：API密钥使用AES-256-GCM加密后存入SQLite，仅在请求前解密至内存
统一API密钥：客户端只需使用一个 freellmapi-... 的Bearer令牌进行认证，上游提供商密钥完全对应用透明
健康检查：定期探测各密钥状态（健康、受限、无效、错误），自动跳过失效的密钥

5. 管理面板与数据分析

React + Vite 构建的管理UI：支持暗色模式，功能包括：
- 管理提供商密钥
- 调整模型故障转移的顺序
- 交互式Playground：直接发送提示词并查看路由结果、模型ID和延迟
- 分析看板：查看请求量、成功率、Token使用量、延迟分布及分提供商统计

快速开始（使用Docker Compose）

这是官方推荐的启动方式，它会将API和面板一同运行在3001端口。

前置要求：Docker、Docker Compose、OpenSSL。

bash

# 1. 克隆仓库
git clone https://github.com/tashfeenahmed/freellmapi.git
cd freellmapi

# 2. 生成加密密钥并创建环境文件
ENCRYPTION_KEY="$(openssl rand -hex 32)"
printf "ENCRYPTION_KEY=%s\nPORT=3001\n" "$ENCRYPTION_KEY" > .env

# 3. 启动服务
docker compose up -d

启动后，访问 http://localhost:3001，在“Keys”页面添加各提供商的API密钥，调整“Fallback Chain”中的模型顺序，然后复制页面顶部的统一API密钥即可开始使用。

使用示例（Python）

python

from openai import OpenAI

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

# 发送请求，model="auto" 让路由器自动选择
response = client.chat.completions.create(
    model="auto",
    messages=[{"role": "user", "content": "用一句话解释什么是递归。"}],
)

print(response.choices[0].message.content)
# 查看实际由哪个提供商处理了请求
print(response.headers.get("x-routed-via"))

使用cURL

bash

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

工作原理

text

┌──────────────┐   统一API密钥    ┌─────────────────────────┐
│ OpenAI SDK   │ ───────────────▶ │  Express 代理 (:3001)   │
│ 或任何客户端   │ ◀─────────────── │  /v1/chat/completions   │
└──────────────┘   流式Token      └───────────┬─────────────┘
                                              │
                                              ▼
                              ┌────────────────────────────────┐
                              │          路由器                 │
                              │ 1. 选择优先级最高的健康模型        │
                              │ 2. 检查是否在速率限制内           │
                              │ 3. 解密密钥，调用提供商SDK         │
                              │ 4. 遇到429/5xx → 冷却并重试下一个  │
                              └────────────────────────────────┘
                                              │
    ┌───────┬───────┬───────┬───────┬───────┴───────┬───────┐
    ▼       ▼       ▼       ▼       ▼               ▼       ▼
  Google   Groq   Cerebras  Mistral  OpenRouter   ...   更多提供商

重要提醒与局限

⚠️ 使用须知

仅供个人实验和学习，不可用于生产环境
项目名称及文档明确指出：“Personal experimentation only”

📉 现实的局限性

无顶尖模型：免费层最高约 Llama 3.3 70B、GLM-4.5、Gemini 2.5 Pro 级别，得不到 GPT-5 或 Claude Opus 等级的能力。
能力随时间衰减：你首选的模型（如 Gemini 2.5 Pro）每日配额最低。一旦用完，会自动降级到链上更小、更弱的模型。因此，每天的晚些时候，这个端点的“智能”水平会下降，并在UTC午夜重置。
延迟不稳定：Cerebras和Groq极快，其他则不一定。能用哪个就用哪个。
免费政策会变：提供商随时可能调整或取消免费层级。
无服务等级协议：没有可靠性保障。

📄 服务条款注意事项（摘要）

项目作者对主要提供商2026年5月的条款进行了审查，结论如下：

需谨慎使用：Google Gemini（新条款缩小范围）、NVIDIA NIM（仅评估）、GitHub Models（限实验/原型）、Z.ai（有反流量重定向条款）。
可能OK：Groq、Cerebras、Mistral、OpenRouter、Ollama Cloud。
建议避免：Cohere（条款禁止个人/家庭用途）。

核心原则：每家提供商一个账户、不转售、不与他人共享你的端点、不将免费层作为生产后端。

总结

FreeLLMAPI 是一个巧妙且实用的工具，它通过工程化手段将碎片化的免费AI资源整合成一个统一、易用的接口。对于想要低成本探索多种LLM、进行原型开发或实验的开发者来说，它极大地降低了门槛和摩擦成本。尽管有诸多限制且不可用于生产，但其设计思想和技术实现（智能路由、故障转移、加密存储等）本身也极具学习价值。如果你是一个AI爱好者或独立开发者，这个项目非常值得尝试。

关于作者：boonya

资深开发工程师，高级架构师。熟悉GIS、车联网、物联网、供应链、林业、互联网家居、游戏、商旅服务。你可以在微信公众号：智驭未来掌门人找到我！

公众号.jpg