第十一章 · 链路追踪
本章定位：前面十章讲了 SparkX RAG 的所有功能。但功能越多、链路越长，出问题时排查就越难——用户反馈「这个回答不对」，你怎么知道是分块的问题、检索的问题、意图路由的问题、还是生成 Prompt 的问题？如果没有追踪，你只能两眼一黑去猜。链路追踪（Trace）就是把整条 RAG 链路的每一步执行过程记录下来，让你能「回放」一次请求经过了哪些环节、每个环节花了多久、产出了什么、跳过了什么。
本章讲 SparkX 的链路追踪体系：它追踪什么、怎么记录、怎么组装成可读的 trace、怎么推送给前端展示、怎么持久化供回溯。
一、为什么 RAG 系统需要链路追踪
1. RAG 是个黑盒长链路
回顾前十章的 RAG 链路：
样例命中 → 查询改写 → 规则意图 → LLM意图分类 → 歧义澄清 → 模糊澄清
→ 多通道检索 → RRF融合 → 父块展开 → 重排 → MMR → 合并截断 → 兜底 → 生成
用户问一句话，背后跑了十几个阶段。最终答案不对时，没有 trace 你根本不知道是哪个环节出了问题：
- 是意图分类把问题路由到错的库了？
- 是检索召回的块本身就错了？
- 还是检索对了但重排把它排下去了？
- 还是都对但生成 Prompt 写错了？
2. Trace 的价值：可观测、可回溯、可调优
| 价值 | 具体场景 |
|---|---|
| 可观测 | 实时看到「这次请求走了哪些阶段、每个阶段多久、跳过了哪些」 |
| 可回溯 | 历史会话能回看「这个回答当时是怎么生成的，检索了哪些块」 |
| 可调优 | 发现「重排阶段耗时占 60%」→ 优化重排；「图谱通道召回全是噪声」→ 降权 |
💡 第九章的三个测试功能解决的是「主动评估质量」，本章的链路追踪解决的是「被动排查问题」——两者互补，共同构成 RAG 的可观测性体系。
二、SparkX 追踪什么：三条管线
SparkX 有三条独立的追踪管线，分别对应三类场景：
| 追踪管线 | 追踪什么 | 记录在哪 | 前端展示 |
|---|---|---|---|
| 检索管线 trace | 一次问答的完整 RAG 链路 | t_chat_message.stage_data + SSE |
RagTraceDrawer |
| 入库管线 trace | 一次文档入库的全过程 | t_knowledge_document.ingestion_summary |
IngestionTimelineModal |
| 节点级 AOP trace | 关键方法的细粒度耗时 | Micrometer 指标 | 监控系统（Prometheus 等） |
下面逐一拆解。
🔒 以上为本章部分预览（约 10%）
本章剩余 90% 内容包含：关键源码逐行拆解、设计细节与工程权衡、代码示例与生产实践要点。
加入知识星球，获取《SparkX 源码深度解析》全部 13 章
💡 本次展示的仅为部分预览内容（约 10%）。完整的源码深度解析包含每一个技术点的完整实现细节。点击上方按钮扫码加入知识星球，解锁全部内容。
