本地 LLM OpenAI API：本地运行，切换至托管

该短语的含义

人们使用“本地 LLM OpenAI API”指代两件事。第一是你自己在笔记本电脑或家庭服务器上运行的语言模型，它在本地端口监听并使用 OpenAI 聊天格式。第二是养成针对该格式编写应用的习惯，以便后端模型可以替换。

该格式是一个简单的契约。你的应用发送包含 model 名称和 messages 列表的 JSON 请求体，每条消息的角色为 system、user 或 assistant。服务器返回包含生成消息的 JSON 对象，或者在请求流式输出时返回小块数据的流。Python 和 JavaScript 的官方 SDK 封装了此接口，并允许你覆盖 Base URL，这就是关键所在。

许多本地工具暴露此契约。Ollama、LM Studio、llama.cpp 服务器和 vLLM 均提供 OpenAI 风格的路由。托管服务也是如此，这就是为什么相同的二十行客户端代码可以与两者通信。本站的接口属于托管类型。它接受 POST /v1/chat/completions 和 GET /v1/models，访问地址为 https://api.onekeyllmapi.com/v1。

本地与托管的概览

两者没有绝对的优劣。它们是用控制权换取工作量。该表格仅列出适用于该类别的差异，而非特定产品。

如果你的数据必须永不离开你控制的机器，本地胜出，托管是不合适的工具。如果你需要比硬件支持的更大的模型，或需要从多处访问的机器人，托管胜出。常见的设置是同时保留两者并按任务选择。

客户端从本地切换到托管

如果你的代码已经与本地运行器通信，迁移只需修改三个值。其余所有内容，包括构建消息和读取流式块的方式，保持不变。

1. Base URL。 使用 https://api.onekeyllmapi.com/v1 替代你的本地地址。
2. API 密钥。 本地服务器通常忽略密钥。托管服务需要它作为 Authorization: Bearer <key>，SDK 会自动为你发送。
3. 模型 ID。 本地名称取决于你拉取的模型。此处的 ID 为 uncensored。

保持灵活性的整洁方法是将所有三个值从环境变量中读取，这样单个文件可以在两处运行。

Copyimport os
from openai import OpenAI

client = OpenAI(
    base_url=os.environ.get("LLM_BASE_URL", "https://api.onekeyllmapi.com/v1"),
    api_key=os.environ.get("LLM_API_KEY", "YOUR_KEY"),
)
MODEL = os.environ.get("LLM_MODEL", "uncensored")

models = client.models.list()
print([m.id for m in models.data])

resp = client.chat.completions.create(
    model=MODEL,
    messages=[
        {"role": "system", "content": "Answer in two sentences."},
        {"role": "user", "content": "Why do OpenAI-style endpoints make switching models easy?"},
    ],
    temperature=0.5,
)
print(resp.choices[0].message.content)

来自命令行的相同调用，适用于快速冒烟测试：

Copycurl https://api.onekeyllmapi.com/v1/chat/completions \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "uncensored", "messages": [{"role": "user", "content": "ping"}], "max_tokens": 20}'

使用 Node 时，模式相同：

Copyimport OpenAI from "openai";

const client = new OpenAI({
  baseURL: process.env.LLM_BASE_URL ?? "https://api.onekeyllmapi.com/v1",
  apiKey: process.env.LLM_API_KEY,
});

const res = await client.chat.completions.create({
  model: process.env.LLM_MODEL ?? "uncensored",
  messages: [{ role: "user", content: "Name three uses for JSON mode." }],
});
console.log(res.choices[0].message.content);

OpenAI 兼容模式涵盖和不涵盖的内容

兼容意味着线格式匹配。它不承诺原始服务提供的每个功能都存在。在迁移真实应用之前，请针对目标检查以下各项。

该 API 支持的功能

• POST /v1/chat/completions 处的聊天补全和 GET /v1/models 处的模型列表。
• 通过 stream: true 进行服务器发送事件的流式输出，并在流结束时报告使用情况。
• 通过 tools 和 tool_choice 进行函数调用，流式输出 tool_calls，并将结果作为 role: "tool" 消息发送回。
• 通过 response_format: {"type": "json_object"} 实现 JSON 模式。
• 采样控制：temperature、top_p、stop、seed 和惩罚参数被透传。

