一个 token 的缓存，
如何通向
一份共享的记忆？

设想一个会读代码、调用终端并修复错误的助手。第一次给它项目资料，第二次带回测试结果，第三次继续修改。同一份工具说明、项目约定和历史对话，会反复出现在请求中。

因此，看待 Flash 类模型，一个有用的问题是：在达到同样验收标准的前提下，完整任务花了多少钱、多久，失败后还要重试几次？ 更低的输入处理成本可能改变这个答案。

先用大白话说：模型读过一个位置后，会留下方便后续位置查询的信息。注意力机制里，K（Key）参与决定“关注哪个位置”，V（Value）提供被读出的内容；Q（Query）表示当前这次查询。 它们都是数字向量，不是原文、回答摘要或普通数据库记录。[1]

一次调用通常包含两种工作：Prefill 是处理已经给定的一长段输入，通常能批量、并行地计算许多位置；Decode 是在通常的自回归生成中，根据前面的结果继续产生下一个 token。缓存让后续计算可以直接使用已生成的 K/V，免去反复编码旧输入。[1]

这里的“每个 token 有对应状态”，描述的是逻辑上的对应关系。它不意味着 Prefill 要把整段输入逐 token 串行运行，也不意味着每个 token 都进行一次独立的 GPU 内存分配。

把这句话作为复用的目标没有问题。但服务端需要在重新计算 KV 之前，就判断能否复用。常见方法是给输入前缀建立可快速查找的身份，例如前缀树或 hash，再去找对应的缓存状态。[2]

对于固定权重、相同输入表示、位置与注意力规则的因果模型，相同前缀为精确复用提供了一个容易检验的充分条件。实际系统还要考虑模型或适配器身份、多模态内容，以及租户隔离等条件。[3]

充分条件不等于数学上唯一可能的条件。 某些不同输入也可能碰巧产生相同的中间值，特殊模型还可能有更强的状态等价关系。但普通前缀缓存无需证明所有等价情形；它选择一种容易保证正确的查找规则。

一次请求可以只复用输入的前半段。假设这次总共输入 110,000 个 token，其中 100,000 个来自已有缓存，剩余 10,000 个需要重新处理，那么按 token 统计的命中率为：

“发生过任意命中的请求占比”和“全部输入 token 中命中的占比”是两个不同指标。一百次请求每次只命中一个 token，前者也能是 100%；它未必省下了多少计算。

这也解释了一个常见的工程建议：在不破坏任务语义的前提下，把稳定资料尽量放在前面，把时间戳和本轮问题等变化内容放在后面。一个很早出现的动态字段，可能让后面很长的相同文本无法直接复用。[4]

比较“我 喜欢 苹果”和“我 讨厌 苹果”。末尾 token 相同、位置相同，但模型处理“苹果”时读到的历史不同。前面注意力层得到的表示，会继续成为后面层计算 K/V 的输入。

因此，仅用 token_id 或 (token_id, position) 作为通用的高层 KV 缓存键，会把不同的上下文混为一谈。需要把此前的条件也区分开。

但这里还没有推出“缓存键必须把整段前缀明文存进去”。那正是下一个问题。

对。你给出的 parent hash 方案成立。 前缀身份完全可以递归表示。令 h₀ 编码初始身份条件，对每个 token 计算：

vLLM 的 hash_block_tokens 就把父块 hash、当前块 token 与附加身份信息一起交给 hash 函数。这与“parent_hash + current_token”的思想一致，只是它通常以块为单位。[3]

你提出的 hash map 可以指向真实 KV。这个想法并未要求“用几十字节替代全部模型状态”。关键边界是：压短标识很容易；要让模型只靠一个小状态继续工作，还需要另外的计算结构。

把 KV_B 与 Hash(A,B) 直接写成等号，会混淆二者。清楚的写法是 cache[key] → KV 或恢复状态的引用。

可以这样做。 SGLang 的公开 RadixCache 代码支持 page_size = 1 的匹配分支；在普通单 token 键模式下，前缀匹配可以精确到一个 token。这足以说明：单 token 级索引没有普遍的理论障碍。[5]

