VRAM Switcher

English · Releases · IndexTTS 集成 · 和 llama-swap / berth 的区别

为本地 AI 情感陪伴（AstrBot / DeepSeek Harness）原生接入的 GPU 调度器 —— 让人设对话、IndexTTS 语音和自拍/改图在同一张 12 GB 卡上轮流用卡。

它不是通用 GPU 租约系统：不换客户端、不加代理、不读 nvidia-smi，只在宿主的事件边界上停/起你明确列出的进程。

在 12 GB 卡上，它把本地 LLM、IndexTTS 和 ComfyUI 从「互相换页」变成「轮流独占」——实测 s2mel 从 30 s/步回到 0.12 s/步，预填从 0.2 tok/s 回到 ~1300 tok/s。

LLM 常驻，显存 4.9 GB / 12 GB
        │
        ├── "/aimg 一只猫" ──► 停 LLM ──► 起 ComfyUI ──► 出图 ──► 等队列跑空
        │                              (腾出 ~6 GB)             停 ComfyUI
        │                                                        拉起 LLM
        └── 语音请求 ──────► 停 LLM ──► 确保 TTS 在线 ──► 合成 ──► 拉起 LLM

它只负责这些「停/起」的顺序。不是模型、不是路由、也不是要你重写的启动器：所有机器相关的参数都在一个 JSON profile 里。

为什么需要它

12 GB 卡上通常是这样：

服务	常驻显存
`llama-server`（Qwen3.6-35B-A3B MoE，256K 上下文）	~4.9 GB
IndexTTS webui	~2.3–5.3 GB
ComfyUI + SD/Flux	~6–7 GB
桌面 + 宿主程序	~2 GB

前三个里任意两个加桌面就会溢出。Windows 不会当场报错，而是开始把显存换页到内存——这不会崩，只会慢 100 倍。在写下它的那台机器上实测：s2mel 扩散从 0.12 s/步变成 30 s/步，一张图跑了 543 秒，预填从 ~1300 tok/s 掉到 0.2 tok/s。进程一直是活的。

这套东西最初就是给一个本地 AI 陪伴机器人写的：她要有人设连续性（本地 LLM）、要能发语音（IndexTTS）、要能自拍和改图（ComfyUI），而且这些经常发生在同一个回合里。通用 GPU 调度器不知道一段语音什么时候真正合成完；对陪伴场景，那个边界恰恰是最重要的。

解法不是换更大的卡，而是确保关键时刻只有一个在占显存。

它做什么

任务前停掉不需要的、拉起需要的，结束后再放回去。
真的等就绪：ComfyUI 必须 8188 在 listen，而不是进程刚起（早 1 秒连接曾让每次自拍都失败）；一批图会先等 /queue 跑空再停服务。
只动你列出的东西：进程名 + 命令行过滤 + 可选端口白名单，没有“杀掉所有 python.exe”这条路。
跨进程串行：AstrBot 插件和 DSH 插件共用 coordinator.lock，语音事件和生图任务不会同时切服务。
一套核心，两个宿主：AstrBot（Python 插件）与 DeepSeek Harness（原生 Cordis 插件 + 小 Python daemon）。另带 MCP stdio 服务，可给 Claude Desktop / Codex 用。

适合谁

显存协调已经不缺项目：llama-swap 6.1k★，berth 2026-10-11 才公开、已 200★，vhotseat、OneGPU4All 也在做类似的事。这个项目不假装是通用调度器，它只解决一个具体问题：

你在 AstrBot 或 DSH 上跑一个本地 AI 陪伴：人设对话（本地 LLM）+ IndexTTS 语音 + 自拍/改图（ComfyUI），全在同一张 12 GB 卡上。

一次回合里可能同时发生：

用户消息
  ├─ 她回复文字（LLM 占卡）
  ├─ 回复带 [语音] → 停 LLM → IndexTTS 合成 → 恢复 LLM
  └─ 调 generate_selfie → 停 LLM/TTS → ComfyUI 出图 → 恢复 LLM

你的情况	更合适的选择
只是 llama.cpp / vLLM 换模型，所有客户端都能改 base URL	llama-swap
要通用 GPU 租约、优先级、游戏/VM/多卡仲裁	berth（alpha，Windows 实验性）
Linux 上 LLM ↔ ComfyUI 轮流	vhotseat
在 AstrBot / DSH 上跑本地 AI 陪伴，不想改端口、不加代理，语音合成结束才切	本项目

相对通用调度器，它多做这些：

AstrBot 的 5 个事件钩子：LLM 请求、回复装饰前后、工具调用前、工具返回后
DSH 原生 Cordis 工具：vram_status / vram_acquire / vram_release
IndexTTS 的 tts_busy.flag / tts_ready.flag 协议（合成边界，不是 HTTP 边界）
真实进程停启：TTS 没有 unload API 也能让出显存

也少做这些：多卡、游戏/VM、优先级队列、网关、nvidia-smi 轮询、provider 自动切换。需要这些就选上面的通用项目。

不跑 AstrBot / DSH 也可以：核心包 vram_switcher 不依赖宿主，VramService 提供 start / acquire / release / status，可以直接在你的 AI 陪伴服务里用：

