HuggingFace + FreeLLMAPI：16 家免费 tier > 月17亿token

如果你平时调大模型 API，大概率遇到过这几种情况：

某个平台今天额度用完了，代码直接报错
想试新模型，又要去另一个网站申请 Key，重复配置 base_url
手里五六个 Key，管理混乱，不知道哪家还剩多少额度
想给内部项目搭一个统一的模型入口，但不想付 OpenAI 的账单

FreeLLMAPI 就是解决这些问题的。它本质上是一个 OpenAI 兼容的代理层，把 Google、Groq、Cerebras、SambaNova、Mistral、OpenRouter、GitHub Models、Cloudflare、Cohere、NVIDIA、HuggingFace、Z.ai、Ollama、Kilo、Pollinations、LLM7 这 16 家提供商的免费额度，聚合到一个 /v1/chat/completions 端点后面。

你前端代码只改一行 base_url，后端自动帮你挑有额度的模型，一家限流了自动切下一家。

为什么不是 LiteLLM 或 One API

市面上类似的代理工具不少，但 FreeLLMAPI 有几个差异化的设计：

第一，它是为「免费 tier」专门优化的。

不是简单地把请求转发过去，而是内置了每家提供商的速率限制模型（RPM/RPD/TPM/TPD）。它会实时跟踪每个 Key 的用量，优先选没触顶的那个。如果某家返回 429，自动进入冷却，换下一个模型重试，最多尝试 20 次。

第二，Sticky Session。

多轮对话里，它会在 30 分钟内尽量把同一串对话固定在同一家模型上。避免聊着聊着模型换了，导致上下文理解断裂、出现幻觉。

第三，Embedding 路由做了特殊处理。

/v1/embeddings 不是像 chat 那样随便 failover 到另一个模型。因为不同模型产出的向量空间不兼容，乱切会污染你的向量数据库。FreeLLMAPI 的做法是按「向量家族」路由，只在同一家族内部做 provider 级别的 failover。

第四，Key 加密存储。

所有上游 API Key 用 AES-256-GCM 加密后存在本地 SQLite，内存中解密后才发请求。你对外只暴露一个统一的 freellmapi-... Key。

第五，自带 Dashboard。

不需要额外部署前端。启动后直接在浏览器里管理 Provider Key、拖拽调整 Fallback Chain、看实时用量和延迟分布。对不想写配置文件的人来说，这比改 YAML 舒服得多。

部署难点：HF 免费 Space 的数据不持久

HuggingFace 免费 Space 的容器存储是临时的。Sleep 之后重启，SQLite 里的配置和 Key 全丢。

解决思路是用 HuggingFace 自己的 Dataset 当「对象存储」。写了一个 Python 守护进程，在后台定时做几件事：

用 sqlite3 .backup 做一致性快照，避免复制到一半的数据库损坏
把快照上传到 Private Dataset，文件名带时间戳
Space 重启时，自动扫描 Dataset 里的历史版本，取最新的还原成 freeapi.db
定期清理旧版本，只保留最近 N 个

整个链路完全内循环，不依赖 Supabase、R2 或任何第三方云。Dataset 是免费的，Private 设置后数据不外泄。

实际部署步骤

访问我的space（https://huggingface.co/spaces/antidark/freellmapi），直接复制，填入相关变量后点击部署即可。具体细节参考readme

构建完成后，Space 提供一个 https://*.hf.space 的 HTTPS 端点，自带证书，不需要自己配域名。

使用方式

拿到 Dashboard 里生成的 unified API Key 之后，调用方式和 OpenAI 完全一致：

from openai import OpenAI client = OpenAI( base_url="https://你的space.hf.space/v1", api_key="freellmapi-xxxxxxxx" ) response = client.chat.completions.create( model="auto", # 让路由器自己选 messages=[{"role": "user", "content": "..."}] )

model="auto" 时，FreeLLMAPI 会根据你的 Fallback Chain 和各家实时额度自动选择。也可以指定具体模型，如 gemini-2.5-flash，它会固定走 Google。

支持流式输出、Tool Calling、Vision（图片输入）、Embeddings。响应头里会带 X-Routed-Via: groq/llama-4-scout，方便你排查实际走了哪家。