Rapid-MLX 服务商 Korkmaz1974/rapid-mlx-dsh-provider

@raullenchai/dsh-provider

一个原生 Rapid-MLX 服务商，用于 DeepSeek Harness —— 这样 dsh 就能从服务器获取模型信息，而不是依赖你在 settings.yaml 里手写的内容。

状态：已发布到 npm，包名为 @raullenchai/dsh-provider。
Verified 中的端到端 dsh 运行是在 M3 Ultra 上针对
dsh 0.1.0-rc.7 完成的；dsh 0.1.0-rc.8 在 API 上兼容 —— LlmAdapter
契约逐字节一致，改动只有新增 —— 适配器已在协议和单元测试层面针对 rc.8 重新验证。DSH 仍是快速迭代的开发者预览版，所以请把它看作在跟踪一个移动目标，而不是一份冻结的兼容性承诺。

它能为你做什么

DSH 已经可以通过通用的 openai-completions 服务商连接本地 Rapid-MLX 服务器。这条路能用 —— 但它对你的模型一无所知，只知道你手写的内容：

what the generic route makes you maintain, by hand, per model
llm-pi-ai:
providers:
rapid-mlx:
baseURL: http://localhost:8000/v1
defaultContextWindow: 262144 # you looked this up. is it still right?
models:
- id: qwen3.6-35b-8bit
contextWindow: 262144
reasoningEfforts: {off: none, low: low, medium: medium, high: high}

Rapid-MLX 的 /v1/models 已经发布了所有这些信息，甚至更多。这个适配器会读取它，所以：

1. 无需手写，切换模型时也无需重写。 换掉 rapid-mlx serve 正在运行的内容，dsh 就会跟着变。不用重新跑设置，不会有过期数字。

2. 推理控制说实话。 Rapid-MLX 会报告模型是否真的有推理解析器。不能推理的模型不再显示一个毫无作用的 off/low/medium/high 选择器。

3. 压缩按这台 Mac 实际能容纳的容量计时，而不是一个漂移的数字。 这一条会悄悄让你付出代价。
dsh-compaction-basic 向服务商询问路由的容量，并在 thresholdRatio × capacity（默认 0.8）处压缩。服务商优先采用服务器的 max_model_len —— Rapid-MLX 按内存拟合的上限（统一内存里能装下的：权重 + KV 缓存），位于 vLLM/SGLang 标准字段 —— 而不是原生 context_window；在不报告该字段的旧服务器上回退到 context_window。所以压缩按机器实际能容纳的容量计时，而不是模型宣称的窗口（可能没空间放），也不是从另一个模型抄来的手写数字。

安装

需要 Node ≥ 22.15（dsh 导入了 Node 的 Zstd 流 API 却没声明依赖）以及一个运行中的 Rapid-MLX 服务器。

From npm:
dsh plugin --profile web add @raullenchai/dsh-provider

…或直接从源码安装——这个包是纯 JS，没有构建步骤：
dsh plugin --profile web add github:raullenchai/rapid-mlx-dsh-provider

export RAPID_MLX_BASE_URL=http://localhost:8000/v1 # 可选；这是默认值
dsh web

然后把智能体指向这条路由：

$DSH_HOME/settings.yaml
agent-default-model:
provider: rapid-mlx
model: qwen3.6-35b-8bit

已验证：该命令能安装，并作为配置档层激活，对应 dsh 0.1.0-rc.7。想改本地代码，见本地开发。

模型管理（v0.2.0）

除了服务商路由，插件还注册了五个工具和一个 /rapid-mlx 命令，智能体不用离开会话就能查看和管理模型。分工依据是每个事实由哪个接口真正掌握：服务中的模型信息来自结构化 HTTP /v1/models；下载缓存和 pull/remove 只有命令行能做，所以只有它们通过 harness 子进程接缝调用 rapid-mlx。

| 工具 | 来源 | 作用 |
| rapid_mlx_serving | HTTP /v1/models | 当前正在服务的模型，去重后列出，附上下文窗口、推理/工具解析器、MoE/混合架构和模态。 |
| rapid_mlx_cached | rapid-mlx models --cached | 已下载的模型及其磁盘占用。 |
| rapid_mlx_pull | rapid-mlx pull <name> | 下载模型（别名或 HF 仓库 id）。可取消；没有固定超时。 |
| rapid_mlx_remove | rapid-mlx rm -y <name> | 删除缓存模型，释放磁盘。 |
| rapid_mlx_health | HTTP + rapid-mlx --version | API 是否在线？命令行是否可达？作为两个独立事实分别报告。 |

/rapid-mlx 打印一次性概览：健康状态、正在服务的模型及其信息、缓存总磁盘占用。

命令行从 cliCommand 配置解析（默认取 PATH 上的 rapid-mlx，或 $RAPID_MLX_CLI）；如果二进制不在 harness 的 PATH 上，就设成绝对路径。rapid_mlx_pull/rapid_mlx_remove 是仅有的会改动磁盘的工具，它们以非交互方式运行（rm 强制加 -y，因为子进程接缝会忽略 stdin）。

已验证

在 M3 Ultra 上对应 dsh 0.1.0-rc.7 验证：

- 能安装，并作为配置档层激活（没有「declares no dsh.bundle」警告；条目会出现在 dsh --profile headless --dump-config 里）。
- 用 ctx.llm 注册 rapid-mlx 路由，能处理真实查询。
- 普通聊天、单次工具调用，以及作为 Rapid-MLX 发布门槛的多步 bug 修复任务——最后一项修好了 bug，目标仓库自带的测试也通过了，独立验证，在 qwen3.6-35b-8bit 上耗时 36 秒。