粗一点的粒度通常是在做成本权衡。把一段连续的 K/V 放进同一个块，索引、引用计数、传输和淘汰操作就可以成组处理。在只复用完整块的简化方案中，公共前缀长为 p、块大小为 b 时：

vLLM 的前缀缓存文档描述了一种完整块复用方案。b = 16 时，999 个相同 token 只能按该规则复用到 992，多算 7 个，换来更少的目录项。[2]

但不能进一步把“单 token 索引”想成“每个 token 调一次 GPU 内存分配”。物理内存池、匹配粒度与树节点表示可以分别设计；压缩前缀树也不必给每个 token 分配一个独立的树节点。更小的物理页甚至能减少尾部空洞，代价需要按实际系统测量。

大王：短键省下了重复保存整段前缀的空间，但链式构造仍有前后依赖。vLLM 的 hash_block_tokens 接受 parent_block_hash；新块的键需要先知道父块的键。对一条首次建立索引、长度为 N 的序列，块大小为 b 时，大约有 N/b 次依次相连的键构造。把 b 从 16 改为 1，就把这条链上的步骤数扩大到约 16 倍。[3]

这里比较的是一个分叉边界的额外 token 数与整条新路径的索引工作量。不能据此直接宣布“常数收益一定抵不过线性代价”：一个 token 的注意力成本也可能随历史长度增加，缓存还可能被许多请求重复利用。

还有两个限定：哈希仍需读取当前块的 token，扫描输入的总工作通常仍是 O(N)；已有会话可以从现成父 hash 增量续算，新增索引主要对应 ΔN。压缩树、批处理和不同哈希方案也可能有不同实现。因此，应当把串行链视作这类实现的具体成本，而非所有单 token 缓存的必然缺陷。

更合适的中文是缓存边界或恢复点。“截断点”容易让人误会后面的内容不再输入给模型。

把 cache_control 放在某个内容块上，表达的是：从整个有效提示的开头，到这个块结束的前缀，成为候选缓存范围。Claude 文档规定相关顺序为 tools → system → messages。[4]

底层 K/V 的产生并不等待这个标记。API 标记决定服务层怎样保存、查找和计费，不能拿来推断 GPU 何时开始拥有 K/V。

多个缓存点可以对应不同稳定程度：工具和系统指令几乎不变，项目资料偶尔改变，对话不断追加。较长的入口失效时，较短的入口仍可能有效。但它们都表示“从开头到某处”，不会把后面相同的文本自动变成独立于前文的缓存片段。

关键要看请求怎样变化。Claude 当前文档支持顶层 cache_control，会把缓存点放到最后一个可缓存内容块。对于不断在旧对话后追加内容的请求，这很方便。[4]

第二种情况下，把显式边界放在稳定资料 A 的末尾通常更合适。自动缓存不会替你发现所有稳定片段并自动建立入口。 当前规则的回看范围也有限，最多检查每个边界附近 20 个内容块位置，查找的是先前真正写入的入口。[4]

response = client.messages.create(
    model=model_id,
    max_tokens=1024,
    cache_control={"type": "ephemeral"},
    system=stable_system,
    messages=growing_history,
)

response = client.messages.create(
    model=model_id,
    max_tokens=1024,
    system=stable_system,
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": stable_document,
             "cache_control": {"type": "ephemeral"}},
            {"type": "text", "text": current_question},
        ],
    }],
)

代码展示请求结构；client、model_id 和内容变量需在应用中提供。前缀还需达到相应模型的最小缓存长度；缓存存在有效期，当前文档提供 5 分钟和 1 小时选项。调用方式、限制与支持范围以所用平台文档为准。

时间从哪里开始算？

Claude 当前文档把 TTL 的起点放在写入或读取缓存的请求开始时。例如一个响应流式输出了 4 分钟，默认 5 分钟 TTL 大约只剩 1 分钟；后续若还要等工具执行，可能来不及复用同一入口。[4]

为什么没有报错，usage 却全是 0？

缓存前缀必须达到模型的最小长度。当前官方文档给出的部分门槛如下；低于门槛仍会正常处理请求，不会因为未缓存而报错。[4]

记录日期：2026 年 9 月 10 日。门槛看被标记的可缓存前缀长度，不只看整个请求是否够长。若 cache_creation_input_tokens 和 cache_read_input_tokens 都为 0，可先查这个条件；平台适配与模型版本仍应对照对应文档。

