ds4.c 学习笔记

Appearance

分布式推理——将超大模型（如 DeepSeek V4 PRO，1.6T 参数）的层切片分配到多台机器上协同执行，突破单机内存限制。

为什么需要分布式推理 ​

DeepSeek V4 PRO 的 Q4_K 量化模型需要 ~838GB 存储，远超任何单机内存。即使 IQ2_XXS 版本也需 ~430GB，只有 512GB Mac Studio 才能单机运行。分布式推理将模型按层切分，每台机器只加载一部分，通过高速网络传递中间激活。

Coordinator/Worker 架构 ​

角色职责命令
Coordinator接收请求、执行前半层、转发激活、采样 token./ds4 --role coordinator -m pro-q4-layers00-30.gguf
Worker注册层范围、执行后半层、返回 logits./ds4 --role worker -m pro-q4-layers31-output.gguf

Worker 启动时发送 HELLO 消息（含 layer_start、layer_end、model_id、quant_bits），Coordinator 据此构建路由表。

传输协议 ​

自定义 TCP 二进制协议，magic 0x44533444（"DS4D"）：

帧头 → 消息类型（HELLO / WORK / RESULT / SNAPSHOT）→ 载荷
每条消息附带遥测：eval_time、downstream_wait、forward_send、byte_count

激活传输支持可配置的 activation_bits（默认 32 = float32），低精度传输减少网络带宽消耗。

KV 快照的拓扑无关设计 ​

保存时聚合所有 worker 持有的层张量为统一格式，加载时按当前实际路由分发。这意味着：

  • 2-worker 保存的快照可以在 3-worker 配置下加载
  • 保存文件格式与单机完全兼容

KV 快照请求 ID 隔离 ​

分布式协议使用递增的 request_id 匹配请求-响应。KV 快照操作在独立的数据连接上执行，可能和流水线化的 WORK 请求并发。之前快照复用了 WORK 的 request_id 序列，导致响应匹配混乱。

修复：快照使用独立的 snapshot_request_id 计数器，从 UINT64_C(1) << 63（高半 ID 空间）开始：

c
// ds4_distributed.c
uint64_t snapshot_request_id; // 从高半 ID 空间开始，避免和 WORK 冲突
// 快照操作: d->snapshot_request_id++
// WORK 操作: d->request_id++

同时移除了控制 socket 的默认 SO_RCVTIMEO——Worker 控制连接在 KV 快照传输期间可能长时间空闲，不应因超时断开。DS4_DIST_SOCKET_RECV_TIMEOUT_SEC 环境变量可在需要时显式设置超时。

模型分片加载 ​

分布式引擎使用 model span API 只加载分配的层范围：

c
// 指定需要映射的字节范围（offset/size 对）
ds4_gpu_set_model_map_spans(
    model_map, model_size,
    offsets, sizes, span_count,
    max_tensor_bytes
);

Worker 不需要加载 token embedding 和 output head（除非它是路由的最后一跳），大幅减少每台机器的内存占用。

相关概念 ​

  • moe — PRO 模型有 384 个路由专家，Q4_K 量化
  • kv-cache — 分布式 KV 快照的拓扑无关设计
  • quantization — Q4_K 是 PRO 路由专家的量化格式
  • mmap — 模型分片通过 mmap + span API 按需加载
  • ssd-streaming — 另一种突破单机内存限制的方式（SSD 缓存专家）

详见 Part 6 — 分布式推理。

出链