本地生图 LisonEvf/dsh-qwen-image

@lisonevf/dsh-qwen-image

在 AI 会话窗口里直接生图 / 改图，模型跑在你自己的显卡上。

给 dsh（DeepSeek Harness）用的对话式生图 / 改图插件，专用于 Qwen-Image-2.1（原生 2K、原生透明 PNG、支持改图）。

- 在对话里说「画一只戴墨镜的柴犬」→ 对话流直接出图，不用切终端、不用另开 WebUI
- 「把刚才那张的背景换成黄昏海滩」→ 改图（最多 10 张参考图）
- 权重体检 + 下载代办、作品相册、worker 显存控制（image_worker unload）

快速开始

第 0 步：把插件下载到本地

git clone https://github.com/lisonevf/dsh-qwen-image.git

或在仓库页面点 Code → Download ZIP 再解压。下面提到的 install.bat / install.sh 都在这个目录里。

前置：Node.js 18+ 与 dsh（npm install -g @deepseek-ai/dsh）。缺 dsh 时安装器仍会装好环境与权重，只是不注册插件，之后装好 dsh 重跑一次即可。

Windows：双击 install.bat　|　Linux / macOS：sh install.sh

装完重启 dsh（客户端界面半只在进程启动时加载；用哪个 profile 安装器收尾会打印，通常是 web）：

dsh --profile web # 若安装时挑的是别的 profile，把 web 换成它打印的那个

先体检不修改：install.bat --check　|　只看要做什么：install.bat --dry-run（Linux / macOS 换成 sh install.sh --check / sh install.sh --dry-run）

出图大概要等多久（P40 实测）：draft 768²/12步 ≈ 2.5 分钟、standard 1024²/24步 ≈ 5.0 分钟、native 2048²/40步 ≈ 43 分钟。

普通用户请先读 使用说明.txt；完整文档见 docs/INSTALL.md。

⚠️ 装完后请不要删除或移动本插件目录（插件是链接安装，删掉目录会导致 dsh 启动时加载失败）。

为什么做成插件，而不是自己拉个脚本跑

本地跑 Qwen-Image-2.1 的难点从来不是"调一次 API"，而是装和管：

| 问题 | 本插件的做法 |
| 我该装哪个 CUDA 版本的 torch？ | 安装器探测驱动，自动在 cu128/cu126/cu124/cu121/cu118 之间选，装不上逐级降级 |
| 我已经有 ComfyUI / conda 环境了 | 复用它的 site-packages，省约 3GB 下载，且不动它本身 |
| 机器上没有 Python | 自动下载 uv 并托管 Python 3.12 |
| 权重 30GB 从哪下、断了下不动 | 权重体检 + 下载代办，走 hf-mirror，失败回落官方 / ModelScope |
| 显存被占了，我想把它还回去 | image_worker unload 一条命令卸载模型 |
| 出过的图去哪了 | 对话内联卡片 + 作品相册 + /raw?id= 直链，可回放 |

它怎么适配不同的机器

| 情况 | 安装器的做法 |
| 已有 torch + diffusers（含 ComfyUI 便携版/conda） | 借它的 site-packages 建 venv，省约 3GB 下载，不动它本身 |
| 完全没有 Python | 自动下载 uv 并托管 Python 3.12 |
| 驱动从 CUDA 11.8 到 12.9 | 自动选 cu128/cu126/cu124/cu121/cu118，装不上逐级降级到 CPU；Linux + AMD 走 ROCm 6.3 |
| 没有 NVIDIA 显卡 | 装 CPU 版并明确警告速度 |
| macOS | 装 PyPI 版 torch，但本插件只认 NVIDIA CUDA，实际按 CPU 推理（1024² 一张要数小时，仅供试跑） |
| 国内网络 | pip 源按实测延迟选镜像；权重走 hf-mirror，失败回落官方/ModelScope |
| 磁盘不够 / 想换盘 | --model-dir，并在下载前就报出空间需求 |

硬件门槛（实测，不是估算）

数据来自本机 P40 / fp16 / 32GB RAM 的实测记录（完整口径见 docs/HARDWARE.md 与 acceptance/LOG.md）：

| 项 | 实测 | 说明 |
| 峰值显存（单条件图） | ~17 GB | 1024×1536 |
| 峰值显存（双条件图） | ~21.6 GB | 已逼近 24 GB 上限 |
| worker 卸载后常驻内存 | 20.2 GB | 32GB 机器上建议每 3–4 张图重启一次 worker |
| 冷启动 | 每张约 85 秒 | 每图重付，32GB 内存装不下 30.86GB 权重的必然结果 |

一句话结论：24GB 显存的卡能舒服跑，显存更小请先看 docs/HARDWARE.md 再决定。
我们不在这里给你一个乐观的数字。

开发

npm install
npm run build # host 半 + client 半 → lib/
npm test # 离线冒烟（含安装器设备矩阵 108 项）powershell
npm run test:gpu # 真 GPU worker 协议端到端
npm run test:integration # host × 真 worker 全链路（能真出一张图）
npm run check:release # ★ 发布闸门：一键安装所依赖的硬约束（见下）

改完 src/ 必须重建并提交 lib/

本项目是零依赖一键安装：普通用户下载后直接双击 install.bat，不会跑 npm install。
所以 lib/index.cjs 与 lib/client.js 是随仓库分发的构建产物，必须入库（.gitignore 里是刻意不忽略 lib/ 的）。
改了 src/ 却忘了重建并提交 lib/，用户装到的就是旧代码 —— 发布前用下面这条兜住： powershell
npm run check:release:full # 重建 lib/ 并核对已提交的产物是否过期；另查 gitignore/行尾/占位符/本机路径/权重泄漏

架构与决策记录见 docs/PLAN.md，实测数据见 docs/HARDWARE.md 与 acceptance/LOG.md。

在 AI 会话里对话式生成和编辑图片 —— 在自己的 GPU 上跑 Qwen-Image-2.1。

这是 dsh 的插件。在聊天里说「画一只戴墨镜的柴犬」，图片就直接出现在对话里；说「把上一张的背景换成日落海滩」就能改图（最多 10 张参考图）。原生 2K 输出，原生透明 PNG。

在本地跑 Qwen-Image-2.1，难的地方从来不是单次调用，而是环境搭建。安装程序会探测你的驱动，挑出合适的 CUDA 构建（cu128 → cu118，再降级到 CPU），复用已有的 torch/diffusers 安装（ComfyUI 便携版、conda），省下约 3GB 下载量；你机器上没装 Python，就用 uv 引导安装；30GB 权重走 hf-mirror 镜像。image_worker unload 能把显存还给你。

在 P40 上实测（fp16，32GB 内存）：单张图冷启动约 85 秒，单条件图片显存峰值约 17GB，双条件约 21.6GB。显卡小的话，先看 docs/HARDWARE.md 再决定。

许可

- 本插件代码：Apache-2.0（见 LICENSE）。
- Qwen-Image-2.1 权重：采用 Qwen Research License（仅限研究用途，商用需另行授权）。
本仓库不携带、不分发任何权重文件，权重由使用者在安装时自行从 HuggingFace / ModelScope 下载；使用权重与生成内容须同时遵守模型自身的许可条款。