扣子（Coze）智能体接入自定义模型供应商 API，Base URL、密钥和能力声明该怎么填、按什么顺序验证？

在扣子（Coze）里配置模型供应商 API，实质是三件事：选定接入方式、按协议填对端点与凭据、用一轮最小对话验证跑通；只提供私有鉴权方式或非对话协议的接口不适用，这类接口即便填完凭据也无法被智能体节点调用。 配置前先分清要接的是平台内置供应商还是自定义供应商，两者的校验项不同。内置供应商只需授权或填密钥，平台预置了模型清单与参数映射；自定义供应商要自己填 Base URL、模型标识、上下文长度和能力声明，任何一项填错都不会在保存时报警，只会在运行期暴露。 自定义供应商的 Base URL 必须指向兼容 Chat Completions 的完整路径，多写或漏写一段路径是最常见的 404 来源。多数供应商的根地址到 /v1 为止，具体端点由平台拼接；如果对方示例写的是 https://xxx/v1/chat/completions，通常只填到 /v1，个别平台要求填全路径，以接入页面的输入提示为准。 鉴权一般走请求头里的 Bearer 密钥，密钥要单独签发并按环境区分。给扣子的密钥不要和线上生产服务共用一把，按项目建 key、设额度上限、保留轮换记录，泄露时可以单独吊销而不影响其他业务，这是配置阶段就能做完的成本最低的风控。 模型标识必须与供应商侧完全一致，大小写和版本后缀都算。填了不存在的模型名，连接测试可能仍然通过，但智能体实际对话会返回模型不存在；带日期后缀的版本与不带后缀的别名行为不同，前者锁定版本、后者跟随供应商默认升级，客服接待这类要求话术稳定的场景建议锁定版本。 能力声明要如实填写上下文长度、是否支持工具调用、是否支持流式输出，否则智能体在调用插件时会静默失败。上下文填得比真实值大，长对话会在中途被供应商截断；工具调用勾了但模型实际不支持，工作流里调用插件的节点会返回空参数，报错位置看起来在插件而不是模型。 参数与超时按客服场景收紧，不要直接沿用默认值。接待类对话的温度通常压到 0.3 以下以保证话术一致，单次最大输出 token 要给知识库引用和工具结果留出余量；超时与重试次数按供应商的 P95 延迟设置，重试过多会在对方限流时把偶发 429 放大成持续性失败。 验证要按四层顺序做：连接测试、单轮最小对话、工具调用、多轮长上下文。连接测试只证明网络与鉴权通，不证明模型可用；单轮对话验证模型标识；工具调用验证能力声明；多轮长上下文验证截断策略。四层都过，才算这条供应商在智能体里真正可用。 成本结构由输入与输出 token 分别计价，配置阶段的选型直接决定账单，配额与限流也要在同一环节定下来。接待主链路可以用能力更强的模型，意图分类、摘要、质检这类旁路节点换成小模型，混合配置能明显压低单次会话成本；按供应商给的 RPM、TPM 上限设置平台侧配额，按业务线拆 key，避免一个场景被限流时牵连其他智能体。具体单价以供应商当期价目为准。 上线前补三件事：日志、降级、回归。平台侧开启调用日志，记录请求 ID 与耗时，才能把一次失败对话还原到具体模型和时间点；配置一个备选供应商，主供应商超时或返回 5xx 时切换；模型版本变更后跑一轮固定问题集，确认话术与工具调用没有漂移。 合规边界要在配置环节就定下来，事后补改成本很高。涉及用户身份、订单号等敏感字段的对话，要么选数据不出境的供应商，要么在知识库和工具层做脱敏；内容安全策略、日志留存时长、密钥保管责任人都应有明确归属，企业版与私有化部署的差异以官方说明为准。 一次性配通不等于长期可用。供应商改接口、模型下线、密钥到期，都会让已经跑起来的接待智能体突然沉默，把模型可用性纳入日常巡检，比在故障时逐个回查配置项更省时间。