详细解读Redis作者antirez开源的ds4项目，ds4.c — DeepSeek V4 Flash 本地推理引擎（中文文档）

ds4.c --- DeepSeek V4 Flash 本地推理引擎（中文文档）

ds4.c 是一个用 C 语言手写、专为 DeepSeek V4 Flash 模型定制的本地推理引擎。它不是一个通用的 GGUF 加载器，也不是其他运行时的封装，而是从模型加载、tokenizer、prompt 渲染、KV 缓存、Metal 计算图，到 OpenAI / Anthropic 兼容 HTTP API 的一整条端到端推理栈。

项目作者：antirez（Redis 作者）。

主仓库：antirez/ds4.c（GGUF 模型托管在 huggingface.co/antirez/deepseek-v4-gguf）。

致谢：本项目不直接链接 GGML，但其能够存在归功于 llama.cpp 与 GGML 项目的开拓与积累。

一、项目定位与设计取舍
[二、为什么单独为 DeepSeek V4 Flash 写引擎](#二、为什么单独为 DeepSeek V4 Flash 写引擎)
三、功能特性总览
四、代码结构
五、运行环境与硬件要求
六、性能数据
七、快速开始
八、命令行（CLI）使用
[九、HTTP 服务器使用](#九、HTTP 服务器使用)
十、思考（Thinking）模式
[十一、磁盘 KV Cache](#十一、磁盘 KV Cache)
十二、推测解码（MTP）
[十三、与本地 Coding Agent 集成](#十三、与本地 Coding Agent 集成)
十四、测试与回归向量
十五、落地使用建议
十六、常见问题（FAQ）
十七、致谢与许可证

一、项目定位与设计取舍

ds4.c 的目标非常克制：

只支持一个模型：DeepSeek V4 Flash。仅能加载本项目专门发布的 GGUF。
生产路径只有一个：Apple Silicon 上的 Metal 计算图。CPU 路径仅作为正确性参考。
小、可读、高性能 ：核心是手写 C，Objective-C 仅在 Metal 必须的地方出现，Metal kernel 集中放在 metal/ 目录下。
不引入 C++，不做永久性的语义分支（feature flag），不做大而全的抽象。
正确性优先于速度：不接受出现 attention/KV/logits 漂移、却跑得更快的实现。
重视长上下文 agent 场景：通过 live KV 复用 + 磁盘 KV checkpoint，让长会话本地推理变得可用。

作者的愿景：本地推理应当是 A）推理引擎 + HTTP API、B）针对引擎和假设特调的 GGUF、C）coding agent 集成的端到端测试，三者协同工作。本项目就是这三件事在一个具体模型上的尝试。

二、为什么单独为 DeepSeek V4 Flash 写引擎

作者认为 DeepSeek V4 Flash 在本地推理这件事上很特殊：

激活参数少，相同尺寸下推理更快。
思考模式短：除非用 Think Max，思考段的长度与问题复杂度成正比，常常是同类模型的 1/5。这让"开思考"在本地真正可用。
1M token 上下文窗口。
284B 大体量带来的世界知识：在意大利文化、政治这类边缘话题上，明显比 27B/35B 级别 dense 模型知道得多。
英文与意大利语写作质量好，"准前沿模型"的手感。
KV cache 极其紧凑，长上下文本地推理可行，且能落盘做磁盘级持久化。
2-bit 量化效果好 （前提是按本项目的非对称量化方式：仅量化 routed MoE 专家，up/gate 用 IQ2_XXS，down 用 Q2_K，其他保留高精度）。这让 128GB 内存的 MacBook 也能跑。
预期 DeepSeek 后续会发布更强的 v4 Flash 更新。

三、功能特性总览

Metal 全图推理：DeepSeek V4 Flash 专属的 Metal 计算图调度器。
mmap 加载：不会把整份 GGUF 提前 copy 进内存。
多种思考模式：thinking（默认）/ Think Max / non-thinking。
OpenAI + Anthropic 双协议 HTTP API：原生支持 SSE 流式输出。
工具调用映射 ：把客户端的 tools schema 渲染为 DeepSeek DSML，再把模型输出的 DSML tool call 映射回 OpenAI / Anthropic 的 tool_use / tool_calls。
Live KV 复用：同一会话续接时，只对增量 token 做 prefill。
磁盘 KV checkpoint：让昂贵的长 prompt 跨 session、跨重启复用。
MTP 推测解码（实验性）：可选附加 GGUF，仅 greedy 模式有效。
官方 logits 回归测试：基于官方 API 抓取的 token 级 logprob 向量做回归比对。
交互式 REPL：linenoise 实现的多轮 chat 终端。

四、代码结构

复制代码

ds4-main/
├── ds4.h               # 公共引擎边界（CLI/server 只依赖这个头）
├── ds4.c               # 模型加载、tokenizer、CPU 参考实现、Metal 图调度、session、磁盘 cache 序列化
├── ds4_metal.h / .m    # Objective-C Metal 运行时与 kernel 包装
├── metal/              # 全部 Metal 计算 kernel
│   ├── flash_attn.metal    # Flash Attention
│   ├── moe.metal           # MoE 路由与专家
│   ├── dense.metal         # 稠密矩阵乘
│   ├── dsv4_hc.metal       # Head Compressor（DS V4 特有）
│   ├── dsv4_kv.metal       # KV 处理
│   ├── dsv4_rope.metal     # RoPE
│   ├── dsv4_misc.metal
│   ├── softmax.metal / norm.metal / glu.metal / unary.metal / ...
├── ds4_cli.c           # ds4 CLI 二进制：one-shot + 交互式 REPL
├── linenoise.c / .h    # REPL 行编辑库
├── ds4_server.c        # ds4-server 二进制：OpenAI/Anthropic HTTP API、worker 队列、磁盘 KV 策略
├── tests/
│   ├── ds4_test.c                    # C 测试 runner
│   ├── test-vectors/                 # 来自官方 API 的 logprob 回归向量
│   └── long_context_security_prompt.txt
├── download_model.sh   # 从 Hugging Face 拉取 GGUF
├── Makefile
├── README.md           # 英文文档（原版）
├── README.zh-CN.md     # 本文档
├── AGENT.md            # 项目维护规范
└── LICENSE

两个最终二进制：

二进制	作用
`ds4`	命令行：one-shot prompt 或交互式 chat REPL
`ds4-server`	HTTP 服务器：OpenAI/Anthropic 兼容 API + 磁盘 KV

五、运行环境与硬件要求

重要：本项目是 Metal-only 。生产路径只在 Apple Silicon 的 macOS 上跑（M1 / M2 / M3 / M4）。

量化	磁盘大小	推荐机器
`q2`	~81 GB	128 GB 内存 MacBook / Mac Studio
`q4`	~153 GB	≥256 GB 内存的 Mac Studio
`mtp`	~3.5 GB	可选，配合 q2 / q4 使用

其他注意：

Linux 可以编译，但无 Metal 路径，仅能跑 CPU 参考实现，不要拿来生产用。
Windows / x86 暂不支持。Makefile 没有 Windows 路径，作者明确表示"将来或许做 CUDA，但仅此而已"。
CPU 路径 仅作正确性 debug。当前 macOS 在大体量 mmap 上有内核 VM bug，作者警告：不要拿 CPU 路径跑大模型，会让内核挂掉。
1M 上下文 ≈ 26 GB 额外内存（仅压缩 indexer 就 ~22 GB）。128GB 机器用 q2 时实际可分配的 --ctx 通常在 100k~300k 之间。

六、性能数据

作者给出的单次运行 Metal 数据（--ctx 32768，--nothink，greedy 解码，-n 256）：

机器	量化	Prompt	Prefill	Generation
MacBook Pro M3 Max, 128 GB	q2	短 prompt	58.52 t/s	26.68 t/s
MacBook Pro M3 Max, 128 GB	q2	11709 token	250.11 t/s	21.47 t/s
MacBook Pro M3 Max, 128 GB	q4	---	N/A	N/A
Mac Studio M3 Ultra, 512 GB	q2	短 prompt	84.43 t/s	36.86 t/s
Mac Studio M3 Ultra, 512 GB	q2	11709 token	468.03 t/s	27.39 t/s
Mac Studio M3 Ultra, 512 GB	q4	短 prompt	78.95 t/s	35.50 t/s
Mac Studio M3 Ultra, 512 GB	q4	12018 token	448.82 t/s	26.62 t/s

七、快速开始

1. 克隆并编译

sh 复制代码

git clone <repo-url> ds4-main
cd ds4-main
make

成功后会得到两个可执行文件：./ds4 和 ./ds4-server。

Makefile 自动检测 uname -s：在 Darwin 上链接 Foundation 与 Metal framework；在其他系统上加上 -DDS4_NO_METAL，只编译 CPU 路径。

2. 下载模型

sh 复制代码

./download_model.sh q2   # 128 GB 内存机器
./download_model.sh q4   # ≥256 GB 内存机器
./download_model.sh mtp  # 可选：推测解码组件

下载脚本会：

从 https://huggingface.co/antirez/deepseek-v4-gguf 拉取 GGUF；
存到 ./gguf/，断点续传（curl -C -）；
把 ./ds4flash.gguf 软链到所选 q2 / q4 文件。

可选鉴权方式（按优先级）：--token TOKEN → 环境变量 HF_TOKEN → 本地 HuggingFace token 缓存（~/.cache/huggingface/token）。公网 GGUF 不强制 token。

3. 跑一发

sh 复制代码

./ds4 -p "Explain Redis streams in one paragraph."

或进入交互式：

sh 复制代码

./ds4
ds4>

或直接拉起本地 API 服务：

sh 复制代码

./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

八、命令行（CLI）使用

./ds4 有三种启动形式：

sh 复制代码

ds4                      # 进入交互式 chat REPL
ds4 -p TEXT              # 单次 prompt 跑完即退
ds4 --prompt-file FILE   # 从文件读 prompt（适合长 prompt）

常用选项（节选）

模型与运行时

-m, --model FILE：GGUF 路径，默认 ds4flash.gguf。
--mtp FILE：可选 MTP GGUF。
--mtp-draft N：每个推测步最大 draft token 数，默认 1。
--mtp-margin F：N=2 fast verifier 的最低 confidence，默认 3。
-c, --ctx N：会话上下文大小，默认 32768。
--metal / --cpu：选择后端，默认 --metal。
--quality：尽可能走精确 kernel（更慢一点点，更稳）。
--warm-weights：启动时预热已 mmap 的权重页。

Prompt 与采样

-p, --prompt TEXT / --prompt-file FILE
-sys, --system TEXT：system prompt，默认 You are a helpful assistant。
-n, --tokens N：最多生成的 token 数，默认 50000。
--temp F / --top-p F / --seed N
--think / --think-max / --nothink：思考模式。

交互式命令

命令	作用
`/help`	显示帮助
`/think`	切到普通思考模式
`/think-max`	切到 Think Max（要求 `--ctx ≥ 393216`，否则降级）
`/nothink`	关闭思考，直答
`/ctx N`	用新的上下文大小重建会话
`/read FILE`	把文件内容当作下一条用户消息
`/quit`、`/exit`	退出
`Ctrl+C`	中断当前生成、回到 `ds4>`，不退出进程

诊断与开发用开关

--inspect：只加载模型、打印 summary。
--dump-tokens：打印渲染后的 prompt token 序列。
--dump-logprobs FILE：把贪心生成的 top-logprobs 以 JSON 写出（不打印文本），用于做回归向量。
--logprobs-top-k N：每位置保留多少候选，默认 20。
--head-test / --first-token-test / --metal-graph-test 等：单元级前向探针。

九、HTTP 服务器使用

sh 复制代码

./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

服务器是 Metal-only。它在内存里只持有一个可变的图/KV checkpoint，因此无状态客户端如果重新发送"和上一条 prompt 共享前缀"的请求，可以直接复用前缀，不必从 0 重新 prefill。

⚠ 当前服务器不会把多个独立请求 batching 在一起：socket 解析是多线程的，但推理本身在唯一一个 Metal worker 上串行排队。

已实现端点

复制代码

GET  /v1/models
GET  /v1/models/deepseek-v4-flash
POST /v1/chat/completions      # OpenAI 风格
POST /v1/completions
POST /v1/messages              # Anthropic 风格（Claude Code 等用）

`/v1/chat/completions` 支持

messages、max_tokens / max_completion_tokens、temperature、top_p、top_k、min_p、seed
stream、stream_options.include_usage
tools、tool_choice：自动渲染为 DSML，并把模型生成的 tool call 映射回 OpenAI 格式。

`/v1/messages`（Anthropic）支持

system、messages、tools、tool_choice、max_tokens、temperature、top_p、top_k、stream、stop_sequences
思考控制：thinking={"type":"enabled","budget_tokens":...} / {"type":"disabled"}
模型 tool 输出会以 Anthropic tool_use 块返回。

流式

两套 API 都支持 SSE。在思考模式下，reasoning 段会按各 API 的原生形态独立输出，不会混入正文。

简单 OpenAI 调用示例

sh 复制代码

curl http://127.0.0.1:8000/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model":"deepseek-v4-flash",
    "messages":[{"role":"user","content":"List three Redis design principles."}],
    "stream":true
  }'

服务器命令行选项（节选）

模型与运行时

选项	默认值	说明
`-m, --model FILE`	`ds4flash.gguf`	GGUF 路径
`--mtp FILE`	---	可选 MTP GGUF
`--mtp-draft N`	1	每步最大 draft token
`--mtp-margin F`	3	fast verifier confidence 下限
`-c, --ctx N`	32768	启动时分配的上下文大小
`-n, --tokens N`	393216 (384K)	客户端未指定时的默认输出上限
`-t, --threads N`	自动	主机端辅助线程
`--quality`	off	优先走精确 kernel
`--warm-weights`	off	预热权重页

HTTP

选项	默认值	说明
`--host HOST`	`127.0.0.1`	绑定地址
`--port N`	`8000`	端口
`--trace FILE`	---	把 prompt、cache 决策、输出、tool call 写到这个人类可读 trace 文件

磁盘 KV cache

选项	默认值	说明
`--kv-disk-dir DIR`	---	启用磁盘 KV checkpoint，目录会自动创建
`--kv-disk-space-mb N`	4096	启用时的磁盘配额（MB）
`--kv-cache-min-tokens N`	512	短于 N token 的不存也不读
`--kv-cache-cold-max-tokens N`	30000	cold-save 仅对 [min, N] 范围内的首条长 prompt 触发；0 关闭 cold save
`--kv-cache-continued-interval-tokens N`	10000	live 会话每增长 N token 存一次；0 关闭
`--kv-cache-boundary-trim-tokens N`	32	cold-save 时砍掉的尾部 token，避免 BPE 边界 retokenize 错位
`--kv-cache-boundary-align-tokens N`	2048	cold-save 时下取整对齐到这个 prefill chunk 边界；0 关闭
`--kv-cache-reject-different-quant`	off	严格只复用相同 routed-expert 量化的 checkpoint

十、思考（Thinking）模式

DeepSeek V4 Flash 有三档思考模式：

模式	触发
non-thinking	`thinking={"type":"disabled"}`，或 OpenAI 的 `think:false`，或别名 `model: "deepseek-chat"`
thinking	默认。OpenAI 的 `reasoning_effort=low/medium/high/xhigh` 都会落到这里
Think Max	`reasoning_effort=max` 或 Anthropic `output_config.effort=max`，且 `--ctx ≥ 393216` 时才会启用

如果上下文不够 393216，Think Max 会自动降级为普通 thinking------这是模型卡的官方建议。

十一、磁盘 KV Cache

为什么要做

Chat / completion API 是无状态的：agent 客户端通常每一次请求都重发整段对话历史。ds4-server 的策略是：

内存里只有一份 live KV------当前会话独占；
磁盘 KV cache 让"不同 session 的有用前缀"在 session 切换、服务器重启之后仍能复用。

Key 设计

key = token id 序列的 SHA1（每个 token 当成 LE u32），不是文本，避免 BPE 边界问题。
文件名：<sha1>.kv。
用普通 read/write IO，不 mmap，避免在已经 mmap 模型权重的进程里再增加 VM 映射。

4 种存盘时机

类型	时机
`cold`	首次长 prompt 跑到稳定前缀、生成开始之前
`continued`	live 会话相对上次保存又增长了配置的 interval
`evict`	一个新无关请求即将顶掉当前 live session 之前
`shutdown`	服务器干净退出

cold save 会主动砍尾几个 token + 对齐到 prefill chunk 边界，避免后续追加 prompt 时 BPE 重新分词导致 cache miss。

默认策略（可调）

至少 512 token 才会写或读
cold save 仅对 [512, 30000] 区间的首条长 prompt 触发
cold save 砍掉尾部 32 个 token、并下取整对齐到 2048 token

文件格式（可用 hexdump 检视）

每个 cache 文件由三部分组成：

text 复制代码

KVC fixed header     48 字节
u32 rendered_text_bytes
rendered_text_bytes  渲染文本（仅 observability 用，加载时不可信）
DS4 session payload  payload_bytes 由 header 给出

固定 header（小端）：

text 复制代码

0   u8[3]  magic = "KVC"
3   u8     version = 1
4   u8     routed-expert 量化位数（当前 2 或 4）
5   u8     save reason: 0 unknown, 1 cold, 2 continued, 3 evict, 4 shutdown
6   u8[2]  reserved
8   u32    cached token 数
12  u32    hit 次数
16  u32    snapshot 写入时的 ctx size
20  u8[4]  reserved
24  u64    创建 unix time
32  u64    上次使用 unix time
40  u64    DS4 session payload 字节数

DS4 session payload 起始 13 个 LE u32：magic="DSV4" / version / saved ctx / prefill chunk / 各路 KV / indexer / vocab / live raw rows 等，后面依次是：checkpoint token id、下一 token 的 raw float32 logits、各层压缩 KV、indexer、live raw sliding-window KV 等。

这是 DS4 专属格式，不是通用的图状态 dump ，只能在兼容的 ds4.c 构建之间复用。

常见操作

直接删 --kv-disk-dir 整个目录就重置 cache。
默认允许跨 q2 / q4 复用同前缀；要严格只复用相同量化用 --kv-cache-reject-different-quant。

十二、推测解码（MTP）

可选的 --mtp MTP.gguf 会启用 DeepSeek V4 Flash 的 MTP 推测解码组件。

仅对 greedy 解码有效。
用 confidence 门限（--mtp-margin）过滤掉容易"部分接受 → 反而变慢"的 case。
当前作者把它定位为 实验性、最多带来轻微加速，不是显著的生成提速。

启用示例：

sh 复制代码

./ds4 --mtp gguf/DeepSeek-V4-Flash-MTP-Q4K-Q8_0-F32.gguf --mtp-draft 2
./ds4-server --mtp gguf/...MTP...gguf --mtp-draft 2

十三、与本地 Coding Agent 集成

ds4-server 暴露 OpenAI + Anthropic 两套兼容 API，可被本地 coding agent 直接当成"模型 provider"使用。先把服务器跑起来，客户端的上下文上限不要超过 --ctx：

sh 复制代码

./ds4-server --ctx 100000 --kv-disk-dir /tmp/ds4-kv --kv-disk-space-mb 8192

输出上限 384000 是为了避免 token cap 截断；服务器自身仍会在 ctx 跑满时停下。

opencode

把下列内容加到 ~/.config/opencode/opencode.json：

json 复制代码

{
  "$schema": "https://opencode.ai/config.json",
  "provider": {
    "ds4": {
      "name": "ds4.c (local)",
      "npm": "@ai-sdk/openai-compatible",
      "options": {
        "baseURL": "http://127.0.0.1:8000/v1",
        "apiKey": "dsv4-local"
      },
      "models": {
        "deepseek-v4-flash": {
          "name": "DeepSeek V4 Flash (ds4.c local)",
          "limit": { "context": 100000, "output": 384000 }
        }
      }
    }
  },
  "agent": {
    "ds4": {
      "description": "DeepSeek V4 Flash served by local ds4-server",
      "model": "ds4/deepseek-v4-flash",
      "temperature": 0
    }
  }
}

Pi

~/.pi/agent/models.json：

json 复制代码

{
  "providers": {
    "ds4": {
      "name": "ds4.c local",
      "baseUrl": "http://127.0.0.1:8000/v1",
      "api": "openai-completions",
      "apiKey": "dsv4-local",
      "compat": {
        "supportsStore": false,
        "supportsDeveloperRole": false,
        "supportsReasoningEffort": true,
        "supportsUsageInStreaming": true,
        "maxTokensField": "max_tokens",
        "supportsStrictMode": false,
        "thinkingFormat": "deepseek",
        "requiresReasoningContentOnAssistantMessages": true
      },
      "models": [
        {
          "id": "deepseek-v4-flash",
          "name": "DeepSeek V4 Flash (ds4.c local)",
          "reasoning": true,
          "thinkingLevelMap": {
            "off": null, "minimal": "low", "low": "low",
            "medium": "medium", "high": "high", "xhigh": "xhigh"
          },
          "input": ["text"],
          "contextWindow": 100000,
          "maxTokens": 384000,
          "cost": { "input": 0, "output": 0, "cacheRead": 0, "cacheWrite": 0 }
        }
      ]
    }
  }
}

可选地把它设为默认（~/.pi/agent/settings.json）：

json 复制代码

{ "defaultProvider": "ds4", "defaultModel": "deepseek-v4-flash" }

Claude Code

走 Anthropic 兼容端点。写一个 ~/bin/claude-ds4 包装脚本：

sh 复制代码

#!/bin/sh
unset ANTHROPIC_API_KEY

export ANTHROPIC_BASE_URL="${DS4_ANTHROPIC_BASE_URL:-http://127.0.0.1:8000}"
export ANTHROPIC_AUTH_TOKEN="${DS4_API_KEY:-dsv4-local}"
export ANTHROPIC_MODEL="deepseek-v4-flash"

export ANTHROPIC_CUSTOM_MODEL_OPTION="deepseek-v4-flash"
export ANTHROPIC_CUSTOM_MODEL_OPTION_NAME="DeepSeek V4 Flash local ds4"
export ANTHROPIC_CUSTOM_MODEL_OPTION_DESCRIPTION="ds4.c local GGUF"

export ANTHROPIC_DEFAULT_SONNET_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="deepseek-v4-flash"
export ANTHROPIC_DEFAULT_OPUS_MODEL="deepseek-v4-flash"
export CLAUDE_CODE_SUBAGENT_MODEL="deepseek-v4-flash"

export CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC=1
export CLAUDE_CODE_DISABLE_NONSTREAMING_FALLBACK=1
export CLAUDE_STREAM_IDLE_TIMEOUT_MS=600000

exec "$HOME/.local/bin/claude" "$@"

Claude Code 首次会话往往会先发 ~25k token 的初始 prompt 才开始干活，务必开 --kv-disk-dir，否则每次重启都会从 0 重 prefill 一次。

十四、测试与回归向量

tests/test-vectors/ 中存有从官方 DeepSeek V4 Flash API（deepseek-v4-flash，greedy，关闭思考，最大 top_logprobs）抓的短/长上下文续写向量。本地用 ./ds4 --dump-logprobs 生成对应文件，按 token 字节比对------tokenizer / 模板 / attention 任一回归都会先在这一步暴露，比"长生成失败"早很多。

sh 复制代码

make test                    # 等价于 ./ds4_test --all
./ds4_test --logprob-vectors
./ds4_test --server          # live server 集成（需要服务器在跑）

十五、落地使用建议

按硬件场景对应的最佳路径：

A. 你有一台 128GB Apple Silicon

用 q2 量化。
--ctx 100000 ~ 200000，务必开 --kv-disk-dir（agent 必备）。
短交互、命令行实验：直接 ./ds4。
长会话 / 接 agent：./ds4-server + 上面三种集成方式。

B. 你有 256GB 以上 Apple Silicon（Mac Studio）

推荐 q4 量化，质量更高。
可考虑把 --ctx 拉到 300000 甚至更大；磁盘 cache 配额相应放大。
同一台机器跑多个并发请求时记住：目前是串行的。

C. 你想给团队用

当前服务器单进程串行、不做请求 batching，不是面向多人共享的方案。如果非要共享，只适合"个人/小组共用一台 Mac Studio + 排队接受"。
想真正多人 serving，建议另寻方案，或者等待项目演进。

D. 你是 Linux / Windows / x86 用户

当前 不能跑生产推理：服务器是 Metal-only，CPU 路径既不可靠也极慢。
你能做的事：阅读代码、做 CUDA 移植研究、用 CPU 路径在小 ctx 下跑 sanity check。
想本地跑 DeepSeek V4 Flash 的话，建议先关注 llama.cpp 生态对 v4 Flash 的支持进展。

E. 调优清单

长 prompt agent 场景：把 --kv-cache-cold-max-tokens 调到比常用 system prompt 更大；把 --kv-disk-space-mb 调到能存 N 条不同会话。
想让生成全部确定可重放：--temp 0（greedy）+ 固定 --seed。
想强制总走最精确路径：--quality。
想把模型权重热装载、避开第一次访问的 page-in 抖动：--warm-weights。

十六、常见问题（FAQ）

Q：我能用任意 DeepSeek 的 GGUF 吗？

不行。本项目对张量 layout、量化组合、metadata、可选 MTP 状态都有特定假设，只接受 huggingface.co/antirez/deepseek-v4-gguf 下面的 GGUF。

Q：能跑 CUDA / NVIDIA GPU 吗？

当前不能。作者表态"将来或许加 CUDA，但仅此而已"。

Q：CPU 路径完全不能用吗？

能用做正确性参考，但 macOS 上对超大 mmap 有内核 VM bug，作者直接警告：会让内核挂掉，需要重启。生产请走 Metal。

Q：服务器支持几个并发请求？

socket 解析多线程，但推理只有一个 Metal worker。多请求会排队、不做 batching。

Q：磁盘 cache 安全吗？

cache 文件中包含原文 prompt（仅作 observability，加载时不信），如果担心隐私，把 cache 目录放在加密卷里、并定期清理。

Q：思考内容怎么显示？

在思考模式下，reasoning 会以各 API 原生字段（OpenAI 的 reasoning_content / Anthropic 的 thinking 块）单独流出，不会混入正文。

Q：Think Max 没生效？

看 --ctx 是不是 ≥ 393216；不到的话会自动降级为普通 thinking。

Q：怎么停止生成？

CLI：Ctrl+C，回到 ds4> 不退出进程。HTTP：客户端断流即可。

十七、致谢与许可证

致谢：本项目不直接链接 GGML，但其能存在归功于 llama.cpp 与 GGML 项目以及 Georgi Gerganov 等贡献者。源码层面保留并改编了部分 GGUF 量化布局表、CPU 量化点积、若干 Metal kernel；LICENSE 文件保留了 GGML 作者的版权声明。
AI 协助：作者公开声明本项目"在 GPT 5.5 的强力辅助下"开发，人主导想法、测试与调试。介意 AI 辅助代码的读者请绕行。
许可证 ：见仓库根目录 LICENSE。

这是 alpha 质量软件------目标是把 一个本地模型 （DeepSeek V4 Flash）+ 一个推理引擎 （ds4.c）+ agent 集成测试 这三件事做完。它不是通用方案，但它完成了它选择要完成的那件事。

详细解读Redis作者antirez开源的ds4项目，ds4.c — DeepSeek V4 Flash 本地推理引擎（中文文档）

ds4.c --- DeepSeek V4 Flash 本地推理引擎（中文文档）

目录

一、项目定位与设计取舍

二、为什么单独为 DeepSeek V4 Flash 写引擎

三、功能特性总览

四、代码结构

五、运行环境与硬件要求

六、性能数据

七、快速开始

1. 克隆并编译

2. 下载模型

3. 跑一发

八、命令行（CLI）使用

常用选项（节选）

交互式命令

诊断与开发用开关

九、HTTP 服务器使用

已实现端点

/v1/chat/completions 支持

/v1/messages（Anthropic）支持

流式

简单 OpenAI 调用示例

服务器命令行选项（节选）

十、思考（Thinking）模式

十一、磁盘 KV Cache

为什么要做

Key 设计

4 种存盘时机

默认策略（可调）

文件格式（可用 hexdump 检视）

常见操作

十二、推测解码（MTP）

十三、与本地 Coding Agent 集成

opencode

Pi

Claude Code

十四、测试与回归向量

十五、落地使用建议

A. 你有一台 128GB Apple Silicon

B. 你有 256GB 以上 Apple Silicon（Mac Studio）

C. 你想给团队用

D. 你是 Linux / Windows / x86 用户

E. 调优清单

十六、常见问题（FAQ）

十七、致谢与许可证

`/v1/chat/completions` 支持

`/v1/messages`（Anthropic）支持