from vram_switcher import load_config
from vram_switcher.service import VramService

cfg = load_config({"profile_path": "profile.local.json"}, plugin_dir=".", data_dir="./data")
service = VramService(cfg)
await service.start()
await service.acquire("image", reason="selfie")   # 停 LLM、起 ComfyUI
# ... 出图 ...
await service.release("selfie")                   # 停 ComfyUI、恢复 LLM

语音侧仍建议走 tts_busy.flag / tts_ready.flag，因为只有 TTS 插件知道合成什么时候真正结束。

快速开始

git clone https://github.com/xiaoxiao150/vram-switcher
cd vram-switcher

# 自动探测正在运行的 llama-server / TTS webui / ComfyUI，生成 profile。
# 这一步不会启动或停止任何进程。
python configure.py --root D:/AI        # 只看不写加 --dry-run

configure.py 会写出 profile.local.json，并打印它找到了什么：

[detected] llm: running process
[detected] tts: running process
[missing ] image: fill this in by hand
[port    ] 8080 (llm) listening
[port    ] 7860 (tts) listening
[port    ] 8188 (image) free

把宿主指向这个文件并重启即可。没探测到的服务会写成 enabled: false，插件仍然合法，只是少做一件事。

状态机

LLM 常驻
  ├─ TTS 请求 → 停 LLM（可停辅助服务）→ 确保 TTS 在线 → 完成后恢复 LLM
  └─ 生图请求 → 停 LLM（可停 TTS/辅助服务）→ 启动图像服务 → 等就绪
       → 出图完成 → 等队列跑空 → 停图像服务 → 恢复 LLM

特性

配置驱动：路径、端口、进程名、启动命令、日志、超时全部在 profile.local.json
三类服务：llm / tts / image，外加任意数量的只停不启 aux_services
引擎 / 版本 profile：多个 LLM 引擎（如 moe、dense27b）、多个 TTS 版本（2.5 / 2.0，支持 auto）
TTS 文件协议：tts_busy.flag 表示合成中，tts_ready.flag 表示显存已就绪
为 AI 陪伴回合设计：文字回复 → 语音合成 → 自拍/改图可以在同一回合内安全切换
生图队列：恢复前轮询 ComfyUI /queue，不打断一批多张图
夜间静默：默认 23:00–07:00 不重新拉起本地 LLM
兼容层：_prepare_switch、_recover_after_tts、事件标记、flag 路径全部保留
默认不切 provider：交给 AstrBot 的 fallback 链，避免与 default_provider_id 打架
原生 DSH Cordis 插件 + MCP 备用入口 + 跨进程协调锁

AstrBot 安装

git clone https://github.com/xiaoxiao150/vram-switcher   AstrBot/data/plugins/astrbot_plugin_vram_switcher

也可以直接从插件市场安装：搜 VRAM Switcher（cloud.astrbot.app）。

然后在插件配置里确认：

profile_path = 你生成的 profile.local.json（建议放 AstrBot/data/plugin_data/astrbot_plugin_vram_switcher/，填绝对路径）
local_llm_engine = profile 里的引擎键（用 configure.py 生成时是 detected）
index_tts_version = auto 或 2.5 / 2.0

没跑过 configure.py 的话，也可以从 profile.example.json 手动复制一份改。如果 profile 找不到或 JSON 非法，插件会记录错误并保持禁用，不会崩溃或乱杀进程。

IndexTTS 集成：为什么必须停进程

IndexTTS webui 没有“卸载模型”的 HTTP API。它常驻时占 2.3–5.3 GB；本地 LLM 占 4.9 GB；ComfyUI 出图要 6–7 GB。12 GB 卡上三者不能共存，只能让 TTS 在合成前把卡让出来，合成后再还回去。

这里用的是进程级互斥 + 两个文件：

AstrBot 决定发语音
  │
  ├─ TTS 插件写 tts_busy.flag（并删掉上一轮的 tts_ready.flag）
  │
  ▼
VRAM Switcher（每 2 s 轮询）
  ├─ 停本地 LLM（以及 profile 里的 aux_services）
  ├─ 确保 IndexTTS webui 在线（没起就按 versions 启动，等端口 listen）
  └─ 写 tts_ready.flag
  │
  ▼
TTS 插件等到 ready + webui 在线，才提交 /gen_single
  │
  ▼
合成结束，TTS 插件删掉 tts_busy.flag
  │
  ▼
VRAM Switcher 恢复：等 ComfyUI 队列跑空 → 停图像服务 → 拉起本地 LLM

关键点：

tts_ready.flag 必须在真正停完 LLM 之后写。TTS 抢跑会让 s2mel 权重被 Windows 换页：实测 0.12 s/步 → 30 s/步，25 步要 731 秒。
电话场景下 busy flag 每 1.5 秒续一次，避免被看门狗当成崩溃残留。
900 秒没更新的 busy flag 会被清理，防止进程崩了以后永远卡在“合成中”。
version_selector: auto 跟随正在运行的 2.5 / 2.0；两个都没起时用 default_version。
IndexTTS 冷启动约 60 秒，TTS 侧等待 ready 的超时要给够（生产用 150 秒）。

