做AI应用架构师这几年我最烦的事有两件一是架构评审前发现PPT里的架构图和线上代码已经对不上二是给新同事讲系统时面对一张画得潦草的手绘图连自己都得先盯着脑补半天。后来我花了大半年时间把“画架构图”这件事直接从工作流里摘了出去——靠自动化转换工具让架构图自动生成。这篇文章就是我折腾出来的完整方法论适合那些既要做AI应用设计、又要负责方案落地、还不想整天泡在绘图工具里的架构师同行。1. 架构图在AI应用项目里为什么是刚需1.1 一个典型AI应用的架构到底有多复杂先别急着聊工具得先认清架构图对我们的意义。AI应用和传统CRUD系统最大的区别在于依赖链路特别长一个稍微像样点的AI产品背后通常站着这样一串组件前端负责交互采集API网关负责鉴权和路由应用服务层负责业务编排向量数据库负责相似度检索模型推理服务负责跑模型对象存储负责存原始素材消息队列负责异步任务再加上缓存、日志、监控。这些组件之间还有不同的通信协议HTTP、WebSocket、gRPC、消息订阅画出来完全是网状结构。我在跟算法团队对方案的时候感受特别深。算法同学关心的是一条数据从输入到推理结果返回全链路是否畅通工程同学关心的是服务边界和容灾运维同学关心的是部署形态和资源消耗产品经理关心的则是哪些环节会影响响应延迟。同一套系统每个人看到的视角都不同。没有一张清晰的架构图评审会就会变成各说各话的混沌现场。这也是为什么我一直认为AI应用架构师的核心交付物之一就是架构图。它不只是给别人看的文档更是你自己梳理系统边界、识别单点风险和依赖环的工具。画图的过程本质上是逼着自己把“系统到底怎么转”这件事想清楚。所以架构图不是锦上添花是刚需。1.2 手绘架构图的三个致命问题既然架构图这么重要为什么很多架构师反而越来越不爱画因为我踩过坑手绘架构图这条路走不通主要有三个原因。第一个是时间成本高得离谱。一张像样的分层架构图手绘至少要小半天。如果是AI应用这种节点多、关系乱的系统光是对齐图标、调布局、配颜色就能消耗一个下午。而且画完不一定对还要反复改。第二个是文档必然腐化。架构图最怕的不是画得丑而是和代码脱节。AI项目迭代速度有多快大家都清楚今天加了向量检索明天换了推理框架后天把消息队列从RabbitMQ换成Kafka。代码改完图往往没跟上过了两周再打开那张图跟实际系统已经完全是两个世界了。第三个是信息失真。手工画图时为了美观很容易隐去关键信息。比如某个服务依赖了外部接口为了版面好看就省略了某个调用关系存在超时重试为了简化就没标注。这些被“优化”掉的细节恰恰是线上故障时最致命的信息。所以我的结论很简单架构图必须跟着代码走必须可追溯、可验证、可自动更新。这正是自动化转换工具最核心的价值。下面的内容我就围绕“如何让架构图自动生成”这件事展开。2. 自动化转换工具选型四条路线怎么选2.1 四种主流自动化生成路线对比市面上的架构图自动生成方案归根结底是四种路线。我踩过不少坑把它们的适用场景整理成一张表方便大家根据自己项目的状态选型。路线输入源产出物适用场景典型工具代码逆向分析源代码、AST、字节码类图、模块依赖图、调用关系图存量系统梳理、单体拆分pyreverse、dependency-cruiser、sourcetrail配置文件解析YAML、JSON、TOML、Dockerfile部署架构图、基础设施关系图容器化部署、多云基础设施docker-compose-viz、cfn-diagram文本描述生成Markdown、结构化文本、DSL通用架构图、时序图、部署图方案设计、技术评审、文档沉淀Mermaid、PlantUML、Graphviz运行时观测数据Trace、Metrics、Span数据调用链拓扑图、流量依赖图线上排查、容量规划、性能分析Jaeger、SkyWalking、Callee这四条路线不是互斥的实际项目中往往是组合使用。比如我这边部署阶段用配置文件解析路线接口梳理阶段用代码逆向路线而评审和沉淀阶段用文本描述路线。关键在于你要清楚每一条路线解决的是哪个生命周期的问题。2.2 我的选型原则文本即图图即代码我个人的选型原则可以总结成一句话文本即图图即代码。原因很简单AI应用架构师也是工程师工程界最可靠的资产就是代码。如果架构图本身只是一张PNG图片那它很难进入版本控制、代码评审和自动化的体系。但如果架构图是由一段文本描述渲染出来的那这段文本就可以放进Git仓库可以被diff可以被review可以接进CI/CD流水线自动更新。这就是我为什么最终把重心放在Mermaid这套语法上。它的表达能力覆盖流程图、时序图、类图、状态图基本上架构师日常需要画的图都能搞定。而且生态成熟GitHub官方渲染、VS Code插件、Mermaid CLI、各类在线编辑器都有团队协作成本降得很低。当然光有Mermaid还不够。自动化的关键在于怎么把代码、配置、运行数据这些“事实来源”转换成Mermaid文本。这一步必须靠解析脚本和工具链来完成不能靠人肉翻译。这也是“自动化转换工具”和“画图工具”最根本的区别画图工具只是帮你把形状拖出来转换工具是直接从源头生成图描述。2.3 我的工具组合拳我把自己的工具链分成三层每层职责单一组合起来就是一套完整的流水线。第一层是“事实来源层”也就是你的代码仓库、docker-compose.yml、Kubernetes配置、OpenAPI文档、运行时指标。这些是架构图的唯一事实依据所有图都必须是它们推导出来的。第二层是“转换层”把配置和代码解析成中间结构。我常用的是Python脚本配合PyYAML、AST模块、json解析必要时也用现成工具。这一层输出的不是最终的图而是一个结构化的依赖关系集合。第三层是“渲染层”把中间的依赖关系拼装成Mermaid文本再用Mermaid CLI渲染成SVG或PNG。渲染产物直接被文档系统引用同时源文本进入Git仓库形成闭环。这套组合拳的好处是每一层都可以单独替换。今天换了K8s我可以只改第一层的事实来源和解析脚本渲染层完全不动明天想在图上加一个“网络隔离域”的视觉表达我只改渲染层的模板逻辑就行。3. 实操三套自动生成流水线照着抄就能用3.1 从docker-compose一键生成部署架构图AI应用依赖的中间件太多了Redis、PostgreSQL、RabbitMQ、Milvus、MinIO几乎每个项目都是一堆容器编排。docker-compose.yml本身就是一份权威的部署拓扑描述完全可以把它的YAML结构直接转换成架构图。我写了一个很简短的Python脚本核心思路是解析services块把每个服务变成一个节点把depends_on关系变成有向边。代码如下import yaml from pathlib import Path def compose_to_mermaid(compose_file: str) - str: with open(compose_file, encodingutf-8) as f: data yaml.safe_load(f) lines [graph LR] nodes [] edges [] for svc, conf in data.get(services, {}).items(): safe_name svc.replace(-, _).replace(., _) nodes.append(f {safe_name}[{svc}]) deps conf.get(depends_on, []) if isinstance(deps, dict): deps list(deps.keys()) for dep in deps: dep_safe dep.replace(-, _).replace(., _) edges.append(f {safe_name} -- {dep_safe}) lines.extend(nodes) lines.extend(edges) return \n.join(lines) if __name__ __main__: print(compose_to_mermaid(docker-compose.yml))用的时候在项目根目录执行python scripts/compose_to_mermaid.py docs/arch/deployment.md整个部署拓扑就出现在Markdown里了。之后用Mermaid CLI或者VS Code插件渲染成SVG。这里面有几个坑我必须提醒。第一个是depends_on的两种写法老版本是数组新版本支持对象形式带condition字段脚本里必须都兼容否则线上就会漏边。第二个是服务名里经常有中划线和下划线混用Mermaid节点ID里不能留中划线需要统一替换否则渲染时会报错。第三个是Compose文件里的环境变量插值比如${VAR:-default}解析时不要直接在脚本里做替换保持源文件原样否则生成的图跟真实运行环境反而对不上。3.2 从FastAPI自动生成接口与数据模型架构图AI应用最常见的服务形态就是FastAPI一套OpenAPI规范已经把接口路径、请求方法、标签、数据模型都定义好了。从OpenAPI生成架构图等于把接口文档变成可视化拓扑非常适合评审和目视检查。解析OpenAPI的要点是先提取tags。FastAPI里我们会给每个路由打tag比如user、rag、inference、admin这些tag天然就是微服务视角下的服务边界。脚本逻辑是每种tag生成一个“服务节点”客户端作为源头指向所有服务节点边上标注方法和路径。import json def openapi_to_mermaid(openapi_file: str) - str: with open(openapi_file, encodingutf-8) as f: spec json.load(f) lines [graph LR, Client[客户端]] services set() edges [] for path, methods in spec.get(paths, {}).items(): for method, op in methods.items(): if method.lower() not in (get, post, put, delete, patch): continue tag (op.get(tags) or [default])[0] services.add(tag) safe tag.replace(-, _).replace( , _) edges.append(f Client --|{method.upper()}| S_{safe}) for tag in sorted(services): safe tag.replace(-, _).replace( , _) lines.append(f S_{safe}[{tag}服务]) lines.extend(edges) return \n.join(lines) \n同类的脚本还可以用来生成数据模型类图。OpenAPI的components.schemas本身就是完整的数据模型定义转换成Mermaid的classDiagram非常顺手。代码很简单遍历每个schema的properties生成类和字段再把$ref引用变成继承或关联关系。这样一张ER风格的数据模型图就自动出来了。我常用的做法是这两个脚本一起跑一个生成接口拓扑图一个生成数据模型图放进同一次评审文档里。效果相当好接口图和模型图相互印证架构评审时信息量直接翻倍而且自动化生成的图永远不会出现“文档里的接口带已经不存在了”这种尴尬。3.3 用大模型从需求描述生成架构图初稿从代码和配置生成架构图很可靠但有个前提——你得先有代码。在方案设计阶段只有一段模糊的需求描述这时候怎么快速得到一张架构图草案我现在的方案是用大模型生成初稿然后人工修正。这块我也踩过不少坑最有价值的一条心得是Prompt必须给足结构约束否则大模型画出来的图只是一个“看起来很热闹”的分层根本经不起推敲。我常用的Prompt模板长这样你是资深AI应用架构师。请根据我提供的信息生成架构方案图。 硬性要求 1. 只输出一份Mermaid格式的流程图文本不要输出任何解释文字。 2. 图类型只允许使用 graph LR。 3. 节点按层次组织必须体现客户端、接入层/网关、应用服务、数据层/外部依赖。 4. 边统一用 -- 表示调用关系有必要的边要标注协议HTTP/gRPC/WS。 5. 节点总数控制在25个以内聚焦核心链路不要堆砌细节。 我的背景信息 [在这里粘贴技术栈、模块列表、关键依赖、部署方式、用户场景]把背景信息填进去之后输出的文本虽然不一定一次就能渲染成功但作为草稿完全够用。我拿到草稿之后会做三件事第一逐条检查节点是不是真的能在我的系统里找到对应模块大模型偶尔会幻觉出一些不存在的组件第二检查边的方向是否跟真实调用方向一致最离谱的一次是它把“用户请求”和“模型返回”画成了同一条双向边信息量直接丢失第三把不满足“25个节点以内”要求的图剪枝。大模型生成的图只能当底稿不能当终稿。但它最大价值在于能把你的经验沉淀成一套“输入需求就产出架构草图”的模板尤其是对AI这种组件高度标准化、模式相对固定的领域草稿的可用度比我预期高很多。4. 进阶玩法让架构图随着代码变更自动更新4.1 把架构图生成接入CI/CD流水线架构图自动生成的核心价值不是省一次画图的时间而是让架构图和代码永远保持同步。想达到这个效果必须把生成脚本接进CI/CD流水线。我的方案是每当主干分支有代码或部署配置变更CI任务自动重新生成架构图然后自动提交回仓库。下面是一个GitHub Actions的示例配置文件我在多个项目里都这么用稳定跑了很久name: auto-generate-architecture on: push: branches: - main paths: - docker-compose.yml - app/** - docs/architecture/** jobs: generate-arch: runs-on: ubuntu-latest steps: - name: 拉取代码 uses: actions/checkoutv4 - name: 安装依赖 run: | pip install pyyaml npm install -g mermaid-js/mermaid-cli - name: 运行生成脚本 run: | python scripts/gen_arch.py - name: 提交自动生成的架构图 uses: stefanzweifel/git-auto-commit-actionv5 with: commit_message: chore: auto update architecture diagrams这套流水线的好处是架构图变成了代码仓库里的“一等公民”。评审代码的时候顺带就能看到这次的改动是否影响了系统拓扑。我有一次排查一个性能问题就是通过CI自动生成的架构diff一眼发现某个服务突然多了一个对慢数据库的同步调用这要是在以前得靠人工盯代码才能发现。需要特别注意的是触发路径。一开始我把触发条件写得很宽任何文件变更都触发结果一天提交了十几张完全一样的架构图PR噪音大到队友直接找我投诉。后来收敛到了三个路径部署描述文件、业务代码目录、文档目录。没有变的就不需要重复生成节省CI时长也减少噪音。4.2 不同粒度的架构图如何自动聚合架构图不是只有一张系统级、应用级、服务级、部署级粒度完全不同。团队里不同角色需要的粒度也不一样。技术委员会看的是系统上下文开发看的是服务模块依赖运维看的是部署资源。我在实践里发现最重要的是按“分层视图”组织生成任务而不是把所有的信息塞进一张图。具体做法是固定三层视图系统上下文图System Context、容器图Container、部署图Deployment。每一层都由不同的脚本独立生成但都基于同一个事实来源。举个例子系统上下文图从docker-compose.yml提取“外部用户”和“核心服务”这两层只画大逻辑不画细节容器图从服务配置文件里提取更详细的内网依赖关系比如某个服务调用了哪个Redis实例部署图则从Kubernetes配置或Compose的resource定义里提取副本数、端口映射、网络域。三层图分开存到docs/arch/下的不同文件里CI流水线每次更新全部三层。这样下来每个角色看一眼自己关心的那层图就够了信息密度和准确度都高。总有人说“一张图看懂系统”是伪需求确实该做的是“一套图看懂系统”每张图各司其职。5. 常见问题与避坑指南实录5.1 自动生成的图太乱了根本没法看这个问题几乎100%会碰到尤其是第一次跑通代码解析脚本后生成的图密密麻麻全是节点和边。原因很直接脚本忠实还原了一切但架构图不是源码map图是要给人类看的必须聚焦。我的解决办法很简单分三步走。第一步设置节点阈值超过40个节点就自动触发剪枝优先剔除无依赖关系的叶子服务。第二步使用subgraph按领域分组把“数据层”“接入层”“应用服务”“基础设施”分别装进不同的视觉分组Mermaid的subgraph会让整张图的结构清晰很多。第三步过滤噪音边。比如健康检查接口的调用、监控指标上报这类边对架构分析没有实际帮助解析时直接在生成阶段丢掉不必走到图里再手动整理。这层逻辑最好下沉到转换脚本里不要图生成之后再人工去改。脚本里的过滤规则就是你的架构规范每个人提交代码后跑一遍CI得到的图都遵循同样的过滤标准。图就不会因为不同的人画图风格不同而千奇百怪。5.2 大模型生成的图语法报错怎么处理用大模型生成图最常遇到的就是Mermaid语法错误。节点ID里混入了中划线、中文括号、特殊字符或者边和节点的定义顺序有问题渲染时直接报错。第一次遇到这种情况我以为是模型能力不行后来把报错信息原样回传给大模型让它自己修发现大多数时候它能修对。更稳定的做法是在Prompt里限制语法子集只允许用graph LR和基本的节点边定义不要给它打开新特性的机会。同时在CI里加一步Mermaid CLI的渲染校验渲染失败直接让流水线失败逼着提交者去处理问题。Mermaid CLI的用法很简单mmdc -i docs/arch/system.mmd -o docs/arch/system.svg如果报错输出的错误信息会明确指向第几行配合大模型的修正能力基本两三轮就能修好。我的经验是跟大模型协作时要明确告诉它“根据这条报错信息修复不要重构整个图的结构”否则它会擅自把布局逻辑都改了反而制造新的问题。5.3 自动化生成和人工到底怎么分工写了这么多自动化但我要说句公道话架构图里最宝贵的那层信息自动化工具是生成不出来的那就是架构决策和设计意图。我现在的分工模式非常明确。自动化工具负责生成“事实层”的图也就是系统当前实际状态的忠实描述包括部署拓扑、服务依赖、接口关系这些硬信息。而“决策层”的图比如目标架构图、演进路线图、故障容灾拓扑图这些涉及未来规划和权衡取舍的仍然需要架构师亲手斟酌。我也并不追求后者自动化因为这类图的价值恰恰在于思考过程本身。所以最终的工作流是事实图靠自动化流水线持续更新保证永远和代码同步规划图在事实图基础上手工加工把架构决策的文字说明、待办标识、风险标记加进去。人工要做的是审图和决策不用做“把节点从一个位置拖到另一个位置”的体力活。写在最后自动化转换工具让我最大的改变是我再也不用因为画图占用太多时间而产生拖延和内疚感了。以前一想到要更新架构图就头疼连续拖几周之后就彻底不碰了现在架构图跟着代码自动刷新评审的时候打开最新的SVG所有人都看同一份“会动”的真实状态。对我来说这就是AI应用架构师该有的工作方式把重复劳动交出去把时间花在判断和权衡上。最后分享一个小技巧把你项目里最常改动的那份架构图模板固定下来沉淀到自己团队的标准模板库里。下次不管谁接手只需要跑两条命令就能在十分钟内拿到一套最新的、分层的、可评审的架构图资产。这套方法论不算复杂但它真的能把你从画图员的身份里解放出来。