llama.cpp 启动台 yu234567/dsh-llamacpp-studio

dsh-llamacpp-studio

给 DeepSeek Harness 加一个本地 llama.cpp 图形启动台：选模型、调参数、点启动，不用再背一长串 llama-server 命令行。

它解决什么问题

本地跑 llama.cpp 通常是这样：打开终端，翻笔记找参数，拼出 llama-server -m ... -c ... -ngl ... --jinja ...，等模型加载，确认端口，然后去另一个界面填 OpenAI 兼容地址。想换模型或换量化，再从头来一遍。

这个插件把这件事搬进 Harness：

- 在侧边栏点 llama.cpp 启动台，进入一个常驻的图形页面；
- 自动发现 llama-server、模型目录和 .gguf 文件；
- 把 llama.cpp 当前版本 234 个启动参数按功能分组做成表单，留空即不传；
- 启动、停止、保存配置、保存多个命名档案；
- 实时查看 stdout / stderr / 插件系统消息；
- 启动后一键打开 llama-server 自带的 Web UI；
- 所有配置只写在本机，不需要改 profile 的 YAML。

它不替代 Harness 的模型供应商配置。这个插件的职责是把本地 llama-server 跑起来并让你看得见它；要不要把这个服务接成 Harness 的模型 provider，由你已有的 provider 插件或后续扩展决定。

界面

┌──────────────────────────────────────────────────────────────┐
│ llama.cpp Studio [运行中] [停止] │ │ 本地同源访问 │ ├──────────────────────────────────────────────────────────────┤ │ 快速启动 │ 全部参数 (234) │ 模型 │ 运行日志 │ 配置档案 │ ├──────────────────────────────────────────────────────────────┤ │ llama-server 路径 [C:\...\llama-server.exe] [自动检测] │ │ 启动模式 [单模型 v] 模型目录 [E:\models] [选择模型] │ │ 模型 [E:\models\Qwen3-32B-Q4.gguf v] │ │ Host [127.0.0.1] Port [8080] 就绪超时 [180] │ │ 核心参数：ctx-size / gpu-layers / threads / flash-attn ... │ │ 启动命令预览 │ │ $ llama-server -m ... -c 8192 -ngl all --jinja │ ├──────────────────────────────────────────────────────────────┤ │ 运行日志 [自动跟随] [清空] │
│ [system] 进程已启动，pid 23120；等待 HTTP 就绪… │
│ [stdout] llama_model_loader: loaded meta data ... │
│ [system] 就绪：http://127.0.0.1:8080/ │
└──────────────────────────────────────────────────────────────┘

侧边栏入口与「插件」「计划任务」并列；主面板注册为 llamacpp-studio，不占用会话面板。

功能

1. 完整参数表单

catalog.js 是 Host 和浏览器共用的唯一参数表。当前覆盖 llama.cpp build 10236 的 llama-server --help，共 234 项，分为：

| 分组 | 内容 |
| 模型与上下文 | -c、-n、-b、-ub、--parallel、-a、LoRA、Control vector、HF / URL / Docker 下载、Embedding、Rerank |
| CPU / 上下文缓存 | 线程、批线程、CPU 亲和、优先级、轮询、Flash Attention、RoPE / YaRN、cache type、prompt cache、KV 复用、上下文检查点 |
| GPU / 显存 | -ngl、split mode、tensor split、main GPU、--fit、device、override tensor、MoE CPU offload、KV offload、load mode |
| 采样 | temperature、top-k/p/min-p、XTC、DRY、Mirostat、动态温度、grammar、JSON Schema、logit bias |
| 投机解码 | draft model、spec type、ngram 系列、draft cache、draft 设备与 GPU 层数 |
| HTTP 服务 | CORS、API prefix、Web UI 配置、MCP、Agent 工具、API key 文件、SSL、metrics、slots、router |
| 对话模板与推理 | --jinja、chat template、模板参数、reasoning 格式 / 预算 / 保留策略、prefill、warmup |
| 多模态 / 视觉 | --mmproj、mmproj URL、图像 token 限制、mmproj GPU offload |
| 日志 | 日志文件、颜色、verbosity、时间戳、prompt 日志 |
| 官方预设 | FIM、gpt-oss、Gemma 3 vision、EmbeddingGemma、spec-default |
| 已弃用 | --mlock、--mmap、--direct-io、--defrag-thold，保留用于旧命令兼容 |

完整表格见 docs/PARAMETERS.md。

「全部参数」页采用左侧分类导航 + 右侧参数区的布局，不再把 234 项一次性堆成长列表；搜索时自动跨分类展示结果。

几个设计细节：