最小 profile：

{
  "services": {
    "tts": {
      "enabled": true,
      "port": 7860,
      "process_names": ["python.exe"],
      "cmdline_contains": ["webui.py"],
      "cmdline_any": ["IndexTTS", "Index-TTS"],
      "stop": {"timeout_seconds": 20, "tree": false},
      "busy_flag": "${DATA_DIR}/tts_busy.flag",
      "ready_flag": "${DATA_DIR}/tts_ready.flag",
      "flag_stale_seconds": 900,
      "start_cooldown_seconds": 150,
      "version_selector": "auto",
      "default_version": "2.5",
      "versions": {
        "2.5": {
          "args": ["D:/AI/IndexTTS2.5/.venv/Scripts/python.exe",
                   "D:/AI/IndexTTS2.5/webui.py", "--version", "2.5", "--fp16"],
          "cwd": "D:/AI/IndexTTS2.5"
        }
      }
    }
  }
}

完整的适配器代码、AstrBot 钩子优先级和失败排查见 docs/indextts.md。注意：这个仓库只提供调度侧；你的 TTS 插件必须按上面的协议写/删 flag，否则联动不会生效。

Profile 参考

完整示例见 profile.example.json。

profile 字符串里支持两个内置变量，避免把绝对路径写死：

${PLUGIN_DIR}：插件源码目录
${DATA_DIR}：AstrBot 的 plugin_data/astrbot_plugin_vram_switcher 目录
${ENV_NAME}：读取同名环境变量

LLM

{
  "services": {
    "llm": {
      "enabled": true,
      "port": 8080,
      "process_names": ["llama-server.exe"],
      "stop": {"timeout_seconds": 15, "tree": true},
      "start": {
        "engine": "moe",
        "profiles": {
          "moe": {
            "args": ["D:/AI/llama/llama-server.exe", "-m", "D:/AI/models/model.gguf", "-c", "32768"],
            "cwd": "D:/AI/llama",
            "log_file": "${DATA_DIR}/llm.log"
          }
        }
      },
      "ready": {"type": "process", "timeout_seconds": 50},
      "recovery_wait_seconds": 45,
      "night_quiet": {"enabled": true, "start": "23:00", "end": "07:00"}
    }
  }
}

process_names 是停止/检查用的进程名白名单。
start.profiles 可以有多个引擎；AstrBot 配置里的 local_llm_engine 选其中一个。
ready.type = process 表示“看到进程存在”即算恢复；如果你的启动器会先起一个壳进程，建议改成 port。
recovery_wait_seconds 是启动后等待时间；0 表示立即检查（适合测试）。

TTS

{
  "services": {
    "tts": {
      "enabled": true,
      "port": 7860,
      "process_names": ["python.exe"],
      "cmdline_contains": ["webui.py"],
      "cmdline_any": ["IndexTTS", "Index-TTS"],
      "stop_extra": [{"process_names": ["cmd.exe"], "cmdline_any": ["IndexTTS"]}],
      "stop": {"timeout_seconds": 20, "tree": false},
      "busy_flag": "${DATA_DIR}/tts_busy.flag",
      "ready_flag": "${DATA_DIR}/tts_ready.flag",
      "flag_stale_seconds": 900,
      "start_cooldown_seconds": 150,
      "version_selector": "auto",
      "default_version": "2.5",
      "versions": {
        "2.5": {"args": ["python.exe", "webui.py", "--version", "2.5", "--fp16"], "cwd": "D:/AI/IndexTTS2.5"}
      }
    }
  }
}

TTS 插件需要配合两个文件：

合成开始时创建 busy_flag，结束时删除；
VRAM Switcher 在 LLM 停掉、TTS 在线后写 ready_flag，TTS 插件应在提交合成前等它出现。

flag_stale_seconds 用于清理崩溃后残留的 busy 文件，避免永远卡在“合成中”。

Image

{
  "services": {
    "image": {
      "enabled": true,
      "port": 8188,
      "process_names": ["python.exe"],
      "cmdline_contains": ["ComfyUI"],
      "stop_by_port": true,
      "start": {
        "args": ["D:/AI/ComfyUI/python/python.exe", "-u", "-s", "D:/AI/ComfyUI/ComfyUI/main.py", "--windows-standalone-build"],
        "cwd": "D:/AI/ComfyUI/ComfyUI"
      },
      "ready": {"type": "port", "timeout_seconds": 300},
      "queue": {"timeout_seconds": 420, "interval_seconds": 6}
    }
  }
}

stop_by_port: true 会额外杀掉监听该端口的进程。只在你确认端口属于该服务时使用。

辅助服务

{
  "aux_services": [
    {
      "key": "prompt_optimizer",
      "process_names": ["pe-server.exe"],
      "stop": {"timeout_seconds": 10, "tree": true}
    }
  ]
}

辅助服务只停不启。适合提示词优化器、临时缓存服务等“下次使用时会自己拉起”的进程。

触发规则