尚未完成

说清楚，因为适配器的意义就是用服务器给出的信息，而其中一些目前还只是读取：

- recommended_sampling —— 应当按模型自动应用。
- tool_call_parser —— 应当让 dsh 对无法发出 tool_calls 的模型快速失败，而不是空转。
- is_hybrid / is_moe / capabilities — 已读取，尚未据此采取动作。
- 感知内存的容量。 目前 resolveModel() 报告的是模型对外宣称的上下文窗口。在 Mac 上，真正的上限是统一内存，改为报告这个数字是剩下最大的一笔收益 —— 前提是 Rapid-MLX 先暴露一个可用的容量数值。
- 图片不会经由 stream() 传递 —— 但现在会按 cookbook 的要求，以 LlmError(..., 'UNSUPPORTED') 拒绝，而不是悄悄丢弃。文本、推理和工具调用都会传递。
- 路由注册为 rapid-mlx。如果你的 settings.yaml 在 llm-pi-ai 下也声明了 rapid-mlx 服务商，两者会争抢同一个路由名（registerAdapter 保证服务商独占）。二选一，或者给我们这个改个名。

与官方适配器契约的一致性

依据 docs/cookbook/adding-an-llm-adapter.md 及其「协议义务」一节构建。每一项都有对应测试：

| 义务 | 如何满足 |
| usage 在 finish 之前，finish 之后不再有任何内容 | usage 先缓冲，流结束时统一刷出，因此末尾只含 usage 的 chunk 无法打乱顺序 |
| 工具调用的 arguments 全程是原始 JSON 字符串 | 片段以 argumentsDelta 流式传输，重组时不解析 |
| 块索引按首次出现顺序，每个块复用同一索引 | 在「先推理后文本」的响应上验证过 |
| 错误只走两条被认可的通路 | 传输/协议失败抛出带稳定错误码的 LlmError；不会有任何情况让流悄悄结束 |
| 遵守 options.signal | 传给 fetch 和 SSE 读取器；AbortError 原样重抛，不重新归类 |
| 服务商无法满足的字段抛 UNSUPPORTED | 图片内容直接拒绝，而不是被悄悄裁掉 |
| 配置是带环境变量回退的 schemastery schema | export const Config，由 cordis.patch.yml 经 !!js process.env.RAPID_MLX_BASE_URL 注入 |

不发出 finish.replayState：Rapid-MLX 在后续调用中不需要原生响应 id 或签名，因此没有可无损投影的内容。

动手改之前值得知道的三件事

每一条都实实在在花过调试时间：

1. package.json 里的 dsh.bundle 才是让它成为插件的关键。 没有它，这个包只会作为惰性依赖安装，dsh 仅警告。它也是让包被追加进配置档 dsh.profile.bundles 的依据。一旦缺失，CI 会失败。
2. LlmReasoningEffortInfo.name 是必填项。 只返回 {id} 会让整个模型以 INVALID_MODEL_REASONING 失败 —— 这个错误报的是模型名，而不是缺失的字段。
3. DSH 没有 tool 角色。 Message.role 只有 system|user|assistant；工具结果是一条 user 角色消息，其 source.kind === 'tool' 携带 callId，内容里放一个 ToolResultBlock。把这些拍平成普通用户文本，模型就会永远重复发起同一个调用 ——症状是回答为空，退出码非零，stderr 上什么都没有。

本地开发

pnpm 会把本地路径链接到配置档目录树之外，于是 Node 向上查找父目录时永远到不了 $DSH_HOME/profiles/node_modules，peer 依赖解析失败。把它们软链进来——仅限开发，node_modules 已加入 gitignore，也不在发布的 files 里：

mkdir -p node_modules/@deepseek-ai
ln -sfn <dsh-install>/node_modules/@deepseek-ai/dsh-llm node_modules/@deepseek-ai/dsh-llm
ln -sfn <dsh-install>/node_modules/@deepseek-ai/cordis node_modules/@deepseek-ai/cordis

export DSH_HOME=/tmp/dsh-dev # never your real ~/.dsh
dsh plugin --profile headless add "$PWD"
export RAPID_MLX_BASE_URL=http://127.0.0.1:8000/v1
dsh --profile headless "say hello"

真正跑 npm install 就不需要这些：包会落在配置档目录树内部，扁平回退在那里能正常解析裸包名。

测试智能体行为时，用 8-bit 的强模型。这里有个多步任务在 qwen3.5-9b-4bit 上失败，在 qwen3.6-35b-8bit 上通过——4-bit 会把「模型弱」和「集成坏了」混在一起。

引擎侧守护这些字段

本包住在自己的仓库里，意味着 Rapid-MLX 里改个名字就会悄悄弄坏它——那边没有任何代码导入本包，本包的 CI 也不在那边跑。所以这些字段钉在拥有它们的一侧，由 Rapid-MLX 里的 tests/test_model_card_client_contract.py 负责，该文件写明本包就是它存在的理由。它钉住的是线上形状：字段名、可空性，以及 ModelInfo 不设 exclude_none 这一事实——正因如此，"reasoning_parser": null 才能和完全省略该键的旧服务器区分开。

如果你在这里开始读 /v1/models 的新字段，那边也要加上。 否则守护会悄悄不再覆盖本包实际用到的东西。

License

Apache-2.0，与 Rapid-MLX 一致。