Rapid-MLX 原生服务商 GiuliaRoberts61/rapid-mlx-dsh-provider

@raullenchai/dsh-provider

为 DeepSeek Harness 打造的 Rapid-MLX 原生服务商——这样 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 流 API，但没声明依赖），以及一个正在运行的 Rapid-MLX 服务器。

From npm:bash
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）

除了 provider 路由，插件还注册了五个工具和一条 /rapid-mlx 命令，让智能体不用离开会话就能查看和管理模型。这样拆分，是看每个事实到底归哪个界面管：已服务模型的事实来自结构化的 HTTP /v1/models；下载缓存和 pull/remove 只有命令行能做，所以只有这两类操作会通过 harness 的子进程接缝去调 rapid-mlx。

| 工具 | 来源 | 作用 |
| rapid_mlx_serving | HTTP /v1/models | 当前正在服务的模型，去重后列出，附带上下文窗口、reasoning/tool 解析器、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() 传递 —— 但它们现在会拒绝，抛出 LlmError(..., 'UNSUPPORTED')，而不是被悄悄丢弃，这符合 cookbook 的要求。文本、推理和工具调用都会传递。
- 路由注册为 rapid-mlx。如果你的 settings.yaml 在 llm-pi-ai 下也声明了一个 rapid-mlx 服务商，两者会争抢同一个路由名（registerAdapter 保证服务商独占）。二选一，或者给我们这个改个名。

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

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

| 义务 | 如何满足 |
| usage 在 finish 之前，finish 之后不再有任何内容 | usage 先缓冲，到流末尾再刷出，因此一个只带 usage 的尾随分块无法打乱顺序 |
| 工具调用的 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 会把本地路径链接到 profile 树之外，所以 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 就不需要这些：包会落在 profile 树里面，扁平回退机制能正常解析裸包名。

测试智能体行为时，用强一点的 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 保持一致。