装完 dsh-commandcode-provider 却找不到模型这个报错场景我太熟悉了。无论是本机调试还是帮别人远程看环境十次里有八次是配置问题而不是程序问题但很多人一上来就怀疑是插件坏了卸载重装好几遍白白浪费时间。这篇文章就是一份纯排错速查手册按步骤走大部分情况十分钟内能定位不需要你有多深的底层基础照着抄作业就行。先说清楚这玩意儿是干嘛的。dsh-commandcode-provider 是一个模型接入服务提供方负责把外部模型能力注册进主框架的模型列表里让上层应用能直接调用。说人话就是你装了一个“转换插座”告诉主程序“我这有几个模型可以用”主程序认了这个插座才会在模型列表里显示对应的模型。如果你装完之后在列表里看不到任何新模型那问题基本就出在“注册”这个环节要么插座没插上要么插上了但没通电要么电通了但型号报错了。这篇文章适合谁看刚装完插件找不到模型的新手、给客户部署环境时踩坑的运维、以及想搞明白 provider 加载机制的前端开发者。我会把常见症状、原理、实操步骤、排查命令、经典翻车案例一次讲完你能直接复制我的排查路径去用。1. 先从症状入手别一上来就怀疑插件坏了1.1 “看不到模型”其实有四种完全不同的现象我接到的求助里“看不到模型”这四个字背后其实藏着完全不同的现象。如果你不问清楚很容易被带到沟里去。我总结下来基本是这四类第一种模型列表是空的连原本内置的模型也没了。这种情况通常是主框架的模型缓存被清掉了或者是 provider 加载后把列表覆盖了问题出在框架侧而不是 provider 侧。第二种内置模型还在但 dsh-commandcode-provider 提供的模型一个都没出现。这是最常见的说明 provider 本身被加载了但里面的模型定义没有被成功解析或注册。第三种模型出现了但报错提示模型不存在、请求失败。这说明注册已经成功但调用链路没走通通常是模型名写错、请求地址不对、鉴权信息缺失。第四种模型出现了也能聊天但走的是内置模型而不是 provider 的模型。这个最隐蔽说明 provider 虽然注册了但是路由优先级不对请求根本没被转发到 provider 上。你在排查前先确认自己到底属于哪一种。因为不同现象的排查方向是完全不一样的。如果是第一种你去改 provider 配置只会越来越乱。1.2 快速判断问题范围的三个问题在打开日志文件之前先问自己三个问题第一个问题重启之后还是这样吗很多“看不到模型”只是框架启动时 provider 加载顺序错乱导致的临时问题重启一次可能就好了。先重启零成本值得第一个试。第二个问题模型配置写在哪个文件里是写在 provider 自带的配置文件还是写在了主框架的模型注册文件里这个问题非常关键因为很多人把模型定义写在了 provider 的默认配置里但主框架压根不认这个路径。第三个问题改完配置之后有没有做“重新加载”有些框架支持热加载有些必须重启进程甚至要清缓存。如果你改完配置没重启看不到模型是正常的别急着报错。这三个问题问完你自己就能过滤掉一半的假故障。2. 核心机制拆解provider 是怎么把模型“送”进列表的2.1 一条完整的链路扫描、解析、注册、展示要想快速排错你得先明白 provider 注册模型的全过程。我之前花了很多时间看源码才理清楚其实无非是四步第一步是扫描。主框架在启动时扫描指定目录寻找符合命名规则的 provider 文件。dsh-commandcode-provider 的目录命名、文件后缀、目录层级如果不符合要求主框架就不会加载它。第二步是解析。provider 被加载后框架会读取它的配置部分里面包含模型列表、模型名称、类型说明、请求地址、密钥等字段。任何字段格式错误比如少了一个逗号、缩进不对、引号没闭合都会导致整个解析失败。第三步是注册。解析成功后provider 会把每个模型作为实例注册到框架的模型注册中心。这个注册中心通常是一个内存列表注册成功与否取决于模型名是否重复、模型类型是否被框架支持。第四步是展示。框架把注册中心的内容渲染到模型列表界面。如果注册成功但展示失败那可能是前端的过滤逻辑有问题比如按状态筛选后把模型藏掉了。之前我遇到过一个非常诡异的案例注册日志里明明有记录但界面上死活不显示。后来发现框架前端默认只显示“正常”状态的模型那个模型因为缺少一个推荐位标签被归类为“其它”被折叠了。这种问题你单看后端日志是看不出来的。2.2 为什么“装了”却不等于“能被看到”我以前带过一个同学他总觉得把插件文件放进去就等于装好了。实际上“放置文件”只是第一步文件能否被识别、配置能否被解析、模型能否被注册每一步都有一票否决权。我用一个类比解释给你听你往公司通讯录里添加一个员工光把员工信息表交到 HR 手里没用HR 得确认表格格式规范确认姓名没跟别人重复确认部门代码存在才会把信息录入系统。通讯录里最终能不能看到这个人取决于后面这一堆动作而不是你提交表格本身。所以当你“装完看不到模型”的时候你要排查的其实是“为什么 HR 没有把信息录入系统”而不是反复强调“我明明交表了”。这就是为什么我建议你把注意力放在加载日志和注册日志上而不是反复卸载重装。2.3 配置文件优先级你以为改对了其实改错了还有一个很容易踩的坑配置文件优先级。很多框架支持多级配置比如默认配置、全局配置、用户配置、provider 自定义配置。优先级一般是用户配置 全局配置 默认配置。问题是很多人不知道这个优先级在 provider 自定义配置里改了模型名和地址但全局配置里存在一份旧配置优先级更高把新配置完全盖掉了。最终的效果是你明明改了个新地址系统运行时用的还是旧地址自然就“看不到模型”。排查方法也简单在配置里加一行调试输出或者直接在注册日志里看最终生效的模型地址是哪个。我之前有次排错花了半小时查来查去最后发现在全局配置里还有个残留的旧模型定义占着茅坑把新配置挤掉了。3. 一步步实操从安装到定位问题的完整排错流3.1 第一步确认 provider 到底有没有被加载这一步是整个排错的起点。你连 provider 有没有被加载都不确定后面全是白费功夫。怎么确认呢最直接的办法是看启动日志。在终端里重启主框架然后把日志打到终端搜索 dsh 相关的关键词比如 provider 名称、commandcode 等。正常的情况下日志里会有一条加载成功的记录类似[INFO] Loaded provider: dsh-commandcode-provider (version 1.2.3) [INFO] Registered 3 model(s) from dsh-commandcode-provider如果日志里压根没有 dsh 相关的字眼那说明 provider 文件根本不在扫描路径里或者文件名不符合规范、目录层级不对、文件依赖缺失导致加载失败。我再给你一个更直接的检查点看 provider 的文件目录和主框架约定的扫描目录是否一致。有些框架只扫描 plugins 根目录下的第一层子目录你如果多套了一层文件夹它就发现不了。比如框架扫描的是plugin/目录下的直接子目录你把 provider 放在了plugin/third_party/dsh/那就不会被找到。这一步排查成本极低但能解决相当一部分问题。3.2 第二步检查模型定义与注册名单如果你确认 provider 已经被加载了但模型数量是 0那问题在模型定义层面。打开 provider 对应的配置文件找到models字段检查几样东西第一模型列表的格式对不对。我见过最多的错误是把单个模型对象写成了数组、数组元素少了括号、JSON 里混进了注释。很多框架用 JSON 格式解析配置JSON 是不允许写注释的但有人习惯性写//注释结果解析失败整个列表为空。第二模型名是否与框架内置模型重复。如果重名框架一般会拒绝注册而且不会给你弹提示只会默默忽略。最好的做法是起一个带前缀的名字比如dsh-code-lite、dsh-chat-pro一眼就能看出是 provider 提供的也降低重名概率。第三模型类型标记是否正确。有些框架区分聊天模型、代码模型、向量模型dsh-commandcode-provider 的特点是偏代码场景如果你把类型标记成了聊天模型但框架的代码模型区才展示 provider 的模型那你同样会“看不到”。第四模型参数是否齐全。有些模型定义里还必须包含上下文长度、请求地址、API Key 引用等字段缺一个框架可能认为这个模型非法直接跳过。3.3 第三步核对 Endpoint 与鉴权配置加载和注册都成功了模型也能显示名字但一点进去就报错“请求失败”“model not found”那就要检查 Endpoint 和鉴权。Endpoint 就是模型 API 的调用地址。常见问题有三种一是地址写错了比如少了一个斜杠、把https写成了http、域名拼错。这个最基础但很多人反而忽略因为地址信息是复制过来的中间可能混进了回车或空格。二是地址填对了但路径不对。好多模型的 API 路径分为基础路径和具体接口路径比如基础地址是https://api.example.com具体接口是/v1/chat/completions。provider 配置里可能只要求填基础地址但你误把完整路径也填了进去导致变成https://api.example.com/v1/chat/completions/v1/chat/completions双重拼接请求必挂。三是鉴权信息没传对。API Key 要么写死在配置里要么引用环境变量。如果你填的是{env:MY_API_KEY}这种引用语法得确保环境变量确实存在并且主框架启动时能读到这个环境变量。我之前有次怎么查都查不到问题最后发现是配置文件里的花括号语法被框架当成了字面量没有做变量替换。3.4 第四步用日志和调试接口精准定位如果你走到这一步还没有解决那就不要瞎猜了用日志来定位。首先打开主框架的日志级别设置调到 debug 或者 trace。然后重启把输出重定向到一个文件里方便翻查# 假设主程序的启动命令是 start.sh ./start.sh debug.log 21重启之后在日志里按照优先级搜索以下关键词dsh-commandcode-provider确认加载阶段是否报错register model查看每个模型的注册结果model list查看最终注册中心里到底有几个模型error|warn|exception快速定位明显的错误信息我再给你一个在日志里排查配置优先级的方法找一个你改过的字段比如模型名称然后在日志里搜索这个字段看最终输出的是旧值还是新值。如果输出的是旧值说明配置优先级压过了你的修改。如果你用的框架自带调试接口比如localhost:端口/debug/provider这种直接访问它返回的信息更集中。我常用这种方式来直接查看 provider 状态和注册的模型列表比翻日志快得多。3.5 第五步重启、清缓存、验证一条龙很多人改完配置后不重启或者只重启了一半比如只重启了前端界面没重启后端服务然后又来问我为什么不行。这里我给你一个标准的验证顺序修改配置文件后保存。如果框架支持“重新加载 provider”的指令先执行重新加载如果不支持直接完全重启进程。如果重启后还是老样子检查框架缓存目录把 provider 相关的缓存文件删除如果有再重启一次。重启完成后等 10 到 30 秒再打开模型列表页面不要秒开有些框架的列表渲染有延迟需要等服务完全就绪。我自己写过一个检查清单每步做完就打个勾避免漏掉。排错最怕的不是问题难而是东看一眼西看一眼最后连自己改过什么都没记住。4. 常见问题速查表与典型翻车案例4.1 一张表解决 80% 的报错场景我把自己遇到过、以及帮别人排查过的高频问题做成了这张速查表。你遇到问题先对照这张表格如果对不上再往日志方向查。现象优先排查点常见解决方案日志里完全没有 provider 加载记录扫描路径、目录层级、文件命名把 provider 放到框架指定的 plugins 目录下检查命名是否带前缀或正确后缀有加载记录但模型注册数量为 0配置文件格式、模型类型标记用 JSON 校验工具检查配置文件确认模型类型填的是代码类而不是聊天类模型有名字但请求报 model not found模型名与 API 服务端模型名不一致核对 provider 配置里的模型标识改为服务端真实的模型 ID请求报鉴权失败API Key、环境变量引用确认环境变量是否正确注入检查 Key 前后是否有空格请求报地址错误Endpoint 拼接方式只填基础地址不要带具体接口路径观察最终请求 URL模型列表里有但界面不展示模型状态标签、过滤条件查看模型状态是否为正常是否有默认隐藏标记改完配置没效果配置优先级、缓存查找更高优先级的配置并修改执行清缓存操作后重启preview 可用但主界面不可用路由规则、模型分组把模型归属到正确的分组或路由策略下这张表格你直接拿去做内部文档都没问题我平时排查问题基本也是按这个顺序过一遍。4.2 案例复盘一个“看不到模型”的螺蛳壳里做道场我给你讲一个印象很深的案例。有个同学装完 dsh-commandcode-provider 后模型列表里只显示了一个模型但他明明在配置里写了四个。他前前后后折腾了一整天挨个试了各种方法还是只显示一个。我远程帮他用调试接口看了注册记录发现只注册成功第一个模型后面三个全部报“模型参数不完整跳过”。我让他把配置文件发给我反复看了十几分钟终于发现问题第二个模型的max_tokens字段他写了32000但框架硬性限制是不能超过32768按理说没超啊再仔细一看原来他写的是32000后面多了个空格拿正则一匹配类型校验直接失败。这种问题单靠肉眼极难发现因为空格在编辑器里几乎看不出来。后来我学乖了凡是遇到“配置写了多个但只有部分生效”第一件事就是把配置文件丢进校验工具同时开启显示空白字符的编辑模式。格式问题远比你想的多。另一个案例是一个部署环境的问题。模型在本地一切正常但部署到客户的服务器上就看不到。查来查去原来是客户服务器上有个老版本框架默认不扫描多级子目录而我把 provider 放在了一个三级目录下。本地新版本框架没问题但客户那台机器的版本不支持。这种兼容性差异光看本地的日志是完全没用的必须看现场环境的版本信息。4.3 容易误导你的“假日志”与“假报错”最后说一下日志里的一些坑。有些日志看起来是报错但实际上只是警告不影响运行。反过来有些日志看起来一切正常但问题已经发生了。你需要学会分辨。比如说日志里出现provider dsh-commandcode-provider skipped这种带 skipped 的记录很多人以为是报错。实际上它可能只是在重复扫描时跳过了已经加载的 provider属于正常输出。再比如说日志里出现model xxx not found有时候这是某个内部请求在探测不存在的模型是框架的探测机制在正常工作不是真出错了。真正的问题可能是响应超时。我常用的一个判断技巧是不看单条日志而是看日志的时间线。如果一条“报错”之后紧跟着一条“正常返回”那说明框架已经做了容错处理这种报错可以忽略。如果一条“报错”之后什么都没有那才是真正值得关注的。5. 预防方案与长期维护的经验5.1 装 provider 之前就做好这四件事后面省一半心排错做得多了你会发现很多问题其实是装之前就能避免的。我总结了四个习惯每次装新 provider 都会执行第一先备份当前配置和模型列表。很多框架支持配置导出先把当前状态导出一份。万一改坏了恢复起来很快不用重新回忆自己改过什么。第二查看 provider 的官方文档里写的支持矩阵确认版本兼容。我见过太多人随便下载一个版本就装结果框架版本太老provider 要求的新配置字段根本不被识别。你要是装之前花两分钟确认一下兼容性能少踩一大堆坑。第三检查端口和网络策略。如果你的模型 API 不在本机需要访问外部地址先确认防火墙、代理、白名单都放通了。这一步常常被忽略等到请求报超时才开始查。第四先建立最小可用配置再逐步增加模型。很多人一上来就写好几个模型结果哪个都没注册成功。我的习惯是先配置一个模型确认从头到尾链路通了再批量加入其它模型。这样即使后续有问题也容易定位。5.2 维护期的小技巧给配置留注释、给模型打标签、给日志留级长期维护 provider我还有一些小习惯分享给你。配置文件里写注释是必须的。虽然说很多人用 JSON 格式不能写注释但你可以用支持注释的 YAML 格式或者在 JSON 里额外加一个_comment字段来备注。别小看这个习惯三个月后再回来改配置你会感激当时的自己。给模型打标签也很重要。在模型定义里加上用途标签比如code-review、code-gen、testing这些框架会根据标签做分类展示同时也便于你自己在界面上快速找到目标模型。我之前的项目里给每个模型都标了用途排查时按标签过滤效率高很多。日志留级的意思是在关键节点打印足够多的上下文。框架自带的日志可能不够细你可以在 provider 的入口处增加一些自定义日志输出记录加载的目录、读取的配置文件路径、最终注册的模型数量。这些日志在排查时非常救命尤其是你把项目丢给同事维护之后。5.3 什么时候该怀疑 provider 本身虽然我说了很多次别一上来就怀疑 provider 坏了但确实有一小部分问题就是 provider 本身的原因。什么时候应该怀疑它我总结出两个信号第一个信号是同一个 provider 在同样版本的框架、同样配置、同样环境下另一台机器的表现完全正常而你的机器一直出问题。这时可以怀疑是不是你本机环境引入了一些特殊变量比如 Python 依赖冲突、JRE 版本过低、动态库缺失。在这种场景下provider 卡在加载阶段日志里大概率有 NoClassDefFoundError、ImportError、libxxx.so 相关的字眼。第二个信号是你升级了 provider 版本之后才出现问题。这种大概率是新版本的配置格式变更了而你还拿着旧配置在写。解决方案是把配置迁移到新格式或者回滚到旧版本。如果一个 provider 最近更新频繁、每次改动都很大我会选择固定版本使用不追新。毕竟稳定性优先模型能用比什么都重要。写在最后装完 dsh-commandcode-provider 看不到模型绝大多数都是加载路径、配置格式、优先级、缓存这四个老问题。我希望你们也能养成一个习惯不要急着怀疑插件坏了先把加载日志打开、把配置文件拉出来校一遍把模型注册记录看一眼。按这套思路走下去你会发现大多数问题基本都在配置层。想起一个细节我第一次排查这种问题的时候也走了很多弯路后来每次安装 provider 都会刻意记录一下当时用的框架版本和配置快照。等到需要复查时能快速找到历史状态不用靠记忆还原。你也可以试试这个方法等踩过几次坑之后就会发现节省的时间远远超过记录时花费的那几分钟。
装完 dsh-commandcode-provider 却找不到模型这个报错场景我太熟悉了。无论是本机调试还是帮别人远程看环境十次里有八次是配置问题而不是程序问题但很多人一上来就怀疑是插件坏了卸载重装好几遍白白浪费时间。这篇文章就是一份纯排错速查手册按步骤走大部分情况十分钟内能定位不需要你有多深的底层基础照着抄作业就行。先说清楚这玩意儿是干嘛的。dsh-commandcode-provider 是一个模型接入服务提供方负责把外部模型能力注册进主框架的模型列表里让上层应用能直接调用。说人话就是你装了一个“转换插座”告诉主程序“我这有几个模型可以用”主程序认了这个插座才会在模型列表里显示对应的模型。如果你装完之后在列表里看不到任何新模型那问题基本就出在“注册”这个环节要么插座没插上要么插上了但没通电要么电通了但型号报错了。这篇文章适合谁看刚装完插件找不到模型的新手、给客户部署环境时踩坑的运维、以及想搞明白 provider 加载机制的前端开发者。我会把常见症状、原理、实操步骤、排查命令、经典翻车案例一次讲完你能直接复制我的排查路径去用。1. 先从症状入手别一上来就怀疑插件坏了1.1 “看不到模型”其实有四种完全不同的现象我接到的求助里“看不到模型”这四个字背后其实藏着完全不同的现象。如果你不问清楚很容易被带到沟里去。我总结下来基本是这四类第一种模型列表是空的连原本内置的模型也没了。这种情况通常是主框架的模型缓存被清掉了或者是 provider 加载后把列表覆盖了问题出在框架侧而不是 provider 侧。第二种内置模型还在但 dsh-commandcode-provider 提供的模型一个都没出现。这是最常见的说明 provider 本身被加载了但里面的模型定义没有被成功解析或注册。第三种模型出现了但报错提示模型不存在、请求失败。这说明注册已经成功但调用链路没走通通常是模型名写错、请求地址不对、鉴权信息缺失。第四种模型出现了也能聊天但走的是内置模型而不是 provider 的模型。这个最隐蔽说明 provider 虽然注册了但是路由优先级不对请求根本没被转发到 provider 上。你在排查前先确认自己到底属于哪一种。因为不同现象的排查方向是完全不一样的。如果是第一种你去改 provider 配置只会越来越乱。1.2 快速判断问题范围的三个问题在打开日志文件之前先问自己三个问题第一个问题重启之后还是这样吗很多“看不到模型”只是框架启动时 provider 加载顺序错乱导致的临时问题重启一次可能就好了。先重启零成本值得第一个试。第二个问题模型配置写在哪个文件里是写在 provider 自带的配置文件还是写在了主框架的模型注册文件里这个问题非常关键因为很多人把模型定义写在了 provider 的默认配置里但主框架压根不认这个路径。第三个问题改完配置之后有没有做“重新加载”有些框架支持热加载有些必须重启进程甚至要清缓存。如果你改完配置没重启看不到模型是正常的别急着报错。这三个问题问完你自己就能过滤掉一半的假故障。2. 核心机制拆解provider 是怎么把模型“送”进列表的2.1 一条完整的链路扫描、解析、注册、展示要想快速排错你得先明白 provider 注册模型的全过程。我之前花了很多时间看源码才理清楚其实无非是四步第一步是扫描。主框架在启动时扫描指定目录寻找符合命名规则的 provider 文件。dsh-commandcode-provider 的目录命名、文件后缀、目录层级如果不符合要求主框架就不会加载它。第二步是解析。provider 被加载后框架会读取它的配置部分里面包含模型列表、模型名称、类型说明、请求地址、密钥等字段。任何字段格式错误比如少了一个逗号、缩进不对、引号没闭合都会导致整个解析失败。第三步是注册。解析成功后provider 会把每个模型作为实例注册到框架的模型注册中心。这个注册中心通常是一个内存列表注册成功与否取决于模型名是否重复、模型类型是否被框架支持。第四步是展示。框架把注册中心的内容渲染到模型列表界面。如果注册成功但展示失败那可能是前端的过滤逻辑有问题比如按状态筛选后把模型藏掉了。之前我遇到过一个非常诡异的案例注册日志里明明有记录但界面上死活不显示。后来发现框架前端默认只显示“正常”状态的模型那个模型因为缺少一个推荐位标签被归类为“其它”被折叠了。这种问题你单看后端日志是看不出来的。2.2 为什么“装了”却不等于“能被看到”我以前带过一个同学他总觉得把插件文件放进去就等于装好了。实际上“放置文件”只是第一步文件能否被识别、配置能否被解析、模型能否被注册每一步都有一票否决权。我用一个类比解释给你听你往公司通讯录里添加一个员工光把员工信息表交到 HR 手里没用HR 得确认表格格式规范确认姓名没跟别人重复确认部门代码存在才会把信息录入系统。通讯录里最终能不能看到这个人取决于后面这一堆动作而不是你提交表格本身。所以当你“装完看不到模型”的时候你要排查的其实是“为什么 HR 没有把信息录入系统”而不是反复强调“我明明交表了”。这就是为什么我建议你把注意力放在加载日志和注册日志上而不是反复卸载重装。2.3 配置文件优先级你以为改对了其实改错了还有一个很容易踩的坑配置文件优先级。很多框架支持多级配置比如默认配置、全局配置、用户配置、provider 自定义配置。优先级一般是用户配置 全局配置 默认配置。问题是很多人不知道这个优先级在 provider 自定义配置里改了模型名和地址但全局配置里存在一份旧配置优先级更高把新配置完全盖掉了。最终的效果是你明明改了个新地址系统运行时用的还是旧地址自然就“看不到模型”。排查方法也简单在配置里加一行调试输出或者直接在注册日志里看最终生效的模型地址是哪个。我之前有次排错花了半小时查来查去最后发现在全局配置里还有个残留的旧模型定义占着茅坑把新配置挤掉了。3. 一步步实操从安装到定位问题的完整排错流3.1 第一步确认 provider 到底有没有被加载这一步是整个排错的起点。你连 provider 有没有被加载都不确定后面全是白费功夫。怎么确认呢最直接的办法是看启动日志。在终端里重启主框架然后把日志打到终端搜索 dsh 相关的关键词比如 provider 名称、commandcode 等。正常的情况下日志里会有一条加载成功的记录类似[INFO] Loaded provider: dsh-commandcode-provider (version 1.2.3) [INFO] Registered 3 model(s) from dsh-commandcode-provider如果日志里压根没有 dsh 相关的字眼那说明 provider 文件根本不在扫描路径里或者文件名不符合规范、目录层级不对、文件依赖缺失导致加载失败。我再给你一个更直接的检查点看 provider 的文件目录和主框架约定的扫描目录是否一致。有些框架只扫描 plugins 根目录下的第一层子目录你如果多套了一层文件夹它就发现不了。比如框架扫描的是plugin/目录下的直接子目录你把 provider 放在了plugin/third_party/dsh/那就不会被找到。这一步排查成本极低但能解决相当一部分问题。3.2 第二步检查模型定义与注册名单如果你确认 provider 已经被加载了但模型数量是 0那问题在模型定义层面。打开 provider 对应的配置文件找到models字段检查几样东西第一模型列表的格式对不对。我见过最多的错误是把单个模型对象写成了数组、数组元素少了括号、JSON 里混进了注释。很多框架用 JSON 格式解析配置JSON 是不允许写注释的但有人习惯性写//注释结果解析失败整个列表为空。第二模型名是否与框架内置模型重复。如果重名框架一般会拒绝注册而且不会给你弹提示只会默默忽略。最好的做法是起一个带前缀的名字比如dsh-code-lite、dsh-chat-pro一眼就能看出是 provider 提供的也降低重名概率。第三模型类型标记是否正确。有些框架区分聊天模型、代码模型、向量模型dsh-commandcode-provider 的特点是偏代码场景如果你把类型标记成了聊天模型但框架的代码模型区才展示 provider 的模型那你同样会“看不到”。第四模型参数是否齐全。有些模型定义里还必须包含上下文长度、请求地址、API Key 引用等字段缺一个框架可能认为这个模型非法直接跳过。3.3 第三步核对 Endpoint 与鉴权配置加载和注册都成功了模型也能显示名字但一点进去就报错“请求失败”“model not found”那就要检查 Endpoint 和鉴权。Endpoint 就是模型 API 的调用地址。常见问题有三种一是地址写错了比如少了一个斜杠、把https写成了http、域名拼错。这个最基础但很多人反而忽略因为地址信息是复制过来的中间可能混进了回车或空格。二是地址填对了但路径不对。好多模型的 API 路径分为基础路径和具体接口路径比如基础地址是https://api.example.com具体接口是/v1/chat/completions。provider 配置里可能只要求填基础地址但你误把完整路径也填了进去导致变成https://api.example.com/v1/chat/completions/v1/chat/completions双重拼接请求必挂。三是鉴权信息没传对。API Key 要么写死在配置里要么引用环境变量。如果你填的是{env:MY_API_KEY}这种引用语法得确保环境变量确实存在并且主框架启动时能读到这个环境变量。我之前有次怎么查都查不到问题最后发现是配置文件里的花括号语法被框架当成了字面量没有做变量替换。3.4 第四步用日志和调试接口精准定位如果你走到这一步还没有解决那就不要瞎猜了用日志来定位。首先打开主框架的日志级别设置调到 debug 或者 trace。然后重启把输出重定向到一个文件里方便翻查# 假设主程序的启动命令是 start.sh ./start.sh debug.log 21重启之后在日志里按照优先级搜索以下关键词dsh-commandcode-provider确认加载阶段是否报错register model查看每个模型的注册结果model list查看最终注册中心里到底有几个模型error|warn|exception快速定位明显的错误信息我再给你一个在日志里排查配置优先级的方法找一个你改过的字段比如模型名称然后在日志里搜索这个字段看最终输出的是旧值还是新值。如果输出的是旧值说明配置优先级压过了你的修改。如果你用的框架自带调试接口比如localhost:端口/debug/provider这种直接访问它返回的信息更集中。我常用这种方式来直接查看 provider 状态和注册的模型列表比翻日志快得多。3.5 第五步重启、清缓存、验证一条龙很多人改完配置后不重启或者只重启了一半比如只重启了前端界面没重启后端服务然后又来问我为什么不行。这里我给你一个标准的验证顺序修改配置文件后保存。如果框架支持“重新加载 provider”的指令先执行重新加载如果不支持直接完全重启进程。如果重启后还是老样子检查框架缓存目录把 provider 相关的缓存文件删除如果有再重启一次。重启完成后等 10 到 30 秒再打开模型列表页面不要秒开有些框架的列表渲染有延迟需要等服务完全就绪。我自己写过一个检查清单每步做完就打个勾避免漏掉。排错最怕的不是问题难而是东看一眼西看一眼最后连自己改过什么都没记住。4. 常见问题速查表与典型翻车案例4.1 一张表解决 80% 的报错场景我把自己遇到过、以及帮别人排查过的高频问题做成了这张速查表。你遇到问题先对照这张表格如果对不上再往日志方向查。现象优先排查点常见解决方案日志里完全没有 provider 加载记录扫描路径、目录层级、文件命名把 provider 放到框架指定的 plugins 目录下检查命名是否带前缀或正确后缀有加载记录但模型注册数量为 0配置文件格式、模型类型标记用 JSON 校验工具检查配置文件确认模型类型填的是代码类而不是聊天类模型有名字但请求报 model not found模型名与 API 服务端模型名不一致核对 provider 配置里的模型标识改为服务端真实的模型 ID请求报鉴权失败API Key、环境变量引用确认环境变量是否正确注入检查 Key 前后是否有空格请求报地址错误Endpoint 拼接方式只填基础地址不要带具体接口路径观察最终请求 URL模型列表里有但界面不展示模型状态标签、过滤条件查看模型状态是否为正常是否有默认隐藏标记改完配置没效果配置优先级、缓存查找更高优先级的配置并修改执行清缓存操作后重启preview 可用但主界面不可用路由规则、模型分组把模型归属到正确的分组或路由策略下这张表格你直接拿去做内部文档都没问题我平时排查问题基本也是按这个顺序过一遍。4.2 案例复盘一个“看不到模型”的螺蛳壳里做道场我给你讲一个印象很深的案例。有个同学装完 dsh-commandcode-provider 后模型列表里只显示了一个模型但他明明在配置里写了四个。他前前后后折腾了一整天挨个试了各种方法还是只显示一个。我远程帮他用调试接口看了注册记录发现只注册成功第一个模型后面三个全部报“模型参数不完整跳过”。我让他把配置文件发给我反复看了十几分钟终于发现问题第二个模型的max_tokens字段他写了32000但框架硬性限制是不能超过32768按理说没超啊再仔细一看原来他写的是32000后面多了个空格拿正则一匹配类型校验直接失败。这种问题单靠肉眼极难发现因为空格在编辑器里几乎看不出来。后来我学乖了凡是遇到“配置写了多个但只有部分生效”第一件事就是把配置文件丢进校验工具同时开启显示空白字符的编辑模式。格式问题远比你想的多。另一个案例是一个部署环境的问题。模型在本地一切正常但部署到客户的服务器上就看不到。查来查去原来是客户服务器上有个老版本框架默认不扫描多级子目录而我把 provider 放在了一个三级目录下。本地新版本框架没问题但客户那台机器的版本不支持。这种兼容性差异光看本地的日志是完全没用的必须看现场环境的版本信息。4.3 容易误导你的“假日志”与“假报错”最后说一下日志里的一些坑。有些日志看起来是报错但实际上只是警告不影响运行。反过来有些日志看起来一切正常但问题已经发生了。你需要学会分辨。比如说日志里出现provider dsh-commandcode-provider skipped这种带 skipped 的记录很多人以为是报错。实际上它可能只是在重复扫描时跳过了已经加载的 provider属于正常输出。再比如说日志里出现model xxx not found有时候这是某个内部请求在探测不存在的模型是框架的探测机制在正常工作不是真出错了。真正的问题可能是响应超时。我常用的一个判断技巧是不看单条日志而是看日志的时间线。如果一条“报错”之后紧跟着一条“正常返回”那说明框架已经做了容错处理这种报错可以忽略。如果一条“报错”之后什么都没有那才是真正值得关注的。5. 预防方案与长期维护的经验5.1 装 provider 之前就做好这四件事后面省一半心排错做得多了你会发现很多问题其实是装之前就能避免的。我总结了四个习惯每次装新 provider 都会执行第一先备份当前配置和模型列表。很多框架支持配置导出先把当前状态导出一份。万一改坏了恢复起来很快不用重新回忆自己改过什么。第二查看 provider 的官方文档里写的支持矩阵确认版本兼容。我见过太多人随便下载一个版本就装结果框架版本太老provider 要求的新配置字段根本不被识别。你要是装之前花两分钟确认一下兼容性能少踩一大堆坑。第三检查端口和网络策略。如果你的模型 API 不在本机需要访问外部地址先确认防火墙、代理、白名单都放通了。这一步常常被忽略等到请求报超时才开始查。第四先建立最小可用配置再逐步增加模型。很多人一上来就写好几个模型结果哪个都没注册成功。我的习惯是先配置一个模型确认从头到尾链路通了再批量加入其它模型。这样即使后续有问题也容易定位。5.2 维护期的小技巧给配置留注释、给模型打标签、给日志留级长期维护 provider我还有一些小习惯分享给你。配置文件里写注释是必须的。虽然说很多人用 JSON 格式不能写注释但你可以用支持注释的 YAML 格式或者在 JSON 里额外加一个_comment字段来备注。别小看这个习惯三个月后再回来改配置你会感激当时的自己。给模型打标签也很重要。在模型定义里加上用途标签比如code-review、code-gen、testing这些框架会根据标签做分类展示同时也便于你自己在界面上快速找到目标模型。我之前的项目里给每个模型都标了用途排查时按标签过滤效率高很多。日志留级的意思是在关键节点打印足够多的上下文。框架自带的日志可能不够细你可以在 provider 的入口处增加一些自定义日志输出记录加载的目录、读取的配置文件路径、最终注册的模型数量。这些日志在排查时非常救命尤其是你把项目丢给同事维护之后。5.3 什么时候该怀疑 provider 本身虽然我说了很多次别一上来就怀疑 provider 坏了但确实有一小部分问题就是 provider 本身的原因。什么时候应该怀疑它我总结出两个信号第一个信号是同一个 provider 在同样版本的框架、同样配置、同样环境下另一台机器的表现完全正常而你的机器一直出问题。这时可以怀疑是不是你本机环境引入了一些特殊变量比如 Python 依赖冲突、JRE 版本过低、动态库缺失。在这种场景下provider 卡在加载阶段日志里大概率有 NoClassDefFoundError、ImportError、libxxx.so 相关的字眼。第二个信号是你升级了 provider 版本之后才出现问题。这种大概率是新版本的配置格式变更了而你还拿着旧配置在写。解决方案是把配置迁移到新格式或者回滚到旧版本。如果一个 provider 最近更新频繁、每次改动都很大我会选择固定版本使用不追新。毕竟稳定性优先模型能用比什么都重要。写在最后装完 dsh-commandcode-provider 看不到模型绝大多数都是加载路径、配置格式、优先级、缓存这四个老问题。我希望你们也能养成一个习惯不要急着怀疑插件坏了先把加载日志打开、把配置文件拉出来校一遍把模型注册记录看一眼。按这套思路走下去你会发现大多数问题基本都在配置层。想起一个细节我第一次排查这种问题的时候也走了很多弯路后来每次安装 provider 都会刻意记录一下当时用的框架版本和配置快照。等到需要复查时能快速找到历史状态不用靠记忆还原。你也可以试试这个方法等踩过几次坑之后就会发现节省的时间远远超过记录时花费的那几分钟。
