用架构图讲清 检索增强一张图要回答一个问题一、深度引言与场景痛点很多 RAG 架构图把用户、网关、模型、向量库、缓存、队列、监控全画在一起箭头绕来绕去。图看起来很专业但读者不知道重点是什么。好的架构图应该回答一个问题数据怎么流、权限在哪里拦、延迟在哪里产生、失败怎么降级。一张图只回答一个问题。想讲全链路就画全链路想讲缓存就只画缓存路径想讲权限就突出鉴权和过滤。架构图是思维工具不是组件清单。二、底层机制与原理深度剖析flowchart TD A[用户问题] -- B[鉴权] B -- C[检索] C -- D[重排] D -- E[生成] C -- F[检索失败降级] E -- G[引用校验]主路径用实线异常路径可以单独标出。读者先理解正常流程再看失败处理。所有箭头都同等重要图就没有重点。三、生产级代码实现这张图回答RAG 请求从进入系统到生成答案经过哪些质量控制点。 重点看三处鉴权、重排、引用校验。 不展示内容更新链路避免信息混杂。图不是独立存在的图题和说明很重要。说明越清楚读者越少误解。四、边界分析与架构权衡架构图容易画得很确定但系统可能还在试验。哪些组件已上线哪些是规划哪些是可选优化要标明。否则读者会以为图上的每个框都已经稳定运行。技术表达要诚实。取舍方面图越完整越复杂越简化越可能遗漏边界。可以用多张图分层业务流程图、数据流图、部署图、故障降级图。不要指望一张图承担所有表达任务。还要保持图和系统一致。架构改了图也要改。过期架构图比没有图更危险因为它会误导新人和评审。把图放进文档仓库和代码一起维护是很好的习惯。图里还要标注数据边界。哪些数据是用户输入哪些是内部知识库哪些会进入模型上下文哪些会落日志这些边界对隐私和安全很重要。RAG 架构图如果只画组件不画数据边界很容易漏掉合规问题。另外架构图不要滥用箭头。每根箭头都应该代表真实的数据、控制或依赖关系。为了好看随手连线会让读者误解调用顺序。复杂系统里准确比华丽重要。给非技术读者看的图可以少画组件多画问题和结果给工程评审看的图则要补上协议、存储、重试和降级。受众不同图的颗粒度也不同。会画图本质上是会选择信息。最后图要能支持讨论。评审会上大家能指着图问这里失败怎么办这里权限在哪里拦这里缓存怎么失效。能承载这些问题的图才是真的有用。RAG 图还可以配一张时序图。架构图说明组件时序图说明一次请求如何经过它们。很多延迟和重试问题只有放到时序里才看得清。组件图和时序图互补读者更容易建立完整理解。如果图面向落地评审建议标注 SLO 和容量假设。比如检索目标 300ms、重排目标 500ms、模型首 token 2s、缓存命中率目标 60%。数字不一定一开始准确但能让讨论从“感觉不错”变成“是否达标”。最后图的版本要和系统版本对应。上线 v2 架构后旧图应归档不要和新图混在一起。文档也需要生命周期管理。图里的颜色和形状也要有规则。比如蓝色代表在线链路灰色代表离线链路红色代表风险点虚线代表异步任务。规则一旦固定读者就能快速扫图。不要每张图都重新发明一套视觉语言。还可以把图和告警面板关联。架构图上标出关键指标入口排障时能从组件直接跳到监控。这样图不只是讲解材料也能成为运维入口。RAG 系统组件多这种关联会很实用。最后画图前先写一句“这张图不讲什么”。例如不讲文档入库、不讲权限细节、不讲部署拓扑。明确排除范围读者更不容易误解。异常路径补充把失败当成接口契约下面的补充片段强调一个原则调用方必须得到稳定、可解释的错误而不是在超时、空输入或依赖失败时收到模糊结果。代码不追求覆盖所有业务细节而是展示输入校验、超时控制和错误封装这三个生产系统最容易遗漏的环节。from __future__ import annotations import asyncio from dataclasses import dataclass dataclass class GuardedResult: ok: bool value: str error: str async def run_with_guard(input_text: str, timeout: float 3.0) - GuardedResult: if not input_text.strip(): return GuardedResult(okFalse, errorinput cannot be empty) try: async with asyncio.timeout(timeout): # 真实项目中这里放模型调用、数据库查询或外部服务请求。 await asyncio.sleep(0.01) return GuardedResult(okTrue, valuefaccepted: {input_text}) except TimeoutError: return GuardedResult(okFalse, erroroperation timeout) except Exception as exc: return GuardedResult(okFalse, errorfoperation failed: {exc})五、总结用架构图讲清 RAG关键是一张图回答一个问题。主路径、异常路径、说明、状态和维护机制都要清楚。图不是装饰是帮助复杂系统被理解。
用架构图讲清 检索增强：一张图要回答一个问题
用架构图讲清 检索增强一张图要回答一个问题一、深度引言与场景痛点很多 RAG 架构图把用户、网关、模型、向量库、缓存、队列、监控全画在一起箭头绕来绕去。图看起来很专业但读者不知道重点是什么。好的架构图应该回答一个问题数据怎么流、权限在哪里拦、延迟在哪里产生、失败怎么降级。一张图只回答一个问题。想讲全链路就画全链路想讲缓存就只画缓存路径想讲权限就突出鉴权和过滤。架构图是思维工具不是组件清单。二、底层机制与原理深度剖析flowchart TD A[用户问题] -- B[鉴权] B -- C[检索] C -- D[重排] D -- E[生成] C -- F[检索失败降级] E -- G[引用校验]主路径用实线异常路径可以单独标出。读者先理解正常流程再看失败处理。所有箭头都同等重要图就没有重点。三、生产级代码实现这张图回答RAG 请求从进入系统到生成答案经过哪些质量控制点。 重点看三处鉴权、重排、引用校验。 不展示内容更新链路避免信息混杂。图不是独立存在的图题和说明很重要。说明越清楚读者越少误解。四、边界分析与架构权衡架构图容易画得很确定但系统可能还在试验。哪些组件已上线哪些是规划哪些是可选优化要标明。否则读者会以为图上的每个框都已经稳定运行。技术表达要诚实。取舍方面图越完整越复杂越简化越可能遗漏边界。可以用多张图分层业务流程图、数据流图、部署图、故障降级图。不要指望一张图承担所有表达任务。还要保持图和系统一致。架构改了图也要改。过期架构图比没有图更危险因为它会误导新人和评审。把图放进文档仓库和代码一起维护是很好的习惯。图里还要标注数据边界。哪些数据是用户输入哪些是内部知识库哪些会进入模型上下文哪些会落日志这些边界对隐私和安全很重要。RAG 架构图如果只画组件不画数据边界很容易漏掉合规问题。另外架构图不要滥用箭头。每根箭头都应该代表真实的数据、控制或依赖关系。为了好看随手连线会让读者误解调用顺序。复杂系统里准确比华丽重要。给非技术读者看的图可以少画组件多画问题和结果给工程评审看的图则要补上协议、存储、重试和降级。受众不同图的颗粒度也不同。会画图本质上是会选择信息。最后图要能支持讨论。评审会上大家能指着图问这里失败怎么办这里权限在哪里拦这里缓存怎么失效。能承载这些问题的图才是真的有用。RAG 图还可以配一张时序图。架构图说明组件时序图说明一次请求如何经过它们。很多延迟和重试问题只有放到时序里才看得清。组件图和时序图互补读者更容易建立完整理解。如果图面向落地评审建议标注 SLO 和容量假设。比如检索目标 300ms、重排目标 500ms、模型首 token 2s、缓存命中率目标 60%。数字不一定一开始准确但能让讨论从“感觉不错”变成“是否达标”。最后图的版本要和系统版本对应。上线 v2 架构后旧图应归档不要和新图混在一起。文档也需要生命周期管理。图里的颜色和形状也要有规则。比如蓝色代表在线链路灰色代表离线链路红色代表风险点虚线代表异步任务。规则一旦固定读者就能快速扫图。不要每张图都重新发明一套视觉语言。还可以把图和告警面板关联。架构图上标出关键指标入口排障时能从组件直接跳到监控。这样图不只是讲解材料也能成为运维入口。RAG 系统组件多这种关联会很实用。最后画图前先写一句“这张图不讲什么”。例如不讲文档入库、不讲权限细节、不讲部署拓扑。明确排除范围读者更不容易误解。异常路径补充把失败当成接口契约下面的补充片段强调一个原则调用方必须得到稳定、可解释的错误而不是在超时、空输入或依赖失败时收到模糊结果。代码不追求覆盖所有业务细节而是展示输入校验、超时控制和错误封装这三个生产系统最容易遗漏的环节。from __future__ import annotations import asyncio from dataclasses import dataclass dataclass class GuardedResult: ok: bool value: str error: str async def run_with_guard(input_text: str, timeout: float 3.0) - GuardedResult: if not input_text.strip(): return GuardedResult(okFalse, errorinput cannot be empty) try: async with asyncio.timeout(timeout): # 真实项目中这里放模型调用、数据库查询或外部服务请求。 await asyncio.sleep(0.01) return GuardedResult(okTrue, valuefaccepted: {input_text}) except TimeoutError: return GuardedResult(okFalse, erroroperation timeout) except Exception as exc: return GuardedResult(okFalse, errorfoperation failed: {exc})五、总结用架构图讲清 RAG关键是一张图回答一个问题。主路径、异常路径、说明、状态和维护机制都要清楚。图不是装饰是帮助复杂系统被理解。