- 常用值下拉：上下文长度旁边有 4K / 8K / 16K / 32K / 64K / 128K 预设下拉，GPU 层数、线程、batch、temperature、top-p、cache、reasoning budget 等也有常用值下拉，选中即填入，仍然可以手动输入。
- 布尔参数是三态：不设置 / 开启 / 关闭。关闭 只在存在 --no- 形式时可用，不会造出无效参数。
- 可选值参数（--flash-attn [on|off|auto]、--fit、--reasoning、--log-colors）用下拉框，默认不传。
- 路径和自由文本可以直接输入；模型、mmproj 可从扫描结果里选。
- 默认不显示用户目录：可执行文件优先写 PATH 中的 llama-server，而不是 C:\Users\<name>\... 的绝对路径；旧配置会自动迁移。
- 恢复默认：启动器卡片右上角可一键恢复 host / port / 上下文 / 参数 / 模型选择等，配置档案不会被删除。
- 额外原始参数是逃生口：按 shell 引号规则解析，追加在表单参数之后。
- 新版 llama.cpp 新增的参数如果还没进表，可以先用原始参数，或提 PR 更新 catalog.js。

2. 模型发现

- 自动探测 PATH、~/llama.cpp/build/bin、WinGet 的 ggml.llamacpp_ 包、常见盘符目录；
- 支持手动填写可执行文件和模型目录；
- 递归扫描 .gguf（最多 4 层、4000 个文件），区分模型与 mmproj；
- 模型列表带文件大小，可直接设为模型或 mmproj；
- 目录不会在每次轮询时重扫，扫描结果缓存 60 秒，点「扫描模型」强制刷新。

3. 进程生命周期

- start：校验可执行文件、模型 / Router 目录、mmproj、端口占用，再以参数数组 spawn，不经过 shell；
- 就绪探测：轮询 /health，失败时回退 /v1/models；带 --api-key 时会带 Bearer 头；
- 启动超时、进程提前退出、端口占用都会作为错误显示在页面，同时写进日志；
- stop：先发 SIGTERM，宽限期后升级 SIGKILL，Windows 下再兜底 taskkill /T /F；
- 插件卸载或 DSH 退出时会停止由它启动的进程，避免孤儿进程。

4. 配置档案

- 「保存配置」写当前表单；
- 「保存为档案」保存整个配置快照，支持多个模型 / 量化 / Router 方案；
- 载入、删除档案；
- 导出 / 导入当前配置 JSON；
- 配置文件路径：$DSH_HOME/llamacpp-studio/config.json（Windows 默认 C:\Users\<you>\.dsh\llamacpp-studio\config.json）。

5. 日志

- 环形缓冲保留最近 3000 行；
- 分为 stdout、stderr、system 三类，带序号与时间；
- 支持过滤、自动跟随、复制、下载 .log；
- 启动命令在日志里会把 API Key 和 HF Token 打码。

安装

从本地目录安装（当前仓库）

这个插件没有运行时依赖、没有构建步骤，直接安装仓库目录即可。

在 Harness 的 设置 → 插件 → 添加插件 里选择「本地目录」，填入：

E:\DS\dsh-llamacpp-studio

或者使用 plugin_manager 工具 / CLI（如果 dsh 在 PATH 上）：

dsh plugin --profile desktop add E:\DS\dsh-llamacpp-studio

安装后：

1. 如果 Host 没有热加载，重启 DSH；
2. 浏览器硬刷新（Ctrl+Shift+R）；
3. 侧边栏出现 llama.cpp 启动台。

从 npm pack 安装

cd dsh-llamacpp-studio
npm pack
dsh plugin --profile desktop add ./dsh-llamacpp-studio-0.2.4.tgz

卸载

dsh plugin --profile desktop remove dsh-llamacpp-studio

或在插件管理页面关闭 / 卸载。

使用

1. 打开侧边栏 llama.cpp 启动台。
2. 点 自动检测，确认 llama-server 路径和模型目录；也可以手动填。
3. 在 模型 页扫描目录，选一个 .gguf；视觉模型再选对应的 mmproj。
4. 在 快速启动 调整 host / port / ctx / GPU 层数等常用项；需要时到 全部参数 调整。
5. 点 启动服务器，等状态变成 运行中。
6. 点 打开 Web UI 访问 http://127.0.0.1:8080/；或者把该地址填到 Harness 的 OpenAI 兼容 provider 中。
7. 在 运行日志 看加载过程；点 停止服务器 结束进程。

常用场景

单模型 + 视觉

- 启动模式：单模型
- 模型：...\Qwen2.5-VL-7B-Q4.gguf
- mmproj：...\mmproj-Qwen2.5-VL-7B-f16.gguf
- 核心参数：ctx-size=8192、gpu-layers=all、flash-attn=on

Router 模式（多模型，不重启进程）

- 启动模式：Router（模型目录）
- 模型目录：E:\models
- 按需在全部参数里设置 --models-max、--models-autoload、--no-models-autoload
- 注意：Router 模式不传 -m 和 --mmproj，与 llama.cpp 的 router 语义一致。

多 GPU

- gpu-layers=all
- split-mode=layer（或 row）
- tensor-split=3,1
- main-gpu=0

低显存

- gpu-layers 设为具体层数
- 开启 --fit
- cache-type-k=q8_0、cache-type-v=q8_0
- 需要时把 MoE 权重留在 CPU：--n-cpu-moe 或 --cpu-moe

安全边界

