Rapid-MLX 模型源 raullenchai/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 自动跟上。不用重跑 setup，也没有过期的数字。

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

3. 压缩按这台 Mac 真正装得下的容量来计时，而不是一个漂移过的数字。 这一条会悄悄让你吃亏。dsh-compaction-basic 向服务商询问路由的容量，再按 thresholdRatio × capacity（默认 0.8）触发压缩。服务商优先用服务器的 max_model_len —— Rapid-MLX 按内存拟合出的上限（统一内存里装得下的：权重 + KV cache），字段沿用 vLLM/SGLang 标准 —— 而不是原生的 context_window；如果服务器较旧、没报告这个字段，就回退到 context_window。
这样压缩就按机器真正能容纳的量来计时，而不是模型标称的窗口（可能根本装不下），也不是从别的模型抄来的手写数字。

安装

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

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

…or straight from source — the package ships plain JS with no build step:

dsh plugin --profile web add github:raullenchai/rapid-mlx-dsh-provider

export RAPID_MLX_BASE_URL=http://localhost:8000/v1 # optional; this is the default
dsh web

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

$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 reader；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 里：
sh
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 里改个名字就会悄悄弄坏它——那边没有任何东西 import 它，这边的 CI 也不会在那边跑。所以这些字段由拥有它们的一侧钉住，靠的是 Rapid-MLX 里的 tests/test_model_card_client_contract.py，文件里写明这个包就是它存在的理由。它钉住的是传输形状：字段名、可空性，以及 ModelInfo 不设 exclude_none 这一点——正因如此，"reasoning_parser": null 才能和更老的、完全省略这个键的服务器区分开。

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

License

Apache-2.0，与 Rapid-MLX 保持一致。