dsh-unsloth

把 Unsloth（本地大模型微调 / 微调数据集生成）接进 DeepSeek Harness 的插件。

装上之后，模型就能直接调用 Unsloth：看本机模型清单、用 Data Recipe 生成微调数据集、起 LoRA/QLoRA 训练、看 loss 曲线、导出 GGUF、跑推理自检——全部以原生工具形式出现，名字是 mcp__unsloth__<tool>。

它是什么 / 怎么工作的

DeepSeek Harness
  └── dsh-unsloth（本插件，很薄）
        ├─ 1. 找 Python 解释器（优先用 Unsloth Studio 自带的 venv）
        ├─ 2. 可选：先把 Unsloth Studio 拉起来（autoStartStudio）
        └─ 3. 挂载 DSH 自带的 @deepseek-ai/dsh-mcp-client
                 └── server/unsloth_mcp_server.py（零依赖，纯标准库）
                        ├── HTTP → Unsloth Studio 后端  http://127.0.0.1:8888
                        │        （训练 / Data Recipe / 模型 / 导出 / 推理）
                        └── CLI  → python -m unsloth_cli
                                 （train / export / inference / chat）

设计上刻意不复刻协议层：MCP 客户端用的是 DSH 自己的那一个，所以工具命名（mcp__<serverName>__<tool>）、单次调用超时、断线自动重连的行为，跟手写一条 cordis.patch.yml 条目完全一致；插件只负责"找到解释器 + 找到脚本 + 挂上去"。

环境要求

要求	说明
Unsloth Desktop	装好即可（默认路径 `~/.unsloth/studio`）。Studio 的 venv 会被自动用作解释器
Python 3.8+	MCP 服务只用标准库，所以任何 Python 都行；没有 Python 时插件会打印明确的错误而不是静默失败
DSH	带 `@deepseek-ai/dsh-mcp-client`（`dsh-base` 的依赖，向来都在）

安装

方式 A：一键脚本（推荐，不需要 pnpm / 不需要联网）

# 在普通 PowerShell 里运行（不要在被文件沙箱限制的环境里跑）
.\install.ps1                       # 默认装到 web 这个 profile
.\install.ps1 -Profile web -AutoStartStudio

脚本做三件事：把插件复制到 <profile>\node_modules\dsh-unsloth；在 profile 的 cordis.patch.yml 里补一条 insert（已有则跳过）；备份原配置。改完是热加载生效，不用重启 DSH。

方式 B：手动（等价于脚本）

把本目录整体复制到 %APPDATA%\dsh-desktop\harness\profiles\web\node_modules\dsh-unsloth
在 %APPDATA%\dsh-desktop\harness\profiles\web\cordis.patch.yml 末尾追加：

- insert:
    - id: unsloth
      name: dsh-unsloth
      config:
        serverName: unsloth
        hfEndpoint: https://hf-mirror.com   # 国内网络建议
        disableXet: true
        autoStartStudio: true

⚠️ 必须是 insert: 列表形式。 这一层是"id 定向覆盖层"，裸写 - id: xxx 会被当成"覆盖已有条目"，新 id 找不到目标就被静默忽略（日志里连报错都没有）。

方式 C：作为正式包分发

推到 npm 后即可用 DSH 插件市场安装——package.json 里 dsh.bundle.patch 已指向插件自带的 cordis.patch.yml，市场装完会自动 insert，无需手改 YAML。

配置项

写在 insert 条目的 config: 下即可，全部有默认值：

键	默认	说明
`enabled`	`true`	关掉整个桥接而不必删条目
`serverName`	`unsloth`	MCP 命名空间，工具名 = `mcp__<serverName>__<tool>`
`python`	`""`	指定解释器绝对路径；留空自动探测（Studio venv → 常见安装位置 → PATH）
`studioUrl`	`http://127.0.0.1:8888`	Studio 后端地址
`hfEndpoint`	`""`	注入 `HF_ENDPOINT` 给派生的 Unsloth 子进程，如 `https://hf-mirror.com`
`disableXet`	`true`	注入 `HF_HUB_DISABLE_XET=1`。Xet 走 `cas-server.xethub.hf.co`，镜像环境下必然 401 中断下载
`homeDir`	`""`	MCP 服务的 config.json 与日志目录；留空 = `<DSH_HOME>\unsloth-mcp`（故意不放 node_modules，重装不会被清掉）
`toolCallTimeoutMs`	`600000`	单次工具调用超时（默认 60s 对训练/导出太短）
`failOnStartupError`	`false`	初始连接失败是否让插件激活失败
`autoStartStudio`	`false`	激活时若 Studio 没在监听就用它的 venv 起一个（真香：不用再手动开桌面版）
`studioArgs`	`[]`	追加给 `unsloth studio` 的参数，如 `["--no-cloudflare"]`

