用 Mermaid 画清 RAG 全链路从文档入库到答案生成的可视化范式一、深度引言与场景痛点我见过太多的技术文档和架构设计文档里RAG 系统的架构图是用 PPT 徒手画的——方框、箭头、各种颜色看着挺热闹但过两周再回头看完全看不懂那条箭头是什么意思。更致命的是PPT 图没法版本管理改了三个方框的位置你无法从 Git diff 里看出到底改了什么。Mermaid 解决了这些问题。它是一种基于文本的图表绘制语言代码即图、图即代码。写在 Markdown 里提交到 Git 里别人 clone 你的仓库后看到的图和你在本地看到的一模一样。对于 RAG 这种流程密集型的系统Mermaid 是画架构图的最佳工具——没有之一。但会用 Mermaid和能用 Mermaid 把 RAG 画清楚是两回事。RAG 系统天然包含多个维度的流程离线索引链路文档入库、在线检索链路用户查询、Agent 决策链路工具调用还有数据流、控制流、错误流……如果把这几种流全揉在一张图里画出来的一定是一团乱麻。本文的目标不是教你 Mermaid 的语法官方文档比我讲得好而是分享一套RAG 系统可视化的分层范式——把 RAG 拆成索引流、检索流、Agent 决策流三条独立链路每条用最合适的 Mermaid 图形来呈现。二、底层机制与原理深度剖析RAG 系统的可视化难点在于信息的层次性。一个完整的 RAG 系统至少包含以下三条流程它们不应该画在同一张图里flowchart TD A[RAG 系统可视化] A -- B[离线索引流] A -- C[在线检索流] A -- D[Agent 决策流] B -- B1[文档解析 → 切分 → Embedding → 索引] C -- C1[Query → Embedding → 检索 → Rerank → 生成] D -- D1[判断 → 调用工具 → 整合结果 → 迭代] B -- B2[适用图形: flowchart LR] C -- C2[适用图形: sequenceDiagram] D -- D2[适用图形: stateDiagram-v2] B1 -- B3[侧重: 数据处理阶段] C1 -- C3[侧重: 时序与交互] D1 -- D3[侧重: 状态转移]为什么不同流程要用不同的图离线索引流是有明确阶段划分的批处理流程flowchart LR从左到右最合适因为它能清晰表达数据在各阶段间的单向流动。在线检索流是多个组件之间的请求-响应交互sequenceDiagram时序图最合适因为它能清晰表达谁调用谁、调用顺序和返回值。Agent 决策流是带分支和循环的决策过程stateDiagram-v2状态图最合适因为它能表达 Agent 在不同状态间的跳转逻辑。三、生产级代码实现这里不是传统意义上的代码而是三张精心设计的 Mermaid 架构图附带详细的标注和说明。3.1 离线索引流flowchart LRflowchart LR subgraph Ingest [文档接入] A1[(S3/MinIO)] -- A2[文档监听器] A2 -- A3{格式判断} A3 --|PDF| A4[PyPDF 解析] A3 --|Markdown| A5[Markdown 解析] A3 --|HTML| A6[BeautifulSoup] end subgraph Process [文档处理] A4 -- B1[文本清洗] A5 -- B1 A6 -- B1 B1 -- B2[段落分割] B2 -- B3{文档切分策略} B3 --|结构化| B4[语义切分] B3 --|非结构化| B5[递归切分] end subgraph Index [向量索引] B4 -- C1[Embedding API] B5 -- C1 C1 -- C2[(向量数据库)] C1 -- C3[(倒排索引 - ES)] C2 -- C4[索引状态监控] C3 -- C4 end subgraph Meta [元数据管理] B4 -- D1[(PostgreSQL)] B5 -- D1 D1 -- D2[版本号管理] D2 -- D3[增量更新触发器] end C4 -- E[索引完成通知] D3 -- E设计要点使用subgraph把流程分为四个逻辑阶段接入、处理、索引、元数据——读者一眼就能看出系统的模块边界使用{菱形}表示决策节点格式判断、切分策略让分支逻辑清晰可读使用[(圆柱)]表示存储层和计算层形成视觉区分数据流向全部从左到右符合阅读习惯3.2 在线检索流sequenceDiagramsequenceDiagram actor User as 用户 participant API as API Gateway participant Cache as Redis 缓存 participant Embed as Embedding 服务 participant VS as 向量数据库 participant ES as Elasticsearch participant Rerank as Rerank 模型 participant LLM as LLM 服务 User-API: POST /query API-Cache: 查询缓存 alt 缓存命中 Cache--API: 返回缓存结果 API--User: 快速响应 else 缓存未命中 API-Embed: embed_query(query) Embed--API: 返回向量 par 并行检索 API-VS: 向量检索 top_k20 VS--API: 返回 20 个候选 and API-ES: BM25 检索 top_k20 ES--API: 返回 20 个候选 end API-API: 混合融合(RRF) API-Rerank: rerank(query, candidates) Rerank--API: 返回 top_5 API-LLM: generate(context query) LLM--API: 生成回答 API-Cache: 写入缓存 API--User: 返回完整结果 end设计要点actor显式标注用户角色和系统组件区分par...and...end展示并行检索向量 BM25 同时发起——这是时序图最强大的特性之一alt...else...end展示缓存命中/未命中的分支逻辑箭头的方向实线请求 →、虚线返回 --严格区分请求和响应3.3 Agent 决策流stateDiagram-v2stateDiagram-v2 [*] -- 接收请求 接收请求 -- 意图分析 意图分析 -- 检索知识库: 需要背景知识 意图分析 -- 调用工具: 需要执行操作 意图分析 -- 直接回答: 简单问题 检索知识库 -- 评估结果 评估结果 -- 检索知识库: 结果不足,需重试 评估结果 -- 整合信息: 结果充分 评估结果 -- 直接回答: 无需额外信息 调用工具 -- 检查工具结果 检查工具结果 -- 调用工具: 需要更多工具 检查工具结果 -- 整合信息: 工具链完成 检查工具结果 -- 报告错误: 工具失败 整合信息 -- 生成回答 生成回答 -- 自我检查 自我检查 -- 整合信息: 回答不完整 自我检查 -- 返回用户: 回答合格 直接回答 -- 返回用户 报告错误 -- 返回用户 返回用户 -- [*]设计要点状态图天然适合表达Agent 在不同状态下做什么、怎么跳转[*]表示起点和终点让读者清楚流程的开始和结束状态间的转移标签写在箭头旁说明触发条件关键决策点评估结果、检查工具结果、自我检查都有多条出边体现 Agent 的自主决策特性四、边界分析与架构权衡1. 一张图 vs 多张图的取舍有些人喜欢把所有东西塞进一张图——一开始我也这么干画了一堆箭头和方框打印出来贴在墙上看起来像个作品。但后来发现除了我自己没人能从那张图里读取出有效信息。正确的做法是一个视角一张图索引视角画索引检索视角画检索不要混。2. flowchart 的两种方向的语义差异flowchart TDTop-Down适合表达层级关系、决策树flowchart LRLeft-Right适合表达数据流、流水线RAG 索引流是数据流所以用 LR。Agent 的决策树是层级关系所以 Agent 决策那部分如果不用状态图可以退而求其次用 TD。3. Mermaid 在复杂图中的极限当节点超过 30 个时Mermaid 的自动布局算法会把图画得非常散——不是那种优雅的分散而是像一盘撒落的棋子。这时有两个选择一是继续拆分把大图拆成更大粒度的子图二是用graph TD的subgraph把节点先分组组间关系简化。我推荐优先拆分——大图的维护成本和阅读成本都太高了。4. 何时不该用 MermaidMermaid 适合画流程和关系但不适合画系统部署拓扑服务器、负载均衡、网络分区和 UI 交互页面跳转、按钮状态。对于部署拓扑用diagrams.net或 excalidraw 更好对于 UI 交互原型工具更合适。Mermaid 的强项是逻辑流不是物理部署。五、总结用 Mermaid 画 RAG 架构图记住四个原则分而治之离线索引流用 flowchart LR在线检索流用 sequenceDiagram决策流用 stateDiagram语义标注菱形 决策圆柱 存储actor 用户实线 请求虚线 响应subgraph 划模块把功能相近的节点放在同一个 subgraph 里标明模块名版本管理Mermaid 代码就是 Markdown 文本直接提交 Git——这是它超越所有可视化工具的核心优势最后分享一个我自己的习惯每篇技术文档的开头一定要有一张总览图用 flowchart 画出系统最粗粒度的模块关系。读者看完这张图就知道自己要读的是一篇什么样的文章、各个环节之间是什么关系。这个习惯对提升文档的可读性帮助极大。下一篇是本系列 0706 的收官篇——Agent 的行为评测体系。我们不只看答案对不对还要看 Agent 的思考过程是否合理。