央企开源的 AI 平台长什么样？元景万悟部署 + 架构全景拆解

📌 本文是《从零吃透企业级 AI 平台：元景万悟源码学习手记》系列第一季·源码学习篇的第 1 篇🎯 读完本文你将：① 理解企业级 AI 平台的整体架构 ② 能在本地一键部署万悟 ③ 能画出从用户请求到模型推理的完整调用链⏱️ 预计阅读时间：25 分钟 | 动手实践：40 分钟💻 环境要求：一台 8G 内存以上的电脑（Mac / Linux / Windows 均可）

一、这篇文章要解决什么问题？

如果你是一个有开发基础的程序员，最近想学 AI，你大概率会遇到这个困境：

"RAG 我看了几篇文章，Agent 我也听了几个播客，MCP 协议我也知道个大概……但这些东西到底怎么组合成一个能用的产品？"

零散的知识点就像一堆散落的乐高积木。你认识每一块，但不知道最终能拼成什么。

元景万悟（Wanwu） 就是那个"拼好的成品"。它是中国联通开源的企业级 AI 智能体开发平台，GitHub 上已有 4200+ Star，采用 Apache 2.0 许可（商用无限制），后端用 Go 语言编写。

它把当前最热门的 AI 技术全部整合在一个平台里：

所以这个系列的目标是：以万悟为"教材"，把上面每一项技术从原理到源码到动手全部吃透。

而今天第 1 篇，我们先做两件事：把它跑起来，然后看懂它的全貌。

二、核心概念：企业级 AI 平台到底在做什么？

2.1 一个类比

把万悟想象成一个 "AI 应用的中央厨房"：

┌─────────────────────────────────────────────┐

│           AI 中央厨房（万悟）                  │

│                                             │

│  🥬 食材仓库        →  模型管理（各种大模型）          │

│  📖 菜谱库          →  知识库 / RAG（企业文档）        │

│  🔪 厨具            →  MCP 工具（100+ 外部能力）      │

│  👨‍🍳 厨师           →  Agent 智能体（推理 + 决策）     │

│  📋 做菜流程        →  工作流引擎（多步骤编排）        │

│  🏪 前厅管理        →  多租户 / 权限（谁能用什么）     │

│                                             │

│  顾客（用户）点菜 → 厨房做菜 → 上菜（流式返回回答）     │

└─────────────────────────────────────────────┘

单独的 RAG 只是一本菜谱，单独的 Agent 只是一个厨师。万悟的价值在于：它把厨房的所有环节都建好了，而且是企业级的（多人同时用、权限隔离、安全合规）。

2.2 技术栈一览

💡 给小白的定心丸：你不需要精通以上所有技术。Go 代码我会逐行注释，Docker 操作我会给出完整命令。你只需要有任意一门语言的开发经验（Python / Java / JS 都行），就能跟下来。

三、动手部署：把万悟跑起来

3.1 环境准备

必须安装的软件：

验证安装：

docker --version# 预期输出：Docker version 24.x.x 或更高docker compose version# 预期输出：Docker Compose version v2.x.xgit--version# 预期输出：git version 2.x.x

⚠️ Windows 用户注意：Docker Desktop 需要开启 WSL2 后端。安装时勾选"Use WSL 2 instead of Hyper-V"。

⚠️ 国内用户注意：拉取 Docker 镜像可能很慢。建议配置镜像加速：Docker Desktop → Settings → Docker Engine → 添加：

{"registry-mirrors": ["https://docker.1ms.run","https://docker.xuanyuan.me"]}

修改后点 "Apply & Restart"。

3.2 克隆代码 & 启动

# Step 1：克隆项目git clone https://github.com/UnicomAI/wanwu.gitcd wanwu# Step 2：查看项目结构（先有个印象）ls-la

你会看到类似这样的目录：

wanwu/├── cmd/                    # 各微服务的 main.go 入口├── internal/               # 核心业务代码（后面几篇重点看这里）├── api/                    # API 定义├── proto/                  # gRPC 协议文件├── web/                    # 前端代码├── docs/                   # 文档和图片资源 ← 本系列图片来源├── docker-compose.yml      # 👈 一键部署的核心文件├── .env.example            # 环境变量模板├── Makefile                # 构建脚本└── README.md# Step 3：配置环境变量cp .env.example .env# 用你喜欢的编辑器打开 .env，检查以下关键配置：# - MYSQL_ROOT_PASSWORD=xxx     （数据库密码，保持默认即可）# - REDIS_PASSWORD=xxx          （Redis 密码）# - MINIO_ROOT_PASSWORD=xxx     （MinIO 密码）# 如果是本地学习，全部保持默认就行，不用改。# Step 4：一键启动（首次会拉取镜像，可能需要 10-30 分钟）docker compose up -d# Step 5：查看服务状态docker compose ps

