Run frontier MoE models on hardware you already own — pure C, zero deps, experts streamed from disk. Tiny engine, immense model. 🐦
C
docs: add Chinese DeepSeek V4 guide
DrewZ0c17d0258975
diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 90b1cfd4..aaf12340 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -217,6 +217,23 @@ COLI_MODEL=/nvme/glm52_i4 ./coli doctor # 只读就绪检查| 语法强制草稿(结构化输出) | [docs/grammar-draft.md](docs/grammar-draft.md) || 环境变量完整清单 | [docs/ENVIRONMENT.md](docs/ENVIRONMENT.md) |+## DeepSeek V4++实验性的 **DeepSeek V4 Flash + DSpark** CPU 路径使用原生 FP4 专家、+自动 RAM 规划和无损推测验证。目前支持 x86-64 Linux 与 Windows/MSYS2;+其他平台仍通过 `make check` 验证 colibri 主引擎。++```bash+cd c+make deepseek-v4+python ./v4 run --model /path/to/DeepSeek-V4-Flash-DSpark --ram 32 \+ --stop-sentence "What is the capital of France?"+```++状态、benchmark、checkpoint 验证和已提交的 tiny 独立 oracle 说明,+请参阅[中文版 DeepSeek V4 文档](docs/deepseek-v4.zh-CN.md);+英文原文见 [docs/deepseek-v4.md](docs/deepseek-v4.md)。+## 支持项目colibrì 最初由一人使用 12 核心、25 GB RAM 的笔记本开发;@@ -247,7 +264,7 @@ c/└── tests/ 零依赖的 C 与 Python 测试web/ 浏览器 UI(纯 OpenAI API client)desktop/ 封装网页 UI 的 Tauri v2 桌面 shell-docs/ 参考文档、实验与媒体文件+docs/ 参考文档、实验、媒体文件与 DeepSeek V4 说明```运行时路径刻意保持扁平、易读:`colibri.c` 加上若干头文件。diff --git a/docs/deepseek-v4.md b/docs/deepseek-v4.mdindex f7177d24..0476e91a 100644--- a/docs/deepseek-v4.md+++ b/docs/deepseek-v4.md@@ -1,5 +1,7 @@# DeepSeek V4 (colibri CPU)+English · [简体中文](deepseek-v4.zh-CN.md)+Local CPU inference for DeepSeek V4 Flash + DSpark on colibri: weight loading,expert caching, sparse attention, speculative decode, and automatic RAMtiering—end-to-end generation that passes smoke tests.diff --git a/docs/deepseek-v4.zh-CN.md b/docs/deepseek-v4.zh-CN.mdnew file mode 100644index 00000000..f8961280--- /dev/null+++ b/docs/deepseek-v4.zh-CN.md@@ -0,0 +1,265 @@+# DeepSeek V4(colibri CPU)++[English](deepseek-v4.md) · 简体中文++colibri 上的 DeepSeek V4 Flash + DSpark 本地 CPU 推理:涵盖权重加载、+专家缓存、稀疏注意力、推测解码和自动 RAM 分层,端到端生成已通过冒烟测试。++## 已完成++- **目标模型引擎**:配置/层/注意力/块/专家存储/数学运算/运行时/+ prompt;FP8 稠密权重与原生 FP4 专家内核;在硬件支持时启用 AVX-512+ 批量验证和 rows16 热门专家布局。+- **DSpark 推测解码**:草稿运行器、heads、验证窗口、prefix/commit;+ 在冒烟测试 prompt 上接受率达到 100%。+- **自动 RAM 策略**:根据操作系统可用内存或 `--ram`,规划常驻张量、+ DSpark stages、专家缓存和输出 head。+- **SSD 专家流式加载**:每个专家使用两次合并读取(scales + weights);+ 无需重新排列成 160 GB 容器。+- **源码布局**:采用与 GLM 类似的聚合源文件 `deepseek_v4.c`/+ `deepseek_v4_dspark.c`;公共 API 位于 `deepseek_v4.h`+ (`ColiV4Engine`/`ColiV4Session`/配置/prompt);实现细节位于+ `deepseek_v4_internal.h`,不承诺接口稳定性。+ `make deepseek-v4` 会构建 `c/deepseek_v4.exe`。+- **CLI**:`c/v4` 是仅使用标准库的 Python 启动器,封装 `run`/`chat`;+ 推理本身由 engine + session 完成(`coli_v4_engine_open` →+ `coli_v4_session_create`/`generate` → 销毁所有 session,再销毁 engine)。+ `deepseek_v4.h` 中的 engine/session 接口是**实验性**公共 API,未来可能变化。+ Engine 会复制模型目录字符串;调用 `coli_v4_engine_destroy` 前必须销毁所有+ session。Index 与 ExpertStore 访问器仍是内部接口+ (`deepseek_v4_internal.h`)。++## 模型概况++典型 `DeepSeek-V4-Flash-DSpark` 结构(来自 checkpoint 元数据):++| 项目 | 数值 |+|------|-----:|+| Transformer 层数 | 43 |+| Hidden size | 4096 |+| 每层路由专家数 | 256(top-k 6) |+| 每条专家记录大小 | 约 12.75 MiB(FP4 E2M1 + UE8M0 scales) |+| 滑动窗口 | 128 |+| 稠密层常驻大小 | 约 6.27 GiB |+| 路由专家 payload | 约 137 GiB(流式加载,不会全部常驻) |++专家使用 packed FP4(I8 safetensors 中的 `float4_e2m1fn_x2`),并非 INT8。+稠密权重使用带 UE8M0 block scales 的 E4M3。参考路径以 FP8×FP4 计算激活,+并使用 FP32 累加。++## 自动 RAM 规划++预算分配顺序:系统保留 → 运行时工作集 → 最小专家 slots+(top-k × 稀疏层数)→ 可选的常驻 BF16 `lm_head`(约 1.06 GiB)→+用剩余预算增加每层专家缓存 slots。++- 未指定 `--ram` 时,规划器使用**操作系统可用内存**而非总内存,并保留+ 自适应系统余量。+- 指定 `--ram GiB` 时,该数值是**规划预算**,不是操作系统强制执行的硬上限;+ 它控制预计常驻权重、缓存和运行时工作区。+- 如果最小专家工作集无法容纳,启动会明确报告差额并失败,不会静默依赖+ swap 超额分配。+- 输出 head 是否常驻是可选的:低内存模式会流式读取 BF16 head;预算充足时+ 则常驻以提高速度。+- 热门专家可固定并原地重排为 16-row AVX-512 布局;冷门专家仍使用官方的+ row-major FP4。重排不会增加容量占用。++显式指定 32 GiB 规划预算时的常驻示例:++```text+dense ≈ 6.27 GiB+dspark ≈ 10.45 GiB+target expert cache ≈ 9.1 GiB(RAM 允许时增加 slots)+head = resident BF16+```++在**宿主机**有足够空闲内存容纳最小工作集时,规划器也能根据 8 GiB 预算+生成进程方案;由于专家缓存更紧,解码会更慢。这不等同于可以在实体 8 GiB+电脑上交付运行,详见下面的基准测试说明。++## 基准测试++以下数据使用的硬件:++| 项目 | 数值 |+|------|------|+| CPU | AMD Ryzen AI MAX+ 395(16 核/32 线程,Radeon 8060S) |+| 系统内存 | 128 GiB |+| 操作系统 | Windows 11 |+| 构建 | `make deepseek-v4`(MSYS2 UCRT64,`-march=x86-64-v3`) |++模型:`DeepSeek-V4-Flash-DSpark`++Prompt:`--stop-sentence "What is the capital of France?"`+(输出:*The capital of France is Paris.*)++这里的 `--ram` 是高内存机器上的**规划预算**,不是 RSS 硬上限,也不代表+实体 8 GiB/32 GiB 电脑。**8 GiB 一行只是规划设置**(`--ram 8`):+宿主机仍有充足的操作系统内存/页面缓存供 SSD 专家 I/O 使用。实体约 8 GiB+系统可能无法启动,或在系统保留、运行时临时空间和磁盘缓存争夺同一预算时+运行得慢得多;请勿把该行当作 8 GiB 硬件保证。++| `--ram` | TTFT | prefill | decode | DSpark 接受率 |+|---------|------|---------|--------|---------------|+| 32 GiB | 9.57s | 1.403 tok/s | 1.236 tok/s | 100% |+| 8 GiB(规划预算) | 10.02s | 1.338 tok/s | 0.712 tok/s | 100% |++```text+# --ram 32+[stats] RAM 31.98/32.00 GiB | TTFT 9.57s | prefill 1.403 tok/s | decode 1.236 tok/s | DSpark acceptance 100.0%++# --ram 8(约 127 GiB 宿主机上的规划预算,并非实体 8 GiB 机器)+[stats] RAM 7.55/8.00 GiB | TTFT 10.02s | prefill 1.338 tok/s | decode 0.712 tok/s | DSpark acceptance 100.0%+```++## 构建++V4 引擎及其聚合源文件单元测试支持以下平台:++- x86-64 Linux(gcc;硬件支持时使用 AVX-512 路径)+- Windows/MSYS2 UCRT64(同上)++macOS、PowerPC 和其他主机仍通过 `make check` 验证 colibri 主引擎,+但**不会**构建或链接 DeepSeek V4。在不支持的平台上,+`make deepseek-v4` 会给出明确错误并退出。++```bash+# MSYS2 UCRT64+export PATH=/ucrt64/bin:/usr/bin+cd /d/ai/colibri/c+make deepseek-v4+```++也可以在仓库根目录运行:`make deepseek-v4` → `c/deepseek_v4.exe`。++聚合源文件按照原先的顶层单元,使用 `-DCOLI_V4_UNIT_*` 分别编译,确保多层+`#include` 与宏封装保持正确。共享内核(`native_quant*`、+`safetensors_index`、`tensor_io`)仍是独立的编译单元。++## 已提交的 tiny 独立 oracle++x86-64 Linux 和 Windows/MSYS2 上的 `make check` 会构建 V4 引擎并运行+`make deepseek-v4-tiny-check`。仓库中的 `c/deepseek_v4_tiny` fixture 是有效的+缩小版 checkpoint,包含一个 DSpark stage,大小约 1.2 MiB。测试时无需网络、+PyTorch、Transformers 或下载模型。不支持的平台会跳过 V4 执行,同时保留+普通 GLM 构建和平台门控检查。++`deepseek_v4_tiny/ref.json` 中的参考结果由官方 Transformers+`DeepseekV4ForCausalLM` 生成,并经过 C checkpoint 使用的稠密 FP8、路由专家+FP4 和 BF16 权重 round trip。这个零依赖测试比较整数 token ID,而不是解码后的+文本,覆盖:++- 目标模型 teacher forcing 与仅目标模型的 greedy decoding;+- 禁用 drafting 时的目标模型 session 生成;+- DSpark proposal 加目标模型验证,并保证与目标路径精确一致;+- 滑动、压缩稀疏和高度压缩注意力;+- 一个 72-token prompt,跨越内部 64-token prefill 边界;+- 重复执行 engine/session 的打开、生成和销毁生命周期。++Fixture 再生成刻意与 CI 分离。仓库中的 fixture 使用 Python 3.12、+PyTorch 2.13.0、Transformers 5.14.1 和 safetensors 0.8.0 创建+(safetensors 作为 Transformers 依赖安装):++```bash+python -m pip install torch==2.13.0 transformers==5.14.1 safetensors==0.8.0+python c/tools/make_deepseek_v4_tiny.py --force+make -C c deepseek-v4-tiny-check+```++生成器没有 C 引擎 fallback:如果官方 DeepSeek V4 支持不可用,它会直接失败;+同时会打印每个张量的名称与 shape,并在 `ref.json` 中记录 schema/generator、+PyTorch 和 Transformers 版本。++这些检查证明缩小量化模型的 top-1 token 一致性,并执行真实的+target/DSpark/session 路径;但不能证明 logit 级一致性、生产 checkpoint 性能、+所有专家/缓存常驻策略或完整模型质量。++要在禁用 drafting 的情况下执行普通运行时:++```text+./deepseek_v4 deepseek_v4_tiny '<t005><t007><t009>' \+ --raw-prompt --draft-model deepseek_v4_tiny/dspark --no-dspark+```++参考来源的区别:++- 已提交的 tiny fixture:独立的 `source=transformers` oracle;+- 下方完整 checkpoint 冒烟测试:`source=coli-self` 一致性 oracle。++## 完整 checkpoint oracle 验证(不属于轻量 CI)++Upstream 要求有针对性的 token 级检查。V4 单元测试覆盖配置/存储/数学运算;+完整模型正确性使用单独的重型路径验证:++```bash+cd c+make deepseek-v4-oracle MODEL=/path/to/DeepSeek-V4-Flash-DSpark MEMORY_GB=32+# 或者:+python tools/make_deepseek_v4_oracle.py \+ --model /path/to/DeepSeek-V4-Flash-DSpark \+ --binary ./deepseek_v4.exe \+ --output tests/deepseek_v4_oracle.json \+ --validate --teacher-forcing 32 --greedy 20 --check-dspark+```++```text+./deepseek_v4 MODEL --oracle tests/deepseek_v4_oracle.json \+ --teacher-forcing 32 --greedy 20 --memory-gb 32+```++### 比较约定++| 检查 | 判定标准 |+|------|----------|+| Teacher-forcing | top-1 token 精确一致:N/N 个位置与 `tf_pred` 比较 |+| Greedy | top-1 token 精确一致:N/N 个续写 token 与 `full_ids` 比较 |+| DSpark 开/关 | greedy token 序列相同(`--check-dspark`) |+| Logits/top-k | 仅用于 `source=transformers` fixture |++Fixture 的 `source` 字段:++- `coli-self`——由 C 引擎使用 `--no-dspark` 记录(Hugging Face DeepSeek V4+ 不可用时的默认方式)。它证明结果可复现,并证明推测解码与目标模型 greedy+ 路径一致;**不代表**与 HF bit-exact。+- `transformers`——成功加载 `DeepseekV4ForCausalLM` 时使用的官方实现+ (`--prefer-transformers`)。++完整 checkpoint oracle JSON 是本地生成文件,不是 `make check` 的必需项;+已提交的 tiny 独立 oracle 则是必需项。++## 运行++```powershell+cd D:\ai\colibri+python ./c/v4 run --model D:/ai/DeepSeek-V4-Flash-DSpark --ram 32 `+ --stop-sentence "What is the capital of France?"+```++也可以直接调用引擎:+`.\c\deepseek_v4.exe <model> <prompt> --max-tokens N --memory-gb G …`。++### 选项++- `--model PATH`(必需):DeepSeek V4 checkpoint 目录+- `--ram GiB`:规划预算;省略时根据操作系统可用内存自适应规划+- `--ngen N`:最大生成 token 数,默认 128+- `--stop-sentence`(`run`):在第一个句子终止符处停止+- `--system`/`--thinking`:仅适用于 `chat`++Chat 每轮都会重新 prefill 历史记录;尚未实现跨轮 KV 复用。+默认的非 thinking 编码为:++```text+<|begin▁of▁sentence|>[system]<|User|>[user]<|Assistant|></think>+```++## 待办事项++- [ ] **session parallel-prefix**:将+ `COLI_V4_EXPERIMENTAL_PARALLEL_PREFIX_VERIFY` 接入+ `coli_v4_session_generate`,达到旧版 CLI 的验证吞吐+- [ ] **16 GiB 性能**:缩小与 32 GiB 的解码差距(缓存、固定、I/O 重叠)+- [ ] **模型量化**:采用更激进的权重/激活路径,降低占用和带宽需求+- [ ] **服务器**:面向多客户端的 HTTP/OpenAI 兼容 API+- [ ] **CUDA**:在 CPU 路径之外增加可选 GPU 后端+- [ ] Chat 跨轮 KV cache 复用,避免每轮重新 prefill 全部历史