工具清单（20 个，全部来自 MCP 服务）

工具	用途
`studio_status`	Studio 是否在跑 + 版本 + 硬件。动手前先调它
`studio_start`	启动 Studio（可 `api_only`），后台常驻
`studio_stop`	停掉全部 Studio 实例（官方 `unsloth studio stop`，按 STUDIO_HOME）
`studio_api`	万能后门：直连 Studio 任意 `/api` `/v1` 端点（400+ 路由）
`unsloth_cli`	原始 CLI 后门：`train` / `inference` / `chat` / `export` / `list-checkpoints` / `studio`（含 `run` `stop` `verify-install`）/ `start`（把 Claude、Codex、dsh 等指向 Unsloth）
`models_list`	`kind=local\|cached\|loras\|checkpoints`，外加 `checkpoints_cli`（扫输出根目录，看得见 CLI 训练的检查点）
`export`	导出检查点：`merged-16bit` / `merged-4bit` / `gguf` / `lora`，可推 HuggingFace
`recipe_seed_inspect`	检查数据集生成的种子（列名 + 预览行）
`recipe_validate`	校验 recipe（建任务前必做）
`recipe_create`	建数据集生成任务（`preview` 试跑 / `full` 全量）
`recipe_status`	任务状态 + 分析（无任务时返回 idle，不报错）
`recipe_dataset`	取回生成的训练样本
`unsloth_text`	文本训练（CLI 路径）。30+ 训练参数；spawn 前自动 `--dry-run` 预检；`dry_run_only=true` 只预检不训练
`unsloth_image`	视觉 / VLM 训练（Studio API 路径）
`unsloth_text_status`	文本训练状态：Studio 状态 + 本服务登记的任务（pid 存活、日志 verdict、最新 loss）
`unsloth_image_status`	视觉训练状态（存活状态取自 Studio 后端）
`train_status`	【已弃用】不分类型的全局状态，等价于上面两个的并集
`train_stop`	停止训练：Studio 后端 + 按 pid 结束 CLI 进程树（`scope=all\|cli\|studio`）
`train_runs`	历史训练记录
`chat`	推理自检；Studio 没加载模型时自动回退到 `unsloth inference`

0.1.3 曾把训练拆成 unsloth_text / unsloth_image，同时删掉了 train_start；本 README 之前还列着 train_start，属于文档滞后，已修正。

训练参数（`unsloth_text`）

参数表直接对照 CLI 的 Typer 定义逐项核对，不是手抄：

model / dataset / local_dataset / format_type / training_type
max_seq_length / load_in_4bit / output_dir
num_epochs / max_steps / save_steps / warmup_steps
learning_rate / batch_size / gradient_accumulation_steps
weight_decay / random_seed / gradient_checkpointing / packing / train_on_completions
lora_r / lora_alpha / lora_dropout / target_modules / use_rslora / use_dora
enable_wandb / wandb_project / enable_tensorboard / tensorboard_dir
config / extra_args / dry_run_only / unload_inference / force

⚠️ `training_type` 的坑（本版本已自动兜住）

unsloth train 只认 lora 与 full；Studio 的 REST API 只认 LoRA/QLoRA / Full Finetuning / Continued Pretraining。两套词表互不通用。

CLI 用 setattr 覆盖配置、且没开 Pydantic 的 validate_assignment，所以传错值不会报错：它会一路走到 use_lora = training_type.lower() == "lora" —— "lora/qlora" != "lora"，于是 use_lora=False，load_in_4bit 也被强制成 False，你要的 QLoRA 悄悄变成完全微调。 4GB 卡上这基本等于必挂。

本机历史证据：unsloth-mcp/logs/train-smoke02.log 第 25 行 Full finetuning mode - training all parameters，可训练参数 72.44% —— 那一次请求的正是 LoRA/QLoRA。本版本会自动归一化，并在返回的 notes 里说明改了什么；修复后同一组参数的实测结果是 LoRA adapters configured successfully、可训练参数 1.75%（8,798,208 / 502,830,976）。

⚠️ `output_dir` 必须在 outputs 根目录内

这条限制由 trainer 自己强制（studio/backend/core/training/trainer.py 的 resolve_output_dir()），CLI 与 Studio API 两条路径都一样 —— 0.1.2 / 0.1.3 「支持任意输出路径」的说法是不成立的，实测会以 Training error: path escapes root: ... is not under ...\.unsloth\studio\outputs 失败。