这个插件会启动本机可执行文件，因此刻意把攻击面收窄：

- 只允许回环 socket；浏览器半会附带 x-llamacpp-studio: 1 同源标记，跨站来源的请求会被拒绝。远程浏览器、局域网访问、外部页面都拿不到 API。
- 启动使用 spawn(executable, argv) 参数数组，不经过 shell；用户输入不能拼接成 shell 命令。
- 请求体限制 1 MiB，只接受 JSON。
- 配置与日志只在本机文件系统；没有遥测、没有外发请求。
- API Key、HF Token 会写入本机配置文件。共享机器上请自行注意文件权限。
- 插件启动的进程归插件管理；卸载 / 退出 DSH 会停止它。

如果你通过局域网地址访问 Harness，启动台 API 会拒绝请求，这是预期行为。需要远程使用时，建议在 DSH 前面做认证反向代理，并单独评估风险。

开发

git clone https://github.com/yu234567/dsh-llamacpp-studio.git
cd dsh-llamacpp-studio
npm install # 只有 React 测试相关的 devDependencies
npm run check # JS 语法 + 参数表完整性 + manifest 检查
npm run docs:parameters # 重新生成 docs/PARAMETERS.md
npm run smoke:host # 无头 Host smoke test（不启动真实 llama-server）
npm run smoke:client # 无头 React 渲染，遍历全部标签页
npm pack # 生成可安装 tgz

目录

.
├─ index.js Host 半：进程管理、配置持久化、模型扫描、同源 HTTP API ├─ client.js Client 半：主面板 + 侧边栏图标（plain CJS factory） ├─ catalog.js llama-server 参数表 / argv 构造 / 原始参数解析 ├─ cordis.patch.yml Bundle patch：插入 Host 行 ├─ locale/{zh,en}.json 插件管理页显示标题与描述 ├─ icon.svg 插件图标 ├─ docs/PARAMETERS.md 自动生成的全部参数表 ├─ scripts/check.mjs 静态检查 ├─ scripts/generate-parameters-doc.mjs ├─ scripts/smoke-host.mjs 无头 API smoke test └─ .github/workflows/ci.yml

架构

Browser (client.js)
├─ sidebar.panellist → 图标入口（id: llamacpp-studio） └─ main key → StudioPage │ fetch /api/llamacpp-studio/* ▼
Host (index.js)
├─ webServer.register 三条 exact route：bootstrap / state / action ├─ config.json 当前配置 + 档案 ├─ scanModels() .gguf / mmproj 扫描 ├─ discovery llama-server / 模型目录 / version └─ child_process llama-server 进程 + 日志环形缓冲

- 参数表只有一份：Host 通过 buildArgs() 生成 argv，浏览器通过同一份 fields 生成命令预览。
- 浏览器每 1.5 秒拉一次 /state?afterLog=<seq>，只取增量日志；没有 SSE，逻辑更简单。
- 配置写入采用 tmp + rename 原子替换。
- 面板样式只使用 Harness 的 --dsw-alias-* 主题 token，跟随明暗主题。

更新参数表

1. 运行 llama-server --help，对照新增 / 删除的开关；
2. 在 catalog.js 加 f(...) 条目（kind 决定控件和 argv 形状）；
3. npm run check && npm run docs:parameters；
4. 重新安装 / 刷新页面验证。

GitHub 仓库

<https://github.com/yu234567/dsh-llamacpp-studio>

git clone https://github.com/yu234567/dsh-llamacpp-studio.git

仓库 Topics：deepseek-harness、dsh-plugin、llama-cpp、local-llm。
- 发布 Release 时附上 npm pack 生成的 .tgz。

已知限制

- 参数表对应 llama.cpp build 10236；上游新增参数需要更新 catalog.js。
- 目前是启动器，不自动注册为 Harness 的模型 provider；需要配合现有 provider 配置使用。
- 文件选择依赖路径输入 + 模型目录扫描，没有调用系统原生文件选择器（DSH 的 directory picker 只返回目录）。
- Windows 停止进程先发 SIGTERM，进程不退出时再 taskkill；llama-server 没有专门的 HTTP shutdown endpoint。
- Host API 只接受 loopback 同源请求，远程浏览器无法使用启动台。
- 没有自动更新，升级靠重新安装 / npm pack。
- 视觉模型需要手动选择匹配的 mmproj；当前不做文件名相似度猜测。

路线图

- [ ] 按模型自动记忆参数（每个 .gguf 一组覆盖项）
- [ ] mmproj 智能配对与预览
- [ ] 把启动实例注册为 Harness provider（可选）
- [ ] 多实例管理（不同端口 / 模型同时运行）
- [ ] 参数表从 llama-server --help 自动 diff
- [ ] 一键下载 HF 模型并跟踪进度
- [ ] OpenAI 兼容连通性测试与首 token 延迟

许可证

MIT © 2026 dsh-llamacpp-studio contributors

llama.cpp 本身由 ggml-org 维护，采用 MIT 许可证；本仓库不包含 llama.cpp 二进制或模型权重。