AI生成架构图：自动解析代码仓库依赖，告别手动画图

但凡是维护过遗留系统的同学都有这种感觉：看代码勉强能看懂，但要在一张图里说清楚整个系统由哪些模块组成、依赖关系是什么，靠人肉梳理非常痛苦。最近 GitHub 全球趋势榜第一的项目，恰好就是干这个的——把代码仓库丢给 AI，它自动分析依赖，直接生成架构图。这篇文章就来拆解它的核心能力、怎么部署、怎么验证、怎么把批量任务和 API 接进自己的工作流。

这个项目的价值不在概念多复杂，而在于把“架构图”从一次性交付物变成了可自动更新的工程资产。以前画架构图靠架构师手动维护，代码一改，图就过期；现在 AI 从代码本身反向生成视图，只要跑一遍分析，模块、依赖、调用关系都能映射到图上。对于需要快速熟悉新项目、做代码评审、写技术文档的团队来说，这比截图 UML 再粘贴到 Wiki 里靠谱得多。

从材料信息看，这类项目重点解决三个问题：第一，代码结构解析，自动识别目录、模块、类、函数；第二，依赖关系抽取，区分项目内部依赖和外部第三方依赖；第三，架构图渲染，支持 Mermaid、PlantUML、SVG 等常见格式。如果还附带 Web 界面和 HTTP API，就可以直接接到自己的文档系统或 CI 流程里。

本文会用一套通用的本地部署流程来演示，具体命令和参数以你实际拿到的项目文档为准。全文覆盖：核心能力、适用场景、环境准备、安装启动、功能测试、API 调用、批量任务、资源占用、常见问题和最佳实践。想看这个项目适不适合自己，前两个章节就够了；打算直接跑通，从第三章开始按步骤操作。

1. 核心能力速览

表格里的参数都属于“这类项目”的通用能力描述，不是某个具体仓库的硬性规格。如果项目文档给出更精确的配置，以文档为准。

2. 适用场景与使用边界

2.1 适合谁

如果你是后端开发、架构师、技术负责人，或者经常要画系统架构图给团队看，这个项目值得试。它最擅长处理“代码量大、文档少、人员变动频繁”的存量系统。新同学入职第一天，扔一个仓库进去，能快速看到模块地图，比翻代码快得多。

做代码评审的时候也有用。AI 生成的依赖图可以直观看出哪个模块被大量引用、哪个模块存在循环依赖、哪一层被跨层调用。这些都是人工 Review 容易漏掉的问题。

2.2 能解决什么问题

• 快速生成系统全貌：不需要读所有代码，AI 帮你归纳模块边界和依赖关系。
• 保持架构文档新鲜：代码有更新，重新跑一遍分析，架构图同步更新。
• 辅助技术设计：在重构前先看当前依赖关系，评估改动影响范围。
• 批量梳理多个仓库：适用于微服务架构，把每个服务的目录扫一遍，汇总出整体依赖网络。

2.3 不适合什么场景

它不能替代架构师做技术决策。AI 生成的架构图是基于静态代码推断出来的，不代表运行时的真实调用链，也不包含异步消息、配置中心、注册中心、数据库中间件等动态信息。涉及核心交易链路、分布式事务、容灾降级这类复杂设计，仍然需要资深工程师人工把关。

2.4 安全与合规边界

这类工具会把代码内容发送给 AI 模型进行分析。如果代码属于公司核心资产，或者包含未公开的业务逻辑、客户数据、密钥硬编码，一定要谨慎：

• 优先选择本地部署的模型，不要把私有代码上传到不受控的外部服务。
• 如果必须使用云端大模型接口，先对代码做脱敏处理，移除密钥、内部域名、真实用户名等敏感信息。
• 生成架构图本身不构成软件版权授权，但代码版权和文档版权归原权利方，使用时注意授权范围。

后面写到的批量任务和接口服务，同样要遵循最小权限原则，只对必要的人员开放。

3. 环境准备与前置条件