现在两个训练工具都会在启动进程之前拦下并给出根目录，可行写法只有两种：

给相对目录名（如 my-run）→ 落到 ~/.unsloth/studio/outputs/my-run
给根目录之内的绝对路径

不传时检查点直接落在 ~/.unsloth/studio/outputs 下。

验证

离线预检（不碰 harness，用桩 ctx 跑 apply()，并让配置通过 mcp-client 自己的 Schema 校验）：

cd $env:APPDATA\dsh-desktop\harness\profiles\web
node .\dsh-unsloth-selftest.mjs

预期输出里应有 mounted mcp-client: true、ACCEPTED、interpreter: ... exists: true。

运行期：看 %APPDATA%\dsh-desktop\logs\harness.log。可靠出现的标志是 MCP 服务那一行（它由插件挂载的 mcp-client 启动，stderr 会被转发到日志）：

[stderr] [unsloth-mcp] ready (base_url=http://127.0.0.1:8888, cli=...)

然后让模型调一次 mcp__unsloth__studio_status：能返回 Studio 版本与 GPU 信息就说明整条链路通了。

插件自己还有一行 banner（[dsh-unsloth] info: ... -> ... (serverName=..., home=...)），它被镜像写到 stderr。在终端里跑 harness 时一定看得到；在 DSH Desktop 里是否落到 harness.log 取决于宿主对 stderr 的捕获方式， 别把它当成唯一的判断依据——以 [unsloth-mcp] ready 和工具调用为准。

排错

现象	原因 / 解法
工具完全不出现，日志无报错	`cordis.patch.yml` 里写成了裸 `- id:` → 改成 `insert:` 列表形式
改了插件的 JS 代码但行为没变	配置热重载会重新挂插件，但 Node 的 ESM 模块缓存不会失效 → 重启一次 DSH Desktop（实测：改配置后 `[unsloth-mcp] ready` 次数会增加，说明插件确实重新执行了；但已 import 的旧模块代码可能被复用）
日志出现 `serverName "unsloth" is already in use`	同时存在另一条 `dsh-mcp-client` 条目用了同名 `serverName` → 删掉重复的那条，或改 `serverName`
`no Python interpreter found`	设 `python:` 为绝对路径；或确认 Unsloth Desktop 已安装
工具能调但全部报"连不上 Studio"	Studio 没在跑 → 开 `autoStartStudio: true`，或让模型调 `studio_start`
下载模型老中断（CAS 401）	保持 `disableXet: true`，并设 `hfEndpoint: https://hf-mirror.com`；GUI 里对应 Model hub 顶部的 HTTP/Xet 开关
Studio 启动报 `unable to open database file`	启动它的进程被文件沙箱限制，写不了 `~/.unsloth` → 让 DSH 自己起（`autoStartStudio`）或在沙箱外手动开桌面版
训练启动几秒后失败，日志只有 `Unsloth: No or negligible GPU memory available for fused cross entropy`	有推理模型占着显存（4GB 卡上推理与训练不能共存）。两个训练工具都会前置检查并拦下，提示你传 `unload_inference: true`（工具会先 `POST /api/inference/unload`，再轮询等显存真正释放）
`train_status` 里 Studio 一直显示 `idle` / `Ready to train`	正常：CLI 训练不会登记进 Studio 的训练后端。看响应里的 `jobs`——含进程存活、日志 verdict（completed/failed）、最新 loss/epoch。想看 CLI 的检查点用 `models_list kind=checkpoints_cli`
后台训练秒退，日志只有 `No such option: --num_epochs (Possible options: --num-epochs)`	0.1.4 之前训练参数表里写错了这个 flag。已修；升级后 `--num-epochs` 正常
请求 LoRA/QLoRA，日志却是 `Full finetuning mode - training all parameters`、可训练参数 70%+	`training_type` 词表错配（见上文「`training_type` 的坑」）。0.1.4 起会自动归一化到 `lora` 并在 `notes` 里说明
`Training error: path escapes root: ... is not under ...\.unsloth\studio\outputs`	`output_dir` 在 outputs 根目录之外。CLI 与 API 两条路径都受限 → 传相对目录名，或用根目录内的绝对路径。0.1.4 起会在启动前就拦下
视觉训练早已结束，`unsloth_image_status` 仍报 `running: true`	0.1.3 及以前把占位 pid `"api_train"` 当成活进程。0.1.4 起存活状态取自 `/api/train/status` 的 `is_training_running`
训练进程偶发 `forrtl: error (200): program aborting due to window-CLOSE event`	Intel Fortran 运行时把 detach 子进程"没有控制台"当成 close 事件而 abort。0.1.5 起已修：注入 `FOR_DISABLE_CONSOLE_CTRL_HANDLER=1`（Intel 官方开关），实测连续两次训练完整跑完
升级插件报 `ERR_PNPM_EPERM ... node_modules\dsh-unsloth`	有进程把插件目录当工作目录 → 0.1.1 起所有派生进程的 cwd 都移出包目录（`<DSH_HOME>\unsloth-mcp`），升级无需先停用插件

与 Unsloth 官方 CLI 的关系（`unsloth start dsh`）

Unsloth 官方 CLI 自带一组面向编码 agent 的命令，其中就包括 DeepSeek Harness：

unsloth start {claude|codex|openclaw|opencode|hermes|pi|dsh}

unsloth start dsh 做的是反方向的事：它把 DSH 的默认模型指向正在运行的 Unsloth 服务（写 <DSH_HOME>/settings.yaml 里的 llm-pi-ai.providers.unsloth，配 baseURL=<base>/v1、apiKeyEnv=UNSLOTH_API_KEY，并把 agent-default-model 设为该模型）。换句话说：unsloth start dsh 让 DSH 用 Unsloth 当大脑；本插件让 DSH 把 Unsloth 当工具。

两者不冲突，可以同时用。本插件额外把官方 CLI 的能力面接成了原生工具，包括 unsloth studio run|stop|verify-install、unsloth train --dry-run、 unsloth export、unsloth list-checkpoints。

其余子命令与参数请以 CLI 自身为准（unsloth --help、unsloth <cmd> --help）—— 本插件的参数表就是照着它核对的，CLI 升级后如果有出入，以 CLI 为准。

与 `unsloth-mcp/` 的关系

本插件的 MCP 服务源码与工作区里的独立版同源：

位置	用途
`G:\DSH\DSH_workspace\dsh-unsloth\server\unsloth_mcp_server.py`	随插件分发的那一份（自包含，安装即用）
`G:\DSH\DSH_workspace\unsloth-mcp\server.py`	独立/CLI 版，配 `mcp_selftest.py` 等调试脚本一起用

两者改动请同步。完整实操手册（数据集构建 → 下载 → 导入 → 训练参数 → 训练 → 导出 → 推理）见 G:\DSH\DSH_workspace\unsloth-mcp\docs\Unsloth-微调全流程实操手册.md。

ZCode 接入

本插件同时可挂到 ZCode：清单在 .zcode-plugin/plugin.json，复用同一份 server/unsloth_mcp_server.py，工具名为 mcp__plugin_dsh-unsloth_unsloth__<tool>（20 个）。差异与装卸步骤见 ZCODE.md。

License

MIT

dsh-unsloth

安装

源码

标签

作者

说明文档

dsh-unsloth

它是什么 / 怎么工作的

环境要求

安装

方式 A：一键脚本（推荐，不需要 pnpm / 不需要联网）

方式 B：手动（等价于脚本）

方式 C：作为正式包分发

配置项

工具清单（20 个，全部来自 MCP 服务）

训练参数（`unsloth_text`）

⚠️ `training_type` 的坑（本版本已自动兜住）

⚠️ `output_dir` 必须在 outputs 根目录内

验证

排错

与 Unsloth 官方 CLI 的关系（`unsloth start dsh`）

与 `unsloth-mcp/` 的关系

ZCode 接入

License

安装

源码

标签

作者

说明文档

dsh-unsloth

它是什么 / 怎么工作的

环境要求

安装

方式 A：一键脚本（推荐，不需要 pnpm / 不需要联网）

方式 B：手动（等价于脚本）

方式 C：作为正式包分发

配置项

工具清单（20 个，全部来自 MCP 服务）

训练参数（unsloth_text）

⚠️ training_type 的坑（本版本已自动兜住）

⚠️ output_dir 必须在 outputs 根目录内

验证

排错

与 Unsloth 官方 CLI 的关系（unsloth start dsh）

与 unsloth-mcp/ 的关系

ZCode 接入

License

训练参数（`unsloth_text`）

⚠️ `training_type` 的坑（本版本已自动兜住）

⚠️ `output_dir` 必须在 outputs 根目录内

与 Unsloth 官方 CLI 的关系（`unsloth start dsh`）

与 `unsloth-mcp/` 的关系