磁盘 KV 缓存深度解析DwarfStar 的 KVC 文件头与 DSV4 载荷格式完全指南【免费下载链接】ds4DeepSeek 4 Flash and PRO local inference engine for Metal, CUDA and ROCm项目地址: https://gitcode.com/GitHub_Trending/ds4/ds4DwarfStards4是 DeepSeek 4 Flash 与 PRO 的本地推理引擎支持 Metal、CUDA 与 ROCm 三大后端。它的磁盘 KV 缓存Disk KV Cache是长对话秒回的关键把已经算过的 KV 状态快照成.kv文件存到磁盘下次同样的提示词前缀直接命中跳过整段 prefill。一、为什么需要磁盘 KV 缓存长上下文的代价很直观一个 8K token 的 Agent 会话如果每次新请求都要重算前 8K 个 token 的 KVprefill 会慢到无法交互。DwarfStar 的解法是把会话的稳定前缀做成检查点checkpoint冷启动锚点cold跨会话复用的稳定系统前缀续跑点continued对话增长每 10000 token 自动落盘一次淘汰/关机补写evict / shutdown防止已算好的前缀白白丢失。缓存目录默认预算为4 GiB超出时按性价比分数淘汰旧检查点。相关策略入口见 docs/SSD_STREAMING.md。二、KVC 文件头52 字节里藏了什么每个缓存文件名为「渲染文本前缀的 SHA-1 十六进制 .kv」例如40位hex.kv。文件结构固定为四段[48 字节固定头][4 字节 text_bytes][渲染文本][DSV4 载荷][可选尾段]前 52 字节的逐字节布局完整写入逻辑在 ds4_kvstore.c偏移长度字段含义0–23 B魔数KVC快速识别文件类型31 B文件版本当前恒为 141 Bquant_bits路由量化位宽2 或 451 Breason冷启动/续跑/淘汰/关机/Agent 系统前缀61 Bext_flags工具映射、响应可见、思考可见、会话标题等位标志71 Bmodel_id模型标识0 为 Flash兼容旧文件8–114 Btokens该检查点覆盖的 token 数小端12–154 Bhits磁盘命中计数16–194 Bctx_size会话上下文规模201 B载荷 ABI当前为 2独立于文件版本演进24–318 Bcreated_at创建时间戳32–398 Blast_used最近使用时间戳40–478 Bpayload_bytesDSV4 载荷字节数48–514 Btext_bytes紧随其后的渲染文本长度头字段常量定义在 ds4_kvstore.h内存中的条目镜像结构见 ds4_kvstore.h。两个设计细节值得新手注意KVC 信封稳定、载荷 ABI 独立第 20 字节外层文件布局可以多年不变而内部会话序列化结构升级时只需 bump 这一个字节旧文件会被安全拒绝而不是误读命中计数直接写回头部每次缓存命中引擎用 ds4_kvstore_touch_file 原地更新hits与last_used作为后续淘汰决策的证据。三、DSV4 载荷快照里到底存了什么紧跟渲染文本之后的是DSV4 载荷——整个文件的主体。它不是一份摘要而是ds4_session的完整序列化快照精确的 token 历史而不是仅靠文本反推图/KV 状态各层已压缩的 KV 行与 prefill 调度状态保证恢复后的数值与冷启动全量重算逐位一致这也是 KV_CACHE_DEFAULT_BOUNDARY_ALIGN_TOKENS 2048 对齐后端 prefill 分块的原因可选尾段trailer由协议层挂载的扩展数据例如 Server 的「工具 ID → 精确 DSML 映射」通过 trailer hooks 写入。加载时的校验链非常严格ds4_kvstore_try_load_text魔数与 ABI → 模型 ID 匹配 → 文本哈希与文件名 SHA-1 一致 → 字节前缀匹配 → 载荷 token 数与头部一致任何一步失败即丢弃该文件并回退冷启动绝不把坏数据喂给引擎。四、命中、写入与淘汰策略速览匹配靠字节前缀查找时对「新提示词的前 N 字节」重算 SHA-1与文件名比对天然免疫 tokenizer 分词边界漂移落盘先写.tmp再原子 rename且按 1% 余量预留预算文件系统抖动不会让新文件刚写完就被淘汰淘汰分数有效命中 1× tokens ÷ 文件大小命中带 6 小时半衰期衰减冷启动/淘汰/关机锚点享 2 倍加权被新文件严格覆盖的旧续跑点会被压到 5%–50% 分数边界处理续跑点默认裁剪 32 token 尾部并对齐 2048使压缩器行收尾与冷启动全量 prefill 完全一致。五、上手路径与延伸阅读资源说明ds4_kvstore.h文件头常量、条目结构、API 全声明ds4_kvstore.c头读写、SHA-1 命名、预算淘汰完整实现docs/SSD_STREAMING.mdSSD 流式与缓存预算的调优指南docs/SERVER.md多会话 Server 下缓存如何复用如果你想动手验证启用磁盘缓存跑一次长对话后在缓存目录里挑一个.kv文件用任意十六进制查看器对照第二节的表格读前 52 字节——KVC魔数、token 数、命中计数一目了然这也是理解KV 缓存到底是什么最快的方式。【免费下载链接】ds4DeepSeek 4 Flash and PRO local inference engine for Metal, CUDA and ROCm项目地址: https://gitcode.com/GitHub_Trending/ds4/ds4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 磁盘 KV 缓存深度解析：DwarfStar 的 KVC 文件头与 DSV4 载荷格式完全指南
磁盘 KV 缓存深度解析DwarfStar 的 KVC 文件头与 DSV4 载荷格式完全指南【免费下载链接】ds4DeepSeek 4 Flash and PRO local inference engine for Metal, CUDA and ROCm项目地址: https://gitcode.com/GitHub_Trending/ds4/ds4DwarfStards4是 DeepSeek 4 Flash 与 PRO 的本地推理引擎支持 Metal、CUDA 与 ROCm 三大后端。它的磁盘 KV 缓存Disk KV Cache是长对话秒回的关键把已经算过的 KV 状态快照成.kv文件存到磁盘下次同样的提示词前缀直接命中跳过整段 prefill。一、为什么需要磁盘 KV 缓存长上下文的代价很直观一个 8K token 的 Agent 会话如果每次新请求都要重算前 8K 个 token 的 KVprefill 会慢到无法交互。DwarfStar 的解法是把会话的稳定前缀做成检查点checkpoint冷启动锚点cold跨会话复用的稳定系统前缀续跑点continued对话增长每 10000 token 自动落盘一次淘汰/关机补写evict / shutdown防止已算好的前缀白白丢失。缓存目录默认预算为4 GiB超出时按性价比分数淘汰旧检查点。相关策略入口见 docs/SSD_STREAMING.md。二、KVC 文件头52 字节里藏了什么每个缓存文件名为「渲染文本前缀的 SHA-1 十六进制 .kv」例如40位hex.kv。文件结构固定为四段[48 字节固定头][4 字节 text_bytes][渲染文本][DSV4 载荷][可选尾段]前 52 字节的逐字节布局完整写入逻辑在 ds4_kvstore.c偏移长度字段含义0–23 B魔数KVC快速识别文件类型31 B文件版本当前恒为 141 Bquant_bits路由量化位宽2 或 451 Breason冷启动/续跑/淘汰/关机/Agent 系统前缀61 Bext_flags工具映射、响应可见、思考可见、会话标题等位标志71 Bmodel_id模型标识0 为 Flash兼容旧文件8–114 Btokens该检查点覆盖的 token 数小端12–154 Bhits磁盘命中计数16–194 Bctx_size会话上下文规模201 B载荷 ABI当前为 2独立于文件版本演进24–318 Bcreated_at创建时间戳32–398 Blast_used最近使用时间戳40–478 Bpayload_bytesDSV4 载荷字节数48–514 Btext_bytes紧随其后的渲染文本长度头字段常量定义在 ds4_kvstore.h内存中的条目镜像结构见 ds4_kvstore.h。两个设计细节值得新手注意KVC 信封稳定、载荷 ABI 独立第 20 字节外层文件布局可以多年不变而内部会话序列化结构升级时只需 bump 这一个字节旧文件会被安全拒绝而不是误读命中计数直接写回头部每次缓存命中引擎用 ds4_kvstore_touch_file 原地更新hits与last_used作为后续淘汰决策的证据。三、DSV4 载荷快照里到底存了什么紧跟渲染文本之后的是DSV4 载荷——整个文件的主体。它不是一份摘要而是ds4_session的完整序列化快照精确的 token 历史而不是仅靠文本反推图/KV 状态各层已压缩的 KV 行与 prefill 调度状态保证恢复后的数值与冷启动全量重算逐位一致这也是 KV_CACHE_DEFAULT_BOUNDARY_ALIGN_TOKENS 2048 对齐后端 prefill 分块的原因可选尾段trailer由协议层挂载的扩展数据例如 Server 的「工具 ID → 精确 DSML 映射」通过 trailer hooks 写入。加载时的校验链非常严格ds4_kvstore_try_load_text魔数与 ABI → 模型 ID 匹配 → 文本哈希与文件名 SHA-1 一致 → 字节前缀匹配 → 载荷 token 数与头部一致任何一步失败即丢弃该文件并回退冷启动绝不把坏数据喂给引擎。四、命中、写入与淘汰策略速览匹配靠字节前缀查找时对「新提示词的前 N 字节」重算 SHA-1与文件名比对天然免疫 tokenizer 分词边界漂移落盘先写.tmp再原子 rename且按 1% 余量预留预算文件系统抖动不会让新文件刚写完就被淘汰淘汰分数有效命中 1× tokens ÷ 文件大小命中带 6 小时半衰期衰减冷启动/淘汰/关机锚点享 2 倍加权被新文件严格覆盖的旧续跑点会被压到 5%–50% 分数边界处理续跑点默认裁剪 32 token 尾部并对齐 2048使压缩器行收尾与冷启动全量 prefill 完全一致。五、上手路径与延伸阅读资源说明ds4_kvstore.h文件头常量、条目结构、API 全声明ds4_kvstore.c头读写、SHA-1 命名、预算淘汰完整实现docs/SSD_STREAMING.mdSSD 流式与缓存预算的调优指南docs/SERVER.md多会话 Server 下缓存如何复用如果你想动手验证启用磁盘缓存跑一次长对话后在缓存目录里挑一个.kv文件用任意十六进制查看器对照第二节的表格读前 52 字节——KVC魔数、token 数、命中计数一目了然这也是理解KV 缓存到底是什么最快的方式。【免费下载链接】ds4DeepSeek 4 Flash and PRO local inference engine for Metal, CUDA and ROCm项目地址: https://gitcode.com/GitHub_Trending/ds4/ds4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考