Appearance
ds4.c 学习知识地图
项目概览
- DwarfStar（ds4.c）：antirez 编写的原生推理引擎，首要支持 DeepSeek V4 Flash（含 Vision-Exp 多模态检查点）与 DeepSeek V4.1 Flash（Engram 外部记忆架构，Metal + CUDA 文本，2026-09），也支持 Qwen3.8 Flash Next（GDN 混合架构 + 盘上 n-gram PLE + MTP，Metal/CUDA，2026-09 中旬）、GLM 5.3（KDA 混合递归/稀疏架构 + 视觉）、GLM 5.2 和（大内存机器上）DeepSeek V4 PRO——不再 DeepSeek 专用
- ~85,000 行 ds4.c 核心（C，另有独立的 ds4_engram.c Engram 子系统），加上 Metal / CUDA / ROCm 后端共 ~350K+ 行（C + Objective-C + MSL + CUDA + HIP）
- 零外部依赖：JSON、HTTP、分词器、图像解码（vendored iris JPEG/PNG）全部手写或头文件内联
- 目标平台：Apple Silicon Mac（Metal）、NVIDIA GPU（CUDA，含多卡与 DGX Spark）、AMD GPU（ROCm，Strix Halo）
- 扩展能力：分布式流水线并行、张量并行（Mac RDMA + CUDA + 双 Spark RoCE）、SSD streaming（含 GLM 全量检查点、V4.1 默认模式）、会话批处理（含 Qwen 批处理推测解码）、多 GPU 放置、多模态视觉输入（四族）、方向性引导
- GGUF 量化工具：
gguf-tools/提供 imatrix 收集和 HF-to-GGUF 量化 - 贡献指南：
CONTRIBUTING.md+QA_BEFORE_RELEASES.md含回归测试流程（make test、CUDA regression、make test-rocm、质量评分）
知识索引
C 语言知识点
| 概念 | 主题 | 对应文件 |
|---|---|---|
| Makefile / 编译流程 | Part 1 | Makefile |
| malloc/free / xmalloc | Part 1 | ds4.c |
| mmap 零拷贝 | Part 1 | ds4.c |
| __thread TLS | Part 1 | ds4.c |
| struct 对齐 / static_assert | Part 1 | ds4.c |
| 字节序 / 二进制解析 | Part 1 | ds4.c |
| 哈希表（开放寻址） | Part 2 | ds4.c |
| 字符串操作 | Part 2 | ds4.c |
| 浮点运算 / softmax | Part 2 | ds4.c |
| union 类型转换 | Part 2 | ds4.c |
| opaque type 设计 | Part 3 | ds4.h |
| 位操作 / 量化 | Part 3 | ds4.c |
| 多维数组索引 | Part 3 | ds4.c |
| 指针数组 | Part 3 | ds4.c |
| volatile / 信号 | Part 4 | ds4.c |
| pthread 线程池 | Part 4 | ds4.c |
| mutex / condvar | Part 4 | ds4.c |
| POSIX socket | Part 5 | ds4_server.c |
| poll I/O 多路复用 | Part 5 | ds4_server.c |
| 文件 I/O / SHA1 | Part 5 | ds4_server.c |
| JSON 手写解析 | Part 5 | ds4_server.c |
| ObjC 互操作 | Part 6 | ds4_metal.m |
LLM 知识点
| 概念 | 主题 | 对应文件 |
|---|---|---|
| 推理引擎是什么 | Part 1 | README.md |
| 模型文件格式 (GGUF) | Part 1 | ds4.c |
| BPE 分词 | Part 2 | ds4.c |
| 采样策略 | Part 2 | ds4.c |
| Transformer 权重结构 | Part 3 | ds4.h |
| 模型量化 | Part 3 | ds4.c |
| imatrix 重要性矩阵 | — | gguf-tools/ |
| GGUF 量化工具 | — | gguf-tools/ |
| Self-Attention | Part 3 | ds4.c |
| KV Cache | Part 3 | ds4.c |
| MLA (压缩注意力) | Part 3 | ds4.c |
| MoE (混合专家) | Part 3 | ds4.c |
| SwiGLU 激活 | Part 3 | ds4.c |
| RoPE 位置编码 | Part 4 | ds4.c |
| prefill vs decode | Part 4 | ds4.c |
| 自回归生成 | Part 4 | ds4.c |
| 推理并行性 | Part 4 | ds4.c |
| SSE 流式响应 | Part 5 | ds4_server.c |
| Responses API (/v1/responses) | Part 5 | ds4_server.c |
| KV Cache 持久化 | Part 5 | ds4.c |
| OpenAI/Anthropic API | Part 5 | ds4_server.c |
| Tool Calling | Part 5 | ds4_server.c |
| Live Tool Continuation | Part 5 | ds4_server.c |
| KV Cache 命中衰减与驱逐 | Part 5 | ds4_server.c |
| KV Cache 用量报告 | Part 5 | ds4_server.c |
| ds4-eval 能力评估 | Part 5 | ds4_eval.c |
| DeepSeek V4 模型卡 | Part 1 | MODEL_CARD.md |
| GPU 加速 / Flash Attention | Part 6 | metal/ ds4_cuda.cu |
| Metal 精确解码融合（bit-exact A/B） | Part 6 | ds4_metal.m metal/ speed-bench/ |
| 客户端断开取消生成 | Part 5 | ds4_server.c |
| CUDA Managed KV Cache | Part 6 | ds4_cuda.cu |
| 分布式流水线并行 | 术语表 | ds4_distributed.c |
| 张量并行（Mac RDMA / CUDA） | 术语表 | ds4_tp.c |
| 会话批处理（--batched-session） | 术语表 | ds4_server.c |
| DSpark 推测解码 | 术语表 | ds4.c |
| 多 GPU 放置 / 层打包 | Part 6 | ds4_layer_pack.c ds4_gpu_args.c |
| GLM 5.2 多模型支持 | Part 3 | ds4.c |
| GLM 5.3 混合架构（KDA 递归线性注意力） | 术语表 | ds4.c metal/glm53_kda.metal |
| 视觉编码器 / 多模态输入 | 术语表 | ds4_image.c ds4_*_vision_gpu.cuh |
| 方向性引导（Directional Steering） | 术语表 | ds4.c dir-steering/ |
| 推测解码采样模式（机会式/精确随机） | 术语表 | ds4.c |
| ROCm MXFP4 专家内核 | Part 6 | rocm/ds4_rocm_moe.cuh |
| gfx1151 kernel lab 调优 | Part 6 | cuda/mmq/test/proto_*.cu |
| 双 Mac RDMA TP 延迟工程（poll gates / 预热 / 队列保活） | 术语表 | ds4_tp.c ds4_metal.m |
| DSpark 种子批处理 + 六 token 验证 + EOS 契约 | 术语表 | ds4.c |
| GLM 全量检查点 SSD streaming（有界优先级 + 前瞻读） | 术语表 | ds4_metal.m |
| Metal prefill MXFP4 路由 GEMM（TensorOps mm_id） | Part 6 | metal/moe.metal |
| hipBLASLt 版本匹配 prefill + ROCm 内存预算 | Part 6 | rocm/ds4_rocm_hipblaslt.cuh |
| 对话前缀条件化（--prefix-file） | 术语表 | ds4_prompt_prefix.c |
| ds4-eval hard 能力套件（50 题多源） | Part 5 | ds4_eval_cases.c |
| Agent 上下文压缩恢复（同消息续写 / 预算结转 / 摘要空间预约） | Part 5 | ds4_agent.c |
| 多模态 live 前缀复用（图像 rebase + 嵌入缓存） | 术语表 | ds4_server.c |
| Agent 教学提示模式（/hints） | Part 5 | ds4_agent.c |
| Qwen3.8 GDN 混合架构（3 GDN + 1 门控 GQA/QSA + PLE 盘上 n-gram） | 术语表 | ds4.c metal/qwen4.metal |
| Qwen 批处理推测解码（整批同进退起草 + EMA 定价） | 术语表 | ds4.c ds4_server.c |
| 服务器槽位路由重构（复用阶梯探测 + 陈旧度驱逐） | Part 5 | ds4_server.c |
| V4.1 CUDA 后端（有界专家缓存 + 双 Spark RoCE TP） | Part 6 | ds4_deepseek41_cuda.cuh |
| Qwen 原生跨会话批处理（共享 arena + 行表寻址） | Part 6 | metal/qwen4.metal |
学习进度
| 天 | 日期 | 状态 | 对应主题 |
|---|---|---|---|
| 1 | 2025-05-09 | 已完成 | Part 1: 构建与加载 |
| 2 | 2025-05-09 | 已完成 | Part 1: 构建与加载 |
| 3 | 2025-05-09 | 已完成 | Part 1: 构建与加载 |
| 4 | 2025-05-09 | 已完成 | Part 2: 分词与采样 |
| 5 | 2025-05-09 | 已完成 | Part 2: 分词与采样 |
| 6 | 2025-05-09 | 已完成 | Part 3: 模型架构 |
| 7 | 2025-05-09 | 已完成 | Part 3: 模型架构 |
| 8 | 2025-05-09 | 已完成 | Part 3: 模型架构 |
| 9 | 2025-05-09 | 已完成 | Part 3: 模型架构 |
| 10 | 2025-05-09 | 已完成 | Part 4: 推理流程 |
| 11 | 2025-05-09 | 已完成 | Part 4: 推理流程 |
| 12 | 2025-05-09 | 已完成 | Part 5: 服务层 |
| 13 | 2025-05-09 | 已完成 | Part 5: 服务层 |
| 14 | 2025-05-09 | 已完成 | Part 5: 服务层 |
| 15 | 2025-05-09 | 已完成 | Part 6: GPU 加速 |