理解 KVC 哈希命名：DwarfStar 如何用 SHA1 前缀命中复用检查点

理解 KVC 哈希命名DwarfStar 如何用 SHA1 前缀命中复用检查点【免费下载链接】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。这篇指南带你理解它的 KVC 磁盘缓存检查点文件名由提示词字节前缀的 SHA1 哈希生成命中即跳过重复 prefill长会话与换回旧会话都能秒级恢复。为什么检查点文件名是一个 40 位十六进制哈希KVC 缓存文件遵循一个非常简单的命名规则文件名 40 位 SHA1 十六进制摘要 .kv后缀总长 43 个字符。目录扫描时会直接校验这个形状不符合的文件一律忽略见 ds4_kvstore.c命名成分内容作用前 40 个字符SHA1 摘要的十六进制唯一定位一个检查点后 3 个字符固定后缀.kv区分缓存文件与其他文件SHA1 摘要由 ds4_kvstore_sha1_bytes_hex 统一计算服务端还内置了经典测试向量sha1(abc)必须等于a9993e364706816aba3e25717850c26c9cd0d89d保证摘要算法在任何平台编译后行为一致见 ds4_server.c。为什么哈希字节前缀而不是 token 序列这是整套机制最关键的设计决策。源码注释写得很直白文件名是缓存文本字节的 SHA1而不是 token 序列的 SHA1ds4_server.c。原因是token 序列只有引擎自己读得懂而客户端CLI、HTTP 客户端、agent重启后能复现的只有渲染出来的文本。用渲染文本的字节前缀做键检查点在进程重启、会话切换后依然可以被再次命中——文件里的 KV 数据、token 数等元信息仍然由文件头承载文件名只负责选对检查点。一次 KVC 命中是如何发生的SHA1 前缀校验三步走缓存查找入口是 ds4_kvstore_find_text_prefix整个流程可以概括为输入 → 校验 → 命中三段管道第一步枚举候选。扫描缓存目录下所有合法的 43 位哈希文件名逐条读文件头先做廉价过滤文本长度、最小 token 数默认 512、模型 ID、量化位宽2/4、上下文尺寸任何一项不匹配直接跳过。第二步SHA1 前缀比对。对新提示词取前 N 字节再算 SHA1N 为该候选检查点保存的文本长度与文件名里的 40 位摘要逐字符比较。如果新提示词恰好从某个旧检查点继续生长这里就能命中——这正是前缀命中的含义不要求整段相等只要求候选文本是新提示词的字节前缀。第三步落盘自检。真正加载时还会把文件里保存的文本重新算一次 SHA1与文件名摘要核对再做逐字节前缀匹配ds4_kvstore.c。任何一步失败——cached text hash mismatch、cached text prefix mismatch——该检查点会被标记无效甚至直接删除绝不会拿错状态的 KV 去恢复会话。写入侧同样讲究新文件先写成名称.tmp.pid临时文件全部落盘后再原子改名为最终哈希文件名避免半截文件污染缓存目录ds4_kvstore.c。三类命名策略自动缓存、继续点与 Agent 会话服务端自动缓存前缀对齐 2048 token服务端在冷提示词 prefill 到达稳定边界时保存检查点。默认会裁剪尾部 32 个 token 并对齐到 2048 token 边界ds4_kvstore.c这与后端 prefill 分块调度一致保证压缩器行收尾与冷启动全量 prefill 完全相同。继续点与锚点淘汰时谁先走磁盘超预算时按评分淘汰命中数带半衰期衰减cold / evict / shutdown 这类锚点检查点得分 ×2ds4_kvstore.c。判断一个新检查点是否覆盖某个旧的continued继续点用的还是 SHA1 前缀技巧——取新文本的前旧长度字节算摘要与旧文件名比对ds4_kvstore.c。Agent 会话SHA1(标题 ‖ 创建时间) 的稳定身份ds4-agent的会话命名策略不同会话 ID 取SHA1(title || created_at_le64)ds4_agent.c。标题取第一条用户消息创建时间在多次保存间保持不变——因此反复保存同一会话时文件名稳定而文件内的转录和 KV 载荷持续演化。系统提示词则固定存放在sysprompt.kv因名称固定加载前会比较文件内保存的文本是否一致不一致就重建覆盖。上手实践查看、恢复与清理 KVC 检查点会话文件统一存放在~/.ds4/kvcacheREADME.md。在ds4-agent交互界面里文件名中的哈希前缀就是会话句柄命令作用/list列出所有可用 SHA1 哈希会话/switch sha按哈希前缀恢复会话跳过 prompt 重建/save保存当前会话为新的 KVC 检查点/del sha//strip sha删除会话 / 剥离大体积 KV 载荷仅留文本服务端的命中与淘汰会写入日志例如kv cache hit ... keytoken-text load41.7 ms或kv cache evicted reasondisk-cache-full ... file....kv可以据此确认 SHA1 前缀缓存是否按预期工作。更多 HTTP 用法见 docs/SERVER.md。小结KVC 文件名 40 位 SHA1 十六进制 .kv目录扫描时按 43 字符形状严格过滤哈希对象是渲染文本的字节前缀而非 token 序列保证客户端可复现、跨进程可命中命中需通过摘要比对 逐字节前缀复核 模型/量化/上下文三重校验失败即弃用写入走临时文件原子改名淘汰按带半衰期的命中评分执行锚点检查点享 2 倍生存加权理解了这套SHA1 前缀即身份的命名方式你就能预判哪些请求会命中检查点、哪些会触发 prefill也让本地长会话推理的成本变得可预期。【免费下载链接】ds4DeepSeek 4 Flash and PRO local inference engine for Metal, CUDA and ROCm项目地址: https://gitcode.com/GitHub_Trending/ds4/ds4创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考