这一章给出通用的环境检查清单。实际安装时先读项目 README，按官方要求来。

3.1 操作系统

Windows、macOS、Linux 都可以跑。如果只是本地小仓库测试，Windows 10/11 即可；如果要分析超大仓库或者做批量任务，推荐 Linux 服务器，内存和进程管理更稳定。

3.2 运行时环境

如果项目提供了独立的一键包，这些依赖可能已经被打包，不需要手动安装。但绝大多数开源项目还是走源码安装，先把基础环境配好。

3.3 CUDA 与 GPU

是否必须安装 CUDA，取决于你使用本地大模型还是远程 API：

• 只做静态代码解析 + 调用远程大模型 API：不需要 GPU，CPU 就能跑。
• 使用本地模型做代码理解：推荐 NVIDIA 显卡，安装驱动和 CUDA，并用 PyTorch 的 GPU 版本。

在 Linux 下查看 GPU 是否正常：

nvidia-smi

如果命令不存在，说明驱动没装好，先解决驱动问题再继续。

3.4 磁盘空间

磁盘占用主要来自三部分：源代码仓库、项目依赖、模型文件。单独跑一个小仓库，几百 MB 足够；如果要加载量化后的本地模型，预留 8GB 以上磁盘空间；如果模型较大，预留的空间要按模型体积翻倍。

3.5 端口检查

Web 服务默认端口可能是 7860、8080、8000 等，启动前先检查端口是否被占用：

# Linux / macOS lsof -i :7860 # Windows PowerShell netstat -ano | findstr 7860

如果端口被占用，换一个端口启动，或杀掉占用进程。服务只在本机调试时，建议监听127.0.0.1，避免暴露到公网。

4. 安装部署与启动方式

下面是一套通用安装流程。因为不同项目命令不一样，代码块中的仓库地址、脚本路径、参数名都需要按你实际部署的项目替换。

4.1 克隆代码

git clone <项目仓库地址> cd <项目目录>

如果项目有子模块，比如依赖特定语言解析器，需要同步子模块：

git submodule update --init --recursive

4.2 创建虚拟环境

python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate

需要说明的是，如果项目同时包含 Python 和 Node.js 代码，可能还要安装前端依赖：

npm install

4.3 安装 Python 依赖

pip install -r requirements.txt

如果安装速度慢，使用镜像源：

pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

安装过程中遇到编译错误，优先看缺了什么系统依赖库，比如libgraphviz-dev、build-essential，安装对应系统包后重试。

4.4 配置模型服务

如果项目支持连接外部大模型 API，一般通过环境变量配置：

export API_BASE_URL="http://your-model-service:8000/v1" export API_KEY="your-key"

如果使用本地模型，需要先启动模型服务。常见方案是使用兼容 OpenAI 协议的服务，再把这个地址填给架构图工具。

如果没有配置模型，项目也能运行，但可能只能做静态语法分析，无法生成语义层面的架构描述。建议至少接一个模型，效果才完整。

4.5 启动 Web 服务

提供 CLI 的项目通常长这样：

python app.py serve --host 127.0.0.1 --port 7860

或者提供了一键启动脚本：

./start.sh

Windows 下可能是：

start.bat

启动成功的标志：控制台日志出现Running on http://127.0.0.1:7860，浏览器能打开对应地址。如果日志报错，优先检查端口、模型地址、Python 依赖三项。

5. 功能测试与效果验证

启动之后不要急着扔大仓库进去，先用一个小项目验证基本功能，确认链路是通的。

5.1 基础生成能力测试

测试目标：确认 CLI 或 Web UI 能对一个示例仓库生成架构图。

操作步骤：

1. 准备一个简单的示例项目，包含 2 到 3 个模块，互相有依赖。
2. 通过命令行提交分析任务。
3. 等待分析完成，检查输出文件。

假设 CLI 是archgen，输出目录是./output，命令可能如下：

archgen analyze --repo ./examples/demo-app --output ./output --format mermaid

