Python 中的免费 LLM API
官方 openai Python 包可与任何兼容 OpenAI 的 API 配合使用。你只需更改 base URL 和密钥。本指南使用 FreeLLMAPI,它用一个密钥汇集 45 个免费服务商额度,并在某个限制阻止请求时切换到下一个服务商。下方每个示例都是完整的,可直接运行。
代码、模型名称和目录中的实时标签以英文显示。
设置
安装 FreeLLMAPI。它在 Docker 中运行。在浏览器中打开控制台:http://localhost:3001,在 Keys 页面添加两个或更多服务商的免费密钥,然后复制统一密钥。接着安装 Python 包。
你的 Python 代码只使用统一密钥。服务商密钥保存在 FreeLLMAPI 中,并在其数据库内加密。如果你更改或添加服务商密钥,无需修改代码。
安装
curl -fsSL https://freellmapi.co/install.sh | bash
python3 -m pip install -U openai
export FREELLMAPI_API_KEY=<unified-key>client.py
import os
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:3001/v1",
api_key=os.environ["FREELLMAPI_API_KEY"],
max_retries=3, # the SDK retries 429, 408, 409 and 5xx errors
timeout=60,
)
resp = client.chat.completions.create(
model="auto",
messages=[{"role": "user", "content": "Name three uses of Python in one line."}],
)
print(resp.choices[0].message.content)模型 auto 遵循控制台中的备用链。你也可以使用 auto:fast、auto:smart 或 auto:reliable,使用配置名称(例如 auto:coding),或使用固定的模型 ID。
流式输出与响应头
流式输出回答
from client import client
stream = client.chat.completions.create(
model="auto:fast",
messages=[{"role": "user", "content": "Write a haiku about Python."}],
stream=True,
)
for chunk in stream:
if chunk.choices:
print(chunk.choices[0].delta.content or "", end="", flush=True)
print()每个响应都带有 X-Routed-Via 请求头,其中包含作出回答的服务商和模型。要使用 SDK 读取响应头,请使用 with_raw_response,并调用 parse() 获取常规对象。
读取路由响应头
from client import client
raw = client.chat.completions.with_raw_response.create(
model="auto",
messages=[{"role": "user", "content": "hi"}],
)
print("Served by:", raw.headers.get("x-routed-via"))
print("Failed attempts:", raw.headers.get("x-fallback-attempts", "0"))
print(raw.parse().choices[0].message.content)工具调用
发送 OpenAI 风格的 tools。路由器会将其传递给兼容 OpenAI 的服务商,并为 Gemini 进行转换。每个服务商返回的回答都采用相同的格式。
一次工具调用及最终回答
import json
from client import client
tools = [{
"type": "function",
"function": {
"name": "get_exchange_rate",
"description": "Get the exchange rate between two currencies.",
"parameters": {
"type": "object",
"properties": {
"base": {"type": "string"},
"quote": {"type": "string"},
},
"required": ["base", "quote"],
},
},
}]
messages = [{"role": "user", "content": "How many euros is 250 US dollars?"}]
first = client.chat.completions.create(model="auto", messages=messages, tools=tools)
msg = first.choices[0].message
if msg.tool_calls:
messages.append(msg)
for call in msg.tool_calls:
args = json.loads(call.function.arguments)
result = {"base": args["base"], "quote": args["quote"], "rate": 0.92} # your real lookup
messages.append({"role": "tool", "tool_call_id": call.id, "content": json.dumps(result)})
final = client.chat.completions.create(model="auto", messages=messages, tools=tools)
print(final.choices[0].message.content)
else:
print(msg.content)部分服务商以纯文本形式返回工具调用。FreeLLMAPI 会将这些回答转换为真正的 tool_calls,因此你的代码只需读取一种格式。在读取 msg.tool_calls 之前,请始终先检查它,因为模型也可能不调用工具直接回答,此时需读取 msg.content。
请使用支持工具调用的模型。以下免费模型支持工具,并且目前实测速度最快:
| 模型 | 免费提供方 | 上下文 | 免费额度(最优惠) | 工具 | 视觉 |
|---|---|---|---|---|---|
| Qwen3.8 27B | ElectronHub, Groq, OVH AI Endpoints | 262K | 30 请求/分钟 250 请求/天 70,000 令牌/分钟 ~6M | 是 | 是 |
| Nemotron 3.5 Lightning | ElectronHub, Kilo Gateway, OpenRouter | 1M | 20 请求/分钟 50 请求/天 50 req/day account-wide (1,000 after a $10 purchase) | 是 | 否 |
| GPT-OSS 120B | Cloudflare Workers AI, ElectronHub, Groq 另外 1 个 | 131K | 30 请求/分钟 1,000 请求/天 8,000 令牌/分钟 200,000 令牌/天 ~6M | 是 | 否 |
| GPT-OSS 20B | Cloudflare Workers AI, Groq, NVIDIA NIM 另外 1 个 | 131K | 30 请求/分钟 1,000 请求/天 8,000 令牌/分钟 200,000 令牌/天 ~6M | 是 | 否 |
| GPT-OSS Safeguard 20B | Groq | 131K | 30 请求/分钟 1,000 请求/天 8,000 令牌/分钟 200,000 令牌/天 ~6M | 是 | 否 |
| Gemini 3.5 Flash Lite | ElectronHub, Google AI Studio | 1M | 15 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
| Step 3.7 Flash | ElectronHub | 256K | $0.25/week shared recurring credit | 是 | 是 |
| Gemini 3.1 Flash-Lite | DreamPrompting, Google AI Studio | 1M | 100 请求/分钟 5,000 请求/天 500,000 令牌/天 500K tokens/day · 5,000 req/day | 是 | 是 |
| Nemotron 3.5 Lightning 30B | Requesty | 1M | 200 请求/天 200 rpd | 是 | 否 |
| Gemini 2.5 Flash-Lite | ElectronHub, Google AI Studio | 1M | 15 请求/分钟 20 请求/天 250,000 令牌/分钟 ~3M | 是 | 是 |
显示 10 个(共 146 个匹配的免费模型)。 查看所有模型.
数据来自 FreeLLMAPI 目录(版本 2026.11.19,检查于 2026-11-19)。免费额度经常变化。该目录每天检查一次。
免费限制内的异步批处理
AsyncOpenAI 会同时发送大量请求。免费额度限制每分钟的请求数,因此请使用信号量限制并发数。该示例还会在所有服务商都达到限制时进行重试。
batch.py
import asyncio
import os
import openai
from openai import AsyncOpenAI
client = AsyncOpenAI(
base_url="http://localhost:3001/v1",
api_key=os.environ["FREELLMAPI_API_KEY"],
max_retries=2,
)
limit = asyncio.Semaphore(4) # at most 4 requests at a time
async def summarize(text: str) -> str:
async with limit:
for attempt in range(5):
try:
resp = await client.chat.completions.create(
model="auto:fast",
messages=[
{"role": "system", "content": "Summarize in one sentence."},
{"role": "user", "content": text},
],
)
return resp.choices[0].message.content
except openai.RateLimitError as err:
header = err.response.headers.get("retry-after", "")
wait = int(header) if header.isdigit() else 2 ** attempt
await asyncio.sleep(min(wait, 60))
return "ERROR: rate limited"
async def main():
docs = [f"Document {i}: Python is a programming language." for i in range(20)]
results = await asyncio.gather(*(summarize(d) for d in docs))
for r in results:
print(r)
await client.close()
asyncio.run(main())只有当链中的所有密钥都达到限制时,路由器才会返回 429。此时响应中会带有 Retry-After 请求头。对于大批量任务,较小的信号量值和更多的服务商密钥可获得最佳效果。
为每项任务选择模型字符串
模型字符串告诉路由器如何选择模型。你可以在每次调用中使用不同的字符串。无需更改控制台设置。
| 任务 | 模型字符串 | 原因 |
|---|---|---|
| 面向用户的聊天回答 | auto | 遵循你在控制台中设置的备用链 |
| 分类、提取、简短摘要 | auto:fast | 按实测速度对已启用的模型排序 |
| 困难问题、代码审查、规划 | auto:smart | 按智能水平对已启用的模型排序 |
| 必须完成的定时任务 | auto:reliable | 按近期成功率对已启用的模型排序 |
| 某个应用专用的独立链 | auto:<profile> | 使用指定名称的备用链 |
| 必须可重复的测试 | 固定的模型 ID | 每次都使用同一模型,但会在该模型达到限制时停止 |
要查看你的密钥当前可以调用哪些模型,请使用过滤条件请求模型列表。完整列表还包括尚未添加密钥的模型。
列出当前可以作答的模型
import os
import httpx
r = httpx.get(
"http://localhost:3001/v1/models",
params={"execution_status": "ready"},
headers={"Authorization": f"Bearer {os.environ['FREELLMAPI_API_KEY']}"},
timeout=30,
)
r.raise_for_status()
for m in r.json()["data"]:
print(m["id"])状态为 exhausted 的模型有密钥,但所有密钥目前都已达到限制。冷却期结束后,该状态会清除。状态为 needsKey 的模型没有已启用的密钥。
对于一段对话,请通过 X-Session-Id 请求头发送会话 ID,即在 extra_headers 中设置。之后,FreeLLMAPI 会在 30 分钟内让该对话保持使用同一个模型。如果没有该请求头,它会使用第一条用户消息的哈希值作为会话键。
Embeddings
对文本进行 embedding
from client import client
resp = client.embeddings.create(
model="bge-m3", # one embedding family
input=["Python is a programming language.", "A snake is a reptile."],
)
print(len(resp.data), "vectors of", len(resp.data[0].embedding), "dimensions")Embedding 故障转移从不更换模型。它只会在提供同一系列的服务商之间切换,因此你的向量保持兼容。值 auto 使用你在控制台中设置的默认系列。
在一个 input 列表中发送多个文本。包含 32 个文本的一次请求只占用免费限额中的一次请求,而不是 32 次。确保每个文本都低于该系列的最大输入。请将系列名称与你的向量一起保存,以便之后使用同一系列为查询生成 embedding。
错误与解决方法
| 异常 | 原因 | 解决方法 |
|---|---|---|
openai.AuthenticationError | 统一密钥错误 | 从 Keys 页面重新复制密钥 |
openai.APIConnectionError | FreeLLMAPI 未运行,或端口错误 | 在浏览器中打开 http://localhost:3001 |
openai.NotFoundError | base URL 中没有 /v1 | 使用 http://localhost:3001/v1 |
openai.RateLimitError | 链中的所有密钥都已达到限制 | 添加服务商,降低并发数,或等待 Retry-After |
openai.BadRequestError,同时使用 auto:name | 配置名称不存在 | 在控制台中检查配置名称 |
发送图片时出现 openai.UnprocessableEntityError(422) | 你的链中没有视觉模型 | 在备用链中启用一个视觉模型 |
免费额度没有服务等级协议(SLA)。延迟会随一天中的时间变化。性能最强的模型会最先达到每日限制,而且许多限制在 UTC 时间午夜重置。不要将免费网关用于必须在固定时间内响应的服务。
常见问题
有适用于 Python 的免费 LLM API 吗?
有。许多服务商提供可与 openai Python 包配合使用的免费额度。FreeLLMAPI 将它们组合在一个 base URL 和一个密钥之后,并在服务商之间进行故障转移。
如何让 openai Python 库使用不同的 base URL?
将 base_url 传递给 OpenAI() 或 AsyncOpenAI(),例如 base_url="http://localhost:3001/v1"。将网关密钥作为 api_key 传入。
如何在 Python 中处理速率限制错误?
在客户端上设置 max_retries。捕获 openai.RateLimitError,读取 Retry-After 请求头并等待。使用 asyncio 信号量限制并发数。
流式输出能与 Python 中的免费 LLM API 一起使用吗?
可以。传入 stream=True,并读取 chunk.choices[0].delta.content。FreeLLMAPI 对所有服务商都以 OpenAI 格式进行流式输出。
能否在 Python 中使用异步调用免费 LLM API?
可以。使用 AsyncOpenAI,并配合相同的 base_url 和密钥。请保持并行请求数较少,因为免费额度限制每分钟的请求数。
相关指南
来源
- OpenAI Python SDK README (async, retries, raw responses, errors) (检查于 20 November 2026)
- FreeLLMAPI docs: REST API (chat, streaming, tool calling, embeddings, headers) (检查于 20 November 2026)
- FreeLLMAPI docs: degraded mode and failover (检查于 20 November 2026)