dsh-local-sd
Verifieddsh-local-sd · v0.9.0 · MIT · Web UI
本地 Stable Diffusion 桥接插件:在「设置 → 本地绘图」里选一下 WebUI / Forge 目录就能用,注册 generate_image_local / generate_image_batch / sd_backend_status / sd_backend_control 四个工具,把本机 sdapi 后端直接接到模型手上。完全本地、零内容过滤、断网可用、后端按需启停。
Install
dsh plugin add dsh-local-sd Confirm the layer applied with dsh --profile default --dump-config — see the install guide.
Source
Tags
Creators
Readme
dsh-local-sd — 本地 Stable Diffusion 桥接插件
在 DSH 里一句话画图:模型把中文需求翻成 Danbooru 标签,直接调用你本机的 Stable Diffusion 出图,图在对话里显示。
全程本地:不联网、不经过任何托管 API、没有任何内容过滤。提示词原样送进采样器。
装好之后只需要做一件事:在「设置 → 本地绘图」里选一下你的 WebUI 目录。之后画图、启后端、关后端全自动。
后端按需启动、闲置自动关闭 —— 不画图时它完全不占显存。
它做什么
注册四个工具给模型:
| 工具 | 作用 |
|---|---|
generate_image_local |
一个提示词,出一张图(后端没开就自动拉起) |
generate_image_batch |
多个提示词 / 同一提示词多张(最多 8 张,串行) |
sd_backend_status |
探测后端,列出已加载的模型、采样器、剩余自动关闭倒计时 |
sd_backend_control |
start / stop / status / detect,手动预热、立刻释放显存、或扫描本机安装 |
外加一个设置页:设置 → 本地绘图。里面能选目录、看状态、调参数、手动启停后端。
出图默认落在工作区 generated/sd-<时间戳>-<序号>.png,同时在对话里渲染。存放位置可以在
设置 → 本地绘图 → 图片存放目录 里改:留空用默认,填相对路径(如 pics/sd)接在工作区后面,
填绝对路径(如 D:\AI\生图)则原样使用。
安装
# 从 npm 装(推荐)
dsh plugin --profile desktop add dsh-local-sd
# 或者从 GitHub 装
dsh plugin --profile desktop add https://github.com/VanYe666/dsh-local-sd
包来源可以是:
| 方式 | 写法 |
|---|---|
| npm 包 | dsh-local-sd |
| GitHub 仓库 | https://github.com/VanYe666/dsh-local-sd |
| 本地 tgz | file:C:\path\to\dsh-local-sd-0.9.0.tgz |
| 本地源码目录(开发) | file:D:\path\to\dsh-local-sd |
不想用 dsh plugin 的话,直接在 profile 目录里 pnpm:
cd %USERPROFILE%\.dsh\profiles\desktop
pnpm add dsh-local-sd
然后把 "dsh-local-sd" 加进 package.json 的 dsh.profile.bundles 数组。
装完重启 DSH。
用官方桌面客户端的话,也可以走 设置 → 插件 的图形界面装,不要命令行——那个 profile 归应用的插件管理器所有。
装完之后:选目录
打开 设置 → 本地绘图,三种方式随便挑一个:
- 浏览… —— 弹系统目录选择框(Electron 桌面版可用;浏览器里跑
dsh web时没有这个框) - 自动探测 —— 扫一遍常见位置,扫到就列出来,点「用这个」
- 手填 —— 直接粘贴路径
填哪一层? 填解压后带 run.bat 的那一层。
D:\AI\forge\webui_forge_cu124_torch24\ ← 填这个
├── run.bat ← 插件要找的就是它
├── webui-user.bat
├── system\
├── webui\
└── models\
Forge 的便携包有两层 run.bat,用外层那个。也接受直接填 run.bat 的完整路径,插件会自己往上取目录。
A1111 原版:Windows 找 webui.bat,Linux / macOS 找 webui.sh,顺序自动。
选好点保存,页面会立刻告诉你识别到了哪个启动文件。识别不到就说明目录填错层了。
后端要求
需要一个 A1111 兼容的 sdapi 后端。任选其一。
SD WebUI Forge(推荐)
webui-user.bat 里必须有 --api:
set COMMANDLINE_ARGS=--medvram --xformers --no-half-vae --api
默认端口 7860。
便携包必看:Forge 的官方 7z 便携包自带
system\python(3.10.6,torch 已装好), 但webui-user.bat默认不指定PYTHON,webui.bat会去建 venv、并从系统 PATH 里找 Python。机器上装了 3.11+ 的话,它会拿新 Python 建 venv、联网重装 torch, 在代理环境下直接失败(ProxyError/Couldn't install torch)。在
webui-user.bat里固定用自带的 Python,并跳过 venv:set PYTHON="%~dp0..\system\python\python.exe" set VENV_DIR= set SKIP_VENV=1 set COMMANDLINE_ARGS=--api --xformers --no-half-vae --skip-python-version-check另外官方
run.bat里call environment.bat用的是相对路径,从别的工作目录启动 会找不到它,于是system\python没进 PATH、又退回系统 Python。插件已经用cd /d兜住了这一层,但自己手动跑的时候仍然建议改成call "%~dp0environment.bat"。
4GB 显存额外注意:
| 场景 | 参数 |
|---|---|
| SD1.5 | --medvram --xformers --no-half-vae --api |
| SDXL | --lowvram --xformers --no-half-vae --api(--medvram 会爆) |
KoboldCpp
koboldcpp.exe --sdmodel <image-model.gguf> --sdoffloadcpu --sdtiledvae 512 --port 5001
4GB 显存建议再加 --sdvramlimit 3000 --sdquant 2 --sdvaedevice CPU --sdclipdevice CPU。
A1111 原版
同上,确保 --api。
生命周期:按需启动,闲置自关
SD 后端占用较高显存,闲置时自动关闭。
你第一次要图
→ 探测 7860/5001… 都没人应答
→ 从「绘图程序目录」推导出 run.bat,cd 进去执行
→ 轮询 /sdapi/v1/options,直到后端应答(最多 启动超时)
→ 出图
→ 每次出图都重置闲置计时器
闲置超过 闲置关闭时间(默认 5 分钟)
→ 杀掉「插件自己启动的」进程树,释放显存
关键细节:
- 只杀自己启动的进程。 你手动双击打开的 Forge,插件永远不会去关它。设置页的「进程归属」会明确显示当前后端是谁启动的。
- 并发调用会合并。 同时来三次请求,只拉起一次后端。
- 冷启动慢是正常的。 Forge 从零启动要 2~3 分钟(加载 torch、扫模型)。第一次出图要等,后续都很快。
- 启动失败会快速报错。 如果 launcher 进程立刻以非 0 退出,插件不等满超时,直接报错并提示你手动运行看输出。
- 代理环境变量会被清掉。 插件拉起后端时剥离
HTTP_PROXY/HTTPS_PROXY并重建NO_PROXY,否则 Forge 的httpx在 import 阶段就崩(InvalidURL: Invalid port: ':1]')。
设置页能改什么
| 项 | 说明 |
|---|---|
| 绘图程序目录 | 含 run.bat / webui.bat / webui.sh 的那一层 |
| 图片存放目录 | 出图存哪儿。留空 = 工作区 generated/;相对路径接在工作区后面;绝对路径原样使用 |
| 自动启动 | 后端没开时是否拉起它。关掉就只连现成的 |
| 启动超时 | 冷启动最长等待,默认 240000 ms(4 分钟) |
| 闲置关闭 | 闲置多久自动关,默认 300000 ms(5 分钟)。填 0 = 永不自动关闭 |
| 接口地址 | 默认 http://127.0.0.1:7860,改过端口才需要动 |
| 默认出图参数 | 宽、高、步数、CFG。4GB 显存建议 512×768 |
| LoRA | 叠加到每一张图上的 LoRA 列表 + 权重。下拉框从 models\Lora 里扫,也可以「浏览…」翻到文件直接加 |
配置写在 $DSH_HOME/local-sd.json(Windows 是 C:\Users\<你>\.dsh\local-sd.json)。每次调用都重新读取,改完不用重启 DSH;手改这个 JSON 也一样有效。
启动进度和命令行输出
后端启动时不再弹出黑色控制台窗口,进度和输出都搬到设置页里:
- 进度条:读绘图程序自己的输出(加载扩展、加载权重、起 API),大致对应当前阶段;没有新输出时会缓慢爬升,不会看起来卡死。
- 查看命令行输出:展开后就是绘图程序真实打印的内容,出错时能看到完整的 traceback,不用再手动跑一遍
run.bat找原因。 - 日志同时写在
$DSH_HOME/local-sd-startup.log,每次启动覆盖。
--nowebui必须配--port:Forge 在--nowebui下如果没指定端口会默认绑 7861 (webui.py里port=cmd_opts.port if cmd_opts.port else 7861),而插件默认找 7860。 想在后台只跑 API 不弹网页,启动参数要写--api --nowebui --port 7860。
用法
装好、选完目录之后,在对话里直接说:
画一个银发红瞳的少女,跪坐在床上,表情迷离
模型会自己:
- 翻成
1girl, solo, silver hair, red eyes, kneeling on bed, ... - 补画质词和负面词
- 调
generate_image_local - 如果 Forge 没开,先把它拉起来(第一次会等 2~3 分钟)
- 出图并显示
手动控制后端
- 「预热一下绘图后端」 →
sd_backend_controlaction=start - 「把显存放掉」 →
sd_backend_controlaction=stop - 「现在用的是哪个模型」 →
sd_backend_status - 「帮我找找 WebUI 装哪了」 →
sd_backend_controlaction=detect
直接控制参数
- 尺寸:
512x512/512x768/768x512/640x640/768x768/832x1216/1216x832/1024x1024 - 步数:
steps1–150(默认 25) - CFG:
cfg1–30(默认 7) - 采样器:
euler_a、dpmpp_2m、dpmpp_2m_sde_gpu、ddim、heun、unipc等,snake_case 自动转后端显示名 - 种子:
seed,-1 随机;固定种子可微调同一构图 - LoRA:
lora数组,覆盖设置页里选的那组(不传 = 用设置页的),见下面一节 - 负面词:
negative,不传用配置默认值
LoRA
LoRA 是挂在底模上的小补丁(画风、角色、服装、姿势都能做),文件放
webui\models\Lora\,一个通常 20~200 MB。
必须和底模同架构:SD1.5 的 LoRA 只能配 SD1.5 的模型,SDXL / Illustrious 的只能配 SDXL 系。 挂错架构不会报错,只会出糊图。
怎么传
lora 参数吃两种写法:
// 文件名,权重默认 1
"lora": ["myStyle"]
// 带权重
"lora": [{ "name": "myStyle", "multiplier": 0.8 }]
- 带不带
.safetensors后缀都行(从资源管理器复制文件名时通常带着) - 权重会被夹到 0~2,一般 0.6~1.0;超过 1.5 多半会把画面烧糊
- 可以同时挂多个,按数组顺序拼接
设置页里选中某个 LoRA 时会显示它文件里写的元数据:架构(SDXL / SD1.5)、dim / alpha、
训练日期、触发词、描述。alpha / dim 偏小(< 0.3)的会提示「天生偏弱,权重往 1.0~1.5 调」。
这些信息读的是 .safetensors 文件头,几 KB 的 IO,后端没开也能看。
插件会把它拼成提示词标签:
1girl, solo, <lora:myStyle:0.8>
所以直接在提示词里手写 <lora:名字:权重> 也是一样的效果,插件不会重复添加。
为什么不是走 API 字段:A1111 / Forge 的
/sdapi/v1/txt2img请求体里根本没有lora这个属性 (/openapi.json里 56 个字段,一个都不是)。往 body 里塞lora会被静默丢掉—— 同一个种子,塞不塞出来的图字节完全一样。后端只认提示词里的标签。
提示词写法
SD1.5 / SDXL 听不懂自然语言,必须用 Danbooru 标签:
画质词 + 角色特征 + 动作姿势 + 场景光影 + 视角构图
常见画质词:
masterpiece, best quality, very aesthetic, absurdres, highres
CetusMix、Counterfeit 这类 SD1.5 融合模型对简洁直白的标签反应最好,别写长句。
性能参考(4GB 显存实测)
| 配置 | 单张耗时 |
|---|---|
| 512×768 / 25 步 | 约 2 分钟 |
| 512×512 / 20 步 | 60~80 秒 |
| 批量 4 张 | 约 8 分钟 |
| 冷启动(Forge 从零) | 2~3 分钟(仅第一次) |
排错
| 现象 | 原因 | 处理 |
|---|---|---|
| 设置页说「没找到启动文件」 | 目录填错层了 | 填带 run.bat 的那一层,不是 system\ 里面 |
| 「浏览…」点了没反应 | 浏览器里跑 dsh web,没有系统目录框 |
手填路径,或用「自动探测」 |
No local Stable Diffusion backend answered |
后端没开且自动启动关了,或端口不对 | 设置页开自动启动,或检查接口地址 |
| 启动超时报错 | 冷启动太慢 | 调大启动超时;确认目录里有 run.bat |
| launcher 立刻退出(exit 1) | 命令写错 / 缺依赖 | 手动双击那个 .bat 看报错 |
| 报「文件名、目录名或卷标语法不正确」 | Windows 上 cmd /c 的引号被 Node 默认处理剥掉,cd /d 收到裸路径(0.4.0 已修) |
升级到 0.4.1+ |
Forge 启动后立刻报 INCOMPATIBLE PYTHON VERSION / ProxyError |
便携包没固定自带 Python,去建 venv 联网装 torch | 见上面「便携包必看」,设 PYTHON + SKIP_VENV=1 |
| 后端活着但出图 500 | 模型没加载 / 显存爆了 | 设置页看状态;降分辨率或改 --lowvram |
| 出图出一半后端没了 / 等到超时 | 0.8.0 及以前:闲置计时器在出图中途把后端关了 | 升级 0.8.1+,或把「闲置关闭」调大 / 填 0 |
| 图糊、花屏 | VAE 半精度问题 | 启动参数加 --no-half-vae |
| 出图全是噪点 | 步数太低或 CFG 异常 | 步数提到 20+,CFG 回到 7 |
| 配置改了没生效 | 端口写错 / JSON 语法错 | 插件容错 BOM;确认 JSON 合法 |
sd_backend_status 是最快的自检:它直接告诉你后端是否可达、加载的是哪个模型、还有多久自动关闭。
开发
npm test
覆盖启动器路径推导:绝对路径、相对路径、带引号、直接指向 run.bat、目录里没有启动文件、目录不存在。
只依赖 Node 内置模块,不需要装任何东西,也不碰网络。
打新包:
npm pack
改完源码重装一次:
cd ~/.dsh/profiles/desktop && pnpm add file:D:\path\to\dsh-local-sd
安全说明
这个插件不做任何内容判断。提示词原样 POST 给本机 sdapi 接口,图片原样写回工作区。没有云端往返,没有审核,没有改写。
出图内容完全取决于你自己加载的模型。
设置页的 API 走同源 POST /local-sd/api,由宿主自己的 connection.requestRejection 把关,只在本机回环可用。
License
MIT