FlashTrace是一款面向推理语言模型的归因分析工具，能够追踪生成答案与提示词Token之间的关联，支持Python API、CLI和HTML热力图导出，为LLM可解释性研究提供了实用工具。

FlashTrace：推理语言模型的多Token归因分析工具\n\n随着大型语言模型（LLM）推理能力的不断增强，理解模型"为什么生成这个答案"变得越来越重要。传统归因方法通常只关注单个token的归因，但在推理模型（Reasoning Models）中，答案往往由一长串中间推理步骤共同决定。FlashTrace正是为解决这一问题而设计的——它提供了高效的多token归因能力，让研究者能够追踪生成答案与提示词token之间的深层关联。\n\n## 项目背景：推理模型的可解释性挑战\n\n现代推理模型（如Qwen3、Llama系列）在回答复杂问题时，会生成包含大量中间推理步骤的长文本。这些步骤共同导向最终答案，但传统归因工具只能分析单个token的归因，无法捕捉"答案span"与提示词之间的整体关系。\n\nFlashTrace的核心洞察是：研究者通常关心的是一段生成文本（如最终答案或某段推理过程）与提示词中哪些部分最相关。这需要一种能够处理"多token span"的归因方法，而非传统的单token归因。\n\n## 核心功能与特性\n\nFlashTrace提供了完整的归因分析工作流：\n\n### 多Token归因追踪\n\nFlashTrace可以针对选定的生成文本span（如最终答案或某段推理）计算其与提示词各token的归因分数。这不同于传统方法只能分析单个token，FlashTrace支持任意长度的span分析。\n\n### Top-K提示词Token排名\n\n系统会返回对生成span贡献最大的前K个提示词token，每个token附带归因分数。这让研究者能够快速定位"关键证据"——哪些提示词内容对答案产生了最大影响。\n\n### JSON格式导出\n\n归因结果可以导出为结构化JSON，包含完整的token列表、分数、生成token序列等信息。这便于下游分析工具集成，支持批量处理和自动化分析。\n\n### 独立HTML热力图\n\nFlashTrace可以生成独立的HTML文件，以热力图形式可视化归因结果。热力图直接嵌入在HTML中，无需外部依赖，可以本地打开或作为分析结果分享。\n\n### 多跳归因（Per-Hop Attribution）\n\n支持多跳归因分析，可以追踪归因在模型不同层之间的传播路径。这为深入理解模型的内部工作机制提供了窗口。\n\n## 技术实现原理\n\nFlashTrace实现了论文《Towards Long-Horizon Interpretability: Efficient and Faithful Multi-Token Attribution for Reasoning LLMs》中提出的方法。核心技术包括：\n\n### Span级别的归因计算\n\n传统归因方法（如输入梯度、积分梯度）针对单个输出token计算归因。FlashTrace扩展了这一框架，支持对连续多个生成token组成的span计算统一归因分数。\n\n### 高效计算优化\n\n针对长序列推理场景，FlashTrace实现了多项优化：\n- 分块处理：支持按chunk处理长序列，避免内存溢出\n- Sink Chunk优化：专门处理序列末尾的关键token\n- 注意力重计算：可选的低内存注意力计算路径\n\n### 三种归因方法\n\nFlashTrace支持三种归因计算模式：\n- flashtrace：项目默认方法，针对多token span优化\n- ifr-span：基于影响力函数的span归因\n- ifr-matrix：基于影响力函数的矩阵形式归因\n\n## 使用方式\n\nFlashTrace提供Python API和命令行两种使用方式：\n\n### Python API使用\n\npython\nfrom flashtrace import FlashTrace, load_model_and_tokenizer\n\nprompt = \"\"\"Context: Paris is the capital of France.\nQuestion: What is the capital of France?\"\"\"\ntarget = \"Paris\"\n\nmodel, tokenizer = load_model_and_tokenizer(\"Qwen/Qwen3-8B\", device_map=\"auto\")\ntracer = FlashTrace(model, tokenizer, chunk_tokens=128, sink_chunk_tokens=32)\n\ntrace = tracer.trace(\n prompt=prompt,\n target=target,\n output_span=(0, 0), # 分析第一个生成token\n hops=1,\n)\n\nprint(trace.topk_inputs(10))\ntrace.to_json(\"trace.json\")\ntrace.to_html(\"trace.html\")\n\n\n### 命令行使用\n\nbash\n# 准备输入文件\nprintf \"Context: Paris is the capital of France.\\nQuestion: What is the capital of France?\\n\" > prompt.txt\nprintf \"Paris\" > target.txt\n\n# 运行归因分析\nflashtrace trace \\\n --model Qwen/Qwen3-8B \\\n --prompt prompt.txt \\\n --target target.txt \\\n --output-span 0:0 \\\n --hops 1 \\\n --html trace.html \\\n --json trace.json\n\n\n## Span选择工作流\n\nFlashTrace的归因分析高度依赖于正确的span选择。项目推荐以下工作流：\n\n1. 初始追踪：先用默认参数运行一次追踪，获取完整的生成token列表\n2. 检查tokenization：查看trace.generation_tokens，了解文本如何被切分为token\n3. 选择span：基于token索引选择感兴趣的span（如答案部分或推理部分）\n4. 重新追踪：使用选定的span重新运行追踪\n5. 导出可视化：生成HTML热力图进行人工检查\n\nspan使用包含式索引（inclusive indices），第一个生成token的索引为0。例如output_span=(80, 85)表示分析第80到85个生成token（共6个token）。\n\n## 支持的模型\n\nFlashTrace针对Llama/Qwen风格的decoder-only因果语言模型设计，要求模型具备以下结构：\n- model.layers层序列\n- Q/K/V/O注意力投影\n- RMSNorm或LayerNorm归一化\n- RoPE位置编码元数据\n\n已验证支持的模型家族包括：\n- Qwen2系列\n- Qwen3系列\n- Llama系列\n\n## 应用场景\n\nFlashTrace在多个研究和应用场景中发挥作用：\n\n### 幻觉检测\n\n通过分析模型生成内容与提示词证据的归因关系，可以识别模型是否在" hallucinating "（编造不存在的信息）。如果高归因分数的提示词token与生成内容不匹配，可能存在幻觉。\n\n### 提示词工程优化\n\n归因分析可以揭示哪些提示词部分对模型决策影响最大。这有助于优化提示词设计，去除无关内容，强化关键信息。\n\n### 模型行为分析\n\n通过对比不同模型或同一模型在不同配置下的归因模式，研究者可以深入理解模型的内部工作机制和偏好。\n\n### 推理过程审计\n\n对于推理模型，可以分别分析推理过程和最终答案的归因，检查模型是否基于正确的逻辑链条得出结论。\n\n## 性能与资源需求\n\nFlashTrace基于PyTorch实现，推荐使用CUDA GPU运行大规模模型。对于资源受限环境，可以使用：\n- 更小的模型\n- 低精度计算（float16/bfloat16）\n- device_map=\"auto\"自动分配层到CPU/GPU\n- --recompute-attention降低内存占用\n\nCPU环境支持小规模模型和短序列的测试，但长序列推理需要GPU支持。\n\n## 项目结构与生态\n\nFlashTrace采用清晰的项目结构：\n- flashtrace/：核心Python包\n- examples/：快速入门示例\n- tests/：CPU冒烟测试\n- exp/：论文实验和研究代码\n- docs/superpowers/：设计文档和实现规划\n\n项目已发布到PyPI，可通过pip install flashtrace安装。开发版本支持pip install -e \".[dev]\"本地安装。\n\n## 总结\n\nFlashTrace填补了推理模型可解释性工具的重要空白。通过支持多token span的归因分析，它让研究者能够更深入地理解模型的推理过程，而不仅仅是单个token的生成。无论是用于学术研究、模型调试还是提示词优化，FlashTrace都提供了一个实用且高效的解决方案。\n\n项目完全开源，代码和文档可在GitHub获取，相关论文已发布到arXiv。对于关注LLM可解释性的研究者和开发者，FlashTrace是一个值得尝试的工具。\n\n## 引用信息\n\n\n@misc{pan2026flashtrace,\n title={Towards Long-Horizon Interpretability: Efficient and Faithful Multi-Token Attribution for Reasoning LLMs},\n author={Pan, Wenbo and Liu, Zhichao},\n year={2026},\n eprint={2602.01914},\n archivePrefix={arXiv}\n}\n