✅ 预期结果：docker compose ps 显示所有服务状态为 Up：

NAME                  STATUSwanwu-mysql           Upwanwu-redis           Upwanwu-minio           Upwanwu-rag-service     Upwanwu-app-service     Upwanwu-assistant       Upwanwu-mcp-service     Upwanwu-operate         Upwanwu-frontend        Up

❌ 如果某个服务起不来：

# 查看具体服务的日志docker compose logs -f <服务名># 例如：docker compose logs -f wanwu-rag-service# 常见问题 1：端口被占用# 解决：修改 .env 中的端口映射，或杀掉占用进程# 常见问题 2：镜像拉取超时# 解决：配置国内镜像源（见 3.1），然后 docker compose pull 重新拉取# 常见问题 3：内存不足（Docker 默认只分配 2G）# 解决：Docker Desktop → Settings → Resources → Memory → 调到 8G

3.3 首次登录 & 功能巡览

浏览器打开：http://localhost:8081

默认账号：admin默认密码：Wanwu123456

▲ 登录后的管理后台首页（图片来源：GitHub 仓库 docs 目录）

登录后，花 10 分钟把每个菜单点一遍：

3.4 接入第一个模型（5 分钟体验 AI 对话）

万悟本身不包含大模型，需要你接入一个。最快的方式是接入 Ollama 本地模型：

# 安装 Ollama（如果还没装）# Mac/Linux：curl-fsSL https://ollama.com/install.sh | sh# Windows：去 https://ollama.com/download 下载安装包# 拉取一个轻量模型（约 4.7G，需要等一会儿）ollama pull qwen2.5:7b# 验证模型可用ollama run qwen2.5:7b "你好，请用一句话介绍你自己"

然后在万悟平台中：

1. 进入 「模型管理」→「添加模型」

2. 类型选择：Ollama

3. 地址填写：

   http://host.docker.internal:11434

   ⚠️ 这个地址是 Docker 容器内访问宿主机的方式。Linux 用户可能需要改成 http://172.17.0.1:11434

4. 模型名称：qwen2.5:7b

5. 点击「测试连接」→ 看到 ✅ 表示成功

6. 保存

▲ 在模型管理页面添加 Ollama 模型

接下来：

1. 进入 「智能体」→「新建」

2. 名称随便填，比如"我的第一个 Agent"

3. 模型选择刚才添加的 qwen2.5:7b

4. System Prompt 填：你是一个友好的AI助手。

5. 保存 → 点击「对话」

6. 输入"你好" → 看到流式返回的回答

🎉 恭喜！你已经跑通了"用户 → 平台 → 模型 → 回答"的完整链路。

四、架构全景：万悟的内部长什么样？

4.1 微服务拆分

万悟不是一个单体应用，而是由多个微服务组成的。打开 cmd/ 目录：

cmd/├── rag-service/        # RAG 知识库服务（文档解析、向量化、检索）├── app-service/        # 应用服务（API Key、敏感词过滤、安全护栏）├── assistant-service/  # 智能体服务（Agent 推理、对话管理）├── mcp-service/        # MCP 工具服务（工具注册、调用代理）├── operate-service/    # 运营服务（系统设置、用户管理）└── ...

▲ 元景万悟整体架构（图片来源：GitHub 仓库 README）

为什么要拆成微服务？ 因为企业场景下：

• RAG 检索是 CPU/内存密集型（向量化、ANN 搜索）

• Agent 推理是 IO 密集型（等 LLM 返回）

• 它们的扩缩容策略完全不同

4.2 一个请求的完整旅程

当你在对话框输入"出差报销流程是什么？"并按下回车：

