dsh-local-llm-controller

---

兼容性说明：DSH 0.1.7-rc.1 进行了大规模底层重构，本插件自 v2.1.0 起适配该架构（仅适配 RC 分支，其余分支不作保证）。

特性

• 一键启停本地服务：在设置 → 插件卡片上启动或停止 llama-server，状态、错误原因与最近日志同卡显示；DSH 重启时插件自动清理子进程。
• 双槽位模型管理：槽位 A / B 各绑定一个模型文件夹，自动扫描其中全部 GGUF 生成候选列表；视觉投影器（mmproj）自动识别，视觉模式自动挂载。
• 八组启动参数：按槽位 × 文本/视觉 × 快速/长上下文划分，参数行自由增删，基础参数预填，每行可标记为开关或取值。
• 一键接入会话：将选中模型写入 DSH 模型页，会话底部即可选用本地模型对话。
• 本地压缩引擎（v2.1.2）：以子路径导出形式提供 DSH 内置压缩引擎的本地替代实现，面向 32k~256k 本地窗口，详见「本地压缩引擎」。

本插件仅承担 DSH 与 llama.cpp 之间的连接与控制：不包含 llama-server 本体，也不负责模型下载。二者分别来自上游 llama.cpp 与社区量化发布（如 Hugging Face）。

快速开始

安装

推荐通过 DSH 内置插件管理器安装：侧边栏 设置 → 插件 → 添加插件，输入下表任意一种地址，选择安装源后安装并启用。安装完成后无需重启 DSH Web。

也可使用命令行安装（重复执行同一命令即为升级；已是最新版本时提示 Already up to date）：

dsh plugin --profile web add <地址>

常用命令：

dsh plugin --profile web outdated                                       # 检查更新，无输出即已是最新
dsh plugin --profile web add dsh-local-llm-controller@2.1.3             # 安装指定版本
npx @deepseek-ai/dsh plugin --profile web add dsh-local-llm-controller  # 未全局安装 dsh CLI 时的等价调用

[!NOTE] 安装或升级时出现 peer 依赖警告属正常现象：本插件的 peer 依赖由 DSH 宿主提供，不随包安装，不影响使用。

使用流程

1. 配置槽位：槽位 A / B 各填写一个模型文件夹路径（含模型 GGUF；视觉场景还需包含 mmproj 文件），点击保存配置。
2. 写入模型列表：保存后文件夹内全部模型 GGUF 显示为候选气泡（mmproj 不出现在列表中，视觉模式自动挂载）。选择一个模型，保存配置，点击「添加到模型列表」。模型名由文件名自动派生，如需修改名称请前往 设置 → 模型 页操作。写入条目每次启动就绪后按当前预设组自动同步（切换快速/长上下文并重新启动即更新），取值如下：

   写入条目	取值
   contextWindow	槽位快速参数组的 -c 值
   maxTokens	上述 -c 值的四分之一（v2.1.2 起由二分之一下调：预留过大会压低压缩阈值，见「本地压缩引擎」）

注意事项

• 同一槽位更换模型文件后，Provider Key 随文件名变化：设置 → 模型 页的旧条目不会被自动覆写或删除，需手动删除后重新写入。
• 旧版 llama-server 的图片解码器不支持 WebP。本插件已将 DSH 的图片请求预算提升至 16 MiB / 4096²，常规 PNG/JPEG 截图与大图可原样直达；WebP 源文件请先转换为 PNG/JPEG 再发送。
• 视觉投影器文件须在文件名中包含 mmproj 方可被自动识别，默认卸载到GPU，需要卸载到CPU添加 -mmdev none 。
• 如需固定 Provider Key（更换模型文件后无需重选模型），可在 设置 → 模型 页为对应模型改名；模型页的修改不回写插件配置。

卸载

1. 模型运行中先在卡片点击「停止」（可选，DSH 重启时插件自动清理子进程）；若默认模型或某预设已设为本地模型，先改回云端模型再卸载，避免默认模型悬空。
2. 通过插件管理器的卸载按钮，或执行以下命令（bundle 注册与 link 依赖自动移除）：

   dsh plugin --profile web remove dsh-local-llm-controller
   

3. 刷新页面，卡片消失，无需重启 DSH。

卸载命令会自动清理 profile 的 bundle 注册与依赖声明，以下内容不会被自动删除（v2.1.0 / DSH 0.1.7-rc.1 实测）：

[!NOTE] 从 v2.0.x 升级：旧版 settings.yaml 中的 local-llm 配置段已随 DSH 0.1.7 的一次性导入更名为 settings.yaml.imported，无程序读取，无需处理。

推荐启动参数

12G VRAM + 32G RAM

35B（Occamy-1.0，MoE，IQ4_NL）

文本

35B · 文本 · 快速    : -ngl 99 -fa on -np 1 --cache-type-k q8_0 --cache-type-v q8_0 -cmoe --moe-cache-mib 8608 --load-mode none --reasoning-budget 8192 --cache-ram 2048 --ctx-checkpoints 8 --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0.0 --repeat-penalty 1 --presence-penalty 0 -c 32768 --metrics --slots
35B · 文本 · 长上下文 : -ngl 99 -fa on -np 1 --cache-type-k q8_0 --cache-type-v q8_0 -cmoe --moe-cache-mib 7600 --load-mode none --reasoning-budget 8192 --cache-ram 4096 --ctx-checkpoints 8 --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0.0 --repeat-penalty 1 --presence-penalty 0 -c 131072 --metrics --slots

