dsh-mlx-local

dsh-mlx-local

本插件是向DSH许愿得到的，本人不对其中的屎山代码负责。

English · 中文

在 Apple Silicon Mac 上通过 DSH 运行本地大模型。插件负责管理 Python 环境、启动和停止 mlx_lm.server,并把本地服务接入 DSH 已有的自定义 provider。

功能

• 在设置页提供“MLX 模型”栏目,可启动、停止、切换本地模型;
• 自动探测 Python 3.9–3.13,创建独立 venv 并安装 mlx-lm;
• 模型目录管理:添加、移除、预下载、列出本地模型;
• 服务异常退出检测、残留进程回收、DSH 退出时自动关闭服务;
• 为本地 Qwen3 自动配置思考强度,主界面模型选择器可切换 Off / High;
• 不注册额外 provider,继续使用 DSH 的“自定义提供方”接入;
• 不注册系统提示词段,也不注册任何工具:插件只是把本地模型跑起来的基础设施,不会给任何会话增加固定请求成本。

环境要求

版本与更新

当前版本 0.5.2。逐版变更见 CHANGELOG.md;这里只列升级前必须知道的。

0.5.2 是 DSH 0.2.1 的兼容性复核,无破坏性变更。

• 已实测在 DSH 0.2.1-rc.2(npm next 标签)上完整可用:具名导入、服务与方法、llm/stream 事件、设置页「MLX 模型」栏目、/mlx/api、Qwen3 思考强度补全与设置写入全部正常。
• 修掉一个「代码兼容但装不上」的问题:peerDependencies 原来写的是 ^0.1.7-rc.1 || ^0.2.0-rc.1,而按 semver 的预发布规则,该范围匹配不了 0.2.1-rc.2——npm install 会报 ERESOLVE(或装上后报 peer 未满足),尽管插件代码在 0.2.1 上完全正常。现已补上 ^0.2.1-rc.1。
• check:runtime 增加第 7 类检查:peerDependencies 的版本范围是否被目标运行时满足,避免再出现「六项全绿却装不上」。该检查自带极简 semver 实现(scripts/semver-lite.mjs)与单元测试。
• 设置页在 dsh web --host <局域网地址> 下可用(DSH 0.2.1 起支持把 GUI 绑到具体接口地址):/mlx/api 的 Host 校验从「必须是回环地址」放宽为「回环 或 恰好等于连接落入的本机接口地址」,DNS rebinding 防护不变。
• 本机判定改用 URL 解析:新增 lib/local.js,让「思考强度补全」与「llm/stream 拦截器」共用同一判据,并修掉 baseURL.includes("127.0.0.1") 会把 https://example.com/?next=127.0.0.1 误判成本机服务的隐患;服务绑到局域网地址时也能按 origin 识别。
• ~/.dsh/mlx/logs/server.log 改为跟随 $DSH_HOME(与启动探针 plugin-boot.log 一致),隔离 home / 测试 profile 不再把日志写进真实 home;venv 目录仍默认共享 ~/.dsh/mlx/venv(可用 venvDir 覆盖)。
• /mlx/api 请求体加上 1MB 上限,超限返回 413。

0.5.0 是破坏性更新:只支持 DSH 0.1.7 及以后,且模型目录需要手工迁移一次。

DSH 0.1.7 重写了设置架构,插件此前依赖的 settings.installSection 与 settings.get 被整体删除。旧版插件在 0.1.7-rc.2 及 0.2.0-rc.1 上处于半失效状态:设置页不显示「MLX 模型」栏目,启动链(接管外部服务、端口监控、Qwen3 思考强度补全)不再执行——而且全程不报错。本版按新架构重写设置接入,需要 DSH 0.1.7-rc.1 或更高。

升级时请做一次配置迁移。 DSH 取消了 settings.yaml,旧文件已被自动改名为 ~/.dsh/settings.yaml.imported;但本插件当时的 Config 没有 volatile 字段,DSH 导入时跳过了它,所以模型目录没进 profile。请在 profile 的 cordis.patch.yml(如 ~/.dsh/profiles/web/cordis.patch.yml)里补上:

- id: dsh-mlx-local
  name: dsh-mlx-local
  config:
    models:
      - id: your-model-id
        repo: /绝对路径/或/HF仓库名
        name: 显示名

然后重启 DSH。此后在设置页里的改动会正常保存,不用再手工编辑这个文件。

0.4.2 是针对 DSH 0.1.6-alpha.2 的兼容性复核,无破坏性变更。

• 已实测在 DSH 0.1.6-alpha.2(npm alpha 标签)与 0.1.5-rc.2 上均可正常加载:具名导入、服务与方法、llm/stream 事件、客户端槽与 __ModuleLoader__ 契约全部未变,无需迁移。
• 修掉一处一直静默失效的客户端注入:dsh.client.inject 原写的 @deepseek-ai/dsh-client-ui-slots 从来不在客户端模块图内(它只是官方包的 devDependency,自身没有 dsh.client 声明),而浏览器端对图里没有的名字会直接跳过、不报错。已改为 slots 服务的真正提供者 @deepseek-ai/dsh-client-ui-renderer。此前「MLX 模型」栏目能正常显示是靠传递依赖与 cordis 服务注入兜住,故升级后无可见行为变化。
• 装 0.1.6-alpha.x 时 npm 会报 ERESOLVE——这是预发布 semver 规则的固有行为,官方包同样如此,用 --legacy-peer-deps 绕过即可;转正后的 0.1.6 不受影响。

