上个月帮一个AI客服项目做架构评审代码已经写了两万多行但团队内部对“我们这个系统到底由哪些部分组成”这个问题居然有三种完全不同的答案。有人说是“一个RAG加一个Agent”有人说是“两个服务加一堆脚本”还有人指着代码说“这不都在里面了吗”。最后对齐的不是代码而是有人画了一张AI应用架构图。那一刻我才意识到在AI应用架构设计这件事上图不是文档负担反而是一张能逼着所有人把话说清楚的公共语言。这几年我评审过不少AI应用项目一个很明显的感受是AI应用架构设计里的“设计”两个字往往被忽略掉了。大家忙着调Prompt、接模型、跑数据管道等系统复杂到一定程度发现谁也说不清全貌。这篇内容我就围绕“图解AI应用架构设计”这个主题讲讲为什么需要图、该画什么、怎么画不翻车。适合正带着团队做AI应用开发的工程师、技术负责人也适合刚入行想建立全局观的同学参考。1. 为什么AI应用架构图比传统软件架构图更“刚需”1.1 AI应用和传统应用的本质差异传统互联网应用核心是“请求-处理-响应”的确定性链路用户点个按钮后端服务查库返回数据逻辑是可控的问题范围是有限的。但AI应用不一样尤其是大模型接入之后系统里多了一个“不确定性的输出源”。模型给出的回答不是查表出来的而是从概率空间里采样的结果同一个Prompt温度调高一点答案可能完全不同。这就导致了一个尴尬的局面你在代码层面很难确定“对错”只能确定“链路是否跑通”。架构评审的时候传统问题可以问“这个接口超时怎么办”AI应用的问题变成了“模型回答错了是Prompt问题、上下文问题、向量召回问题还是工具调用问题”。这种跨层定位问题的场景下没有一张把所有环节画清楚的架构图排查起来基本靠猜。另外AI应用里的数据链路是混在一起的。传统系统里数据流和调用链相对清晰A服务调B服务B服务查数据库。AI应用里用户输入可能先被改写、再被向量化、检索增强、拼装Prompt、模型生成、工具调用、后处理、再生成。这条链上的每一步都可能引入新的数据、新的接口、新的成本。图画不清楚问题定位就无从谈起。1.2 架构图在AI项目里解决的三个真实问题我总结下来AI应用架构图至少在三个场景里是不可替代的。首先是团队对齐。AI项目经常是算法、后端、前端、产品混在一起协作每个人对“我们做了什么”的理解完全不同。后端同学看到的是接口和队列算法同学看到的是Prompt和模型参数产品同学看到的是对话体验。一张图能把这些视角统一成一个整体。前面说的那个客服项目就是典型图一出来大家才知道原来系统里还挂着一个一直没人维护的旧意图识别服务。其次是故障排查。AI应用出问题症状往往在入口根因在深处。用户说“回答不准”你很难判断是检索召回不准、上下文被截断、模型指令遵循能力不够还是工具返回的数据格式把模型带偏了。如果架构图里画清楚了数据流和每一步的输入输出排查时就能按图索骥一段一段做隔离测试。最后是成本治理。大模型调用的每一项都有成本而且成本分布极度不均匀。一次工具循环可能触发三到四次模型调用Token消耗呈指数级叠加。没有架构图大家脑子里只有“每次对话要花多少钱”这种粗粒度概念有了图才能精准看到成本产生在链路哪个环节值不值得优化。1.3 给三类读者看图侧重点完全不同画图之前想清楚给谁看比想清楚怎么画更重要。我的经验是AI应用架构图需要服务三类人而他们看图的顺序恰好是相反的方向。第一类是开发执行的你。你要看的是细节组件之间怎么调用、消息格式是什么、异步链路在哪、失败重试策略是什么。这类图可以很复杂甚至可以拆分到单服务内部。第二类是评审架构的同事和领导。他们要看到边界和契约系统分几层、哪些是核心组件、数据如何流动、瓶颈在哪、扩展性如何。细节可以隐去但分层和责任边界必须清楚。第三类是业务方或决策层。他们要看到的是系统能做什么、有哪些外部依赖、多引入一个模型或工具大概会带来什么变化。这类图要尽量简化突出输入、输出、成本和风险。一张图不可能同时满足三个视角所以“图解AI应用架构”天然不是一张图而是一组图。后面我会专门讲怎么按视角拆图。2. 拆解AI应用架构的五个核心部件画图前心里要有底很多架构图画得乱不是画工不行而是对AI应用本身的构成没想清楚。我习惯把AI应用拆成五个核心部件画图前先用这个方法把系统“切一刀”然后再决定哪些画进去、哪些不画。这五个部件不是严格的层级有点像是切片分别是入口与编排层、知识供给层、模型推理层、外部工具层、治理与可观测层。一张架构图可能是这五个部件的某种组合也可能是其中几项的深挖但缺了任何一个你对系统的理解都是不完整的。2.1 入口与编排层Agent框架在这里起作用入口层负责接收外部请求编排层负责决定“接下来该干什么”。传统系统里的编排通常是预定义流程但AI应用里的编排往往是动态的模型自己决定下一步调用哪个工具、要不要追问用户、要不要结束任务。这也是“Agent”这个概念落地的地方。画图时入口与编排层至少要表达三件事第一用户请求从哪里进来是Web对话、API调用、还是消息队列第二会话状态与上下文怎么管理是存在Redis里、数据库里还是干脆放在内存里很不推荐第三编排逻辑是用LangChain、LlamaIndex这类框架还是自研的状态机还是让模型自由发挥。这里有个我反复踩过的坑很多团队把编排层画成了一个叫“Agent”的大方块里面什么都没有。这种画法等于没画。哪怕用一张子图也要把“规划-工具调用-记忆读写-结果生成”这个小循环画出来不然别人看了图还是不知道你的Agent到底是怎么工作的。2.2 知识供给层RAG和向量库不是全部知识供给层是AI应用和传统应用差异最大的一块。模型的知识在训练时就固定了想让系统知道私域知识、实时信息就得把外部知识“喂”进去。RAG是主流方案但知识供给不只是“向量库检索”这么简单。完整来看知识供给层包含数据源接入数据库、文件、爬虫、消息流、数据清洗与切分、向量化、索引管理、检索、重排、引用与溯源管理。这一层在架构图里往往是离线路上的重头戏但它和在线推理链路是分开跑的。画这一层时我最强调画清“离线链路”和“在线链路”的分界线。离线任务是文档导入、切分、Embedding入库在线任务是用户问题向量化、检索、重排、拼装上下文。两条链路容易画乱也容易让阅读者误以为“用户请求会触发整个RAG管道”。实际上绝大多数情况下离线和在线是异步解耦的。图上没分开日后出问题新人很容易去离线管道里找在线故障的原因。2.3 模型推理层模型网关是必须的组件模型推理层是整个架构的钱包也是性能瓶颈聚集地。画这一层时我不建议只画一个“大模型”图标了事。要么服务商是OpenAI、Azure、通义、文心、Gemini等要么是通过本地推理服务部署的Qwen、Llama、DeepSeek这类开源模型还有可能是针对不同任务路由到不同模型的“模型路由”。我特别推荐在架构图里引入“模型网关”这个概念类似传统架构里的API网关。模型网关负责统一封装不同模型厂商的API统一处理鉴权、重试、限流、降级、成本统计。没有这一层的话架构图里的连线会乱成一团每个服务都直连模型API牵一发动全身。画模型推理层时至少标注这几个信息模型名称与版本、上下文窗口大小、温度等关键参数、超时和重试策略、费用估算方式。这些信息不一定要全部写进图里可以挂在组件描述里但图上必须能看出“这里接的是什么模型替代方案是谁”。2.4 外部工具层Function Calling和工具的架构边界AI应用走向实用的核心能力是和外部世界交互。工具层就是模型能调用的所有外部能力查数据库、调第三方API、发邮件、执行业务操作甚至操作浏览器和代码仓库。设计架构图时外部工具层的边界很关键。你需要在图上画出每个工具对应的执行体在哪、权限边界是什么、调用前后怎么做参数校验。现在很多Agent框架支持工具直接映射到函数但生产环境里工具调用往往要落到真实的RPC、HTTP、SQL、Shell命令上这些执行动作必须有身份验证和审计。我在画工具层时一定会加上“工具注册中心”和“工具执行日志”这两个组件。工具注册中心负责给模型提供“有哪些工具可用、参数Schema是什么”工具执行日志负责回答问题“模型刚才调用了谁、传了什么参数、结果是什么”。没有这两个组件Agent调用工具出错时你只能干瞪眼完全不知道模型“心里”想干什么。2.5 治理与可观测层AI应用最容易被忽略的第五层很多团队的AI应用架构图画到前四层就停了。但生产环境跑过两个星期就会发现AI应用的排查复杂度远超传统系统因为问题多样性来自模型、语义、数据甚至同一个问题在时间序列上表现还不稳定。治理与可观测层要画进来的内容至少包括请求日志和Prompt日志、Token成本统计、回答质量评测入口、安全与内容合规过滤、敏感信息脱敏、A/B实验与回滚机制。这一层在架构图里通常是横跨所有其他层的“横切面”我习惯用一条虚线区域把它们框起来不放在某条功能链路过深的位置。尤其要强调Prompt和模型返回的日志记录。Prompt里往往带着业务上下文和用户信息一旦出问题没有日志连事实都还原不了。而很多传统的日志方案默认不记录请求体直接套用的话等到要排查“模型为什么在这个例子上胡说八道”时手边没有任何证据。日志这块画进架构图的意义是提醒团队“这是系统的一部分不是事后补的功能”。3. 一套经过实战检验的AI架构图解方法前面说了拆解和分析的结构这一章讲具体操作要怎么画用什么工具按什么顺序才能既快又不出废图。3.1 先分三种视图逻辑图、部署图、链路图一张图画到天荒地老往往是因为想在一张图里塞进所有维度。我的建议是至少按三种视图拆开画。第一种是逻辑架构图。它回答“系统有哪些逻辑部件、它们怎么协作”。这是团队讨论最多、迭代最频繁的图。画的时候按第二部分那五层来组织组件的名字用业务术语不说“xxService”这种名词而是说“意图识别模块”、“检索服务”、“记忆存储”这种能看懂的名字。第二种是部署架构图。它回答“每个组件运行在哪台机器、哪个环境、依赖什么基础服务”。这张图给运维和后端同学看需要画出微服务拆分、K8s部署单元、数据库实例、缓存集群、外部SaaS服务。AI应用在这里可能多两个组件GPU推理服务或模型API出口的网络边界。特别是企业环境里模型API能不能通、需要走哪个代理这张图上必须标清楚。第三种是关键链路时序图。它回答“一次典型请求从头到尾经过了哪些步骤、每步耗时多少”。比如一次含RAG的客服请求用户输入进来先做会话恢复再做查询改写接着向量化、检索、重排、拼装上下文、调用模型、做工具调用、再调用模型、输出。每一步都画成一个泳道加上延迟和Token数这就是后续做性能优化和成本治理的依据。我见过最好的AI应用架构文档是这三种视图互相引用而不是三张图各说各话。逻辑图上的组件在部署图里有对应实例链路图上的每一步能对应到逻辑图上的组件。这种对应关系是架构文档真正的价值所在。3.2 图例规范连接线、边界、颜色的约定画架构图最怕的不是技术复杂而是“每个人画的都是一种风格”。我给团队定了简单的图例规范几个关键约定如下供参考。组件形状业务服务和外部API用圆角矩形数据存储用圆柱或半圆柱模型服务用方形加特殊边框人/外部用户用非矩形图标区分。连线语义实线表示同步调用关系箭头指向被调用方虚线表示异步消息或事件通知带圆点的线表示数据流双线表示网络边界跨越内网到外网。颜色语义蓝色系表示核心业务组件绿色系表示数据存储与检索紫色系表示模型相关橙色系表示外部依赖灰色表示待拆除或过时的组件红色表示当前版本不稳定的点。边界绘制用大圆角框表示“进程边界”或“服务边界”用虚线框表示“信任边界”。信任边界尤其重要模型输出内容默认不可信工具执行的结果也必须校验后才能进入业务系统。这套规范不需要很复杂但一致性会让图的阅读成本大幅下降。画图的人省了“这段是什么”的解释时间看图的人不用猜“这个方块代表什么”。3.3 工具选型从白板到Markdown生态画AI应用架构图工具不是越重越好。我试过几类都有适用场景。轻量白板工具Excalidraw、在线白板适合头脑风暴和快速对齐缺陷是画完很难维护。通用绘图工具draw.io / diagrams.net、ProcessOn、Lucidchart适合正式的逻辑图和部署图规范性更强。代码化绘图Mermaid、D2、PlantUML适合放在代码仓库里和文档一起维护能diff能评审这是我最推荐的架构文档形态。文本型拓扑Markdown嵌文本图形适合在Issue、PR描述里快速表达碎片化想法特点是零成本但它不是维护型文档。如果是小团队或项目初期我建议直接用draw.io或Excalidraw先把逻辑图画出来快速试错。等系统稳定到需要组内评审和长期维护就迁移成Mermaid或D2这类代码化方案放到仓库里跟着版本走。这里多说一句Mermaid的架构图能力不如它的流程图能力画复杂组件关系时会受限。如果架构图复杂度上来了可以试试D2它在画“组件依赖关系”时表达能力更强。实在不行就用PlantUML的组件图也足够稳。3.4 实例示范一个AI客服Agent的图解过程拿前面提到的AI客服项目举例。我先在白板上理逻辑部件最后整理成的逻辑架构图包含这些内容用户入口Web/H5/小程序统一会话网关、会话服务管理session和短期记忆、意图理解网关轻量模型做初步分类、RAG检索中心向量库重排、知识库更新管道离线文档处理、工具服务层查订单、查物流、改地址三个Tool、模型网关统一接大模型API、评测与日志平台收集每轮对话的Prompt和响应。关键链路图里画出的主流程是用户提问到会话网关网关做用户身份识别和上下文加载。请求进入意图理解网关轻量模型判断是“闲聊”、“商品咨询”还是“订单查询”。商品咨询的请求送到RAG检索中心检索结果带引用粒度返回给编排层。编排层把检索结果和对话历史拼进Prompt调用模型网关大模型生成回答回答前还可能要求调用查订单工具。工具调用单独一条线先到工具服务层做参数补全、权限校验、实际调用、结果整理再回到模型做最终回答。整条链路上我标出了两处可以优化的瓶颈一是轻量意图模型和主模型会串行调用延迟叠加明显二是工具调用的结果没有缓存同样的订单号会被反复查询。这两个问题就是架构图带来的直接收益代码评审阶段看不出来但图画出来大家都在点头。4. 三类主流AI应用架构范式图解拆解不是每个AI应用都需要完整的Agent、RAG、工具调用的全家桶。根据业务的复杂程度我把见到的AI应用架构归成三类常见范式每一类都有典型的画法特征和坑位下面分别拆解。4.1 轻量范式业务系统直接调用模型API很多内部工具类AI应用其实是轻量范式比如合同摘要、邮件分类、资料翻译。它的架构图很简单业务系统直接调一个或多个模型API拿到结果后回填到业务流里本质上是“把大模型当成一个高级函数”。这类架构图画起来要克制不要为了好看硬加RAG或Agent层。图画的核心是两个点一是模型的调用位置是同步调用还是异步任务二是输入数据的边界特别是敏感数据是否离开了你信任的区域。我见过一个法务部做合同审查的应用架构图画完才发现原始合同文档被打包发到了外部模型API而图上完全没有标出这条数据出口。后来加上了一个脱敏服务和人工审批节点架构图才真正反映了生产逻辑。画轻量范式时还有一个常见误区是把“模型API”画成一个大方框旁边的业务组件全挤在一起。合理做法是把模型API拆成两个环节请求构建Prompt模板上下文拼装和响应处理结构化解析错误处理兜底逻辑。这两个环节才是轻量AI应用真正的工作量所在图上一目了然后评审时才有得聊。4.2 RAG范式数据供给决定架构形态RAG范式检索增强生成是目前企业落地最广的AI应用范式。它的架构图核心是画出“知识供给在线检索生成”两条路。离线知识管道通常长这样多源数据接入数据库、对象存储、爬虫、文档预处理格式转换、清洗、去重、切分策略按固定长度、语义段落、子标题、向量化Embedding模型、向量库入库索引构建、元数据标签、质量评估抽样检查嵌入效果。这一段在图上要独立成一个工作流区域标注“离线更新频率”和“数据来源责任人”。在线检索链路则是用户问题进来、查询改写可选、查询向量化、向量库检索、多路召回、重排、上下文拼装、模型生成答案。这一链路的时序关系非常重要画成链路时序图比逻辑图更有用。我在画RAG应用时一定会把“引用溯源”单独画出来它表示最终回答里附带的可信来源。如果架构图里没有溯源这个元素说明团队还没想清楚“回答错了由谁负责”。RAG架构图最容易翻车的地方是“把离线管道画得比在线链路还长”。实际运行中离线管道的构建节奏通常是小时级甚至天级在线链路要求秒级。图上如果不强调这条速度差异新人就会误以为RAG每次请求都要跑一遍完整的文档处理继而设计出荒谬的高延迟方案。4.3 Agent范式从单Agent到多Agent协作当AI应用需要自主完成多步骤任务架构就演进到Agent范式。单Agent架构图里核心是一个“循环”模型思考、决定调用工具、执行工具、观察结果、继续思考直到任务完成。这个循环在架构图里一定要描出来。单Agent的图还需要画出三块配套能力记忆系统短期会话记忆长期持久记忆、工具集可用工具及Schema、规划策略是一步一步计划还是一口气生成全步骤。这三块缺一块画出来都会让人觉得Agent是“伪Agent”只是带工具的模型调用。多Agent协作架构是当前更复杂的形态。这类架构图的核心不再是某个Agent内部而是Agent之间的“协作协议”。你需要画出调度者角色谁来分配任务、消息传递通道Agent之间怎么通信是共享队列还是事件总线、共享记忆有没有一个大家都读写的记忆库、任务结果汇总最后谁负责把子结果合并成回答。画多Agent图时我特别警惕被“网络效应”带偏。每个Agent画一个方块用一堆箭头连起来看起来很高大上但实际系统里Agent之间的通信如果不收敛到一个调度中心根本不可能保证一致性。所以我的建议是多Agent架构图一定要有一个明显的“调度中枢”所有协作路径都经过它而不是画成Agent之间互相随便直连的网状图。5. 画图时最容易踩的五个坑以及我的应对办法画多了总会踩坑。下面五个问题是AI应用架构图里出现频率最高的每个都是我在实际评审里反复遇到的情况。5.1 把Prompt画成组件或者干脆不画两个极端都见过。一边是把“Prompt文件”画成一个独立组件和数据库、模型服务并列误导别人以为Prompt是一个运行单元另一边是架构图里完全没有Prompt的影子好像模型是无状态直接吐出答案的。正确做法是Prompt是“配置”不是“组件”。在架构图里我习惯把Prompt模板放在编排层或模型网关的配置说明里标注版本号和变更记录不单独占一个盒子。但是Prompt的关键作用必须体现在链路图里在“构造输入”这一步明确说明这里要根据上下文来生成模型输入。架构图评审时要能回答一个问题改了Prompt之后重新发布的是什么是代码、是配置、还是数据库记录这条主线理清了架构图就不会把Prompt的地位画错。5.2 调用关系和数据流混在一条线里传统架构图里组件之间的连线往往就是调用关系。但AI应用里调用关系和实际数据流动经常不一致。比如编排层调用了模型网关但真正把上下文数据传给模型的是另一个数据通道又比如RAG检索中心返回引用文档可能走的是消息队列而同步的调用只是发个“任务完成”信号。图上把两种线混画会导致排查时判断错方向。我的应对办法很朴素同步调用用实线箭头异步数据流用虚线或特殊颜色每次画线先问自己“这条线上传的是控制信号还是业务数据”。如果一个组件同时有两种连接就分开画两条线哪怕看起来密集一点也比让看图的人猜强。5.3 忽略了异步回调和事件驱动链路AI应用里有很多异步逻辑尤其是Agent调用外部工具的时候。模型给出一个工具调用请求系统去执行执行完再回填这个来回可能是秒级甚至分钟级的长耗时操作。很多架构图把工具调用画成同步请求完全没画“任务挂起、恢复、超时、重试”的状态变化。这类问题的本质是状态管理缺失。架构图里应该在编排层画出“任务状态存储”标注正在进行的工具调用、等待中的回复、超时策略。我在实际项目里吃过这个亏一个Agent要调一个外部查询接口接口偶尔要七八秒才返回同步等待把整个会话线程占死了后来改成异步轮询才解决。图里如果提前画出“异步等待”这个状态就不会用同步实现的思路去设计了。5.4 模型被画成黑盒输出质量没有反馈回路架构图里把模型画成黑盒没有问题因为模型内部确实不可解释。但很多团队画图时忘记画出“质量反馈回路”。这意味着系统一旦上线只能一直用、一直错没有任何机制把错误反馈回开发流程。质量反馈回路至少包含三个组件评测集一组标准问题和期望答案、评测任务触发器每次发布前跑一遍或定期抽样、回归分析与告警比较新旧版本回答差异。这一条回路在架构图里经常被画到系统外其实它应该是系统的一部分。特别是企业想把AI应用正经跑在生产环境时没有质量回路的架构等于盲飞。5.5 架构图过度设计画成了类图最后一个坑是过度表达。AI应用架构图的价值在于沟通但有人把它画得非常“精细”其实就是把代码类名、方法名、字段名全搬进了图里。一张架构图如果塞进了上百个节点基本没有人愿意看也就失去了沟通价值。解决思路是分层架构图只画到“可部署单元”和“关键依赖”的粒度具体的类和方法交给代码不要在架构图里重复。如果一张图有超过二十个主要组件就考虑拆分。我在团队里立了一个默认规则单张架构图不超过二十个核心节点超出就拆成子图主图只保持能让人看懂全貌的粒度。6. 架构图的后续生命力让它从一份文档变成一个协作工具画一张架构图不难难的是一直有这张图、一直有人拿它说话。6.1 架构图要进代码仓库跟着版本走AI应用的演进速度比传统应用还快模型换版本、Prompt大改、向量库换品牌、RAG切分策略调整。架构图如果只存在某个人电脑的draw.io文件里三个月后一定过期。我强烈建议把架构图迁移成代码化格式Mermaid或D2放到仓库的docs目录里随代码一起评审、一起合并、一起发布。代码化架构图的好处是可以diff。评审的时候大家能直接看到“这次改动把检索环节顺序换了”“新增了一个调用缓存服务”比描述性的文字变更更直观。这个习惯相当于把架构图从“快照”变成了“活文档”。6.2 用架构评审让图持续被使用架构图画出来不评审很快就被遗忘。我的做法是凡是涉及架构决策的改动先在PR描述里贴上对应的子图和链路说明评审时先看图再看代码。看图的顺序也反过来逼着画图的人保持图的最新状态。做AI应用还有一个特殊情况就是模型本身也在迭代。模型网关配置的文件里不同模型版本对应的流量切分比例应该画在部署图旁边。我见过一个项目因为模型版本悄悄切换用户评测分数波动很大后来在架构评审里把这个信息补到图上才让大家注意到“线上用的模型和评测时用的模型根本不是同一个”。这类问题远比代码Bug隐蔽而架构图恰好能把它暴露出来。6.3 我的一点实际体会做架构图这件事很多人觉得是额外负担但在AI应用领域我觉得它是投入产出比极高的习惯。我的切身体会是架构图最大的价值不在于画得多好看、多完整而在于它迫使你把“系统到底是什么”想清楚。哪怕你画的图只有你能看懂只要动笔画过你的设计至少从“感觉能做”推进到了“逻辑上成立”这一步。如果你正带着AI应用项目不妨从一次小型的架构图工作坊开始找一块白板把五层部件往上一摆让团队轮流解释“你为什么这么认为”。当你发现大家对同一个词的认知完全不同架构图的第一层价值就已经兑现了。之后再把图迁进仓库、跟着版本更新它就会从一个工作坊产物慢慢变成一个长期陪伴你迭代的协作工具。最后分享一个小技巧每张架构图右下角都标上“最后校对人”和“生成日期”。AI应用架构变化频繁一条过期的图比没有图更容易误导人。有了这个角落团队自然会形成看图先看时间的习惯也能避免拿着半年前的架构图讨论明天要上的新功能。