1. 为什么需要一个 Go 写的 AI 模型 API 统一网关如果你手上同时用着 OpenAI、Claude、Gemini、DeepSeek、通义千问、智谱甚至本地 Ollama大概率会遇到一个很烦的问题每个平台的 Base URL、鉴权方式、请求体字段、返回结构都不一样。写业务代码时每接一家就要改一次 SDK 初始化密钥散落在各个.env里想统计一下这个月谁烧的 token 多还得挨个登录后台翻账单。One API 就是来解决这件事的。它是一个用 Go 语言开发的开源大模型网关核心能力是把多家 AI 模型 API 统一收敛到一个入口对外只暴露一套 OpenAI 兼容接口。你原来的代码只要认 OpenAI 的/v1/chat/completions就能通过它路由到任意后端渠道。它适合三类人一是同时接多家模型做对比或降级的产品开发者二是想给团队内部做一个统一 Key 分发入口的技术负责人三是自己折腾多个模型、希望用一个面板管理额度和渠道的个人开发者。Go 语言带来的好处很直接编译成单个二进制、内存占用低、并发处理 stream 流式响应稳。实测在一台 1 核 1G 的小机器上跑日常几十路并发请求内存也就几十 MB。这篇文章我会从部署、渠道配置、令牌分发、curl 验证路由到常见报错排查完整走一遍配置片段都可以直接复制。需要说明的是One API 本身是网关它不生产模型能力只是把你已有的各家 API Key 聚合起来做转发和分发。所以第一步你得先有至少一个可用的上游模型 Key比如某云厂商的 API Key或者本地 Ollama 的地址。2. 部署 One API 与 TaoToken 前置准备2.1 用 Docker Compose 起一个 One API最省事的方式是 Docker。新建一个目录比如one-api-demo在里面创建docker-compose.ymlversion: 3 services: one-api: image: justsong/one-api:latest container_name: one-api restart: always command: --log-dir /app/logs ports: - 3000:3000 volumes: - ./data:/data - ./logs:/app/logs environment: - SESSION_SECRETchange_this_to_a_random_string - TZAsia/ShanghaiSESSION_SECRET一定要改成一串随机字符否则会话安全性没保障。./data挂载出来是为了持久化数据库容器重建后渠道和令牌不会丢。启动docker-compose up -d docker logs -f one-api看到日志里出现监听 3000 端口的提示就说明起来了。浏览器访问http://你的服务器IP:3000默认账号密码是root / 123456登录后第一件事就是改密码。2.2 准备上游模型渠道以 TaoToken 为例One API 需要至少一个上游渠道才能转发。这里我用 TaoToken 作为上游示例它提供 OpenAI 兼容接口接入 One API 很顺。先到官网注册并拿到 API Key官网地址https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content拿到 Key 之后在 One API 后台点「渠道」→「添加新的渠道」。关键字段这样填字段填写内容类型OpenAI名称taotoken分组default模型按需填如 gpt-4o,claude-3-5-sonnet代理留空密钥你的 TaoToken API Key代理地址https://taotoken.net/api注意「代理地址」这里填的是上游的 Base URLOne API 会在后面自动拼/v1/chat/completions。填完点「提交」然后点渠道右侧的「测试」按钮如果返回绿色成功说明这条渠道通了。如果你还想接本地 Ollama再加一个类型为 Ollama 的渠道代理地址填http://你的内网IP:11434即可。多个渠道可以同时存在One API 会按你配置的规则做负载均衡。2.3 创建对外分发的令牌渠道通了之后点「令牌」→「添加新的令牌」。这里有几个参数值得注意名称随便起比如team-dev额度可以设成 0 表示不限制也可以设具体金额过期时间按需分组和渠道分组对应创建完会生成一个sk-开头的令牌这个才是你业务代码里要用的 Key。上游的真实 Key 被 One API 藏起来了对外只暴露这个令牌这样团队成员用的时候你随时可以吊销不影响上游。3. 可复制的 One API 配置与分发规则3.1 渠道配置的 JSON 结构One API 的渠道本质是一条条记录如果你要批量导入可以用它的管理 API。下面是一个渠道配置的等价 JSON 结构方便你理解字段含义{ name: taotoken, type: 1, base_url: https://taotoken.net/api, models: gpt-4o,claude-3-5-sonnet,deepseek-chat, group: default, priority: 0, weight: 1, status: 1 }type: 1代表 OpenAI 兼容类型。weight是权重多个同组渠道时按权重分配流量。priority优先级高的先被选中失败再降级到低的。3.2 模型映射与重命名One API 支持模型映射这个功能很实用。比如你希望对外统一叫my-gpt实际路由到gpt-4o可以在渠道的「模型重定向」里填{ my-gpt: gpt-4o, my-claude: claude-3-5-sonnet }这样客户端请求my-gptOne API 会自动改写成gpt-4o再发给上游。好处是以后换供应商客户端代码一行都不用动。3.3 指定渠道与负载均衡如果你有多个渠道都提供同一个模型One API 默认会按权重随机分发。想强制走某个渠道可以在令牌后面加-渠道ID比如令牌是sk-abc渠道 ID 是 3那请求时用sk-abc-3就会固定走 3 号渠道。这个在排查某个渠道问题时特别有用。负载均衡方面把多个渠道设成同一个分组、同一个模型权重都设 1请求就会均匀打散。如果某个渠道挂了One API 会自动重试下一个可用渠道前提是你在「系统设置」里开启了失败重试。3.4 用 settings 片段控制全局行为One API 的系统设置里有一些关键开关对应到配置层面大致是这些{ retry_times: 2, stream_support: true, channel_disable_threshold: 3 }retry_times是失败重试次数channel_disable_threshold是渠道连续失败多少次自动禁用。这几个值建议按你的稳定性要求调生产环境重试 2 次、失败 3 次禁用比较稳妥。4. 用 curl 验证多模型路由是否生效配置完别急着写业务代码先用 curl 把路由验证一遍。假设你的 One API 部署在http://127.0.0.1:3000令牌是sk-your-token。4.1 验证基础对话接口curl http://127.0.0.1:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-token \ -d { model: gpt-4o, messages: [{role: user, content: 用一句话说明什么是网关}], stream: false }如果返回结构里有choices[0].message.content说明整条链路通了客户端 → One API → TaoToken → 模型 → 原路返回。4.2 验证模型映射如果你配了my-gpt到gpt-4o的映射把上面的model换成my-gpt再请求一次返回应该和直接请求gpt-4o一致。这一步能确认重定向规则生效。4.3 验证 stream 流式输出curl http://127.0.0.1:3000/v1/chat/completions \ -H Content-Type: application/json \ -H Authorization: Bearer sk-your-token \ -d { model: claude-3-5-sonnet, messages: [{role: user, content: 数到五}], stream: true }正常会看到一行行data: {...}陆续输出最后以data: [DONE]结束。如果卡住不动多半是上游不支持 stream 或者网络层缓冲了检查渠道配置里的 stream 开关。4.4 验证指定渠道用sk-your-token-3这种带渠道 ID 的令牌再请求一次然后去 One API 后台的「日志」里看这条请求应该记录在 3 号渠道上。日志里能看到模型、耗时、token 消耗方便对账。5. 常见报错排查5.1 401 Unauthorized最常见的就是 401。分两种情况一是你请求 One API 时令牌错了检查Authorization: Bearer后面的值是不是后台生成的sk-令牌别把上游 Key 填进来了二是 One API 转发到上游时上游返回 401这时候去渠道测试里看多半是上游 Key 失效或代理地址填错。注意代理地址不要多写/v1One API 会自己拼。5.2 local proxy failed / 连接超时如果日志里出现local proxy failed或dial tcp timeout说明 One API 所在机器访问不到上游地址。先curl一下上游 Base URL 确认网络可达。如果是容器部署注意容器内的 DNS 和宿主机可能不同必要时给容器配dns或改用宿主机网络模式。5.3 reading choices 字段为空报错类似invalid response: reading choices通常是上游返回了非标准结构或者上游本身报错但 HTTP 状态码是 200。去渠道测试里看原始返回确认上游是不是返回了{error: ...}。这种情况多半是模型名写错了上游不认识这个 model。5.4 OAuth 相关报错如果你接的是需要 OAuth 的渠道比如某些云厂商报错里带OAuth字样说明鉴权方式选错了。One API 里不同渠道类型对应不同鉴权OpenAI 兼容类型只认 Bearer Token。需要 OAuth 的要用对应的渠道类型别硬套 OpenAI 类型。5.5 渠道自动被禁用如果发现渠道莫名其妙变成禁用状态看下「系统设置」里的失败阈值。连续失败达到阈值会自动禁用避免拖垮整体。排查完上游问题后手动把渠道重新启用即可。建议把阈值设成 3 以上避免偶发网络抖动误伤。6. 把统一入口接进你的开发流到这里一套可用的统一 API 管理与分发入口就跑起来了。你对外只需要记住一个 Base URL 和一个令牌所有模型都从这一个口子走。业务代码里把 OpenAI SDK 的base_url指向 One APIapi_key填生成的令牌就能在多个模型之间自由切换。如果你还想进一步做长期编码或 Agent 类应用可以了解下 TaoToken 的 Coding Plan配合 One API 做上游渠道额度管理会更清晰Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite想直接在网页里试模型效果可以用模型对话入口模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite需要管理 API Key 或查看接入文档时API Keyshttps://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite最后分享一个我踩过的坑One API 的日志默认只保留一段时间如果你要做成本核算记得定期把日志导出或者接一个外部统计。另外渠道的权重别一次性调得太激进先小流量跑几天确认稳定再放大。