用户浏览器    │    │  HTTP POST /api/v1/assistant/chat    │  Body: { "messages": [{"role":"user","content":"出差报销流程是什么？"}] }    │  Header: Authorization: Bearer     ▼┌─────────────────────────────────────────────────┐│  Nginx（前端容器）                                        ││  - 静态资源服务                                           ││  - 反向代理 /api/* → 后端网关                             │└────────────────────┬────────────────────────────┘                                                  ▼┌─────────────────────────────────────────────────┐│  app-service（应用服务）                                  ││  - JWT 鉴权：验证 token，提取 user_id / tenant_id         ││  - 敏感词检测：输入内容过安全护栏                           ││  - 路由：根据 assistant_id 找到对应的 Agent 配置           │└────────────────────┬────────────────────────────┘                                                  ▼┌─────────────────────────────────────────────────┐│  assistant-service（智能体服务）                           ││                                                         ││  1. 加载 Agent 配置（关联了哪些知识库、工具）               ││  2. 组装 System Prompt                                  ││  3. 判断是否需要 RAG 检索 ──→ 是 ──→ 调用 rag-service    ││  4. 判断是否需要工具调用 ──→ 是 ──→ 调用 mcp-service     ││  5. 将检索结果 + 用户问题 → 组装最终 Prompt               ││  6. 调用 LLM（通过模型适配器）                            ││  7. 流式返回（SSE）                                     │└──────┬──────────────────────────────┬───────────┘                ▼                                                                       ▼┌──────────────┐              ┌──────────────┐│ rag-service               │              │ 模型适配器层           ││                                  │              │                                 ││ 1.问题向量化              │              │ OpenAI API?           ││ 2.向量检索                 │              │ Ollama?                  ││ 3.关键词检索              │              │ 元景?                      ││ 4.混合排序                 │              │                                ││ 5.返回Top-K              │              │ 统一走                      ││   文本块                     │              │ /v1/chat/                 │└──────────────┘              │ completions             │                                                     └──────────────┘

📌 这张图非常重要。建议你用 draw.io 或 Excalidraw 自己画一遍。后面每一篇博客，我们都会在这张图上"放大"某一层。

4.3 源码分层结构

以 rag-service 为例，打开 internal/rag-service/：

internal/rag-service/├── handler/          # 接口层：接收 HTTP/gRPC 请求，参数校验│   └── search.go     #   → 对应"用户发起检索"这个动作├── service/          # 业务层：核心逻辑编排│   └── search.go     #   → 调用 embedding → 调用向量库 → 融合排序├── repository/       # 数据层：数据库 / 向量库 / 外部 API 调用│   ├── vector.go     #   → 向量数据库的 CRUD│   └── document.go   #   → 文档元数据的 MySQL 操作├── model/            # 数据模型：struct 定义│   └── chunk.go      #   → 文本块的数据结构└── config/           # 配置：数据库连接、模型地址等

阅读顺序建议：handler → service → repository，从上往下，跟着请求走。

4.4 数据流：一份文档的"一生"

PDF 上传  → MinIO 存储原始文件  → rag-service 拉取文件  → MinerU 解析（PDF → Markdown）  → 文本分块（Chunking）  → Embedding 模型向量化  → 写入向量数据库 + 关键词索引  → 状态标记为"可用"用户提问  → 问题向量化  → 向量检索 + 关键词检索  → RRF 融合排序  → 取 Top-K 文本块  → 注入 Prompt  → LLM 生成回答

五、自己画一张架构图（巩固练习）

🎯 目标：不看上面的内容，凭记忆画出万悟的架构图

打开 Excalidraw，画出：

1. 最外层：用户浏览器 + Nginx

2. 中间层：5 个微服务（app / assistant / rag / mcp / operate）

3. 底层：MySQL + Redis + MinIO + 向量数据库

4. 外部：Ollama / OpenAI API（模型服务）

5. 箭头：标出请求方向和数据流向

六、总结 & 下一篇预告

本文要点回顾

1. ✅ 万悟是中国联通开源的企业级 AI 平台，覆盖 RAG / Agent / MCP / 工作流 / 多租户

2. ✅ 后端用 Go 语言，微服务架构，Docker Compose 一键部署

3. ✅ 一个用户请求经过：Nginx → 鉴权 → Agent 推理 → RAG 检索 → 模型调用 → 流式返回

4. ✅ 源码分层：handler → service → repository，跟着请求读

课后作业

• 在本地成功部署万悟，所有服务 Up

• 接入 Ollama 模型，完成一次对话

• 画出架构全景图（手绘或用工具）

• 浏览 cmd/ 和 internal/ 目录，记录每个服务的职责

• 在万悟平台上把每个菜单都点一遍，截图保存

下一篇预告

第 2 篇：一个请求的旅程——万悟如何管理 10 种不同的 AI 模型

参考资源

• 元景万悟 GitHub：https://github.com/UnicomAI/wanwu

• Docker 官方文档：https://docs.docker.com/

• Ollama 官方文档：https://ollama.com/

• Go 语言官方 Tour：https://go.dev/tour/

📮 如果这篇文章对你有帮助，欢迎 点赞 / 收藏 / 关注🔔 下一篇：《一个请求的旅程——万悟如何管理 10 种不同的 AI 模型》