DeepSeek 的上下文缓存文档公开了三类持久化位置：请求输入和输出的结束位置、多个请求的共同前缀、长输入或输出中的固定 token 间隔。 后续请求要完整匹配一个已经保存的缓存前缀单元，才能复用它。[6]

用一个抽象式表达就很清楚。设两次请求客观共有的前缀长度为 p，已经保存且可恢复的边界集合为 E。在这一完整单元规则下，最长的直接恢复位置可以写成：

请求边界抓住自然的继续点；公共前缀检测补上真实出现的复用位置；固定间隔为长序列提供额外覆盖。它们都在增加“可以找回并使用的状态”，不会让两个原本不同的前缀 变成相同。

上图是服务行为的解释。DeepSeek 未在这份 API 文档中公开完整缓存目录的数据结构，不能据此认定服务端一定采用某种 radix tree、hash 链或特定 checkpoint 间距。

大王：多保留一个入口，会占用索引、写入带宽、存储空间，某些模型还需要额外的恢复快照。这就需要决定“哪些状态值得占着资源”，也就是缓存准入策略（cache admission policy）。

公共前缀被重复使用，是比“它曾经出现过”更强的复用信号。资源有限时，优先保留这类前缀，可以减少只用一次的内容对热缓存的挤占。DeepSeek 文档也提示缓存构建需要数秒，因此刚完成计算与持久化入口立即可用之间，还可能存在时间差。[6]

“再次使用后更值得保存”与 cache-on-second-access 的思想相通。DeepSeek 同时还保存请求边界和固定间隔入口，不能把整个系统概括为严格的二次访问缓存，也不能声称所有前缀都必须等重复两次才落盘。

这是比“索引太多”更深入的一问。对于保存了每层完整历史 K/V 的标准实现，这个想法可以成立： 只要数据还在，取出前 A 个位置即可；是否能找到相应入口，是另一层问题。

但很多长上下文架构会主动丢掉旧的局部状态。DeepSeek 文档也明确指出，滑动窗口注意力使它的缓存存储与匹配规则发生变化。[6]

所以，“存在 A+B 的压缩恢复状态” 并不自动推出 “A 的全部恢复状态仍可被切片拿出”。模型采用什么记忆结构，直接影响缓存系统能提供多细的恢复边界。

同一个前缀，可能因为缓存未写完、已经被淘汰、过期或隔离条件不同而无法命中。DeepSeek 当前文档描述的是默认开启的硬盘缓存，并说明构建需要时间、采用尽力而为策略，不承诺 100% 命中。[6]

上面是一条有条件的因果链，并非产品命中率提升的实测结论。缓存小了，可以选择多保留历史，也可以把资源拿去服务更多并发；最终怎么分配，取决于系统策略。

到这里，hash 已经完成了它擅长的事：快速识别身份。下一个问题开始碰模型架构——为什么那份需要保存的状态会那么大？

普通的全历史 Transformer 中，各层使用各自的中间表示产生 K/V。每一层都要记住整个历史，于是序列越长、层数越多，缓存越大。

这个公式只描述标准全历史 K/V 的一个简化形状。它也让几种优化的位置变得直观：减少 KV 头数，减少每个状态的维度，降低数值精度，减少保留的位置，或减少重复保存长期 KV 的层数。YOCO 主要从最后一项切入。[7]

第六项要通过架构与训练来实现。普通模型中的 K 和 V 可以不同，无法在服务端把两份向量直接并成一份而保持原计算。第 18 问会用一个带位置旋转的共享方案，把这个边界讲清楚。

YOCO 的全称是 You Only Cache Once。原论文把模型分成前半的 Self-decoder 和后半的 Cross-decoder：前半先得到上下文表示，由它生成共享的全局 K/V；后半各层通过各自的查询读取这份记忆。[7]

“Once”说的是全局历史 K/V 只保留一套，供多个后半层复用。它不表示一个 token 在整个模型里只计算一次，不表示模型跨请求只运行一次，也不表示前半部分完全没有状态。原论文专门在脚注中说明了后一点。[7]