如果项目没有这个命令，去 README 里找 CLI 说明，替换成实际命令。

预期结果：

• 输出目录下生成.mmd文件或.md文件。
• 内容包含模块节点和连线关系。
• 使用支持 Mermaid 的编辑器（如 VS Code 插件、Typora）可以渲染成图。

判断标准：图上能看到项目的主要模块，依赖方向与源码中的 import/require 基本一致。

5.2 Web UI 测试

如果项目带 Web UI，启动后在浏览器上传一个代码目录：

1. 选择本地文件夹或直接粘贴 Git 仓库地址。
2. 点击“分析”按钮。
3. 等待分析进度条走完。
4. 查看生成的架构图。

常见失败情况：

• 上传目录过大导致浏览器卡死：先用小目录测试。
• 分析结果为空：可能是语言解析器没匹配到文件类型。
• 图片渲染空白：缺少 Graphviz 或前端依赖，按日志提示安装。

5.3 自定义参数测试

大多数架构图工具支持几个关键参数：

• 分析深度：只分析顶层目录还是递归到函数级别。
• 忽略目录：排除node_modules、build、dist、vendor等。
• 输出格式：Mermaid、PlantUML、SVG、JSON。
• 语言过滤：只分析指定语言。

测试时先调大忽略目录，把无关构建产物过滤掉，生成结果更干净。如果发现图太复杂，缩小分析范围；如果图太粗，增加分析深度。

5.4 不稳定因素验证

架构图生成最怕两种不稳定：一是同一份代码两次分析结果不一致，二是不同模型生成结果差异很大。

测试方法：对同一仓库连续跑三次，对比输出 JSON 或 Mermaid 的差异。如果模型参数使用固定温度（比如 temperature=0），结果应该基本稳定。如果差异过大，检查随机采样参数和提示词模板。

5.5 失败时的排查方向

6. 接口 API 与批量任务

如果项目提供 HTTP API，这是最有价值的部分。接上 API 后，架构图生成能力可以做成公司内部工具，也可以嵌入文档系统。

6.1 API 服务启动

先确认 API 服务是否随 Web 服务一起启动。有些项目需要单独指定--api参数：

python app.py serve --api --port 8000

启动后测试：

curl http://127.0.0.1:8000/health

返回ok或类似 JSON 说明服务正常。

6.2 调用一个分析任务

假设接口路径是/api/analyze，请求参数包含仓库路径和输出格式，cURL 示例：

curl -X POST http://127.0.0.1:8000/api/analyze \ -H "Content-Type: application/json" \ -d '{ "repo_path": "/data/projects/demo-app", "format": "mermaid", "ignore_dirs": ["node_modules", "build", "dist"] }'

返回内容可能是一个任务 ID，用于轮询结果；也可能直接返回架构图文本。

如果项目使用任务队列模式，会立刻返回task_id：

{ "task_id": "a3f8c92e-1b7d-4f0a-9d5f-1c2e3b4a5d6e" }

然后轮询查询接口：

curl http://127.0.0.1:8000/api/tasks/a3f8c92e-1b7d-4f0a-9d5f-1c2e3b4a5d6e

这个流程适合耗时较长的分析任务，避免 HTTP 请求长时间挂起。

需要注意，以上路径是示例，不是项目真实接口。实际使用时，先阅读项目的 OpenAPI 文档或/docs页面，确认请求和响应结构。

6.3 Python 调用示例

如果要在自动化脚本里调用，用requests很直接：

import requests import time base_url = "http://127.0.0.1:8000" headers = {"Content-Type": "application/json"} payload = { "repo_path": "/data/projects/demo-app", "format": "mermaid", "ignore_dirs": ["node_modules", "build", "dist"] } resp = requests.post(f"{base_url}/api/analyze", json=payload, headers=headers, timeout=30) resp.raise_for_status() data = resp.json() task_id = data.get("task_id") if not task_id: print(data.get("content")) else: while True: task_resp = requests.get(f"{base_url}/api/tasks/{task_id}", timeout=30) task_data = task_resp.json() status = task_data.get("status") if status == "completed": print(task_data.get("content")) break elif status == "failed": print("任务失败:", task_data.get("error")) break time.sleep(5)

