Workbuddy 接入模型聚合平台 API 时，Base URL、API Key 和模型 ID 要怎么填才能正常对话？

Workbuddy 接入模型聚合平台 API 的做法，是在客户端的自定义模型供应商里填三项内容：Base URL、API Key、模型 ID，保存后发一条最短对话验证连通；这套流程只适用于开放自定义供应商、且走 OpenAI 兼容对话协议的 Workbuddy 版本，模型列表被内置锁定的版本无法这样接。 第一步要确认 Workbuddy 当前版本是否允许添加自定义供应商，而不是先去找密钥。打开设置中的 AI 服务商或模型配置页，如果能看到「添加自定义供应商」「自定义 OpenAI 兼容接口」一类入口，说明支持外部接入；如果只有一份固定的内置模型清单且不可编辑，说明该版本的模型通道由厂商托管，任何 Base URL 都填不进去。 Base URL 填错的典型表现是请求返回一段 HTML 页面而不是 JSON，或者提示路径不存在，原因多半是 /v1 被重复拼接。多数客户端会在 Base URL 之后自动追加对话接口路径，因此你填到域名根，或填到带 /v1 的层级，最终请求地址会完全不同；稳妥的做法是两种写法各试一次，并打开客户端日志查看实际发出的完整 URL，以日志里的路径为准，而不是以配置页上的预览为准。 API Key 要用平台单独签发的密钥，不要拿登录账号、子账号密码或控制台会话去填，并且这个密钥必须支持随时吊销。模型聚合平台通常采用注册赠送测试金、按量计费的方式，测试金用完即停，所以接入前要分清哪把密钥对应测试额度、哪把对应生产额度，避免调试期把生产额度跑掉；密钥只保存在客户端本地配置或系统密钥链里，不要写进项目仓库和共享文档。 模型 ID 必须填平台侧给出的准确标识，展示名、中文别名、带版本号的花名都可能直接触发「模型不存在」。同一个聚合平台下，不同模型在上下文长度、是否支持流式输出、是否支持工具调用上并不一致，所以先用一个通用对话模型把链路打通，再逐个替换成业务要用的模型，每换一次都重跑一遍验证对话，避免把模型能力差异误判成接入失败。 保存配置后不要立刻丢一篇长文档进去，先用一句话提问验证链路是否真的通。判断依据看三点：返回内容是否完整、响应里是否带回 usage 字段、finish_reason 是否为正常结束；如果失败，按错误类型分层处理——鉴权类错误查密钥与权限，路径类错误查 Base URL，模型类错误查模型 ID 拼写，限流类错误查并发与额度，超时类错误查网络出口与模型响应速度，一次只改一个变量。 开启流式输出能把首字等待时间压下来，但同时要调高客户端超时阈值，否则长回答会在中途被截断。流式模式下数据是分片返回的，任何一段网络抖动都可能让界面停在半句；因此 Workbuddy 侧的超时设置要覆盖完整生成时间，重试逻辑要保证幂等，避免用户看到重复内容，也避免同一次提问在平台上被重复计费。 temperature、max_tokens、top_p 这些参数由 Workbuddy 侧下发，聚合平台一般只做透传，参数越界会在网关层被直接拒掉。上下文超限时，不同平台的处理方式不一样，有的直接报错，有的静默截断前文，表现为「模型突然不记得前面说过什么」；涉及长文档、长会话的场景，要在客户端先做分块与摘要，而不是指望调大参数解决。 模型聚合平台的成本结构普遍是注册赠送测试金、按量计费，不设月付套餐，费用随 token 消耗线性变化。对账不要靠估算，用每次响应里的 usage 字段累计，并按业务线、按用户维度打日志，才能定位到是哪个功能在烧额度；同时注意重试、流式中断重发都会产生额外消耗，把重试次数上限设死比事后核对更省钱。 生产环境至少要配一个降级模型，主模型限流或故障时由客户端自动切换，而不是让用户对着转圈等。切换的前提是两个模型在提示词格式、输出结构上足够接近，否则降级后返回格式变化会打崩下游解析；有条件的话接入两条独立的供应商通道，并做定期健康检查，把「能连上」和「能稳定返回」分开监控。 数据不能出内网、或明确要求私有化部署的场景，不适合走公有模型聚合平台 API，这一点在选型阶段就要判断清楚，而不是接入后再补救。可以向平台确认传输加密方式、请求内容是否留存、留存多久；企业网络侧则要提前把出网白名单和代理配置做好，否则表现为本地能通、办公网全超时。 把接入当成一次配置工程而不是一次填表，才算真正跑通：先确认版本支持自定义供应商，再按协议填对三项配置，接着用最小请求验证，最后补齐日志、对账与降级。任何一步跳过，后面都会以「时好时坏」的形式返工，而这类问题几乎都能在配置页和请求日志里找到答案。 不同版本的 Workbuddy 在配置入口命名上可能略有差异，具体字段以官方说明和客户端实际界面为准；平台侧的密钥额度、赠送规则与计费方式同样以官方页面为准。