它不做什么

• 不支持图像、音频或视频生成。仅支持文本。
• 无嵌入接口且无微调。如果你的应用构建向量索引，你需要单独的嵌入源。
• 仅一个模型。该模型是由独立提供商运行的开放权重模型。它不是任何大型厂商的官方 API，也不是跨厂商的路由器，因此你无法通过更改 ID 在模型系列之间进行选择。

本地运行方式有时则相反：本地服务器可能提供嵌入接口或允许加载多个模型，上下文大小取决于你的配置。请分别阅读各目标文档，并列出你的应用真正使用的功能。快速入门文档 完整展示了请求字段。

上下文、限制和成本差异

离开本地服务器时，有三个数字会发生变化。首先是窗口。本地运行器的上下文长度是与你的内存相关的设置。此处固定为 100,000 token，由提示词和补全共享，且 max_tokens 是可选的。其次是并发。你自己的机器可以排队任意深度，但完整密钥允许 8 个并发请求和每分钟 300 个请求，试用密钥允许 2 个和 60 个。第三是账单。

托管使用成本为每 1M 输入 token $0.15，每 1M 输出 token $0.50，从预付额度按量付费。以每日作业为例：摘要器每天处理 400 份文档，每份输入 3,000 token，输出 300 token。输入为 400 x 3,000 = 1,200,000 token，成本为 1.2 x $0.15 = $0.18。输出为 400 x 300 = 120,000 token，成本为 0.12 x $0.50 = $0.06。当天总计 $0.24，30 天月份为 $7.20。在决定之前，将其与保持 GPU 运行及显卡本身的成本进行比较。

超出限制时，API 返回 HTTP 429 状态码，错误码为 rate_limited 或 concurrency。短暂过载时还会添加 Retry-After: 5。保留等待并重试的逻辑。失败或被拒绝的请求不会计费。额度永不过期，因此闲置一个月不产生费用。

流式请求会占用并发槽位，直到流结束，因此停止读取时应关闭流。充值从 $20 起；各档位及奖励详见 定价页面。

切换异常时的调试方法

大多数迁移失败都归结为少数几个原因。请按以下顺序排查。

• 404 或连接错误。 基础 URL 可能缺少 /v1 后缀，或者包含了多余的路径。请严格按照 https://api.onekeyllmapi.com/v1 使用。
• 认证错误。 密钥缺失或发送到了错误的 Header。格式为 Authorization: Bearer <key>。SDK 用户应确认环境变量是否已正确加载。
• 未找到模型。 旧的本地模型名称仍保留在你的配置中。调用 GET /v1/models 并使用其列出的 ID，即 uncensored。
• 负载下的 429 错误。 你的并发请求数超过 8 个或每分钟请求数超过 300 个（针对完整密钥）。请添加队列或信号量。
• 某个参数似乎被忽略。 检查该参数是否属于上述透传的字段，并与固定的 seed 和低 temperature 进行行为对比。

每个响应都包含 X-Request-Id Header。请将其记录在你的请求 ID 旁边，以便后续追踪不良响应。如果你在生产环境中运行流量并希望随时间推移衡量质量，站点文章 LLM 可观测性：常见误区与事实 是很好的延伸阅读。响应 Header X-Balance-USD、X-RateLimit-Limit-Requests 和 X-RateLimit-Limit-Concurrency 也值得捕获。

无承诺试用

测试代码能否顺利迁移的最便宜方法是运行一次。使用 Google 或电子邮件及密码创建账户，然后从密钥页面领取 $0.50 的试用额度。只需点击一次，无需绑定银行卡，每人限领一次，有效期为 7 天。在 API 密钥页面 获取密钥，设置上述三个环境变量，然后运行你现有的测试套件。

如果测试通过且用量符合预算，可通过银行卡（Visa、Mastercard、Apple Pay、Google Pay）或加密货币（TRC20 上的 USDT、Base 上的 USDC）充值，最低 $20。提示词不用于训练。该模型经过调整，可在合法成人使用中无内容拒绝地回答，唯一固定规则是：不涉及未成年人的性内容。

更多指南

• LLM 可观测性：常见误区与事实