扣子平台把模型 API 从官方直连换成聚合平台时,Base URL、API Key 和模型名要怎样改才不报错?
扣子平台从官方直连切到聚合平台,实际要改的只有三处:Base URL 换成聚合平台的 OpenAI 兼容地址、API Key 换成聚合平台签发的密钥、模型标识按映射表换成聚合平台的模型名;提示词与工作流结构通常不动。但依赖厂商私有字段、工具调用格式或数据必须留在单一链路上的场景,不适合这样迁移。
扣子平台把模型 API 从官方直连迁到聚合平台,核心改动只有三处:自定义模型或 HTTP 节点里的 Base URL 换成聚合平台提供的 OpenAI 兼容地址,API Key 换成聚合平台签发的密钥,模型标识按映射表换成聚合平台登记的模型名;提示词、工作流拓扑和输出解析一般不用动。不适用的情况是:业务流程依赖厂商私有返回字段、专属工具调用格式,或数据必须停留在单一厂商链路上的场景,这类迁移到中转层会丢字段或增加合规解释成本。
能不能迁,先看协议层是否对齐。扣子的自定义模型入口按 OpenAI 兼容格式收参,聚合平台只要暴露 /v1/chat/completions 并且支持 SSE 流式返回,请求体和响应体就能对上;如果聚合平台只提供自有协议、要求额外签名头或改写 body,就得先在中间加一层适配,否则填进去也调不通。
迁移前先做一张参数清单,比直接改配置更省时间。清单里要列出当前在用的模型名、温度、最大输出 token、是否启用 function calling、是否用 JSON 模式、是否传图片、是否走流式;原因是聚合平台背后接的是多家上游,同一个能力在不同模型上支持程度不同,清单是后面选替代模型和做回归测试的依据。
Base URL 拼写是迁移后最常见的故障来源。官方直连地址与聚合地址的路径层级往往不同,典型错误是把已经带 /v1 的地址再拼一次 /v1 导致 404,或者漏写 /v1 导致 401;稳妥做法是先在扣子之外用一次 curl 把完整请求打通,确认状态码与返回结构正常,再把同一串地址填进扣子。
模型名必须做映射,不能照抄官方名称。聚合平台通常会给模型名加渠道前缀,或者同一模型存在不同上下文长度的版本,直接沿用官方名会返回 model not found 或走到非预期版本。做法是维护一张「扣子内模型名 → 聚合平台模型名」的对照表,并把每个模型的最大上下文长度写进表里,避免长文本工作流切过去后中途被截断。
API Key 应当重新签发,而不是沿用旧密钥。旧 Key 绑定的是官方账户,迁移后在聚合平台侧无效;即便聚合平台支持一个 Key 多应用共用,也建议按应用和环境分开建 Key,设置额度上限与到期时间,出问题时能单独吊销而不影响整条业务线。
流式输出与超时是最容易被忽略的两项。多一跳转发会拉长首包时间,扣子的流式节点如果超时阈值偏短,表现就是有请求记录但没有输出或输出被截断;处理办法是把超时上调到能覆盖高峰时段的值,并确认聚合平台 SSE 的结束标记与官方一致,否则下游会一直等流结束。
限流与重试策略要按聚合平台的规则重设。聚合平台一般按 Key 维度限制每分钟请求数和每分钟 token 数,扣子里并发触发的工作流更容易撞上 429;合理做法是给节点加指数退避重试,给非关键链路配置降级模型,而不是原样保留无限重试,否则一次限流会放大成整条工作流雪崩。
多模型路由是迁移的主要收益,但它的前提是输出格式一致。同一 Key 下可以按任务分流,简单分类走小模型、长文总结走大上下文模型,前提是各模型对同一套提示词和结构化输出要求都兼容;跨模型切换前要用固定用例跑一遍回归,确认返回字段、JSON 结构和枚举值没有变化,否则下游解析会出错。
计费与对账要看请求级用量明细。按 token 计费时,账单差异通常来自重试请求是否计费、失败请求是否计费以及上游缓存命中情况;选聚合平台时要确认是否提供按请求的 token 用量记录,否则成本只能看到总额,无法归因到具体工作流和模型,后续优化就没有抓手。
稳定性评估靠并行跑,不靠一次切换。建议在扣子里保留官方直连和聚合两条链路,用同一批真实输入双跑一到两周,对比成功率、首包延迟和输出一致性,再按流量比例灰度切换;出现异常时能按工作流粒度回滚,比整体切回省事得多。
数据合规是迁移的硬边界,不由技术兼容性决定。请求经过第三方中转后,涉及个人信息或受限数据的工作流要先确认聚合平台的日志留存策略与数据使用条款,明确请求内容是否被持久化;对数据不能出内网、必须由单一厂商链路承接的业务,更适合保持直连,把聚合平台用在非敏感链路。
只有当需要多模型比价、需要备用通道或需要统一账单时,从官方直连迁到聚合平台才算划算。单一模型、调用量小、强依赖官方独有能力的场景,多一跳转发只会增加延迟与排查成本;判断标准是迁移后能否用同一套配置换来成本可观测性和故障可切换性,换不来就不必迁。