{
  "triggers": {
    "tts_keywords": ["语音"],
    "image_prefixes": ["aimg", "img2img", "改图", "/改图"],
    "image_tool_names": ["generate_selfie", "generate_image", "comfyui_txt2img"],
    "tts_reply_marker_pattern": "[\\[【]\\s*语音\\s*[\\]】]"
  }
}

tts_keywords：用户消息包含关键词 → TTS 预切换。
image_prefixes：消息首词匹配 → 生图预切换。
image_tool_names：LLM 决定调用这些工具前 → 生图预切换。
tts_reply_marker_pattern：LLM 回复里出现语音标记 → TTS 预切换。

AstrBot 插件配置里的 extra_tts_keywords / extra_comfyui_prefixes 会追加到 profile 对应列表。

与其它 AstrBot 插件兼容

为了兼容已有生态，插件保留以下接口：

事件 extra：_vram_switcher_active、_vram_switcher_reason、_vram_switcher_indextts_killed
await plugin._prepare_switch(event, "tool:...")
await plugin._recover_after_tts()
on_decorating_result(event)（也会把最终恢复跑完）
flag 路径可通过 profile 配置；默认仍建议放在 plugin_data/astrbot_plugin_vram_switcher/

如果其它插件硬编码了 flag 路径，保持 busy_flag / ready_flag 指向同一位置即可。

DSH 原生 Cordis 插件

这个仓库同时就是一个原生 DSH 插件包（dsh-vram-switcher）：

DSH Cordis -> dsh-plugin/index.js -> ctx.tools.register(...)
                              └─ Python daemon.py -> vram_switcher.Orchestrator

package.json 的 dsh.bundle.patch 指向仓库根的 cordis.patch.yml
dsh-plugin.json 是 DSH manifest v0.15
原生工具：vram_status / vram_acquire / vram_release
DSH 加载时启动一个长驻 Python daemon，复用 AstrBot 的同一套核心和锁

安装与市场发布说明见 dsh/README.md，配置覆盖模板见 dsh/cordis.patch.example.yml。DSH 和 AstrBot 必须使用同一个 profile.local.json 与 dataDir，否则跨进程锁不会生效。

如果当前 DSH 轮次正在使用本地 LLM，不要调用 vram_acquire，否则它会停掉正在生成回复的模型。

MCP 仍作为备用入口保留：mcp_server.py 可给 Claude Desktop、Codex 等没有原生 Cordis 插件的宿主使用；不要和原生插件同时加载，避免重复管理同一组服务。

开发与测试

核心包 vram_switcher/ 不依赖 AstrBot，可以直接测试：

python -m unittest discover -s tests -v

测试使用 FakeSystem，不会启动/停止真实进程，也不需要 GPU；tests/test_configure.py 会验证 configure.py --dry-run 只输出 JSON、拒绝覆盖已有文件，并确认生成的 profile 能被真实 loader 接受。

CI 见 .github/workflows/ci.yml，在 Python 3.10 / 3.11 / 3.12 上跑单元测试。

起源

2026-08：第一版写在一个本地 AI 陪伴项目里。当时她在 AstrBot 里用本地 LLM 聊天、用 IndexTTS 发语音、用 ComfyUI 自拍，三件事只能手动杀进程轮换，经常把正在生成的回复卡死。
2026-09-28：一次自拍请求撞上 ComfyUI 冷启动（当时只等 120 秒），插件误判未就绪，请求落到云端节点，触发隐私事故。此后把就绪等待改成 300 秒，并把“停/起”做成显式状态机。
2026-10：重构成 profile 驱动的 2.0，同一套核心接上 AstrBot 插件与 DSH 原生 Cordis 插件，开源。
2026-10-26：公开仓库。代码在公开前已经在一台 12 GB 机器上跑了两个多月。

公开时间不等于开始时间。这段历史写在这里，是因为在“谁先”这个问题上，最早的生产日志比仓库创建日期更有说服力；也是因为这个项目的第一需求从来不是“调度 GPU”，而是“让她在只有一张 12 GB 卡的情况下，仍然能同时聊天、发语音和自拍”。

已知限制

Windows 优先；Linux 有基本的 ps/kill 支持，但进程名和启动器差异需要自行适配。
不读取 nvidia-smi 显存数值；显存是否释放由进程/端口/标志文件推断。这样更可预测，也避免驱动差异。
TTS 必须实现 busy/ready 文件协议；其它 TTS 可以自己写一个薄适配器。
ComfyUI 队列接口默认为 /queue；其它图像服务可以在 profile 里改 queue.url，或设为不可用。
默认不做 provider 切换；需要的话继承 NullProviderHooks 并在适配器里实现。

在市场里安装

AstrBot：WebUI → 插件市场搜 VRAM Switcher，或 cloud.astrbot.app 搜仓库 xiaoxiao150/vram-switcher。
DSH：已提交 awesome-dsh-plugin 收录（PR #9555），合并后即可在 DSH 插件市场搜到 vram-switcher。

源码安装：

# AstrBot
git clone https://github.com/xiaoxiao150/vram-switcher     AstrBot/data/plugins/astrbot_plugin_vram_switcher

