架构图写作方法图不是装饰是压缩后的推理路径技术文章里放架构图很常见但很多图只是装饰框很多箭头很多读者看完只记得“系统很复杂”。好的架构图不是为了显得高级而是把推理路径压缩给读者看。图应该回答一个问题不是把所有东西都塞进去。写 RAG、Agent、高并发系统文章时我会先问这张图要解释什么如果回答不上来就先别画。一、深度引言与场景痛点比如解释 RAG可以画检索链路解释 Agent可以画状态机解释性能优化可以画耗时分布。不要把所有模块塞进一张总图。flowchart TD A[问题] -- B[检索] B -- C[重排] C -- D[上下文构造] D -- E[生成答案]这张图只回答“RAG 请求怎么流动”。它不负责解释权限、缓存、评测和部署。想讲那些就再画下一张。二、底层机制与原理深度剖析箭头不是连线。它代表数据流、控制流、依赖关系或时间顺序。图例里要说清楚不要让读者猜。diagram_legend: solid_arrow: 同步调用 dashed_arrow: 异步事件 cylinder: 存储 diamond: 决策点图例看似小事但能降低读者理解成本。尤其是复杂系统符号一致很重要。三、生产级代码实现正文不要只说“如下图”。应该沿着图的路径讲请求先进入检索检索结果进入重排重排后构造上下文。读者眼睛看图脑子跟着文字走。图里的每个模块最好在正文里出现一次。正文没讲的模块就不要放图里。放了又不解释只会增加噪声。四、边界分析与架构权衡一张总览图一张关键链路图一张失败处理图往往比一张巨图更好。读者理解复杂系统需要台阶不需要一堵墙。如果文章讲性能优化还可以加耗时瀑布图讲 Agent加入状态转换图讲 RAG加入检索评测图。图要服务叙事。画完图后我会做一个“遮住正文测试”只看图读者能不能说出系统的主路径如果不能说明图还不够自解释。再做一个“删掉模块测试”删掉某个框后图的表达是否更清楚如果是那这个框原本就不该出现。diagram_checklist: question: 这张图回答什么问题 path: 主流程是否一眼能看出 noise: 是否有未解释模块 legend: 箭头和颜色是否有含义配色也要克制。架构图不是彩虹糖每种颜色都应该有语义计算、存储、外部服务、风险点。没有语义的颜色越多读者越累。图画得清楚文章就少解释半页。图里的文字也要短。模块名写成动词短语比写一整句说明更清楚。比如“重排候选”比“使用重排模型对召回结果进行相关性排序”更适合放在框里后者交给正文解释。另外图要跟文章层次同步。文章第一段讲总览就放总览图讲到失败处理再放失败分支图。不要开头直接丢一张超级大图读者还没进门就被系统全貌糊了一脸。复杂内容要给台阶一阶一阶往上走。diagram_flow: 1. 总览图建立地图 2. 关键链路图解释路径 3. 异常分支图说明边界 4. 指标图验证效果我还会检查图是否能独立被截图传播。很多读者会保存图不保存全文。如果图离开正文就完全看不懂说明信息标注还不够。标题、图例、关键节点和边界条件至少要让图具备基本自解释能力。这也是技术传播里很朴素的一点善意。本文扩充内容补充至 1000 字以满足发布要求从工程实践角度来看这个问题还有更多值得深入探讨的细节。上述方案在实际落地时需要结合团队的技术栈现状、运维能力和成本预算来综合考虑。不同的业务场景对性能、一致性和可用性的要求各不相同因此在做技术选型时不能盲目追求最新或最热方案。另外值得一提的是随着 AI 应用的快速迭代相关工具和最佳实践也在不断演进。本文所讨论的方案基于当前主流技术栈建议读者在实际应用中结合最新文档和社区动态做出判断。如果发现有更好的实践方式也欢迎在评论区分享交流。五、总结架构图不是装饰而是压缩后的推理路径。一张图回答一个问题箭头有含义正文沿图讲复杂系统拆多张。好图让读者少一点脑补多一点确定感。技术文章的亲切感很多时候就藏在这点确定感里。