因此 YOCO 也没有把整个百万 token 历史压成一个固定长度 hash。它减少的是长期记忆在层与层之间的重复保存。越长的上下文，固定大小的局部窗口所占比例越小。

两部分仍按因果顺序运行：当前位置只能使用允许看到的历史，后续新 token 还会再经过前半和后半。这里的“前半像编码器”不意味着它可以双向读到未来。[7]

在普通 Transformer 中，历史位置必须经过前面的层，才能生成后面每层要使用的 K/V。即便你不需要那些历史位置的输出，也很难跳过这些计算。

YOCO 改变了依赖关系：后半各层需要的历史 K/V 直接由前半部分输出提供。于是，已经给定的历史位置不必再经过整个后半部分，只为建立未来要用的缓存。公开实现中，CrossDecoder.forward 会先生成并追加共享 K/V，再根据 skip_cross_decoder 决定是否继续跑后半层。[8]

这个设计要按位置理解。若提示词有 N 个位置，要得到第一个新 token 的概率，仍需用最后一个输入位置的表示运行后半层。能够省去的是许多此前历史位置的后半计算。

此外，前半部分采用高效的局部或递归结构，也会降低长输入处理成本。论文中出现的倍数，依赖于对照模型、序列长度与实现；不能把它们直接贴到另一个产品上。

它可以具体展开为：哪些层生产历史，哪些层共享历史，哪些状态仍归各层自己保留。 按技术摘录的配置，40 层分为 0–19 与 20–39 两部分；global KV 源为 [2, 8, 14, 20]，前两层只保留滑窗。[9]

摘录把后半段的 global KV 联系到前半段的最终表示，同时保留了各层自身的局部滑窗状态。这与 YOCO 的跨层记忆共享有明确的结构联系；前半部分内部也可以分组共享。比较模型时，应看实际的依赖边，而不只看“Encoder / Decoder”两个名字。[7][9]

先明确计算单位：每增加一个原始输入 token，需要多保留多少 global KV。 这与“整条序列共占多少显存”不同。按给定的量化和共享条件，每个压缩位置需要 356 字节。[9]

这里的尺度，是把低精度数值还原到正确大小所需的系数。FP4 的每个数值占 0.5 字节，但不能只乘 0.5 就结束：main KV 的尺度贡献 32 字节，indexer K 的尺度再贡献 4 字节。报告摘录将它们分别称为 E4M3 与 UE8M0 尺度。[9]

再看局部窗口：按 40 层、每层 128 个位置、512 维且每数值 1 字节的 FP8 载体估算，SWA 的数值本体为：

K 和 V 描述两种用途：一个参与匹配，一个参与汇总。模型可以被设计成让同一个存储向量承担这两种用途；此时就少保存一份数值。技术摘录说 V4.1 的 kv_shared 同时用于匹配与输出乘法，账本按这一条件计算。[9]

旋转位置编码（RoPE）会按 token 位置旋转一部分向量，使匹配能表达相对位置。如果作为 Key 的旋转向量同时也是 Value，那么汇总后的输出也带有这些旋转。对查询位置 i 的输出乘 R_i⁻¹，可以把它表达在当前位置的坐标系里。

同理，num_key_value_heads = 1 本身只说明 KV 头少，不能单独证明 K 与 V 是同一个向量。是否共用，需要继续看实际投影、张量引用和两个矩阵乘法的输入。

分成两个问题看：不保存的局部状态怎么补回来；补回来的状态需要多精确。 单层只看最近 W 个位置，多层叠加后的理论依赖范围通常会扩大。对窗口包含当前位置的简单 L 层堆叠，单个输出位置的感受野可达到 1 + L(W−1)。

技术摘录将 V4.1 的 SWA Bounded Replay 描述为：为避免保存各层 SWA 状态，只重放一个窗口来近似恢复。摘录同时指出，报告承认实际有效依赖可能短于理论感受野，并将这类恢复列为需要进一步刻画的鲁棒性边界。[9]

大王：需要。YOCO 的可见参考实现有 skip_cross_decoder，可以沿共享 KV 的依赖关系跳过许多历史位置的后半计算。V4.1 的技术摘录则区分了两条路径：