这里的字段名都是假设，实际需要根据 API 返回结构调整。

6.4 批量任务设计

批量分析多个仓库时，不建议一次性并发几百个请求，容易把服务打爆。建议按以下步骤设计：

1. 用脚本扫描指定根目录，收集所有包含代码仓库的文件夹。
2. 逐个提交分析任务，记录task_id到日志文件。
3. 定时查询任务状态，失败的任务记录错误原因。
4. 所有任务完成后，统一检查输出文件。

示例脚本思路：

import os import requests import time import logging logging.basicConfig( filename="batch_arch.log", level=logging.INFO, format="%(asctime)s %(levelname)s %(message)s" ) base_url = "http://127.0.0.1:8000" repo_root = "/data/projects" repos = [os.path.join(repo_root, d) for d in os.listdir(repo_root) if os.path.isdir(os.path.join(repo_root, d))] for repo in repos: payload = {"repo_path": repo, "format": "mermaid"} try: resp = requests.post(f"{base_url}/api/analyze", json=payload, timeout=30) resp.raise_for_status() task_id = resp.json().get("task_id") logging.info(f"submitted {repo} task_id={task_id}") except Exception as e: logging.error(f"submit failed {repo}: {e}") time.sleep(10) print("等待任务执行，建议用 supervisor 或 cron 做轮询。")

批量任务一定要加日志和失败重试。最稳妥的方式是把待分析仓库列表写入队列文件，处理完一个标记一个，遇到失败可以断点续跑。

7. 资源占用与性能观察

这类工具的资源消耗主要分两部分：代码解析部分和 AI 模型调用部分。

7.1 内存观察

静态解析代码时，工具会把文件内容和语法树加载到内存中。小型仓库可能只占几百 MB，大型仓库或者包含大量 Node.js 依赖的项目可能吃掉几个 GB。建议使用top（Linux）、任务管理器（Windows）或htop观察。

如果内存持续增长且不释放，先检查是否一次性扫描了node_modules之类的巨型目录。在配置中增加忽略目录，通常能明显降低内存峰值。

7.2 CPU 消耗

代码解析阶段是 CPU 密集型，多核 CPU 会明显加快速度。如果项目支持多进程并发，可以通过--workers参数设置。不建议在本地开发机同时跑多个大型仓库分析，容易拖垮整个系统。

7.3 GPU 显存占用

如果架构图工具需要调用本地大模型，显存占用才是主要瓶颈。观察方法：

watch -n 1 nvidia-smi

• 7B 级别量化模型，显存占用大约在 4G 到 8G 之间，具体看量化位数和上下文长度。
• 13B 级别模型，可能超过 10G。
• 如果显存不足，优先使用 API 模式，把推理放到远端。

注意，不要只看模型加载后的固定显存，还要关注推理过程中的峰值显存。文本长度越长，峰值越高。如果分析超长代码文件导致显存溢出，可以启用模型分片加载、降低批量大小，或者把单个文件切成更小片段。

7.4 影响性能的关键因素

7.5 降低占用的实践

• 第一次分析先用--ignore-dirs排除构建产物。
• 只分析src或核心代码目录。
• 使用小模型或远程 API。
• 设置超时时间，避免慢任务长期占用资源。
• 批量任务使用队列，控制同时进行的任务数。

7.6 避免端口冲突和进程残留

服务崩溃后，端口可能仍被占。重新启动前先检查端口：

lsof -i :7860 kill -9 <PID>

如果服务是以后台方式启动，日志文件会越来越大，注意定期清理或配置日志轮转。

8. 常见问题与排查方法

如果问题出现在某个语言的具体解析过程，最好的方法是去项目 GitHub Issues 搜索对应语言和报错信息，通常能找到现成答案。提 Issue 前，把仓库结构、运行命令、完整报错日志都贴出来，维护者才能快速定位。

