★ FEATURED ARTICLE 1. 为什么要把火山方舟模型接进统一网关火山方舟是字节跳动旗下的模型服务平台上面跑着豆包系列、以及不少第三方开源模型。很多团队一开始是直接在业务代码里硬编码方舟的 API Key 和 endpoint跑通一个 demo 没问题但只要模型一多、业务线一多问题就全冒出来了Key 散落在各个项目里、用量没法统一看、想换个模型得改代码重新发版、限流和重试逻辑每个项目各写一套。我自己的做法是把火山方舟当成一个上游供应商前面挂一层统一网关。网关这一层负责鉴权、计费、路由、日志、限流业务侧只认网关的地址和 Key完全不关心后面接的是方舟还是别的平台。这样做的直接好处是换模型、加模型、调价格都只动网关配置业务代码一行不改。标题里提到的new-api和sub2api就是干这件事的两个工具定位不太一样我后面会拆开讲。核心思路是new-api 做统一网关多上游聚合 按量计费 令牌分发sub2api 做订阅转 API把包月订阅额度转成标准 API 接口。两者可以单独用也可以串起来用。这篇文章适合三类人看一是手里有火山方舟账号、想把模型统一管起来的后端或运维二是想用订阅制额度对外提供 API 的小团队或个人开发者三是单纯想搞明白网关这一层到底该放什么的技术负责人。我会把配置、参数、踩坑点都写清楚尽量让你照着做就能跑起来。提示本文所有配置均基于常见实践整理具体参数以你实际使用的版本为准。涉及计费的部分务必以火山方舟官方控制台显示的单价为准网关里的价格配置只是用于内部核算。2. new-api 与 sub2api 的定位拆解2.1 new-api 到底解决什么问题new-api 是一个开源的 LLM 网关项目前身是 one-api 的分支社区活跃度比较高。它的核心能力可以概括成四件事多上游聚合一个网关后面可以挂 OpenAI、Claude、Gemini、火山方舟、智谱、DeepSeek 等一堆渠道对外暴露统一的 OpenAI 兼容接口。令牌分发给每个业务方发一个网关自己的 Key通常叫令牌 token业务方拿这个 Key 调网关网关再拿真实的上游 Key 去调模型。按量计费网关按 token 用量乘以你配置的单价算出每个令牌花了多少钱可以设额度上限用完自动停。日志与统计每次调用都有记录谁调的、调了哪个模型、用了多少 token、花了多少钱一目了然。为什么选它而不是自己写一层因为自己写网关最麻烦的不是转发请求而是计费口径和渠道故障转移。new-api 把这两块做得很成熟计费支持按输入/输出分别定价渠道支持优先级和自动重试。你自己从零写光是对齐各家 token 计数口径就得折腾很久。2.2 sub2api 的适用场景sub2api 的定位更垂直把订阅制的额度转换成标准 API。典型场景是你买了一个包月套餐比如某个平台的会员额度但这个额度只能在其官方客户端里用没法直接给程序调用。sub2api 做的事情就是模拟客户端行为把订阅额度包装成 OpenAI 兼容的 API 接口。它和 new-api 的关系是互补的sub2api 负责把订阅变成 APInew-api 负责把 API 统一管理并计费。你可以把 sub2api 当成 new-api 的一个上游渠道接进去这样对外就只有一个网关入口。注意sub2api 这类工具的使用要严格遵守对应平台的服务条款。本文只讨论技术实现思路是否合规使用请自行判断我不做任何合规性背书。2.3 两者组合的架构长什么样把两者串起来数据流是这样的业务方 → new-api 网关鉴权/计费/路由 ↓ ┌─────┴─────┐ ↓ ↓ 火山方舟渠道 sub2api 渠道 按量计费 订阅转 API业务方只需要知道 new-api 的地址和令牌。new-api 根据你配置的渠道优先级决定这次请求走方舟还是走 sub2api。如果方舟渠道报错可以自动切到 sub2api反之亦然。这就是统一网关的价值——对上游做冗余对下游做统一。3. 火山方舟渠道的接入配置3.1 拿到方舟的接入信息在火山方舟控制台里你需要准备三样东西API Key在API Key 管理里创建注意保存页面关闭后不再完整显示。模型 Endpoint ID方舟的调用方式和 OpenAI 略有不同它用的是 endpoint id形如ep-xxxxxxxx而不是模型名。你需要在在线推理里为每个模型创建一个接入点拿到对应的 endpoint id。Base URL方舟的 OpenAI 兼容接口地址通常是https://ark.cn-beijing.volces.com/api/v3这种形式具体以控制台文档为准。这里有个新手最容易踩的坑方舟的模型名和 endpoint id 是两回事。你在 new-api 里填模型名的时候如果填的是doubao-pro-32k这种请求会失败必须填ep-开头的 endpoint id。我一开始就栽在这报错信息还比较隐晦排查了半天。3.2 在 new-api 里新建方舟渠道进入 new-api 后台渠道管理里新增渠道关键字段这样填字段填写内容说明渠道类型自定义渠道 / OpenAI 兼容方舟兼容 OpenAI 协议渠道名称火山方舟-豆包自己看得懂就行Base URL方舟的 v3 地址注意结尾不要多斜杠密钥方舟 API Key多个 Key 可以换行填模型ep-xxxxxxxx填 endpoint id不是模型名分组default按业务分组管理模型那一栏可以填多个 endpoint id用英文逗号分隔。如果你有多个接入点建议每个接入点单独建一个渠道这样计费和故障隔离更清晰。3.3 计费单价怎么配new-api 的计费是按每 1K token 多少额度来算的。方舟的官方计费单位是元/千 token你需要做一个换算。假设方舟某模型输入 0.0008 元/千 token输出 0.002 元/千 token而你在 new-api 里设置的额度换算比例是 1 元 500000 额度这个比例在系统设置里配那么输入单价 0.0008 × 500000 / 1000 0.4 额度/1K token输出单价 0.002 × 500000 / 1000 1.0 额度/1K token这个换算一定要自己算一遍别直接抄别人的数字因为每个人的额度比例设置不一样。算错了要么亏要么贵对不上账很麻烦。实操心得我习惯把额度比例设成 1 元 500000 额度这样单价数字比较整心算方便。你也可以设成 1 元 1000000看个人习惯。4. sub2api 的部署与对接4.1 部署前的环境准备sub2api 一般是 Node.js 或 Python 写的服务部署方式看具体项目。常见做法是用 Docker 跑省得折腾依赖。你需要准备一台能访问目标平台的服务器网络要通Docker 和 docker-compose如果用容器部署一个空闲端口比如 8080部署命令大致是这样以 Docker 为例docker run -d \ --name sub2api \ -p 8080:8080 \ -e API_KEYyour_sub2api_key \ -e UPSTREAM_TOKENyour_subscription_token \ your_sub2api_image环境变量的名字各项目不一样具体看项目的 README。核心就是两个一个是 sub2api 自己对外提供的 Key一个是它用来访问上游订阅的凭证。4.2 把 sub2api 接进 new-apisub2api 跑起来之后它对外就是一个 OpenAI 兼容接口。在 new-api 里再建一个渠道渠道类型选 OpenAI 兼容Base URL 填http://你的sub2api地址:8080/v1密钥填 sub2api 的 API Key模型填 sub2api 支持的模型名这样 new-api 就有两个上游了。你可以在渠道里设置优先级比如方舟优先级 1、sub2api 优先级 2方舟挂了自动切 sub2api。4.3 订阅转 API 的常见报错标题热词里出现了unexpected status 401 unauthorized: incorrect api key provided: sk-svcac****这个报错在 sub2api 场景里很典型。它说明上游拒绝了你的 Key可能的原因有订阅凭证过期了需要重新登录获取Key 复制的时候带了空格或换行上游平台改了鉴权方式sub2api 版本太旧没跟上排查顺序建议是先确认凭证本身有效用官方客户端能正常用再确认 sub2api 日志里实际发出去的请求头最后看是不是版本问题。我遇到过好几次都是凭证过期重新抓一次就好。5. 统一网关的进阶玩法5.1 多渠道负载与故障转移new-api 支持给同一个模型配多个渠道然后设置不同的权重。比如你有两个方舟账号可以都配上权重各 50%这样单个账号限流了另一个还能顶。故障转移的逻辑是请求失败后自动重试下一个渠道重试次数可以配。这里要注意重试的代价。如果失败发生在生成到一半的时候重试会导致重复计费。所以对于流式输出建议把重试次数设小一点或者只在连接阶段失败时重试。5.2 令牌额度与分组管理给每个业务方发一个独立令牌设置额度上限和过期时间。这样某个业务方用量异常你能第一时间定位也能直接停掉它的令牌而不影响别人。分组功能可以把令牌归类比如生产组测试组分别配不同的渠道策略。5.3 日志与用量对账new-api 的日志页面能看到每次调用的详情。我一般每周导出一次日志和方舟控制台的用量对一下看有没有对不上的地方。对账主要看两个数总 token 数和总费用。如果网关算出来的费用明显低于方舟账单可能是某些模型的单价配低了如果明显高于可能是重试导致的重复计费。6. 常见问题与排查速查表现象可能原因排查方向401 incorrect api keyKey 错误或过期检查 Key 是否完整、是否过期400 maximum context length上下文超长检查输入 token 数方舟部分模型上限 32K模型不存在填了模型名而非 endpoint id改成 ep- 开头的接入点 ID计费对不上单价换算错误重新核对额度比例和单价请求超时上游限流或网络问题看方舟控制台限流记录加渠道冗余sub2api 无响应服务挂了或凭证失效看容器日志重新获取凭证关于400 this models maximum context length is 1048576 tokens这个报错虽然数字很大但实际能用的上下文往往受你账号等级和模型版本限制。别看到 1M 就真往里塞 1M先小批量测一下实际可用上限。7. 我踩过的几个坑第一个坑是方舟 endpoint id 和模型名混淆前面说过了不再重复。第二个坑是额度比例和单价没对齐导致内部账单和实际支出差了一大截后来我固定用一张表格记录每个模型的官方单价和网关单价每次调价都更新。第三个坑是sub2api 的凭证过期没有告警某天业务突然全挂查了半天才发现是订阅凭证失效。后来我在 new-api 里配了渠道健康检查定时发一个最小请求探活失败就告警。还有一个细节方舟的流式输出和 OpenAI 的格式基本兼容但个别字段有差异比如usage字段在某些版本里流式返回时是空的。如果你依赖 usage 做计费建议在网关侧自己统计或者用非流式请求做对账。最后分享一个小技巧new-api 的渠道可以配模型重定向把业务侧用的模型名映射到实际的 endpoint id。这样业务代码里写的是doubao-pro网关自动转成ep-xxxxxxxx换接入点的时候只改映射表业务无感。这个功能在多环境测试/生产用不同接入点场景下特别好用。
阅读完成 · 觉得有帮助？