因此，从“架构允许短路径”走到“服务端实际更快”，还要经过调度实现与测量。最后一个输入位置需要产生首个新 token 的概率；逐位置打分或训练任务也不能直接套用只生成下一个 token 的跳过方式。

还差一个决定速度的问题：每生成一个 token，究竟需要触碰多少历史状态？ 把所有 KV 从 10 GB 压到 1 GB 会减少容量压力；如果仍在许多层反复扫描完整历史，读取和匹配依然会很贵。

根据技术摘录，layer 20 先建立候选池；后面的若干 indexer 只在这个池内挑选 top-512，另一些层复用选择结果。这样就能把“每层都查一遍全历史”的重复工作减掉。[9]

稀疏读取还有能力取舍：相关位置如果没有进入候选池，后续精排通常无法把它凭空找回来。因此需要同时看候选召回、答案质量与真实延迟。共享 KV 解决“存几份”，共享候选解决“找几遍”，稀疏读取解决“每次读多少”。

Engram 给模型增加一种“遇到某个局部组合，就读取已学习向量”的能力。官方公开实现先把 n-gram 映射到若干哈希地址，再取嵌入向量，随后通过投影、由当前隐藏状态控制的门以及局部融合，注入主干网络。[10]

这里的 n-gram，指连续 n 个 token 的局部组合。固定模型和表大小后，每个位置只读取有限数量的表项；地址仅依赖局部 token，因此可以在相应深层计算发生前准备，并适合预取。官方论文还讨论了将大型表放在主机内存中的系统安排。[11]

“把每个 n-gram 都存下来”也需要限定：哈希表容量有限，不是给所有可能组合各建一个无碰撞的槽。不同组合可以落到相同地址，多头哈希和训练共同处理这种压缩。与精确 KV 缓存尽量避免身份误匹配的目标相比，这里的碰撞本身属于表示设计要面对的条件。[10]

V4.1 技术摘录列出在层号 1、14 使用 2/3/4-gram 记忆。这描述的是特定装配；原始 Engram 演示代码有另一组配置。无论具体装在哪层，它都不会绕过“上下文不同，高层 KV 可能不同”的事实：静态表项与动态隐藏状态融合后，仍能产生不同结果。[9][10]

于是，模型里的“记忆”至少包含两类东西：过去这个请求算出了什么，以及训练阶段为常见模式学到了什么。一个由缓存系统管理生命周期，一个通常跟随模型权重；两者可以同时存在。

先画出每次请求的真实输入顺序，标出最早变化的位置。对于追加式对话，尽量保留已有内容的原样顺序；对固定资料的不同问题，把稳定资料与动态后缀分开，并根据服务规则放置缓存边界。

随后看实际 usage，区分“读缓存”“写缓存”和“普通输入”。不要把供应商同名的 input_tokens 想当然当作同一种总量。

read  = usage.cache_read_input_tokens
write = usage.cache_creation_input_tokens
fresh = usage.input_tokens

total_input = read + write + fresh
hit_ratio = read / total_input if total_input else 0

Claude 文档的这个 input_tokens 口径不包含上述读缓存和写缓存部分。服务端工具或多轮聚合还应对照相应 usage 结构。[4]

hit  = usage["prompt_cache_hit_tokens"]
miss = usage["prompt_cache_miss_tokens"]

hit_ratio = hit / (hit + miss) if hit + miss else 0

字段定义来自 DeepSeek 上下文缓存文档。批量统计时，用“全部命中 token 之和 / 全部输入 token 之和”；不同长度请求的命中百分比不宜直接做简单平均。[6]

再把费用和验收放回同一张表。如果仅作一个忽略写入溢价的输入价格模型，输入量为 N、命中率为 h，那么：

更有价值的最终指标是：评测期间的总费用 ÷ 通过验收的任务数，同时报告成功率、任务类型，以及耗时的中位数和较慢尾部。冷缓存与已预热的缓存应分开测，避免把不同条件混成一个漂亮平均值。

对于带近似恢复或稀疏读取的方案，评估还应覆盖恢复前后的一致性、候选遗漏带来的任务失败，以及长会话累积表现。优化目标始终是通过同一套验收；节省的字节和扫描次数，需要最终落到任务成本与完成时间上。