Vmarcelo49/dsh-local-models

dsh-local-models

一个 dsh 插件，为 dsh Web GUI 添加一个 Local Models 标签页：选择一个 .gguf 文件，调整上下文和投机解码参数，查看实时显存估算，并通过 llama-server 加载它——然后一键将正在运行的服务器注册为 dsh 中的 LLM 提供商。

基于原版上游 llama.cpp（llama-server）构建。无需分叉、无需补丁、无需构建步骤：客户端 bundle 是手写的 React.createElement（没有 JSX 工具链），node 部分无依赖。

功能

- 模型选择器 — 应用内文件浏览器（仅目录 + .gguf），在 POST /local-models/gguf-meta 背后进行仅解析头部的 GGUF 解析（架构、量化、层数、上下文长度、MoE 检测）
- 启动选项 — 上下文滑块（8K 步进，上限为模型训练时的上下文）+ 微调输入、固定 MTP 草稿深度（0–3）、思考级别（off/low/medium/xhigh）、可选的视觉 mmproj（GPU 或 CPU 卸载）、MoE 专家放置（--cpu-moe / --n-cpu-moe / top-k 覆盖）以及适配显存的辅助工具
- 实时显存估算 — 权重 + Q8_0/Q4_0 KV 缓存 + 循环状态 + 计算/图 + 开销，对照 16 GB，并显示可容纳 / 安全余量 / 可容纳的最大上下文行（Gemma 系列的准确性见 Known issues）
- 配置文件 — 保存命名的启动配置，一键重新加载
- 路由模式 — 从单个 OpenAI 兼容端点提供所有已保存的配置文件（--models-preset）；模型按需加载，默认一次只驻留一个。启动路由会自动在 dsh 中（重新）注册其模型——无需手动按 Register。
- 在 dsh 中注册 — 将就绪的服务器写为 llm-pi-ai 提供商路由（包含视觉模态 + 思考级别）
- 终端浮层 — 从标签页实时跟踪 llama-server 日志

要求

- 带有 web 配置文件的 dsh（该插件会组合进其中）
- 一个 llama-server 二进制文件（上游 llama.cpp，Vulkan/CUDA/CPU——取决于你的机器使用哪种）
- 显存估算常量针对 16 GB GPU；如果你的不同，它们位于 lib/client.js 顶部（TOTAL_VRAM_BYTES、SAFE_MARGIN_BYTES）

安装

cd ~/.dsh/profiles/web
dsh plugin --profile web add /path/to/dsh-local-models
then add "dsh-local-models" to the "bundles" array in package.json

重启 dsh web 进程（bundle 组合仅在启动时生效），刷新浏览器，打开 Settings → Local Models。

node 部分的更改（路由、注入列表）需要重启 dsh；客户端部分的更改只需刷新页面。

用法

1. Choose GGUF… — 选择一个模型文件（Home / Models 快捷方式，Up 导航）。
2. 调整 context、Max MTP head（固定草稿；上限为 3——更深的在大上下文下会崩溃）、thinking level、可选的 mmproj 和 MoE 设置。
3. Load model，查看状态卡片，通过 Open terminal 检查输出。
4. Register in dsh — 该路由（默认 local-）会出现在 Models 选择器中。
5. 或者，为多模型端点保存 profiles 和 Start router (from profiles)。

配置

| 变量 | 默认值 | 含义 |
|---|---|---|
| LOCAL_MODELS_PORT | 8080 | llama-server 端口 |
| LOCAL_MODELS_BIN | ~/Projetos/llama.cpp/build/bin/llama-server | 服务器二进制文件 |
| LOCAL_MODELS_SHORTCUTS | /mnt/raid0/GGUF | 以冒号分隔的文件浏览器快捷目录（name=path 用于自定义标签） |
| LOCAL_MODELS_MMPROJ_CPU | 1 | 视觉投影器权重保留在 RAM 中（0 = 卸载到 GPU） |
| LOCAL_MODELS_ROUTER_MAX | 1 | 同时驻留的路由模型最大数量 |
| LOCAL_MODELS_MAX_IMAGE_BYTES | 10485760 | 视觉图像保护限制 |
| LOCAL_MODELS_IMAGE_PIXEL_BUDGET | 4194304 | 视觉像素预算 |
| DSH_HOME | ~/.dsh | 数据目录（local-models/profiles.json、llama-server.log） |

启动标志固定为经过验证的日常配置：完全卸载、-b 2048 -ub 512 -t 4 -np 1、--flash-attn on --kv-unified、--cache-type-k q8_0 --cache-type-v q4_0、MTP --spec-type draft-mtp --spec-draft-n-max N --spec-draft-p-min 0.75（在超过 131072 上下文时会被丢弃，除非配置文件设置了 ignoreCtxCap —— 即该标签页的“ignore the MTP ctx softcap”复选框，它会在任意上下文下强制启用 draft，并可能导致 OOM 或解码崩溃）。

HTTP API（挂载在 /local-models 下）

| 路由 | 含义 |
|---|---|
| GET /local-models/browse?dir= | 目录 + .gguf 文件 |
| POST /local-models/gguf-meta | {path} → 解析后的 GGUF 头部（已缓存） |
| GET /local-models/status | 状态 + 实时 /health 探测 |
| GET /local-models/logs?offset=&max= | llama-server.log 的增量尾部 |
| POST /local-models/run | 启动服务器 |
| POST /local-models/stop | 停止子进程（或回收端口） |
| POST /local-models/profiles / GET | 保存（upsert）/ 列出配置文件 |
| POST /local-models/profiles/remove | 删除配置文件 |
| POST /local-models/router/start | 从配置文件构建预设 + 启动路由器 |
| POST /local-models/router/unload | 卸载一个路由模型 |
| POST /local-models/router/unload-all | 卸载所有路由模型 |
| POST /local-models/register | 将就绪的服务器添加为 llm-pi-ai 路由 |

项目结构

lib/index.js    node 部分：进程管理器、GGUF 解析器、路由、预设
lib/client.js   浏览器部分：设置标签页（单一免构建 bundle）
skills/         操作员技能：spawn-parity 检查清单、配置文件审计
docs/           UI 模型图

纯函数、可导出的辅助函数（normalizeEffort、moeArgsFor、generateRouterPresets、buildProviderProfile、profiles store）无需运行服务器即可进行单元测试；node lib/index.js /path/to/model.gguf 会转储解析后的头部作为自测。

已知问题

参见 KNOWN_ISSUES.md —— 最值得注意的是，对于 Gemma 系列布局，VRAM 估算值是近似值。

许可证

MIT —— 参见 LICENSE。