Cherry Studio 模型供应商通道健康检查怎么配置才算真正验过?

在 Cherry Studio 里,通道健康检查要分四层做完:地址可解析、密钥可鉴权、模型列表可枚举、对话可生成。设置页的「检查」通过只代表地址和密钥被接受,不代表你选中的模型 ID 真能出字,必须再发一条最小对话请求才算验完。

Cherry Studio 的模型供应商通道健康检查不能只靠点一次「检查」来完成:它要依次验证地址可解析、密钥可鉴权、模型列表可枚举、对话可生成这四层,任何一层没验到,都会出现「设置页显示正常、发消息立刻报错」的情况。这套流程适用于自定义通道和官方通道;本地部署的推理服务只走其中三层,鉴权那一层通常可以跳过。 健康检查最容易被漏掉的一层是「可生成」。Cherry Studio 设置页的检查动作本质是向供应商发一次轻量请求,确认地址与密钥能被接受,它并不保证你随后选中的那个模型名真实存在。所以正确顺序是先过检查拿到模型列表,再用一条最小请求验证出字。 Base URL 的写法决定了一半以上的故障。兼容协议的地址应填到版本号为止,客户端会自行拼接后续路径,如果你手动再补一段相同的路径,请求就会落到不存在的端点上并返回 404。判断方法很直接:把同一串地址放到浏览器或命令行里请求一次,看返回的是 JSON 数据还是 HTML 报错页。 API Key 校验要分清 401 与 403。401 说明密钥根本没被识别,常见原因是复制时带了空格或换行、或者把 A 通道的 key 贴到了 B 通道;403 说明密钥有效但无权访问该模型或该端点。两种情况处理方向完全不同,先看状态码再动配置,能省掉大半试错时间。 点「检查」或拉取模型列表失败,不等于通道不可用。这个动作请求的是模型枚举端点,部分通道只开放对话端点、不开放枚举端点,于是列表拉不出来,但模型其实能正常对话。遇到这类情况应改为手动填入模型名,再用最小请求验证,不要因为列表拉不到就换供应商。 模型 ID 必须逐字符精确匹配。供应商侧的模型名区分大小写,带日期后缀的版本、带 preview 标记的版本与主版本通常不是同一个名字,写错一律返回模型不存在。稳妥做法是从供应商控制台的模型列表里整段复制,不要手打,也不要想当然地简写。 最小请求才是端到端可用的唯一证据。把最大输出长度调到很小、清空上下文、只发一句「你好」,看是否返回内容;这一步同时验证了路由、鉴权、模型存在性和额度四项。这一步失败,前面所有检查通过都没有意义,排查也应从这里往下走。 超时要按首包时间设定,不能按总时长设定。长上下文请求和推理型模型的首包本来就慢,超时设得过短会把正常通道判成故障;反过来,超时设得过长,真正断掉的通道会迟迟不报错,让人误以为在排队。建议先用默认值跑通一次,再按实测首包时间适度放宽。 429 属于容量层问题,不属于通道层问题。健康检查通过、最小请求也通过,但在批量调用或高峰期报限流,说明这个密钥的并发或额度触到了上限,此时反复改地址和 key 没有用。要做的是增加通道、切换通道或降低并发,把请求摊到多条通道上。 网络层要单独排一遍,不要和配置混在一起查。系统代理、企业网关的证书拦截、以及本地推理服务的地址被代理劫持,都会表现成含义模糊的「连接超时」或「握手失败」。本地地址应加入不走代理的名单,跨境通道则要单独确认代理本身可达,而不是只盯着 key 看。 多通道配置是健康检查的自然延伸。同一个模型可以挂两条不同来源的通道,用能看懂的备注名区分主备,主通道异常时手动切换即可恢复;把检查动作固定成换 key 之后、换网络之后、升级客户端之后的例行步骤,比出问题再回头排查要省时间得多。 排查顺序固定下来,绝大多数「通道连不上」都能在十分钟内定位到具体一层。先看地址写法和返回的状态码,再核对模型 ID,然后发最小请求,最后才去查额度与网络;跳过前两步直接怀疑供应商,往往是把配置问题误判成了服务故障。不适用于把通道本身当成唯一变量的场景,例如供应商侧整体维护,这时无论怎么改配置都验不过,只能等或换通道。