# DSH（包名 dsh-vram-switcher）
dsh plugin --profile web add github:xiaoxiao150/vram-switcher

仓库名是 vram-switcher，但 AstrBot 会把插件安装到 data/plugins/astrbot_plugin_vram_switcher/（取自 metadata.yaml 的 name），两者不一致是正常的。

发布信息：v2.0.3 Release。

安全模型

风险	处理
杀错进程	进程名且命令行过滤，可选端口白名单；没有裸名字匹配
杀到自己	排除当前 PID 与父 PID
Shell 注入	`start` 是 argv 数组，`shell=False` 执行
两个宿主打架	`coordinator.lock` 覆盖整个 acquire → release 窗口
配置写错	加载时校验；非法 profile 只禁用插件并记录原因，不猜
路径泄漏	`profile.local.json` 已 git-ignore；示例里没有真实路径

License

MIT. See LICENSE.

VRAM Switcher

English · Releases · IndexTTS 集成 · 和 llama-swap / berth 的区别

为本地 AI 情感陪伴（AstrBot / DeepSeek Harness）原生接入的 GPU 调度器 —— 让人设对话、IndexTTS 语音和自拍/改图在同一张 12 GB 卡上轮流用卡。

它不是通用 GPU 租约系统：不换客户端、不加代理、不读 nvidia-smi，只在宿主的事件边界上停/起你明确列出的进程。

LLM 常驻，显存 4.9 GB / 12 GB
        │
        ├── "/aimg 一只猫" ──► 停 LLM ──► 起 ComfyUI ──► 出图 ──► 等队列跑空
        │                              (腾出 ~6 GB)             停 ComfyUI
        │                                                        拉起 LLM
        └── 语音请求 ──────► 停 LLM ──► 确保 TTS 在线 ──► 合成 ──► 拉起 LLM

它只负责这些「停/起」的顺序。不是模型、不是路由、也不是要你重写的启动器：所有机器相关的参数都在一个 JSON profile 里。

为什么需要它

12 GB 卡上通常是这样：

服务	常驻显存
`llama-server`（Qwen3.6-35B-A3B MoE，256K 上下文）	~4.9 GB
IndexTTS webui	~2.3–5.3 GB
ComfyUI + SD/Flux	~6–7 GB
桌面 + 宿主程序	~2 GB

解法不是换更大的卡，而是确保关键时刻只有一个在占显存。

它做什么

任务前停掉不需要的、拉起需要的，结束后再放回去。
真的等就绪：ComfyUI 必须 8188 在 listen，而不是进程刚起（早 1 秒连接曾让每次自拍都失败）；一批图会先等 /queue 跑空再停服务。
只动你列出的东西：进程名 + 命令行过滤 + 可选端口白名单，没有“杀掉所有 python.exe”这条路。
跨进程串行：AstrBot 插件和 DSH 插件共用 coordinator.lock，语音事件和生图任务不会同时切服务。
一套核心，两个宿主：AstrBot（Python 插件）与 DeepSeek Harness（原生 Cordis 插件 + 小 Python daemon）。另带 MCP stdio 服务，可给 Claude Desktop / Codex 用。

适合谁

你在 AstrBot 或 DSH 上跑一个本地 AI 陪伴：人设对话（本地 LLM）+ IndexTTS 语音 + 自拍/改图（ComfyUI），全在同一张 12 GB 卡上。

一次回合里可能同时发生：

用户消息
  ├─ 她回复文字（LLM 占卡）
  ├─ 回复带 [语音] → 停 LLM → IndexTTS 合成 → 恢复 LLM
  └─ 调 generate_selfie → 停 LLM/TTS → ComfyUI 出图 → 恢复 LLM

你的情况	更合适的选择
只是 llama.cpp / vLLM 换模型，所有客户端都能改 base URL	llama-swap
要通用 GPU 租约、优先级、游戏/VM/多卡仲裁	berth（alpha，Windows 实验性）
Linux 上 LLM ↔ ComfyUI 轮流	vhotseat
在 AstrBot / DSH 上跑本地 AI 陪伴，不想改端口、不加代理，语音合成结束才切	本项目

相对通用调度器，它多做这些：

AstrBot 的 5 个事件钩子：LLM 请求、回复装饰前后、工具调用前、工具返回后
DSH 原生 Cordis 工具：vram_status / vram_acquire / vram_release
IndexTTS 的 tts_busy.flag / tts_ready.flag 协议（合成边界，不是 HTTP 边界）
真实进程停启：TTS 没有 unload API 也能让出显存

也少做这些：多卡、游戏/VM、优先级队列、网关、nvidia-smi 轮询、provider 自动切换。需要这些就选上面的通用项目。

不跑 AstrBot / DSH 也可以：核心包 vram_switcher 不依赖宿主，VramService 提供 start / acquire / release / status，可以直接在你的 AI 陪伴服务里用：

from vram_switcher import load_config
from vram_switcher.service import VramService