0.4.1 是破坏性更新:插件不再注册任何工具。

• 移除了全部 mlx_* 工具。 0.4.0 的 10 个工具(mlx_status / mlx_list_models / mlx_add_model / mlx_remove_model / mlx_pull_model / mlx_setup / mlx_start / mlx_stop / mlx_switch_model / mlx_chat)整体下线:本插件只负责把本地模型跑起来,服务与模型目录的管理请在设置页完成,不再由智能体代劳。没有需要迁移的调用——原先让智能体做的事,在 设置 → MLX 模型 里都能手动完成。
• 同时移除了系统提示词注入。 此前插件会向每段对话注入一小段本地服务说明。现在插件对任何会话的固定请求成本都是 0。
• inject 收敛为 ["llm"],不再依赖 tools 服务,peerDependencies 去掉了 @deepseek-ai/dsh-tools;旧设置里残留的 enableTools 会被自动忽略。

从 0.3.x 及更早版本升级,还需要知道 0.4.0 的变更:

1. 移除了「随 DSH 启动自动拉起服务」。 服务现在一律由你显式启动——设置页的「启动」按钮。配置项 autoStart 同时删除;旧设置里若残留该字段会被自动忽略,不需要手动改 settings.yaml。
2. DSH 要求提高到 0.1.5-rc.1。 插件此前面向 0.1.0-rc.x 编写,在 0.1.5-rc.1 上完全无法加载(三个具名导入已被上游移除);同时客户端有服务改名与栏目排序的修复。0.2.x 及更早版本请勿在 0.1.5 上使用。

0.3.0–0.3.3 未单独发布,内容已并入 0.4.0。

升级

标准插件的安装/更新/卸载都会改 profile,需要重启 DSH 后生效。从旧版本升级时先移除再安装:

dsh plugin --profile web remove dsh-mlx-local
dsh plugin --profile web add https://github.com/JshGao/dsh-mlx-local/releases/download/v0.5.2/dsh-mlx-local-0.5.2.tgz

然后重启 DSH。模型目录等设置保存在 settings.yaml 中,升级不会丢失。

安装

方式一:使用 GitHub Release 发布包

直接安装:

dsh plugin --profile web add https://github.com/JshGao/dsh-mlx-local/releases/download/v0.5.2/dsh-mlx-local-0.5.2.tgz

如果 DSH 不跟随下载跳转,先手动下载:

curl -L -O https://github.com/JshGao/dsh-mlx-local/releases/download/v0.5.2/dsh-mlx-local-0.5.2.tgz
dsh plugin --profile web add ./dsh-mlx-local-0.5.2.tgz

安装后重启 DSH。

方式二:从源码安装

git clone https://github.com/JshGao/dsh-mlx-local.git
cd dsh-mlx-local
npm install
npm run pack
dsh plugin --profile web add ./dsh-mlx-local-0.5.2.tgz

然后重启 DSH。

安装、更新、卸载标准插件会修改 profile,需要重启 DSH 后生效。

快速开始

1. 重启 DSH 后打开 设置 → MLX 模型;
2. 如果本地已有 MLX 模型目录,点击 加载模型… 选择目录;否则可直接使用内置 HF 模型;
3. 选择模型后点击 启动,等待状态变为“运行中”;
4. 在 设置 → 模型 → 添加 provider 中:
   • 选择 自定义提供方;
   • route 名任意,例如 local;
   • 协议选择 openai-completions;
   • baseURL 填 http://127.0.0.1:8080/v1;
   • 模型 id 填 MLX 插件目录中显示的模型 id;
   • API Key 填任意值,本地服务不会校验。
5. 新建会话,在主界面选择该 provider。若模型是 Qwen3,思考强度会显示 Off / High。

模型管理

• 本地模型目录会保存在设置中;也可以在设置页中加载新的本地 MLX 模型。
• 服务不随 DSH 启动自动拉起:每次都由你在设置页显式启动,以免在意想不到的时候占用内存。
• HF 模型首次启动时会自动下载,也可以先用「预下载」把权重拉到本地缓存。
• 切换模型会先停止旧服务再启动新服务。
• 插件不会自动注册 mlx-local provider;接入统一使用 DSH 自定义 provider。

卸载

dsh plugin --profile web remove dsh-mlx-local

然后重启 DSH。插件设置和 ~/.dsh/mlx/ 下的 venv、日志会保留;如需彻底删除,可手动删除 ~/.dsh/mlx/ 和 HuggingFace 缓存。

常见问题

见 docs/TROUBLESHOOTING.md。