扣子平台配置第三方模型供应商 API 时,Base URL、模型 ID 和鉴权密钥分别该怎么填才不会调不通?

在扣子平台的模型供应商入口填入 Base URL、API Key 与模型 ID 三项即可接入,但只有提供标准 chat/completions 接口的服务能直接生效;地址要写到 /v1 层级,密钥用单独签发的推理密钥,模型 ID 与供应商侧保持一致,再按连通性、多轮对话、工具调用的顺序逐项验证。

扣子平台配置模型供应商 API 的核心动作,是在「模型供应商」或「自定义模型」入口填入三项内容:请求地址(Base URL)、鉴权密钥(API Key)和模型标识(Model ID),然后用平台自带的连通性测试确认这条通道支持标准对话补全协议。这套流程只适用于提供 /v1/chat/completions 这类标准接口的服务;如果对方使用私有签名协议,或者只提供向量化能力,就要先加一层协议转换,否则字段填得再准也调不通。 入口的位置比字段本身更容易出错。扣子的模型配置分散在资源库的模型列表与工作空间的模型管理两处,个人版与团队版、国内站点与海外站点的菜单命名并不一致,先确认自己当前所在的工作空间再操作,否则会出现配好了、智能体里却选不到的落差。稳妥的做法是先在空白智能体里试着挂载一次,确认下拉列表能选到,再回填到正式项目。 Base URL 要写到协议版本前缀,而不是只写域名根路径。多数兼容接口的完整形式是 https://域名/v1,平台调用时会自行拼接 /chat/completions,只填域名的话拼接后路径就会变成 404。最快的判断方法是在本机用同一份地址和密钥发一条 POST 请求,返回结构里能拿到 choices 数组,说明路径层级正确,再去平台里填。 API Key 应该用单独签发的推理密钥,不要复用控制台的主密钥。主密钥通常带账户管理权限,一旦写进智能体配置并被多人协作调用,泄露面会明显放大;推理密钥则可以单独设额度、单独吊销。建议为扣子单独建一个子密钥并记录签发时间,后续轮换只换这一把,不影响其他业务。 模型 ID 必须与供应商侧完全一致,大小写和版本后缀都不能猜。带日期后缀或轻量版后缀的模型,在部分服务里属于两个独立计费项,填错后缀不一定报错,而是被路由到能力更弱的版本,表现为能正常回答但工具调用总是失败。填完后先在测试会话里发一条需要触发插件的指令,确认函数调用真的生效。 参数映射比字段填写更影响可用性。需要对齐上下文窗口、最大输出长度、是否支持流式返回、是否支持工具调用这四项,其中工具调用最关键——扣子的插件节点与工作流节点依赖模型返回结构化的调用请求,不支持函数调用的模型只能做纯问答。遇到回答正常但插件不触发的情况,先查这一项,而不是反复改写提示词。 验证要按顺序做,跳步会掩盖问题。顺序是连通性测试、单轮问答、多轮上下文记忆、插件调用、知识库召回、并发压测;每一步失败对应的排查面完全不同,混在一起测只会得到「有时好用有时不好用」的模糊结论。建议每一步都留下请求与响应样本,作为后续变更时的对照基线。 错误码要按层归因,不要一律当成密钥错误。401 与 403 多为密钥无效或权限不足,404 多为 Base URL 路径层级不对,429 是额度或并发触顶,5xx 是上游服务自身异常,能区分这四类,排查时间通常能压缩一半以上。平台侧报错往往是二次封装的,必要时抓上游原始响应体再判断。 有几类服务不适合直接填进平台。一是使用自定义签名机制的云厂商原生接口,二是只提供向量化或重排能力的服务,三是返回结构不符合 choices 数组的私有协议;它们都需要中间层做协议转换与字段裁剪。判断方法很简单:用最朴素的 POST 请求能否拿到标准对话结构,拿不到就说明必须先适配。 成本要按 token 与调用次数两条线同时看。供应商侧按输入输出 token 计费,平台侧按调用次数与资源占用计量,两条线口径不同,容易在月度账单上出现偏差;给智能体设置单次会话上限和日预算上限,比事后对账更有效。上线前先用真实话术样本跑一轮压测,拿到单次会话的平均 token 消耗,再换算成可承受的日活规模。 上线后的运维重点是密钥轮换与模型版本锁定。供应商下线某个模型版本时不会同步通知所有接入方,配置里写死一个浮动别名会在某天突然改变回答风格;把版本号固定下来、变更时走灰度,是客服类智能体最稳妥的做法。同时保留一条备用通道,主通道遇到 429 或 5xx 时能够切换。 在客服接待场景里,模型通道只是下限,不是上限。知识库的分段粒度、召回条数、兜底话术的触发条件,对最终答复质量的影响往往大于换一个更强的模型;把通道配置与知识运营分开评估,才不会把所有问题都归因到模型供应商这一层。