cfg = load_config({"profile_path": "profile.local.json"}, plugin_dir=".", data_dir="./data")
service = VramService(cfg)
await service.start()
await service.acquire("image", reason="selfie")   # 停 LLM、起 ComfyUI
# ... 出图 ...
await service.release("selfie")                   # 停 ComfyUI、恢复 LLM

语音侧仍建议走 tts_busy.flag / tts_ready.flag，因为只有 TTS 插件知道合成什么时候真正结束。

快速开始

git clone https://github.com/xiaoxiao150/vram-switcher
cd vram-switcher

# 自动探测正在运行的 llama-server / TTS webui / ComfyUI，生成 profile。
# 这一步不会启动或停止任何进程。
python configure.py --root D:/AI        # 只看不写加 --dry-run

configure.py 会写出 profile.local.json，并打印它找到了什么：

[detected] llm: running process
[detected] tts: running process
[missing ] image: fill this in by hand
[port    ] 8080 (llm) listening
[port    ] 7860 (tts) listening
[port    ] 8188 (image) free

把宿主指向这个文件并重启即可。没探测到的服务会写成 enabled: false，插件仍然合法，只是少做一件事。

状态机

LLM 常驻
  ├─ TTS 请求 → 停 LLM（可停辅助服务）→ 确保 TTS 在线 → 完成后恢复 LLM
  └─ 生图请求 → 停 LLM（可停 TTS/辅助服务）→ 启动图像服务 → 等就绪
       → 出图完成 → 等队列跑空 → 停图像服务 → 恢复 LLM

特性

配置驱动：路径、端口、进程名、启动命令、日志、超时全部在 profile.local.json
三类服务：llm / tts / image，外加任意数量的只停不启 aux_services
引擎 / 版本 profile：多个 LLM 引擎（如 moe、dense27b）、多个 TTS 版本（2.5 / 2.0，支持 auto）
TTS 文件协议：tts_busy.flag 表示合成中，tts_ready.flag 表示显存已就绪
为 AI 陪伴回合设计：文字回复 → 语音合成 → 自拍/改图可以在同一回合内安全切换
生图队列：恢复前轮询 ComfyUI /queue，不打断一批多张图
夜间静默：默认 23:00–07:00 不重新拉起本地 LLM
兼容层：_prepare_switch、_recover_after_tts、事件标记、flag 路径全部保留
默认不切 provider：交给 AstrBot 的 fallback 链，避免与 default_provider_id 打架
原生 DSH Cordis 插件 + MCP 备用入口 + 跨进程协调锁

AstrBot 安装

git clone https://github.com/xiaoxiao150/vram-switcher   AstrBot/data/plugins/astrbot_plugin_vram_switcher

也可以直接从插件市场安装：搜 VRAM Switcher（cloud.astrbot.app）。

然后在插件配置里确认：

profile_path = 你生成的 profile.local.json（建议放 AstrBot/data/plugin_data/astrbot_plugin_vram_switcher/，填绝对路径）
local_llm_engine = profile 里的引擎键（用 configure.py 生成时是 detected）
index_tts_version = auto 或 2.5 / 2.0

IndexTTS 集成：为什么必须停进程

这里用的是进程级互斥 + 两个文件：

AstrBot 决定发语音
  │
  ├─ TTS 插件写 tts_busy.flag（并删掉上一轮的 tts_ready.flag）
  │
  ▼
VRAM Switcher（每 2 s 轮询）
  ├─ 停本地 LLM（以及 profile 里的 aux_services）
  ├─ 确保 IndexTTS webui 在线（没起就按 versions 启动，等端口 listen）
  └─ 写 tts_ready.flag
  │
  ▼
TTS 插件等到 ready + webui 在线，才提交 /gen_single
  │
  ▼
合成结束，TTS 插件删掉 tts_busy.flag
  │
  ▼
VRAM Switcher 恢复：等 ComfyUI 队列跑空 → 停图像服务 → 拉起本地 LLM

关键点：

tts_ready.flag 必须在真正停完 LLM 之后写。TTS 抢跑会让 s2mel 权重被 Windows 换页：实测 0.12 s/步 → 30 s/步，25 步要 731 秒。
电话场景下 busy flag 每 1.5 秒续一次，避免被看门狗当成崩溃残留。
900 秒没更新的 busy flag 会被清理，防止进程崩了以后永远卡在“合成中”。
version_selector: auto 跟随正在运行的 2.5 / 2.0；两个都没起时用 default_version。
IndexTTS 冷启动约 60 秒，TTS 侧等待 ready 的超时要给够（生产用 150 秒）。

最小 profile：

{
  "services": {
    "tts": {
      "enabled": true,
      "port": 7860,
      "process_names": ["python.exe"],
      "cmdline_contains": ["webui.py"],
      "cmdline_any": ["IndexTTS", "Index-TTS"],
      "stop": {"timeout_seconds": 20, "tree": false},
      "busy_flag": "${DATA_DIR}/tts_busy.flag",
      "ready_flag": "${DATA_DIR}/tts_ready.flag",
      "flag_stale_seconds": 900,
      "start_cooldown_seconds": 150,
      "version_selector": "auto",
      "default_version": "2.5",
      "versions": {
        "2.5": {
          "args": ["D:/AI/IndexTTS2.5/.venv/Scripts/python.exe",
                   "D:/AI/IndexTTS2.5/webui.py", "--version", "2.5", "--fp16"],
          "cwd": "D:/AI/IndexTTS2.5"
        }
      }
    }
  }
}

