在 LLM serving 系统的性能优化里稀疏化几乎是一个必须考虑的方向。MoE 路由、ReLU 激活、注意力稀疏化、KV Cache 淘汰本质上都是在说同一个事实模型推理过程中并不是每个 token、每个隐藏维度、每个历史缓存都同等重要。SparSEEty 这个名字所指向的问题就是在这种利用稀疏性的 LLM serving 系统里如何把真正重要的 token 提取出来。这个问题表面上像是取一个最大值、查一个索引那么简单实际落地时却要同时处理 tokenizer 对齐、稀疏向量维度、注意力矩阵形状、生成阶段差异和线上开销控制。本文面向推理引擎开发者、算法工程师和想深入分析生成行为的 LLM 应用开发者围绕 SparSEEty 的定位梳理稀疏化 serving 系统中 token 提取的原理、实现方式、验证方法和生产落地要点。1. 先理解 SparSEEty 在 LLM serving 稀疏化链路中的作用1.1 稀疏化 serving 系统中token 并不是均匀等价的在传统稠密 Transformer 推理里每一个 token 都会经过几乎相同路径的计算。虽然注意力分数有高低之分但所有 token 的隐藏状态都会参与后续层的计算。到了利用稀疏性的 serving 系统里情况发生了变化一部分 token 可能只激活少数专家一部分 token 的某些隐藏维度被置为零一部分 token 在注意力计算中被显式忽略还有一部分 token 会因为 KV Cache 淘汰而被删除。这种情况下系统里实际上存在两个 token 集合一个是输入文本对应的完整 token 序列另一个是真正参与并影响了输出分布的关键 token 集合。SparSEEty 要做的就是把后面这个集合从 serving 系统的中间状态中提取出来。提取出来的结果可以继续用于三个方向判断某个 token 对生成结果的影响、分析服务端的稀疏计算是否合理、帮助缓存策略决定该保留哪些 token。如果把问题说得更直白一点普通日志记录的是生成出了哪些 tokenSparSEEty 这类组件还需要回答生成过程中哪些 token 是被系统真正看重的。这两者之间隔着一层稀疏权重、一组 mask 和一次对齐操作。1.2 提取 token 的三种典型用途第一种用途是生成质量分析。当模型输出了不符合预期的句子时仅看最终 token 很难定位问题。如果能够拿到每层注意力分数较高或激活值较大的 token就可以判断模型是否把注意力放到了错误的位置。这比单纯看 token 贡献度更接近模型内部行为。第二种用途是 serving 性能剖析。稀疏化 serving 系统经常通过减少参与计算的专家或 token 数量来提升吞吐。但是稀疏策略是否真的只丢弃了不重要的 token需要证据支撑。通过提取 token 和对应的稀疏分数可以统计不同请求中被保留 token 的分布从而评估稀疏策略是否存在偏差。第三种用途是缓存优化。KV Cache 淘汰策略需要估计每个历史 token 在未来生成中的价值。SparSEEty 提取出的重要 token 列表可以作为一种离线或在线信号帮助缓存模块决定淘汰顺序。它不是唯一信号但比单纯按位置或时间淘汰更接近注意力语义。这三种用途都有一个共同前提提取动作不能破坏 serving 原有的计算路径。也就是说SparSEEty 应当是旁路分析组件而不是侵入式修改模块。这也决定了它的实现思路通常是在 serving 系统的 hook 点或回调接口上做采集。1.3 SparSEEty 不是通用日志系统有人可能会觉得记录 token 不就是打日志吗实际差距很大。通用日志只需要记录文本、token ID 和时间戳而 SparSEEty 需要记录的是 token 与中间权重的关联关系。这个关联关系往往依赖批量计算后的矩阵比如注意力权重的形状是[batch, heads, query_len, key_len]激活掩码的形状可能跟随隐藏维度。要把这些多维矩阵压缩成一份 token 列表需要明确每个维度的语义。此外serving 系统通常使用连续批处理和动态 shape这导致不同请求的 token 长度不同同一 batch 内 token 和矩阵的对应关系也会变化。没有经过专门设计的采集逻辑很容易出现拿到了矩阵却不知道这行对应哪个 token的问题。所以 SparSEEty 的定位应当是 serving 系统与可观测性系统之间的一个语义转换层。2. 在实现之前先理清 serving 系统里的稀疏性来源2.1 MoE 路由产生的稀疏性在 MoE 架构中每一层有多个专家输入 token 只会被路由到其中的 top-k 个专家。这个路由过程天然是稀疏的。对于某个 token其他专家上的输出并不会被计算因此可以从路由权重中提取高相关 token。常见的实现是gating_logits或者routing_probs。如果 serving 系统暴露了路由概率SparSEEty 可以从路由矩阵中取出每个 token 激活的专家 ID 和对应概率。这个信息有助于发现一类常见问题是不是某些提示词方向固定导致负载都压在同一个专家上。不过要注意路由概率是每个专家一个值并不是每个 token 一个值提取时必须先确定维度含义。2.2 激活函数与注意力产生的稀疏性部分模型采用 ReLU 类激活函数隐藏状态中会出现大量零值。这种稀疏性使得模型可以用更少的计算资源完成前向过程。提取这类稀疏性时通常需要拿到隐藏状态张量按 token 维度做聚合例如计算非零元素占比或最大绝对值。注意力稀疏化则更常见。比如局部注意力只允许 token 关注固定窗口内的历史 token或使用了 top-k 注意力。此时可以从注意力权重矩阵中提取某个 token 关注度最高的若干个历史 token。这种方式得到的 token 列表通常与人类直观的关键信息比较接近也是调试 prompt 时最常看的信号。2.3 与 KV Cache 逐出策略的关系KV Cache 逐出是把部分历史 token 的 Key 和 Value 从缓存中移除目的是减少显存占用和计算量。逐出策略需要一个重要性判断。SparSEEty 提取出的重要 token 恰好可以服务这个判断过程。但有一点要特别提醒KV Cache 逐出发生在生成阶段早前层的 token 重要性可能和后续层不一致。比如一个 token 在第一层注意力中很重要到了第十二层可能已经不再重要。所以如果要把提取结果用于缓存优化最好保留按层、按生成步的信息而不是只输出一个全局 token 列表。否则缓存策略拿到的信号会丢失关键粒度。2.4 token 提取链路的基本输入为了统一处理上述几种稀疏性SparSEEty 风格的提取器至少需要四类输入tokenizer 转换后的 token ID 序列、模型中间输出的稀疏信号矩阵、当前生成步长或层数、以及请求的元信息。其中稀疏信号矩阵的形状需要根据来源区分。来自注意力形状通常为[query_len, key_len]或包含 batch 和 head 维度。来自路由形状通常为[token_len, num_experts]。来自隐藏状态形状通常为[token_len, hidden_size]。如果 serving 框架对这些矩阵做了重排或分块提取器还需要先做维度恢复。这是最容易出错的地方也是下文要实现的最小提取器里最需要验证的部分。3. 最小环境准备用 Python 搭一个可演示的提取骨架3.1 依赖选择学习环境里只需要安装最小依赖即可复现本文的提取逻辑。如果从零开始可以先准备 Python 3.10 或更高版本然后安装 PyTorch 和 NumPy。PyTorch 用于模拟张量操作NumPy 用于矩阵排序和归一化。python -m venv .venv source .venv/bin/activate pip install numpy torch如果希望直接对接现有模型可以再安装 transformers但最小案例不依赖它。这里刻意不锁定具体版本因为不同项目使用的 CUDA 版本和模型版本差异很大。落地前先确认本机 Python、PyTorch 和 NumPy 的版本兼容性。生产环境的依赖管理建议单独维护requirements-lock.txt把版本锁到具体小版本。torch这类库不建议在 serving 系统内部随意升级要等模型推理框架的兼容性验证通过后再调整。3.2 项目目录结构一个用于演示的目录结构可以这样组织sparseety-demo/ ├── sparseety/ │ ├── __init__.py │ ├── config.py │ ├── extractor.py │ └── records.py ├── examples/ │ └── run_demo.py ├── tests/ │ └── test_extractor.py └── requirements.txtsparseety包放核心提取逻辑examples放可运行示例tests放最小验证用例。这个结构在真实项目中同样适用核心提取器独立成包后可以方便地被 serving 进程或离线分析任务导入。3.3 采集数据的 JSON 约定为了让提取器不依赖具体 serving 框架可以约定一种中间表达格式。每个请求产生一条记录记录中包含 token 序列和稀疏信号矩阵的引用。{ generation_id: gen_20250101_001, prompt_tokens: [101, 2001, 3958, 2039, 102], generated_tokens: [2076, 2025, 2001, 2030, 102], layer: 6, score_type: attention, scores_path: /data/scores/gen_20250101_001_layer6.npy }把矩阵保存为独立文件而不是序列化进 JSON是为了避免大数组导致 JSON 膨胀。SparSEEty 风格的提取链路适合先用这份约定做离线实验等确认提取逻辑正确后再把scores_path替换成 serving 进程内的内存张量。4. 设计 SparSEEty 风格 token 提取器从中间状态到 token 列表4.1 提取器的输入与输出先定义几个数据类让提取逻辑的边界更清晰。TokenRecord表示一个被提取出来的 token# sparseety/records.py from dataclasses import dataclass from typing import Optional dataclass class TokenRecord: token_id: int score: float layer: int rank: int token_type: str important text: Optional[str] None def to_dict(self): return { token_id: self.token_id, score: self.score, layer: self.layer, rank: self.rank, token_type: self.token_type, text: self.text, }ExtractionConfig定义提取参数# sparseety/config.py from dataclasses import dataclass, field from typing import Optional dataclass class ExtractionConfig: top_k: int 16 min_score: float 0.05 layer: Optional[int] None score_type: str attention aggregate_heads: bool True def validate(self): if self.top_k 0: raise ValueError(top_k must be positive) if not 0.0 self.min_score 1.0: raise ValueError(min_score should be in [0, 1)) if self.score_type not in {attention, route, activation}: raise ValueError(funsupported score_type: {self.score_type})这里的关键是score_type。它决定了输入矩阵的语义也决定了后续维度对齐方式。不同 score_type 不能混用否则提取结果没有可比性。4.2 核心提取实现下面的extract_tokens函数是一个可运行的演示实现。它接受 token ID 列表和分数矩阵输出按分数降序排列的 token 记录。为了简化默认按注意力权重处理并聚合多头。# sparseety/extractor.py from typing import List, Tuple import numpy as np from .config import ExtractionConfig from .records import TokenRecord def _aggregate_to_token_level(scores: np.ndarray, token_len: int) - np.ndarray: 将多维注意力分数聚合到 token 级别。 输入形状可能为 [heads, query_len, key_len] 或 [query_len, key_len]。 这里假定最后一个维度是 key_len倒数第二个维度是 query_len。 if scores.ndim 2: aggregated scores elif scores.ndim 3: aggregated scores.mean(axis0) elif scores.ndim 4: # 如果出现 batch 维度先去掉 batch 再聚合 head aggregated scores[0].mean(axis0) else: raise ValueError(funsupported scores shape: {scores.shape}) if aggregated.shape[-1] ! token_len: raise ValueError( flast dim {aggregated.shape[-1]} does not match token_len {token_len} ) return aggregated def extract_tokens( token_ids: List[int], scores: np.ndarray, config: ExtractionConfig, decode_fnNone, ) - List[TokenRecord]: config.validate() token_len len(token_ids) if scores.shape[0] token_len or scores.shape[-1] token_len: aggregated _aggregate_to_token_level(scores, token_len) else: raise ValueError( fcannot align scores shape {scores.shape} with token_len {token_len} ) # 对最后一维做 L2 归一化让分数更具可比性 norm np.linalg.norm(aggregated, axis-1, keepdimsTrue) norm_scores aggregated / (norm 1e-8) if config.layer is not None: # 当配置了固定 layer 时只从对应层提取 if norm_scores.ndim 1: # 这里忽略 batch 维度只取第一个 layer_scores norm_scores[config.layer] if norm_scores.ndim 2 else norm_scores else: layer_scores norm_scores aligned layer_scores else: aligned norm_scores # 将任意维度都压缩成一维后进行排序 flat_scores np.asarray(aligned).reshape(-1) if len(flat_scores) ! token_len: raise ValueError(internal score length mismatch after aggregation) top_indices np.argsort(flat_scores)[::-1][: config.top_k] records [] for rank, idx in enumerate(top_indices): score float(flat_scores[idx]) if score config.min_score: continue text None if decode_fn is not None: try: text decode_fn([token_ids[idx]]) except Exception: text None records.append( TokenRecord( token_idint(token_ids[idx]), scorescore, layerconfig.layer if config.layer is not None else 0, rankrank, token_typeimportant, texttext, ) ) return records这个实现有几个值得注意的地方。第一函数假定scores的最后一个维度与token_len对齐。这是最常见的注意力矩阵布局。真实 serving 系统里如果框架返回的是[sequence_len, hidden_size]就需要额外加一个映射分支避免盲目取平均。第二config.layer参数在实现里只用于给结果打标记和选层实际使用时如果没有层维度这一参数的语义会模糊。更好的做法是在调用前先确认矩阵确实包含层信息再传入该参数。第三decode_fn用于把 token ID 转回文本。它只是一个回调不引入 tokenizer 依赖。这样在离线脚本里用tokenizer.decode在线服务里用bytearray解析都可以。4.3 提取结果的结构化输出提取结果不能只给出一个 token 列表还需要同时给出分数、层号、排序和文本。这样的结构便于下游使用。按层保存可以分析不同层关注的 token 是否一致。按 rank 保存能看出系统对某个 token 的重视程度排序。携带 score能判断 top-1 和 top-2 之间是否差距明显。携带 text便于人工日志检索。输出时可以使用to_dict()转成 JSON 行。例如{token_id: 2001, score: 0.731, layer: 6, rank: 0, token_type: important, text: the}这种输出可以直接写入对象存储或消息队列供后续分析任务消费。5. 跑通一个小例子如何验证提取结果可靠5.1 构造模拟 serving 中间状态为了验证提取器逻辑先造一组与真实情况近似的输入。假定有一句 prompt 被 tokenizer 切成 5 个 token服务端在第 6 层给出注意力分数矩阵形状为[4, 5, 5]表示 4 个注意力头。# examples/run_demo.py import numpy as np from sparseety.config import ExtractionConfig from sparseety.extractor import extract_tokens token_ids [101, 2001, 3958, 2039, 102] rng np.random.default_rng(42) scores rng.random((4, 5, 5)) config ExtractionConfig(top_k3, min_score0.2, layer6, score_typeattention) records extract_tokens( token_idstoken_ids, scoresscores, configconfig, decode_fnlambda ids: [tok] * len(ids), ) for r in records: print(r.to_dict())运行上述示例后预期输出类似{token_id: 2039, score: 0.5123, layer: 6, rank: 0, token_type: important, text: tok} {token_id: 2001, score: 0.4489, layer: 6, rank: 1, token_type: important, text: tok} {token_id: 3958, score: 0.3977, layer: 6, rank: 2, token_type: important, text: tok}由于随机种子固定结果可以复现。如果运行后出现了维度不匹配说明_aggregate_to_token_level对形状的处理与预期不一致。这个问题正好引出验证提取器可靠性的核心方法先喂固定形状再喂真实 shape最后再喂异常 shape。5.2 检查点至少验证三个维度验证提取器并非只看能否运行。可靠性的判断标准至少有三个维度。第一维度对齐正确。矩阵的最后一个维度必须等于 token 数。如果 serving 系统给出的矩阵是[heads, key_len, query_len]提取前必须先转置。忽视这一点是最常见的错误。第二过滤逻辑正确。当min_score高于某些 token 的分数时这些 token 应该被过滤。可以通过构造全零矩阵来验证正常情况下全部分数归一化后会接近 0结果列表应该为空。第三rank 连续且可解释。top-1 的分数必须大于 top-2否则排序逻辑有误。对于 top-k 输出可以写一个简单断言scores_in_order [r.score for r in records] assert scores_in_order sorted(scores_in_order, reverseTrue)这个断言应放入单元测试防止后续修改提取器时引入回归。5.3 边界分支验证除了正常输入还需要验证以下分支。输入长度与 score 最后维度不一致时应抛出明确异常。top_k大于 token 总数时提取结果应少于等于 token 总数。decode_fn抛出异常时不应影响主流程。scores为全零矩阵且min_score大于 0 时结果为空。这些边界分支决定了线上遇到脏数据时提取器是优雅跳过还是直接拖垮整个分析任务。生产环境尤其要保证采集侧失败不影响 serving 主线程。6. 关键参数说明与在线离线差异6.1 参数速查表ExtractionConfig里的参数看似简单实际决定整个提取结果的意义。下面用一个速查表说明参数含义和选择建议。参数名默认值含义调小影响调大影响推荐场景top_k16每个请求最多提取多少 token结果更少噪声更少但可能漏掉关键 token结果更多覆盖更全但分析成本升高质量分析用 16 到 32缓存策略用 4 到 8min_score0.05分数低于该值的 token 被过滤保留更多低分 token过滤更严格结果更精炼注意力分数不稳定时调高到 0.1 以上layerNone只提取指定层的 token不限制层时结果跨层混合固定层后结果更一致观察某一层行为时使用score_typeattention分数来源类型只能取对应矩阵不匹配时会报错按信号来源选择aggregate_headsTrue是否把多头分数平均保留 head 维度会得到更细粒度但输出更大聚合后结果更简洁默认开启异常分析时可关闭6.2 top_k 与 min_score 怎么配合top_k和min_score是两道并联过滤条件。只有同时满足两个条件的 token 才会被输出。比如 top_k5、min_score0.5 时即使排序前五的 token 中第四个分数是 0.4它也不会出现在结果里。实际项目里多数情况先调大 top_k 确认候选范围再根据分数分布确定 min_score。不能只看 top_k因为如果 serving 系统对分数做了温度缩放分数整体会变高或变低固定阈值可能失效。建议先在离线数据集上跑一遍分数分布再在 25%、50%、75% 分位附近选阈值。6.3 在线提取要额外考虑什么上面的示例适合离线分析。线上 serving 进程里跑提取器时额外成本不能忽略。首先是内存。注意力矩阵通常很大尤其是长文本场景。如果每个请求都保存完整矩阵再提取可能比推理本身还占内存。推荐做法是在算子内直接对最后一维做聚合不落完整矩阵。其次是耗时。argsort在 CPU 上对 1 万维向量做排序并不慢但如果每个请求每个层都做总量会放大很多。线上建议只对最大注意力权重所在层提取或者按概率采样请求。再次是线程安全。serving 进程通常是多线程或异步并发处理请求提取器必须是无状态函数不能使用类级共享缓冲区。上面示例中的extract_tokens是无状态函数可以安全用于并发场景。7. 常见坑与排查路径7.1 提取结果为空现象调用extract_tokens后返回空列表。常见原因有三个。第一min_score设置过高所有 token 都被过滤。第二scores输入全零或全部为负数归一化后都低于阈值。第三维度对齐逻辑出错导致取到了错误的分数切片。排查顺序先用一个只含一个局部最大值的矩阵测试打印flat_scores的 min、max 和 mean确认分数分布再逐步调低min_score到 0观察是否开始出现结果。如果降到 0 仍然为空那问题在维度对齐而不是过滤参数。7.2 token ID 与文本对不上现象提取出的token_id通过 tokenizer decode 后得到明显不合理的文本片段。常见原因是 token 序列的生成顺序与分数矩阵不一致。有些 serving 框架会 trim 掉特殊 token比如 CLS、SEP、BOS、EOS但分数矩阵仍保留原始长度。这时直接按索引取 token 会整体错位。检查方式打印 token 序列的文本和长度再打印分数矩阵的 shape。如果长度不一致一般需要先对 serving 的输出执行token_ids token_ids[:matrix_len]或token_ids token_ids[1:]。预防方法是让 serving 在输出矩阵时一起输出 token 偏移量。7.3 在线埋点后服务吞吐下降现象接入提取后服务 QPS 明显下降P99 延迟升高。原因通常是采集逻辑做了同步操作比如在每个请求路径里写对象存储、执行 decode、或对完整矩阵做保存。这些操作不属于推理请求本身却占用了 CPU 和 IO。处理方案把提取结果写入内存队列由后台线程批量异步上报限制采样比例比如只对 1% 请求提取decode 操作放在消费端而不是请求端。同时最好在测试环境压测对比埋点前后的 QPS量化损耗后再上线。7.4 同一 prompt 多次请求提取结果不一致现象相同输入在同一服务版本下两次生成的 token 列表不同。原因可能是采样策略引入了随机性也可能是模型本身没有固定 seed。SparSEEty 提取的是当前这次生成的中间状态不是所有可能的生成结果。如果只关注模型对 prompt 的注意力分布可以把采样关闭使用 greedy decoding 重新跑一次再提取。另外如果 serving 系统在长文本场景下使用 sliding window 或 chunked attention那么不同请求即便 prompt 相同也可能因为 KV Cache 分布不同导致注意力分数不同。这种情况需要同时记录请求上下文长度和缓存状态才能判断提取差异是合理波动还是异常。8. 生产落地建议与可复用检查清单8.1 不要全量上报先采样提取器在生产环境中最大的风险不是算法错误而是资源开销。与其每个请求都做完整提取不如先设置一个采样率比如 5% 的请求。采样时通过写入请求 ID 的 hash 值来决定是否提取这样同一请求在不同链路节点会得到一致判断不会出现同一请求只提取了一半数据的问题。示例def should_sample(request_id: str, rate: float 0.05) - bool: if not request_id: return False digest int(hashlib.md5(request_id.encode()).hexdigest()[:8], 16) return digest % 100 rate * 100采样逻辑要和报表系统对接否则看数据时无法还原采样分母。8.2 把提取结果接入监控体系提取结果不只是离线分析用的还可以算成一系列服务指标。例如重要 token 的 top-1 命中率。每层提取出来的 token 重叠度。被过滤 token 的比例。提取耗时 p50、p99。这些指标可以接入 Prometheus、Graphite 或公司内部监控系统。每次请求提取完成后计数服务端再按时间聚合。这样当注意力分布发生异常偏移时监控曲线可以提前暴露问题。8.3 保留可回放的原始记录提取结果的抽象层数越高越难回溯问题。建议在离线分析场景保留一份最小原始记录token_ids、scores_path、generation_id、config。这样发现任何异常后都可以重新加载原始矩阵复现问题。在线场景不适合保留完整矩阵但可以保留一个经过聚合的中间文件比如按层聚合后的 token 分数数组。这个文件比原始矩阵小很多但足够支持大部分重放分析。8.4 落地前检查清单下面是可直接复制使用的检查清单提取器是否接受 serving 框架实际输出的矩阵 shape而不是测试环境伪造的 shapetoken 序列长度与矩阵长度是否严格对齐是否处理了特殊 token 的偏移在线提取是否放在异步链路中是否设置了采样率提取结果是否包含请求 ID、层号、分数、rank 和文本是否对提取耗时和内存做了压测是否验证过全零矩阵、空序列和超大 sequence 的边界行为是否能从监控指标中看到提取覆盖率是否有回放原始数据的路径这份清单可以贴到服务上线 MR 的检查项里。任何一项不满足都可能在上线后变成排障成本。9. 扩展方向与下一步实践SparSEEty 这个问题域并不只是写一个提取函数。后续真正有价值的方向是把它和 serving 系统的调度策略、缓存策略、可观测体系结合起来。例如可以用提取出的 token 热度动态调整 speculative decoding 的草稿长度也可以在离线任务里用提取结果训练一个轻量模型预测哪些 token 在未来生成中可能被再次访问从而辅助 KV Cache 逐出。对于刚接触这个方向的新手建议不要一上来就对接大模型 serving 框架。先用手里的 tokenizer 和一个小模型打印出每层注意力分数把本文的提取器跑通再尝试接入本地推理框架。理解维度对齐和矩阵语义比急着看到漂亮的可视化结果更重要。如果要在实际项目里落地 SparSEEty 风格组件优先选择只读的 hook 点避免修改 serving 核心代码。提取结果先做离线存储等确认数据质量和监控指标稳定后再逐步参与在线策略。整个过程最该保留的是一份可回放的原始记录因为速度优化、缓存淘汰和异常分析最终都依赖它。