视觉

35B · 视觉 · 快速    : -ngl 99 -mmdev none -fa on -np 1 --cache-type-k q8_0 --cache-type-v q8_0 -cmoe --moe-cache-mib 8608 --load-mode none --reasoning-budget 8192 --cache-ram 2048 --ctx-checkpoints 8 --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0.0 --repeat-penalty 1 --presence-penalty 0 -c 32768 --metrics --slots
35B · 视觉 · 长上下文 : -ngl 99 -mmdev none -fa on -np 1 --cache-type-k q8_0 --cache-type-v q8_0 -cmoe --moe-cache-mib 7600 --load-mode none --reasoning-budget 8192 --cache-ram 4096 --ctx-checkpoints 8 --temp 0.6 --top-k 20 --top-p 0.95 --min-p 0.0 --repeat-penalty 1 --presence-penalty 0 -c 131072 --metrics --slots

9B（Qwen3.5-9B，Dense，Q4_K_M）

文本

9B · 文本 · 快速    : -ngl 99 -fa auto -np 1 --cache-type-k q8_0 --cache-type-v q8_0 --reasoning-budget 8192 --cache-ram 4096 --ctx-checkpoints 8 --temp 0.8 --top-k 40 --top-p 0.95 --min-p 0.05 --repeat-penalty 1 --presence-penalty 0 -c 32768 --metrics --slots
9B · 文本 · 长上下文 : -ngl 99 -fa auto -np 1 --cache-type-k q8_0 --cache-type-v q8_0 --reasoning-budget 8192 --cache-ram 4096 --ctx-checkpoints 8 --temp 0.8 --top-k 40 --top-p 0.95 --min-p 0.05 --repeat-penalty 1 --presence-penalty 0 -c 65536 --metrics --slots

视觉

9B · 视觉 · 快速    : -ngl 99 -mmdev none -fa auto -np 1 --cache-type-k q8_0 --cache-type-v q8_0 --reasoning-budget 8192 --cache-ram 4096 --ctx-checkpoints 8 --temp 0.8 --top-k 40 --top-p 0.95 --min-p 0.05 --repeat-penalty 1 --presence-penalty 0 -c 32768 --metrics --slots
9B · 视觉 · 长上下文 : -ngl 99 -mmdev none -fa auto -np 1 --cache-type-k q8_0 --cache-type-v q8_0 --reasoning-budget 8192 --cache-ram 4096 --ctx-checkpoints 8 --temp 0.8 --top-k 40 --top-p 0.95 --min-p 0.05 --repeat-penalty 1 --presence-penalty 0 -c 65536 --metrics --slots

更完整的实测数据、选型结论与实验方法见「推荐阅读」。

推荐阅读

• 本地模型调优实测存档（分模型报告）：跨模型共同经验 + 35B / 9B / 27B / Occamy 每模型一份实测报告（编号 00-08），含结论速览、横向能力对比与原始日志留存说明。
• Occamy-1.0 调优与部署存档（-ncmoe 方案）：含视觉预设实测；-cmoe 方案与 -ncmoe 方案的同显存三档对照见 08-occamy-cmoe.md。
• llm-experiment-design · DSH 调优 Skill：面向新 GGUF 深度调优的 Skill，按「运行时探查 → 必要性驱动扫描 → 四件套测量 → 能力验证」流程输出可复现的最优启动参数（MoE 与 Dense 通用）。

本地压缩引擎（v2.1.2）

本插件以子路径导出形式提供压缩引擎 LocalCompactionEngine，继承官方 CompactionEngine 基类，用于替换 DSH 内置压缩引擎。面向 32k~256k 本地上下文窗口，解决内置引擎的两类问题：触发阈值被固定预留量压低乃至静默停用；压缩后占用仍然偏高，下一轮再次触发压缩形成正反馈。

包名与存在形式

与 DSH 默认压缩的区别

核心机制

接入方式：创建自定义 agent 模式

本引擎无法在安装后自动替换官方预设内置的压缩组：官方补丁机制的寻址范围不覆盖预设内部的插件列表。使用方式为在 DSH 中创建自定义 agent 模式（预设），并在其插件列表中声明压缩组：

- id: compaction
  name: cordis:group
  group: true
  isolate:
    compaction: true
    toolResultPruner: true
  config:
    - id: local-compaction
      name: 'dsh-local-llm-controller/compaction'
    - id: command-compact
      name: '@deepseek-ai/dsh-command-compact'
    - id: tool-result-pruner
      name: '@deepseek-ai/dsh-compaction-tool-result-pruner'
      config:
        thresholdChars: 4096
        headChars: 2048
        tailChars: 512

isolate 字段必须保留：引擎通过 ctx.get 读取工具结果修剪器，两者需处于同一 isolate realm。

预设可通过用户层补丁文件声明（以 link 依赖注册进 profile 并列入 dsh.profile.bundles），也可通过 Web 设置编辑器创建。回落与停用：将压缩子行的 name 改回 @deepseek-ai/dsh-compaction-basic 即恢复官方引擎；修改后需重启 DSH 生效（bundle 补丁文件不参与热重载）。

引擎子行的可选配置：

实测验证

许可