FlashTrace：推理语言模型的多Token归因分析工具\n\n随着大型语言模型（LLM）推理能力的不断增强，理解模型"为什么生成这个答案"变得越来越重要。传统归因方法通常只关注单个token的归因，但在推理模型（Reasoning Models）中，答案往往由一长串中间推理步骤共同决定。FlashTrace正是为解决这一问题而设计的——它提供了高效的多token归因能力，让研究者能够追踪生成答案与提示词token之间的深层关联。\n\n项目背景：推理模型的可解释性挑战\n\n现代推理模型（如Qwen3、Llama系列）在回答复杂问题时，会生成包含大量中间推理步骤的长文本。这些步骤共同导向最终答案，但传统归因工具只能分析单个token的归因，无法捕捉"答案span"与提示词之间的整体关系。\n\nFlashTrace的核心洞察是：研究者通常关心的是一段生成文本（如最终答案或某段推理过程）与提示词中哪些部分最相关。这需要一种能够处理"多token span"的归因方法，而非传统的单token归因。\n\n核心功能与特性\n\nFlashTrace提供了完整的归因分析工作流：\n\n多Token归因追踪\n\nFlashTrace可以针对选定的生成文本span（如最终答案或某段推理）计算其与提示词各token的归因分数。这不同于传统方法只能分析单个token，FlashTrace支持任意长度的span分析。\n\nTop-K提示词Token排名\n\n系统会返回对生成span贡献最大的前K个提示词token，每个token附带归因分数。这让研究者能够快速定位"关键证据"——哪些提示词内容对答案产生了最大影响。\n\nJSON格式导出\n\n归因结果可以导出为结构化JSON，包含完整的token列表、分数、生成token序列等信息。这便于下游分析工具集成，支持批量处理和自动化分析。\n\n独立HTML热力图\n\nFlashTrace可以生成独立的HTML文件，以热力图形式可视化归因结果。热力图直接嵌入在HTML中，无需外部依赖，可以本地打开或作为分析结果分享。\n\n多跳归因（Per-Hop Attribution）\n\n支持多跳归因分析，可以追踪归因在模型不同层之间的传播路径。这为深入理解模型的内部工作机制提供了窗口。\n\n技术实现原理\n\nFlashTrace实现了论文《Towards Long-Horizon Interpretability: Efficient and Faithful Multi-Token Attribution for Reasoning LLMs》中提出的方法。核心技术包括：\n\nSpan级别的归因计算\n\n传统归因方法（如输入梯度、积分梯度）针对单个输出token计算归因。FlashTrace扩展了这一框架，支持对连续多个生成token组成的span计算统一归因分数。\n\n高效计算优化\n\n针对长序列推理场景，FlashTrace实现了多项优化：\n- 分块处理：支持按chunk处理长序列，避免内存溢出\n- Sink Chunk优化：专门处理序列末尾的关键token\n- 注意力重计算：可选的低内存注意力计算路径\n\n三种归因方法\n\nFlashTrace支持三种归因计算模式：\n- flashtrace：项目默认方法，针对多token span优化\n- ifr-span：基于影响力函数的span归因\n- ifr-matrix：基于影响力函数的矩阵形式归因\n\n使用方式\n\nFlashTrace提供Python API和命令行两种使用方式：\n\nPython API使用\n\npython\nfrom flashtrace import FlashTrace, load_model_and_tokenizer\n\nprompt = \"\"\"Context: Paris is the capital of France.\nQuestion: What is the capital of France?\"\"\"\ntarget = \"Paris\"\n\nmodel, tokenizer = load_model_and_tokenizer(\"Qwen/Qwen3-8B\", device_map=\"auto\")\ntracer = FlashTrace(model, tokenizer, chunk_tokens=128, sink_chunk_tokens=32)\n\ntrace = tracer.trace(\n prompt=prompt,\n target=target,\n output_span=(0, 0), 分析第一个生成token\n hops=1,\n)\n\nprint(trace.topk_inputs(10))\ntrace.to_json(\"trace.json\")\ntrace.to_html(\"trace.html\")\n\n\n命令行使用\n\nbash\n准备输入文件\nprintf \"Context: Paris is the capital of France.\\nQuestion: What is the capital of France?\\n\" > prompt.txt\nprintf \"Paris\" > target.txt\n\n运行归因分析\nflashtrace trace \\\n --model Qwen/Qwen3-8B \\\n --prompt prompt.txt \\\n --target target.txt \\\n --output-span 0:0 \\\n --hops 1 \\\n --html trace.html \\\n --json trace.json\n\n\nSpan选择工作流\n\nFlashTrace的归因分析高度依赖于正确的span选择。项目推荐以下工作流：\n\n1. 初始追踪：先用默认参数运行一次追踪，获取完整的生成token列表\n2. 检查tokenization：查看trace.generation_tokens，了解文本如何被切分为token\n3. 选择span：基于token索引选择感兴趣的span（如答案部分或推理部分）\n4. 重新追踪：使用选定的span重新运行追踪\n5. 导出可视化：生成HTML热力图进行人工检查\n\nspan使用包含式索引（inclusive indices），第一个生成token的索引为0。例如output_span=(80, 85)表示分析第80到85个生成token（共6个token）。\n\n支持的模型\n\nFlashTrace针对Llama/Qwen风格的decoder-only因果语言模型设计，要求模型具备以下结构：\n- model.layers层序列\n- Q/K/V/O注意力投影\n- RMSNorm或LayerNorm归一化\n- RoPE位置编码元数据\n\n已验证支持的模型家族包括：\n- Qwen2系列\n- Qwen3系列\n- Llama系列\n\n应用场景\n\nFlashTrace在多个研究和应用场景中发挥作用：\n\n幻觉检测\n\n通过分析模型生成内容与提示词证据的归因关系，可以识别模型是否在" hallucinating "（编造不存在的信息）。如果高归因分数的提示词token与生成内容不匹配，可能存在幻觉。\n\n提示词工程优化\n\n归因分析可以揭示哪些提示词部分对模型决策影响最大。这有助于优化提示词设计，去除无关内容，强化关键信息。\n\n模型行为分析\n\n通过对比不同模型或同一模型在不同配置下的归因模式，研究者可以深入理解模型的内部工作机制和偏好。\n\n推理过程审计\n\n对于推理模型，可以分别分析推理过程和最终答案的归因，检查模型是否基于正确的逻辑链条得出结论。\n\n性能与资源需求\n\nFlashTrace基于PyTorch实现，推荐使用CUDA GPU运行大规模模型。对于资源受限环境，可以使用：\n- 更小的模型\n- 低精度计算（float16/bfloat16）\n- device_map=\"auto\"自动分配层到CPU/GPU\n- --recompute-attention降低内存占用\n\nCPU环境支持小规模模型和短序列的测试，但长序列推理需要GPU支持。\n\n项目结构与生态\n\nFlashTrace采用清晰的项目结构：\n- flashtrace/：核心Python包\n- examples/：快速入门示例\n- tests/：CPU冒烟测试\n- exp/：论文实验和研究代码\n- docs/superpowers/：设计文档和实现规划\n\n项目已发布到PyPI，可通过pip install flashtrace安装。开发版本支持pip install -e \".[dev]\"本地安装。\n\n总结\n\nFlashTrace填补了推理模型可解释性工具的重要空白。通过支持多token span的归因分析，它让研究者能够更深入地理解模型的推理过程，而不仅仅是单个token的生成。无论是用于学术研究、模型调试还是提示词优化，FlashTrace都提供了一个实用且高效的解决方案。\n\n项目完全开源，代码和文档可在GitHub获取，相关论文已发布到arXiv。对于关注LLM可解释性的研究者和开发者，FlashTrace是一个值得尝试的工具。\n\n引用信息\n\n\n@misc{pan2026flashtrace,\n title={Towards Long-Horizon Interpretability: Efficient and Faithful Multi-Token Attribution for Reasoning LLMs},\n author={Pan, Wenbo and Liu, Zhichao},\n year={2026},\n eprint={2602.01914},\n archivePrefix={arXiv}\n}\n