9. 最佳实践与使用建议

9.1 先小参数验证再大规模运行

不要刚装完就分析一个几百万行代码的仓库。先用一个小项目跑通全流程，确认输出符合预期，再把参数调大。第一次运行耗时长，大概率是忽略了目录太大，或者模型服务配置有问题。

9.2 保存一套最小可运行配置

把启动命令、模型地址、忽略目录、输出格式写进一个配置文件，放到项目根目录。团队里其他人使用时，只需要复制配置文件，不需要重新研究参数。

{ "repo_path": "./examples/demo-app", "output_dir": "./output", "format": "mermaid", "ignore_dirs": ["node_modules", "build", "dist", ".git"], "model": { "api_base": "http://localhost:8000/v1", "temperature": 0 } }

参考配置可以参考以上结构，具体字段按项目文档调整。

9.3 分目录管理输入、输出和日志

• input/repos/：存放待分析的代码仓库。
• output/arch/：存放生成的架构图。
• logs/：存放批量任务日志。

这可以避免把代码和生成结果混在一起，也方便做增量分析。每个仓库的分析结果按仓库名命名，后续需要对比历史版本时更清晰。

9.4 批量任务要做幂等和重试

批量分析时，如果中途失败，重新执行任务可能会重复生成。建议每个任务都生成固定唯一的repo_id，以repo_id作为输出文件名。任务重启时，先检查输出文件是否存在，存在则跳过或追加更新时间，避免重复计算。

9.5 接口服务要限制访问范围

如果 API 服务是给内部工具用的，启动时把 host 绑定到内网地址，不要暴露公网。如果必须对外开放，加上认证和鉴权，例如 API Key 或 OAuth2。代码仓库路径参数也不能让任意用户传入，否则可能被用来探测服务器文件系统。

9.6 涉及敏感代码必须脱敏

AI 架构图工具会把代码内容发给模型，如果代码中有硬编码的密码、Token、内网 IP，一定要在做分析前处理掉。简单做法是在测试副本里用正则替换敏感字段：

# 示例：把疑似密钥替换成占位符 sed -i 's/your-secret-token-here/<REDACTED>/g' src/config.py

更稳妥的方案是提前整理一份脱敏后的代码仓库，只包含结构信息，不包含真实业务数据。

9.7 生成结果必须人工复核

AI 生成的架构图不等于真实系统架构。依赖分析可能漏掉反射调用、Spring 注解、接口动态绑定等运行时行为。输出结果在用于技术方案评审前，要有熟悉项目的开发者逐层核对，确保模块边界和依赖方向正确。

9.8 定期重新生成

架构文档最怕过期。可以把架构图生成过程接入 CI 流水线，每次主分支有代码合并后自动跑一次任务，并把最新架构图上传到文档站点。这样团队看到的图永远反映最近代码状态，而不是半年后的过期图纸。

10. 总结与下一步

这个项目最值得尝试的点，是它把“看懂代码 -> 画架构图”这一过程自动化了。对于代码仓库数量多、模块依赖复杂的团队，它能够明显降低文档维护成本。建议第一次部署后先用一个小型 Java 或 Go 项目验证，看看识别出的模块边界是否符合预期，再决定是否引入到正式工作流。

最容易踩的坑有三个：一是模型服务没配置好，导致只能生成静态结构图，缺少语义分析；二是没有排除node_modules、build等目录，导致输出图特别乱；三是直接把生成结果当作最终架构视图，缺少人工复核。把这三点控制好，剩下的就是规模问题。

后续可以继续扩展的方向包括：把架构图生成接入 CI，在代码合并后自动更新文档；结合本地大模型做私有化部署，避免代码出网；对微服务仓库批量扫描，生成全局服务依赖拓扑；甚至可以用自然语言对话的方式，让 AI 解释某个模块的职责和变更影响范围。这些都是基于现有能力往上叠加的玩法，值得持续跟进。