AI 智能体的免费 LLM API
一个 AI 智能体会为一项任务发送许多模型请求。每一步都需要工具调用和大上下文。一个免费层级很快就会让智能体停下。FreeLLMAPI 将 45 个免费提供商层级汇集在一个兼容 OpenAI 的密钥之后。当某个限制导致请求失败时,它会切换到下一个提供商,因此智能体可以继续运行。本指南介绍工具调用、按步骤路由、长会话,以及路由器的 MCP 服务器。
代码、模型名称和目录中的实时标签以英文显示。
AI 智能体对免费 API 的要求
| 需求 | 原因 | FreeLLMAPI 的做法 |
|---|---|---|
| 工具调用 | 智能体选择并运行工具 | 将 OpenAI 风格的 tools 传递给每个提供商。将纯文本工具调用转换为真正的 tool_calls。 |
| 大量请求 | 一项任务可能需要 20 到 100 个步骤 | 统计每个密钥的配额,遇到 429 时切换到下一个密钥或提供商 |
| 大上下文 | 每一步的工具结果和历史记录都会增长 | 路由到你的链中的模型。你可以创建长上下文配置档案。 |
| 稳定的行为 | 任务中途更换模型可能会让智能体混乱 | 将会话保持在同一模型上 30 分钟。发生切换时可选择交接上下文。 |
| 可见性 | 你必须知道哪个模型失败了 | 每个响应中的 X-Routed-Via 和 X-Fallback-Trail 标头 |
免费层级有限制。故障转移会把负载分散到你的密钥上,但总量仍然是各免费限制之和。智能体工作请添加来自四个或更多提供商的密钥。
| 模型 | 免费提供方 | 上下文 | 免费额度(最优惠) | 工具 | 视觉 |
|---|---|---|---|---|---|
| GLM 5.3 | UnoRouter | 1M | 1 请求/分钟 1 req/min per model | 是 | 否 |
| GLM 5.3 Flash | NVIDIA NIM, UnoRouter | 1M | 40 请求/分钟 40 RPM | 是 | 是 |
| Gemini 3.8 Flash | Google AI Studio | 1M | Recurring provider quota | 是 | 是 |
| Qwen3.8 Flash Next | AMD Radeon Cloud | 262K | Recurring daily account allowance | 是 | 否 |
| Qwen3.8 Flash | ElectronHub | 1M | $0.25/week shared recurring credit | 是 | 是 |
| Gemini 3.7 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| GPT-5.6 Luna | ElectronHub | 1M | $0.25/week shared recurring credit | 是 | 是 |
| Dots3 Note Preview | Kilo Gateway, OpenRouter | 512K | 20 请求/分钟 50 请求/天 50 req/day account-wide (1,000 after a $10 purchase) | 是 | 是 |
| DeepSeek V4 Flash | AMD Radeon Cloud, BazaarLink, ElectronHub | 1M | 10 请求/分钟 50 请求/天 Shared rate limit | 是 | 否 |
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 请求/分钟 250 请求/天 70,000 令牌/分钟 ~6M | 是 | 是 |
| Gemini 3.6 Flash | Google AI Studio | 1M | 10 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Qwen 3.8 27B | Cloudflare Workers AI | 262K | Shared 10k neurons/day | 是 | 是 |
显示 12 个(共 109 个匹配的免费模型)。 查看所有模型.
数据来自 FreeLLMAPI 目录(版本 2026.11.19,检查于 2026-11-19)。免费额度经常变化。该目录每天检查一次。
Python 中的完整智能体循环
下面的循环使用官方 OpenAI SDK。它发送工具,运行每个工具调用,将结果发回,并在模型给出最终答案时停止。它也会在达到最大步骤数后停止。
agent.py
import json
import os
import time
import openai
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:3001/v1",
api_key=os.environ["FREELLMAPI_API_KEY"], # <unified-key>
max_retries=3,
)
def get_weather(city: str) -> dict:
return {"city": city, "temp_c": 18, "sky": "cloudy"}
TOOLS = [{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city.",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"],
},
},
}]
FUNCTIONS = {"get_weather": get_weather}
def call_model(messages, session_id):
for attempt in range(5):
try:
return client.chat.completions.create(
model="auto:smart",
messages=messages,
tools=TOOLS,
extra_headers={"X-Session-Id": session_id},
)
except openai.RateLimitError as err:
header = err.response.headers.get("retry-after", "")
wait = int(header) if header.isdigit() else 2 ** attempt
time.sleep(min(wait, 60))
raise RuntimeError("All free providers are at their limit")
def run(task: str, session_id: str, max_steps: int = 10) -> str:
messages = [
{"role": "system", "content": "Use the tools when they help. Be brief."},
{"role": "user", "content": task},
]
for _ in range(max_steps):
msg = call_model(messages, session_id).choices[0].message
messages.append(msg)
if not msg.tool_calls:
return msg.content
for call in msg.tool_calls:
fn = FUNCTIONS.get(call.function.name)
try:
args = json.loads(call.function.arguments or "{}")
result = fn(**args) if fn else {"error": "unknown tool"}
except Exception as exc: # return tool errors to the model
result = {"error": str(exc)}
messages.append({
"role": "tool",
"tool_call_id": call.id,
"content": json.dumps(result),
})
return "Stopped: too many steps."
print(run("Should I take an umbrella in Dublin today?", session_id="task-001"))- X-Session-Id: 当该模型仍有配额时,将一项任务的所有步骤保持在同一模型上。
- Retry-After: 当所有密钥都达到限制时,网关返回带此标头的 429。循环会等待后重试。
- 工具错误: 循环将错误作为工具结果发回给模型。模型随后可以更正其调用。
将每一步路由到正确的模型
智能体的各个步骤并不相同。规划步骤需要强大的模型。只提取一个字段的步骤需要快速模型。为每种步骤类型使用不同的模型字符串。你无需更改仪表板。
| 模型字符串 | 排序依据 | 智能体用途 |
|---|---|---|
auto:smart | 智能能力 | 规划、工具选择、最终答案 |
auto:fast | 实测速度和首字节时间 | 提取、分类、工具输出的简短摘要 |
auto:reliable | 近期成功率 | 必须完成的定时智能体 |
auto:balanced | 先看可靠性,再看速度和智能能力 | 通用默认值 |
auto:<profile> | 你命名的备用链 | 仅包含支持工具调用模型的链 |
auto:* 策略会对所有已启用的模型排序,并忽略你的链顺序。带工具的请求仍需要支持工具调用的模型。如果某些已启用的模型对工具的支持不佳,请创建一个仅包含支持工具调用模型的配置档案。然后对工具步骤使用 auto:<profile>。未知的配置档案名称会返回错误 400。
标头 X-FreeLLM-Task-Type: code 会为单个请求将路由权重从速度转向智能能力。这只是一个软偏好。它不会改变能力检查或备用链。
长智能体会话与模型切换
在长任务期间,某个模型可能达到每日限制。路由器随后会切换到另一个模型。新模型会收到完整的消息历史,但不知道前面的步骤是由另一个模型完成的。
开启上下文交接后,模型切换时会添加一条简短的系统消息。该消息告诉新模型继续任务,并保留之前的工具结果。
FreeLLMAPI .env
FREELLMAPI_CONTEXT_HANDOFF=on_model_switch- 仅当会话所选的模型发生变化时,才会添加交接消息。
- 会话在内存中保留 3 小时。不写入磁盘。
- 会话键是
X-Session-Id标头。没有该标头时,它是第一条用户消息的哈希值。
将路由器用作 MCP 服务器
FreeLLMAPI 同时也是位于 /mcp 的 MCP 服务器。支持 MCP 的智能体可以向 FreeLLMAPI 模型发送文本任务。在会话期间,它还可以读取网关状态:可用模型及其参数、提供商健康状况、用量和缓存统计,以及路由策略。
全新安装时 MCP 功能默认关闭。请在仪表板的密钥页面中,于智能体兼容性下将其开启。关闭期间,/mcp 返回 403。
将 MCP 服务器添加到 Claude Code
claude mcp add --transport http freellmapi http://localhost:3001/mcp \
--header "Authorization: Bearer <unified-key>"任何支持 Streamable HTTP 的 MCP 客户端的设置方式都相同。将其指向 /mcp,并以 Bearer 令牌的形式发送统一密钥。常用的工具包括 healthcheck、list_models 和 ask_freellmapi。ask_freellmapi 工具通过与 API 相同的聊天路由运行任务,包括路由和故障转移。
对于编码智能体,FreeLLMAPI 提供设置命令,可为你写入客户端配置。例如 npx freellmapi setup-claude、setup-codex、setup-cline、setup-openclaw 和 setup-hermes。每个命令都支持 --dry-run,并会先创建备份。
故障排除
| 问题 | 原因 | 解决方法 |
|---|---|---|
| 模型以文本形式回答,未调用任何工具 | 模型的工具调用能力较弱 | 仅对支持工具调用的模型使用 auto:<profile> |
| 智能体在任务中途重新开始 | 某个限制迫使模型切换 | 发送 X-Session-Id 并开启上下文交接 |
| 多个步骤后出现错误 429 | 链中的所有密钥都已达到限制 | 添加提供商,对小步骤使用 auto:fast,并等待 Retry-After |
使用 auto:name 时出现错误 400 | 该配置档案不存在 | 在仪表板上检查配置档案名称 |
/mcp 返回 403 | MCP 功能已关闭 | 在密钥页面的智能体兼容性下开启它 |
| 任务后期出现上下文长度错误 | 历史记录超过了模型的窗口 | 总结旧的工具结果,或使用长上下文配置档案 |
常见问题
是否有适用于 AI 智能体的免费 LLM API?
有。多家提供商提供支持工具调用的免费层级。FreeLLMAPI 将它们组合在一个兼容 OpenAI 的密钥之后,并在某个限制导致请求失败时切换到下一个提供商。
哪个免费 LLM 最适合工具调用?
请使用支持工具调用且上下文窗口为 128K 个 token 或以上的模型。本页的表格列出了目前同时满足这两条规则的最强免费模型。
我能否将 FreeLLMAPI 用作 MCP 服务器?
可以。在密钥页面的智能体兼容性下开启 MCP 功能。然后以 Bearer 令牌的形式使用统一密钥,将你的 MCP 客户端连接到 /mcp。
如何避免智能体因速率限制而失败?
添加更多提供商的密钥,将小步骤发送到 auto:fast,遇到 429 时借助 Retry-After 标头重试,并设置最大步骤数。
智能体任务中途切换模型会怎样?
新模型会收到完整的消息历史。开启上下文交接后,它还会收到一条简短的说明,告诉它继续任务。
相关指南
- 支持函数调用的免费 LLM API
- Python 中的免费 LLM API
- LangChain 的免费 LLM API
- n8n 免费 LLM API
- 如何免费使用 Claude Code
- 免费 LLM API 速率限制
来源
- FreeLLMAPI docs: REST API (tool calling, routing strategies, response headers) (检查于 20 November 2026)
- FreeLLMAPI docs: clients, MCP server and context handoff (检查于 20 November 2026)
- OpenAI Python SDK: errors and retries (检查于 20 November 2026)
- Claude Code docs: MCP (检查于 20 November 2026)