Profile 参考

完整示例见 profile.example.json。

profile 字符串里支持两个内置变量，避免把绝对路径写死：

${PLUGIN_DIR}：插件源码目录
${DATA_DIR}：AstrBot 的 plugin_data/astrbot_plugin_vram_switcher 目录
${ENV_NAME}：读取同名环境变量

LLM

{
  "services": {
    "llm": {
      "enabled": true,
      "port": 8080,
      "process_names": ["llama-server.exe"],
      "stop": {"timeout_seconds": 15, "tree": true},
      "start": {
        "engine": "moe",
        "profiles": {
          "moe": {
            "args": ["D:/AI/llama/llama-server.exe", "-m", "D:/AI/models/model.gguf", "-c", "32768"],
            "cwd": "D:/AI/llama",
            "log_file": "${DATA_DIR}/llm.log"
          }
        }
      },
      "ready": {"type": "process", "timeout_seconds": 50},
      "recovery_wait_seconds": 45,
      "night_quiet": {"enabled": true, "start": "23:00", "end": "07:00"}
    }
  }
}

process_names 是停止/检查用的进程名白名单。
start.profiles 可以有多个引擎；AstrBot 配置里的 local_llm_engine 选其中一个。
ready.type = process 表示“看到进程存在”即算恢复；如果你的启动器会先起一个壳进程，建议改成 port。
recovery_wait_seconds 是启动后等待时间；0 表示立即检查（适合测试）。

TTS

{
  "services": {
    "tts": {
      "enabled": true,
      "port": 7860,
      "process_names": ["python.exe"],
      "cmdline_contains": ["webui.py"],
      "cmdline_any": ["IndexTTS", "Index-TTS"],
      "stop_extra": [{"process_names": ["cmd.exe"], "cmdline_any": ["IndexTTS"]}],
      "stop": {"timeout_seconds": 20, "tree": false},
      "busy_flag": "${DATA_DIR}/tts_busy.flag",
      "ready_flag": "${DATA_DIR}/tts_ready.flag",
      "flag_stale_seconds": 900,
      "start_cooldown_seconds": 150,
      "version_selector": "auto",
      "default_version": "2.5",
      "versions": {
        "2.5": {"args": ["python.exe", "webui.py", "--version", "2.5", "--fp16"], "cwd": "D:/AI/IndexTTS2.5"}
      }
    }
  }
}

TTS 插件需要配合两个文件：

合成开始时创建 busy_flag，结束时删除；
VRAM Switcher 在 LLM 停掉、TTS 在线后写 ready_flag，TTS 插件应在提交合成前等它出现。

flag_stale_seconds 用于清理崩溃后残留的 busy 文件，避免永远卡在“合成中”。

Image

{
  "services": {
    "image": {
      "enabled": true,
      "port": 8188,
      "process_names": ["python.exe"],
      "cmdline_contains": ["ComfyUI"],
      "stop_by_port": true,
      "start": {
        "args": ["D:/AI/ComfyUI/python/python.exe", "-u", "-s", "D:/AI/ComfyUI/ComfyUI/main.py", "--windows-standalone-build"],
        "cwd": "D:/AI/ComfyUI/ComfyUI"
      },
      "ready": {"type": "port", "timeout_seconds": 300},
      "queue": {"timeout_seconds": 420, "interval_seconds": 6}
    }
  }
}

stop_by_port: true 会额外杀掉监听该端口的进程。只在你确认端口属于该服务时使用。

辅助服务

{
  "aux_services": [
    {
      "key": "prompt_optimizer",
      "process_names": ["pe-server.exe"],
      "stop": {"timeout_seconds": 10, "tree": true}
    }
  ]
}

辅助服务只停不启。适合提示词优化器、临时缓存服务等“下次使用时会自己拉起”的进程。

触发规则

{
  "triggers": {
    "tts_keywords": ["语音"],
    "image_prefixes": ["aimg", "img2img", "改图", "/改图"],
    "image_tool_names": ["generate_selfie", "generate_image", "comfyui_txt2img"],
    "tts_reply_marker_pattern": "[\\[【]\\s*语音\\s*[\\]】]"
  }
}

tts_keywords：用户消息包含关键词 → TTS 预切换。
image_prefixes：消息首词匹配 → 生图预切换。
image_tool_names：LLM 决定调用这些工具前 → 生图预切换。
tts_reply_marker_pattern：LLM 回复里出现语音标记 → TTS 预切换。

AstrBot 插件配置里的 extra_tts_keywords / extra_comfyui_prefixes 会追加到 profile 对应列表。

与其它 AstrBot 插件兼容

为了兼容已有生态，插件保留以下接口：

