免费API与本地网关接入要点及死循环排查

作者:问答酱2026.11.17 03:25浏览量:0

简介:本文围绕免费模型API与本地大模型网关,说明接入前要核实的额度、限速和模型名称,对比Ollama与LM Studio的端口和接口差异,给出超时、重试和流式结束判断的写法,并按步骤排查网关死循环。同时说明密钥管理和成本估算方法,帮助开发者少走弯路,稳妥完成多模型接入。

大模型服务的免费额度、模型名称和开源模型发布变化很快。接入前应先在官方文档中确认三件事:模型名称是否存在,免费额度是否仍然有效,调用限制(速率、并发、上下文长度)是多少。本文不引用具体模型的参数或价格,相关数值请以服务商官方页面为准。

一、免费 API 试用前要核实什么

免费 API 能降低试错成本,但通常带有条件。接入前建议记录以下信息:

  1. 申请入口与账号要求,例如是否需要实名认证。
  2. 免费额度的计量单位,是按 Token、按调用次数还是按时间计算。
  3. 速率限制与并发限制,以及超出后返回的错误码。
  4. 鉴权方式,通常是请求头中携带的 API Key。
  5. 模型版本与下线时间。模型名称可能变更,因此应把模型名写入配置,而不是硬编码在代码里。

配置建议使用环境变量,例如 MODEL_NAME、API_BASE_URL 和 API_KEY。代码只读取变量,更换模型或地址时无需改动业务逻辑。

把以下信息整理成表格,可以在原型阶段判断免费额度能否支撑后续的测试流量:

核实项 记录内容 信息来源
模型名称 官方模型 ID 与版本 模型列表接口或模型文档
额度单位 Token、调用次数或时间 计费页面
速率与并发 每分钟请求数、同时连接数 限流说明
错误码 超限时返回的状态码,例如 429 错误码文档
鉴权方式 请求头名称与 Key 格式 鉴权文档
下线时间 模型停用或额度调整日期 官方公告
成本估算 见下方公式 官方单价

成本按官方单价估算,并计入重试带来的额外请求。计算公式如下:

单次成本 = 输入 Token 数 ÷ 1,000,000 × 输入单价 + 输出 Token 数 ÷ 1,000,000 × 输出单价

月成本 ≈ 日均请求数 × 30 × 单次成本 × (1 + 重试率)

重试率指额外发出的请求占总请求的比例。这个数字无法从文档中得到,应在压测时实际统计。

二、本地模型与云端 API 的分工

本地部署适合数据不能出域、需要离线运行或希望控制长期成本的场景。云端 API 适合快速调用、弹性扩容和较复杂的推理任务。两者常组合使用:先在本机用小模型完成功能验证,效果或并发不足时再切换到云端。

维度 本地模型 云端 API
数据是否出域 不出域 出域,需查看服务商的数据条款
离线运行 可以 需要网络
弹性扩容 受本机硬件限制 按需扩展,但受配额限制
长期成本 以硬件和电费为主,用量高时较低 按用量计费,用量高时增长较快
复杂推理 取决于本机能运行的模型规模 通常可调用规模更大的模型

网关层应把后端类型和请求地址分开管理。页面只选择后端类型,地址与模型名由配置决定。更换端口或模型时,请求逻辑无需改动。

密钥管理要注意以下几点:

  • API Key 只放在服务端的环境变量或密钥管理服务中,不下发到浏览器或移动端代码。
  • 本地网关需要转发到云端时,由服务端代理添加鉴权头,前端不接触 Key。
  • 日志中不打印完整 Key,输出前做脱敏,例如只保留后四位。
  • 开发、测试和生产环境使用不同的 Key,便于单独吊销。
  • 定期轮换 Key。怀疑泄露时,立即在服务商控制台吊销。

三、本地网关死循环的常见原因

网关出现死循环时,问题多数出在请求链路,而不是模型本身。常见原因有五类:

  1. 请求地址指向了网关自身。前端 fetch 请求的是当前页面或代理地址,请求会不断递归。典型现象是 Network 面板中同一地址反复出现,并返回 404、405 或重定向循环。
  2. 地址或路径不匹配。Ollama 与 LM Studio 的端口和接口路径不同,混用后请求失败,错误处理又触发重试。典型现象是返回 404,或返回的 JSON 无法解析。
  3. 流式结束判断缺失。没有正确识别结束标记时,前端会持续等待,或重新发起请求。典型现象是界面一直显示加载中。
  4. 无上限的自动重试。捕获异常后立即重试,且没有次数限制,会形成循环。另一种常见情况是 useEffect 的依赖项在状态变化时重复触发请求。典型现象是控制台中同一请求每秒多次出现。
  5. 浏览器跨域限制。直接用 file:// 打开页面,或从其他域名访问本地服务时,请求可能被浏览器拦截,随后触发重试。典型现象是控制台出现 CORS 报错。

Ollama 与 LM Studio 的接口对比如下。端口与路径可能随版本调整,请以官方文档为准。

项目 Ollama LM Studio
默认端口 11434 1234
对话接口 /api/chat,原生格式,流式输出为逐行 JSON /v1/chat/completions,OpenAI 兼容格式,流式输出为 SSE
流式结束标记 返回对象中 done 为 true 数据流末尾为 data: [DONE]
模型列表 /api/tags /v1/models

Ollama 也提供 /v1 兼容接口。同一个项目只选一种格式,不要在原生接口和兼容接口之间混用。

四、超时与重试的写法

超时和重试必须同时设置上限。下面的函数限制了单次请求超时时间和最大重试次数,只对网络错误、5xx 和 429 进行重试,其他 4xx 直接抛出错误:

```javascript
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
const backoff = (attempt) =>
Math.min(1000 2 ** attempt, 8000) + Math.random() 200;

async function callWithRetry(url, body, maxRetries = 3, timeoutMs = 30000) {
for (let attempt = 0; attempt <= maxRetries; attempt++) {
const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), timeoutMs);
let res;
try {
res = await fetch(url, {
method: “POST”,
headers: { “Content-Type”: “application/json” },
body: JSON.stringify(body),
signal: controller.signal,
});
} catch (err) {
// 网络错误或超时
if (attempt === maxRetries) throw err;
await sleep(backoff(attempt));