事件 extra：_vram_switcher_active、_vram_switcher_reason、_vram_switcher_indextts_killed
await plugin._prepare_switch(event, "tool:...")
await plugin._recover_after_tts()
on_decorating_result(event)（也会把最终恢复跑完）
flag 路径可通过 profile 配置；默认仍建议放在 plugin_data/astrbot_plugin_vram_switcher/

如果其它插件硬编码了 flag 路径，保持 busy_flag / ready_flag 指向同一位置即可。

DSH 原生 Cordis 插件

这个仓库同时就是一个原生 DSH 插件包（dsh-vram-switcher）：

DSH Cordis -> dsh-plugin/index.js -> ctx.tools.register(...)
                              └─ Python daemon.py -> vram_switcher.Orchestrator

package.json 的 dsh.bundle.patch 指向仓库根的 cordis.patch.yml
dsh-plugin.json 是 DSH manifest v0.15
原生工具：vram_status / vram_acquire / vram_release
DSH 加载时启动一个长驻 Python daemon，复用 AstrBot 的同一套核心和锁

如果当前 DSH 轮次正在使用本地 LLM，不要调用 vram_acquire，否则它会停掉正在生成回复的模型。

MCP 仍作为备用入口保留：mcp_server.py 可给 Claude Desktop、Codex 等没有原生 Cordis 插件的宿主使用；不要和原生插件同时加载，避免重复管理同一组服务。

开发与测试

核心包 vram_switcher/ 不依赖 AstrBot，可以直接测试：

python -m unittest discover -s tests -v

CI 见 .github/workflows/ci.yml，在 Python 3.10 / 3.11 / 3.12 上跑单元测试。

起源

2026-08：第一版写在一个本地 AI 陪伴项目里。当时她在 AstrBot 里用本地 LLM 聊天、用 IndexTTS 发语音、用 ComfyUI 自拍，三件事只能手动杀进程轮换，经常把正在生成的回复卡死。
2026-09-28：一次自拍请求撞上 ComfyUI 冷启动（当时只等 120 秒），插件误判未就绪，请求落到云端节点，触发隐私事故。此后把就绪等待改成 300 秒，并把“停/起”做成显式状态机。
2026-10：重构成 profile 驱动的 2.0，同一套核心接上 AstrBot 插件与 DSH 原生 Cordis 插件，开源。
2026-10-26：公开仓库。代码在公开前已经在一台 12 GB 机器上跑了两个多月。

已知限制

Windows 优先；Linux 有基本的 ps/kill 支持，但进程名和启动器差异需要自行适配。
不读取 nvidia-smi 显存数值；显存是否释放由进程/端口/标志文件推断。这样更可预测，也避免驱动差异。
TTS 必须实现 busy/ready 文件协议；其它 TTS 可以自己写一个薄适配器。
ComfyUI 队列接口默认为 /queue；其它图像服务可以在 profile 里改 queue.url，或设为不可用。
默认不做 provider 切换；需要的话继承 NullProviderHooks 并在适配器里实现。

在市场里安装

AstrBot：WebUI → 插件市场搜 VRAM Switcher，或 cloud.astrbot.app 搜仓库 xiaoxiao150/vram-switcher。
DSH：已提交 awesome-dsh-plugin 收录（PR #9555），合并后即可在 DSH 插件市场搜到 vram-switcher。

源码安装：

# AstrBot
git clone https://github.com/xiaoxiao150/vram-switcher     AstrBot/data/plugins/astrbot_plugin_vram_switcher

# DSH（包名 dsh-vram-switcher）
dsh plugin --profile web add github:xiaoxiao150/vram-switcher

仓库名是 vram-switcher，但 AstrBot 会把插件安装到 data/plugins/astrbot_plugin_vram_switcher/（取自 metadata.yaml 的 name），两者不一致是正常的。

发布信息：v2.0.3 Release。

安全模型

风险	处理
杀错进程	进程名且命令行过滤，可选端口白名单；没有裸名字匹配
杀到自己	排除当前 PID 与父 PID
Shell 注入	`start` 是 argv 数组，`shell=False` 执行
两个宿主打架	`coordinator.lock` 覆盖整个 acquire → release 窗口
配置写错	加载时校验；非法 profile 只禁用插件并记录原因，不猜
路径泄漏	`profile.local.json` 已 git-ignore；示例里没有真实路径

License

MIT. See LICENSE.

xiaoxiao150/vram-switcher

VRAM Switcher

为什么需要它

它做什么

适合谁

快速开始

状态机

特性

AstrBot 安装

IndexTTS 集成：为什么必须停进程

Profile 参考

LLM

TTS

Image

辅助服务

触发规则

与其它 AstrBot 插件兼容

DSH 原生 Cordis 插件

开发与测试

起源

已知限制

在市场里安装

安全模型

License

Community comments

xiaoxiao150/vram-switcher

VRAM Switcher

为什么需要它

它做什么

适合谁

快速开始

状态机

特性

AstrBot 安装

IndexTTS 集成：为什么必须停进程

Profile 参考

LLM

TTS

Image

辅助服务

触发规则

与其它 AstrBot 插件兼容

DSH 原生 Cordis 插件

开发与测试

起源

已知限制

在市场里安装

安全模型

License

Community comments