1. 项目概述：一个企业级AI Agent开发平台的深度拆解

最近在开源社区里，一个名为“万悟”（Wanwu）的AI Agent开发平台引起了我的注意。这并非又一个简单的“玩具级”开源项目，而是由中国联通旗下“元景”团队推出的、定位为企业级的AI应用一站式开发平台。作为一个在AI工程化领域摸爬滚打了多年的从业者，我深知将一个大型语言模型（LLM）的能力真正落地到企业复杂的业务流程中，中间隔着多少“坑”。从模型选型、知识库构建、工具链集成，到最终的权限管控和系统集成，每一步都需要大量的工程化工作。万悟平台的出现，恰好瞄准了这个痛点，它试图提供一个“开箱即用”的、覆盖AI应用全生命周期的解决方案。

简单来说，你可以把万悟理解为一个“AI应用的操作系统”或“AI应用的低代码开发平台”。它集成了模型管理、知识库（RAG）、工具调用（MCP）、可视化工作流编排、智能体（Agent）开发框架等核心模块，并提供了多租户、API服务等企业级特性。最吸引人的是，它采用了对开发者极其友好的Apache 2.0开源协议，这意味着无论是个人开发者、创业公司还是大型企业，都可以基于它进行自由的二次开发和商业化部署，而无需担心复杂的许可证限制。这在国内的开源AI项目中，算是一个相当有诚意的姿态。

在接下来的内容里，我将以一个技术实践者的视角，带你深入万悟平台的内部，不仅会手把手演示如何从零部署和上手，更会剖析其核心架构的设计思路、各功能模块的实战用法，以及在实际企业场景中落地时可能遇到的“坑”和应对技巧。无论你是想快速搭建一个内部智能问答机器人的技术负责人，还是希望研究AI Agent平台架构的开发者，相信这篇深度解析都能给你带来实实在在的参考价值。

2. 核心架构与设计思路解析

2.1 为什么需要“一站式”AI Agent平台？

在深入万悟的技术细节之前，我们有必要先理解它所解决的问题域。当前，企业利用大模型技术构建应用，普遍面临几个核心挑战：

技术栈碎片化 ：一个完整的AI应用可能涉及多个环节：你需要接入一个或多个LLM API（如GPT-4、Claude或国内的各种大模型），需要搭建向量数据库和检索系统来做知识库（RAG），需要让模型能调用外部工具（如查询数据库、发送邮件），还需要设计复杂的对话逻辑或业务流程。每个环节都对应着不同的技术选型和运维成本。

工程化门槛高 ：将上述技术栈整合成一个稳定、可运维、可扩展的生产系统，需要大量的后端开发、运维和AI工程经验。例如，如何管理不同模型的API密钥和计费？如何保证RAG检索的准确性和效率？如何设计一个可维护的Agent执行流程？这些问题往往让业务团队望而却步。

企业级需求缺失 ：很多开源项目侧重于单点功能的实现，但缺乏企业级应用必需的特性，如多租户支持（为不同部门或客户隔离数据和成本）、细粒度的权限控制、审计日志、与现有OA/CRM系统的API集成能力等。

万悟平台的设计目标，正是为了解决这些“最后一公里”的问题。它采用微服务架构，将上述功能模块化，并通过一个统一的控制平面（BFF层）进行管理和编排。这种设计思路，让开发者可以更专注于业务逻辑本身，而非底层基础设施的搭建。

2.2 平台核心模块深度解读

根据官方文档和代码结构，我们可以将万悟的核心能力分解为以下几个层次：

1. 基础设施层（模型与计算） 这是平台的基石。万悟的“模型中心”支持接入数百种开源和闭源的大模型，不仅包括国际主流的OpenAI API兼容模型，也深度适配了联通元景自身的模型生态。更重要的是，它支持vLLM、TGI等高性能推理后端，这意味着企业可以在自己的GPU集群上私有化部署大模型，完全掌控数据和算力。这种“云原生+私有化”的混合支持模式，很好地平衡了灵活性与安全性。

2. 能力中间件层（RAG、MCP、工作流） 这是平台的核心价值所在。

  • 高精度RAG引擎 ：万悟的RAG并非简单的“文本切分-向量化-检索”三步走。它集成了多模态检索、级联分割、自适应分割等技术，并特别强调了其GraphRAG能力。GraphRAG通过构建知识图谱来理解文档中实体间的关系，在需要进行多跳推理或跨文档总结的复杂问答场景下，能显著提升答案的准确性和逻辑性。官方宣称其在MultiHop-RAG基准测试中，F1分数比Dify高出17.2%，这个数据值得关注。
  • MCP（模型上下文协议）集成 ：这是让AI模型“手眼通天”的关键。MCP是一种标准化的协议，允许模型安全、规范地调用外部工具（如GitHub、Slack、数据库）。万悟内置了100多个精选的行业MCP服务器，并支持用户导入自定义的MCP，极大地扩展了Agent的能力边界。
  • 可视化工作流引擎 ：对于复杂的业务逻辑，单纯的对话式Agent可能力不从心。万悟的工作流模块提供了一个低代码的拖拽画布，可以将大模型调用、条件判断、API调用、知识库查询等节点像搭积木一样组合起来，实现端到端的业务流程自动化。这对于合同审核、报销审批等有固定规则的场景非常实用。

3. 应用构建层（Agent与API） 在这一层，开发者可以基于上述能力，快速构建两类应用：

  • 智能体（Agent） ：基于Function Calling范式，结合预设指令（Prompt）、知识库、MCP工具和工作流，创建具备特定目标的对话式AI助手。
  • 后端即服务（BaaS） ：所有通过平台构建的Agent、工作流或知识库问答，都可以通过标准的RESTful API暴露出来，方便与企业现有的IT系统（如OA、CRM）进行深度集成。平台提供的细粒度权限控制，确保了API在生产环境中的安全稳定运行。

4. 平台管理与生态层 包括多租户体系、应用市场、模板广场、安全护栏等。多租户是企业级平台的标志，它允许平台管理员为不同团队创建独立的租户，实现资源、数据和成本的隔离。模板广场内置了50多个经过优化的行业提示词模板，能帮助业务人员快速启动项目。

设计心得 ：万悟的架构体现了一种“分层解耦，模块化组合”的思想。这种设计的好处是显而易见的：企业可以根据自身需求，选择全部或部分模块进行部署和集成。例如，一个已经拥有成熟向量数据库的团队，可以主要使用其工作流和Agent编排能力；而一个从零开始的团队，则可以享受其全栈解决方案的便利。Apache 2.0许可证则为这种灵活性提供了法律保障，消除了商业化的后顾之忧。

3. 从零开始：实战部署与核心配置指南

理论讲得再多，不如亲手部署一遍来得实在。下面我将以最常用的Docker Compose方式，带你完成万悟平台的本地部署，并详细解释每个关键配置项的含义。

3.1 环境准备与前置检查

在开始之前，请确保你的服务器或本地开发机满足以下条件：

  • 操作系统 ：Linux (Ubuntu 20.04+/CentOS 7+)， macOS 或 Windows (需安装WSL2)。对于生产环境，官方推荐使用国产化操作系统如openEuler、CULinux或麒麟。
  • Docker & Docker Compose ：这是部署的基石。请确保安装的是较新版本（Docker >= 20.10， Docker Compose >= v2）。
  • 硬件资源 ：这是最容易出问题的地方。官方推荐配置为8核CPU、32GB内存、200GB存储。 特别注意 ：Elasticsearch服务对虚拟内存映射有要求，在Linux上需要单独配置。

第一步：解决Elasticsearch启动报错（Linux系统必看） 如果你在Linux上部署，很大概率会在启动 elastic-wanwu 容器时遇到错误：“Memory limited without swap”。这是因为Elasticsearch默认要求 vm.max_map_count 内核参数至少为262144。

# 临时生效（重启后失效）
sudo sysctl -w vm.max_map_count=262144

# 永久生效，编辑 /etc/sysctl.conf，在文件末尾添加
vm.max_map_count=262144
# 然后执行
sudo sysctl -p

这个操作必须在启动Docker Compose之前完成，否则Elasticsearch容器将无法正常启动。

3.2 详细部署步骤与配置解析

假设我们已经从GitHub克隆了项目代码到本地。

git clone https://github.com/UnicomAI/wanwu.git
cd wanwu

1. 初始化环境变量 环境变量是配置的集中入口，理解它们至关重要。

# 复制环境变量模板
cp .env.bak .env
# 使用你熟悉的编辑器打开 .env 文件进行修改
vim .env

打开 .env 文件，你会看到很多配置项，我们重点关注以下几个：

  • WANWU_ARCH=amd64

    • 作用 ：指定系统架构。根据你的服务器CPU架构选择 amd64 （Intel/AMD）或 arm64 （苹果M系列、华为鲲鹏等）。
    • 实操注意 ：务必选对，否则拉取的Docker镜像不对，会导致容器无法启动。

  • WANWU_EXTERNAL_IP=localhost

    • 作用 ：平台对外访问的IP地址。如果你只是在本地浏览器访问，保持 localhost 即可。
    • 关键场景 ：如果你将万悟部署在服务器上（例如IP为 192.168.1.100 ），并且希望通过同一网络下的其他电脑访问， 必须 将此值修改为服务器的IP，如 WANWU_EXTERNAL_IP=192.168.1.100 。否则，前端页面可能无法正确连接到后端服务。

  • WANWU_BFF_JWT_SIGNING_KEY=

    • 作用 ：用于生成和验证JWT（JSON Web Token）的密钥。这是系统安全的核心，用于用户登录态保持和API鉴权。
    • 实操注意 ： 务必 将其设置为一个足够长且复杂的随机字符串。你可以用以下命令生成一个： 
      openssl rand -base64 32
      然后将输出结果填入。如果留空或使用简单字符串，会带来严重的安全风险。

  • WANWU_DB_NAME=wanwu_mysql

    • 作用 ：指定使用的数据库类型。默认是MySQL。如果你计划使用国产数据库如TiDB或OceanBase，需要修改为对应的配置，并启用相应的Docker Compose文件。

2. 创建Docker网络 为了让所有服务在同一个网络内方便通信，需要创建一个自定义网络。

docker network create wanwu-net

3. 启动所有服务 这是最关键的一步。根据你的架构选择命令：

# 对于 amd64/x86_64 架构系统
docker compose --env-file .env --env-file .env.image.amd64 up -d

# 对于 arm64/aarch64 架构系统（如Mac M系列、华为鲲鹏服务器）
docker compose --env-file .env --env-file .env.image.arm64 up -d
  • --env-file .env ：加载我们刚才修改的主配置文件。
  • --env-file .env.image.amd64 ：加载架构特定的镜像标签配置文件。这两个文件共同决定了拉取哪个版本的Docker镜像。
  • up -d ：以后台模式启动所有定义的服务。

4. 检查服务状态 启动完成后，建议使用以下命令查看所有容器是否都处于“Up”状态。

docker compose ps

你可能会看到 mysql-wanwu-setup 和 elastic-wanwu-setup 这两个容器的状态是“Exited (0)”。 这是完全正常的 。它们是一次性任务容器，负责执行数据库表初始化、Elasticsearch索引创建等准备工作，任务完成后就会自动退出。

5. 访问平台 在浏览器中打开 http://localhost:8081 （如果你修改了 WANWU_EXTERNAL_IP ，则替换为对应的IP）。 使用默认账号登录：

  • 用户名： admin
  • 密码： Wanwu123456 强烈建议 在首次登录后，立即在“系统设置”或用户中心修改默认密码。

3.3 国产化环境（信创）适配部署

万悟平台的一个突出亮点是对国产化软硬件环境的良好支持。如果你的部署环境是华为鲲鹏CPU + 国产操作系统 + 国产数据库，可以按以下步骤操作：

  1. 修改数据库配置 ：在 .env 文件中，将 WANWU_DB_NAME 修改为 wanwu_tidb 或 wanwu_oceanbase 。
  2. 启动对应的数据库服务 ： 
    # 启动 TiDB
docker compose --env-file .env --env-file .env.image.amd64 -f docker-compose.tidb.yaml up -d
# 或启动 OceanBase
docker compose --env-file .env --env-file .env.image.amd64 -f docker-compose.oceanbase.yaml up -d
  3. 启动主服务 ：与上述步骤3相同，使用 docker compose up -d 启动。平台会自动识别配置，连接到国产数据库。

避坑指南 ：

  1. 镜像拉取失败 ：由于网络原因，拉取Docker Hub镜像可能较慢或失败。项目贴心地提供了网盘备份（链接在README中）。如果遇到问题，可以下载离线镜像包，通过 docker load 命令导入。
  2. 端口冲突 ：万悟默认会占用多个端口（如8081前端，后端API端口等）。如果启动失败，检查端口是否被占用。可以在 docker-compose.yaml 文件中修改服务映射的宿主机端口。
  3. 磁盘空间不足 ：Elasticsearch和数据库都会持久化数据。确保 /var/lib/docker 或你指定的数据卷有足够空间（建议200GB以上）。
  4. 内存不足 ：32GB是推荐配置。如果内存不足，Elasticsearch和MySQL可能会频繁OOM（内存溢出）被系统杀死。可以尝试在 docker-compose.yaml 中为这些服务单独限制内存（ mem_limit ），但这不是根本解决办法，升级硬件才是正道。

4. 核心功能模块实战与技巧

成功登录平台后，我们终于可以开始探索其强大的功能了。我将以构建一个“智能合同审核助手”的场景为例，串联起模型管理、知识库、工作流和Agent等核心模块的使用。

4.1 模型管理：连接AI的“大脑”

没有模型，一切AI应用都是空谈。万悟的模型中心支持多种接入方式。

实战：接入联通元景大模型 这是最典型的接入方式。假设你已经从联通元景MaaS平台申请了API Key。

  1. 获取接入信息 ：你需要三样东西： API Key 、 推理URL 和 模型名称 。例如：
    • API Key: sk-abc123...xyz
    • 推理URL: https://maas.ai-yuanjing.com/openapi/compatible-mode/v1 (注意： 不要 包含 /chat/completions 后缀)
    • 模型名称: yuanjing-70b-chat (具体名称以平台为准)
  2. 平台内配置 ：在万悟后台，进入“模型管理” -> “添加模型”。
    • 模型类型选择“LLM”。
    • 供应商选择“联通元景”或“OpenAI兼容”（元景的接口兼容OpenAI格式）。
    • 填入上述信息。 关键点 ：模型名称必须与API后端支持的名称完全一致，否则会调用失败。
  3. 测试连接 ：保存后，使用平台提供的测试功能，发送一个简单问题（如“你好”），验证模型是否能正常返回结果。

接入其他模型 ：对于其他兼容OpenAI API的模型服务（如本地部署的Ollama、通义千问、DeepSeek等），流程大同小异。核心是确认对方的API端点（Endpoint）和认证方式（通常是Bearer Token）。对于Embedding模型和Rerank模型，接入方式类似，只是模型类型和推理URL的后缀不同（Embedding不需要 /embeddings ， Rerank不需要 /rerank ）。

经验之谈 ：

  • 模型别名 ：在添加模型时，除了官方名称，可以设置一个自己容易记忆的“别名”，方便在后续的工作流和Agent中选择。
  • 备用模型 ：对于生产环境，建议为关键应用配置备用模型。可以在工作流或Agent的“高级设置”中，指定主模型调用失败时自动切换的备用模型，提高系统可用性。
  • 成本监控 ：如果接入的是按Token计费的商用模型，务必关注平台内的使用统计，或通过模型的API自身提供的用量接口进行监控，避免意外开销。

4.2 知识库构建：打造专属的“知识引擎”

知识库是让AI“懂业务”的关键。我们以“公司合同范本与法规库”为例。

第一步：创建知识库

  1. 进入“知识库”模块，点击“新建”。
  2. 输入名称，如“公司合同法规库”。
  3. 关键选择：索引方法 。万悟提供多种检索方式：
    • 向量检索 ：最常用，基于语义相似度查找。适合回答概念性、解释性问题。
    • 全文检索 ：基于关键词匹配。适合查找具体的条款编号、特定名称。
    • 混合检索 ：结合两者，通常能获得更全面的结果。 对于合同审核这种需要精确性的场景，我推荐使用混合检索 。

第二步：文档解析与处理 这是影响RAG效果最关键的步骤之一。

  1. 上传文档 ：支持PDF、Word、Excel、PPT、TXT等多种格式。你可以一次性上传公司的《劳动合同范本》、《采购合同范本》、《民法典合同编》等相关PDF文件。
  2. 解析引擎 ：万悟支持两种文档解析方式：
    • OCR ：适用于扫描版PDF或图片中的文字提取。
    • MinerU模型 ：这是万悟集成的专有模型，对于文档中的 标题、表格、公式 有更强的解析和结构还原能力。 对于结构复杂的合同文件，强烈建议启用MinerU解析 ，它能更好地保留条款的层级关系。
  3. 文本分割（Chunking） ：
    • 常规分割 ：按固定长度（如500字符）分割。简单，但可能把一条完整的条款切断。
    • 父子分割（Parent-Child） ：这是更高级的策略。先按较大块（如1000字符）分割为“父文档”，再将其按较小块（如200字符）分割为“子文档”。检索时先定位到父文档，再精确定位到子文档。 对于法律合同这种逻辑性强、上下文关联紧密的文档，父子分割能显著提升检索精度 。
  4. 元数据管理 ：在上传时或处理后，可以为文档或段落添加元数据，如“文档类型：采购合同”、“生效日期：2023-01-01”、“部门：法务部”。后续可以通过这些元数据进行过滤查询，例如“只在采购合同中搜索付款条款”。

第三步：高级功能——GraphRAG 对于我们的合同知识库，可以尝试启用GraphRAG功能。

  1. 在知识库设置中启用“知识图谱”。
  2. 平台会自动分析文档，提取实体（如“甲方”、“乙方”、“违约金”、“不可抗力”）和关系（如“甲方 支付给 乙方”、“合同 包含 违约责任条款”）。
  3. 当用户提问“如果甲方逾期付款，需要承担什么责任？”时，系统不仅能找到提及“逾期付款”的段落，还能通过图谱关联到“违约责任”、“违约金计算方式”等相关条款，给出更全面、逻辑连贯的答案。

避坑指南 ：

  1. 分割策略是双刃剑 ：分割得太细，会丢失上下文；分割得太粗，会引入噪声。没有绝对标准，需要根据文档类型和问答场景进行测试调整。 建议 ：对同一份文档尝试不同分割参数，然后用一些典型问题测试检索效果。
  2. “垃圾进，垃圾出” ：如果上传的文档本身质量差（如扫描不清、格式混乱），解析效果会大打折扣。尽量使用清晰、结构化的电子版文档作为源文件。
  3. 及时更新与优化 ：知识库不是一劳永逸的。当有新法规或合同范本更新时，需要及时同步。平台支持对已有知识库进行文档的增删改。对于效果不好的问答，可以利用平台的“命中测试”功能，查看具体是哪段文本被检索出来，从而调整分割策略或优化文档内容。

4.3 工作流编排：可视化构建复杂业务逻辑

工作流适合将固定的、多步骤的业务流程自动化。我们的“合同审核助手”可以拆解成这样一个工作流： 接收合同文本 -> 提取关键信息 -> 查询知识库（法规/范本） -> 进行合规性对比 -> 生成审核报告与风险提示 。

实战：创建一个合同审核工作流

  1. 进入“工作流”模块，点击“新建” 。你会看到一个空白的画布。
  2. 从节点库拖拽组件 ：
    • 开始节点 ：设置为接收一个“合同文本”输入变量。
    • 大模型节点 ：连接开始节点。配置使用我们接入的 yuanjing-70b-chat 模型。在“系统指令”中编写Prompt，要求模型从合同文本中结构化提取信息，例如：“你是一个专业的法务助理。请从用户提供的合同文本中，提取以下信息：合同双方名称、合同标的、金额、付款方式、交付日期、违约责任条款、争议解决方式。请以JSON格式输出。”
    • 知识库节点 ：连接上一步。配置调用我们创建的“公司合同法规库”。将上一步模型提取出的“合同标的”（如“软件开发”）、“违约责任条款”等内容作为检索查询词（Query），去知识库中查找相关的规范条款和风险案例。
    • 条件判断节点 ：根据知识库检索结果，判断风险等级。例如，如果检索到“该付款方式存在垫资风险”的案例，则走“高风险”分支；否则走“低风险”分支。
    • 大模型节点（生成报告） ：连接条件判断节点的两个分支。这个节点的Prompt可以设计为：“根据提取的合同信息、检索到的相关法规条款和风险案例，生成一份合同审核报告。报告需包含：基本信息摘要、关键条款合规性分析、识别出的主要风险点（分高、中、低）、具体的修改建议。最后给出一个总体风险评级。”
    • 结束节点 ：输出最终的审核报告。
  3. 调试与测试 ：工作流支持“单步调试”。你可以输入一份示例合同，查看每个节点的输入输出，确保流程按预期运行。特别是大模型节点的输出，可能需要调整Prompt来获得更稳定的JSON格式。

工作流的强大之处 在于，它将不确定的LLM调用和确定性的业务逻辑（条件判断、API调用）结合了起来。你可以轻松地在工作流中加入“发送邮件通知法务人员”、“将审核结果写入CRM系统”等API节点，实现端到端的自动化。

4.4 智能体（Agent）开发：创建交互式助手

工作流是自动化的流水线，而Agent则是更灵活、更具交互性的“智能员工”。我们可以基于刚才的知识库和工作流，创建一个对话式的合同审核助手。

  1. 进入“智能体”模块，点击“新建” 。
  2. 基础配置 ：设定名称、描述，并选择一个大模型作为Agent的“大脑”。
  3. 能力赋予 ：
    • 指令（Prompt） ：这是Agent的“角色设定”。写一个清晰、具体的指令，例如：“你是一名专业的法务合同审核助手。你的核心职责是帮助用户分析合同文本，识别潜在的法律和商业风险。你必须基于我提供的知识库进行回答，不可编造信息。对于不确定的问题，应明确告知用户。你的回答应专业、清晰，并优先引用知识库中的条款依据。”
    • 知识库 ：关联我们创建的“公司合同法规库”。这样，Agent在回答时就会自动检索相关知识。
    • 工具（MCP） ：可以关联一些外部工具，比如“计算器”（用于计算违约金）或“联网搜索”（用于查询最新的司法解释）。但在这个场景下，核心工具是我们构建的工作流。
    • 工作流 ：关联我们创建的“合同审核工作流”。这是最关键的一步！这意味着，当用户在对话中提交一份完整的合同时，Agent可以自动调用这个工作流，执行复杂的审核流程，并将结构化的报告返回给用户。而对于简单的合同概念咨询，Agent则可以直接基于知识库进行对话。
  4. 会话开场白与调试 ：设置一个友好的开场白，如“您好，我是合同审核助手，请粘贴或上传您需要审核的合同文本。” 然后进入“调试”窗口，模拟用户提问，观察Agent的思考过程、工具调用情况，不断优化Prompt和工具配置。

Agent与工作流的区别与结合 ：工作流是 预设路径的自动化 ，适合标准化、流程固定的任务。Agent是 目标导向的对话式交互 ，适合处理边界模糊、需要多轮沟通的任务。将工作流作为Agent的一个“超级工具”，让Agent在合适的时机调用它，就能结合两者的优势，打造出既智能又可靠的业务助手。

4.5 MCP与技能广场：扩展Agent的“手脚”

MCP是Agent调用外部能力的桥梁。万悟内置了丰富的MCP服务器，也支持自定义。

使用内置MCP ：在“资源库”或“MCP广场”中，你可以看到诸如“天气查询”、“股票信息”、“GitHub操作”、“数据库查询”等上百个预置工具。只需点击“启用”，并在创建Agent或工作流时选择它们，你的AI就立刻拥有了这些能力。

导入自定义MCP ：如果内置工具不满足需求，你可以导入任何符合MCP协议的服务。这通常需要该服务提供一个 schema.json 文件来描述其接口。将MCP服务器的地址和必要的认证信息配置到万悟中，它就能被平台内的Agent和工作流所调用。

技能（Skills） ：这是一个更高级的概念。技能可以看作是一组预配置好的Prompt、工具和知识库的打包组合，用于解决某个特定领域的问题（例如“招聘简历筛选技能”）。万悟支持技能的创建、分享和导入，这有助于团队内部的能力沉淀和复用。

5. 企业级部署考量与性能调优

将万悟从本地测试环境迁移到生产环境，还需要考虑更多因素。

5.1 多租户与权限体系

万悟的多租户架构是其企业级特性的核心体现。

  • 组织与角色 ：管理员可以创建多个组织（如“研发部”、“市场部”），在每个组织下创建用户，并分配不同的角色（如“管理员”、“开发者”、“访客”）。
  • 资源隔离 ：每个租户（组织）下的模型配置、知识库、应用和数据都是相互隔离的，实现了数据和成本的分账管理。
  • 实操建议 ：在规划初期就设计好租户结构。对于中小型企业，可以按部门划分；对于ISV（独立软件开发商），可以为每个最终客户创建一个独立的租户。

5.2 性能优化建议

  1. 数据库优化 ：

    • MySQL/OceanBase/TiDB ：确保为数据库容器分配足够的内存和CPU资源。对于数据量大的知识库，需要关注向量存储和检索的性能。可以考虑对频繁查询的知识库表建立合适的索引。
    • Elasticsearch ：这是全文检索的核心。除了之前设置的 vm.max_map_count ，还需要根据数据量调整ES的堆内存（ -Xms 和 -Xmx 参数，通常在容器编排文件中设置），通常设置为系统可用内存的50%，但不超过32GB。

  2. RAG检索优化 ：

    • 混合检索权重 ：调整向量检索和全文检索在混合检索中的权重比例。对于强调语义理解的问题，提高向量权重；对于强调关键词匹配的问题，提高全文检索权重。
    • 重排序（Rerank）模型 ：在检索出Top K个相关片段后，使用一个专门的Rerank模型对它们进行精排，可以进一步提升最终答案的准确性。万悟支持接入Rerank模型，在知识库的高级设置中启用即可。
    • 缓存策略 ：对于高频且不变的知识库问答，可以考虑在应用层（即调用万悟API的上游系统）增加缓存，避免重复的检索和LLM调用，大幅降低响应延迟和成本。

  3. 模型推理优化 ：

    • 推理后端选择 ：如果私有化部署大模型，使用vLLM或TGI等高性能推理框架，可以极大提高吞吐量，支持更高的并发。
    • 请求批处理 ：对于异步或可延迟的处理任务，可以将多个请求批量发送给模型，能有效提升GPU利用率和整体处理速度。

5.3 高可用与监控

  • 服务高可用 ：对于生产环境，建议将Docker Compose部署方式转换为Kubernetes编排，这样可以方便地实现服务的多副本部署、滚动更新和故障自愈。
  • 监控告警 ：需要监控关键指标：各容器的CPU/内存使用率、服务响应时间、LLM API调用成功率与延迟、知识库检索耗时等。可以结合Prometheus和Grafana来搭建监控面板。
  • 日志收集 ：集中收集和分析容器日志，便于故障排查。可以使用ELK（Elasticsearch, Logstash, Kibana）或Loki + Grafana方案。

6. 常见问题排查与社区资源

即使在最顺利的部署中，也难免会遇到问题。这里汇总一些常见问题的排查思路。

Q1: 模型测试时一直报错“调用失败”或“超时”。

  • 检查网络连通性 ：确保部署万悟的服务器能够访问你配置的模型API地址（如 https://maas.ai-yuanjing.com ）。可以尝试在服务器上用 curl 命令直接测试。
  • 检查API Key和模型名称 ：这是最常见的问题。确认Key是否有权限、是否过期；确认模型名称与API提供商后台完全一致（注意大小写）。
  • 检查推理URL格式 ：确保URL没有多余的后缀。对于LLM，URL应到 /v1 为止；对于Embedding，应到 /v1 为止（不要 /embeddings ）。

Q2: 知识库文档上传成功，但问答时检索不到相关内容。

  • 检查分割策略 ：可能分割得太细或太粗，导致检索片段不包含答案。尝试调整分割长度或切换为“父子分割”。
  • 检查检索方式 ：尝试切换不同的检索模式（向量/全文/混合），看哪种效果更好。
  • 检查Embedding模型 ：确保知识库使用的Embedding模型已正确配置且运行正常。不同的Embedding模型对同一段文本生成的向量差异很大。
  • 进行“命中测试” ：在知识库管理界面，使用你的问题直接进行测试，查看系统实际检索到了哪些文本片段，这是最直接的调试手段。

Q3: 工作流或Agent调用非常慢。

  • 定位瓶颈节点 ：使用工作流的调试功能，查看每个节点的执行耗时。瓶颈通常出现在：1) 大模型调用（网络延迟或模型本身慢）；2) 知识库检索（特别是首次检索，需要加载向量索引）。
  • 优化知识库 ：如果知识库过大，考虑按主题拆分为多个更小的知识库，在调用时按需选择。
  • 设置超时与重试 ：在工作流节点或Agent的工具调用配置中，可以设置合理的超时时间，并配置失败重试策略。

Q4: 如何获取帮助与进行二次开发？

  • 官方文档 ：项目README和 configs/microservice/bff-service/static/manual/ 目录下的中文手册是最权威的参考资料，涵盖了从安装到每个功能的详细操作说明。
  • 社区交流 ：项目提供了多个QQ群（如1019579243），开发者可以在里面提问和交流。在提问前，最好先准备好你的环境信息、错误日志和已经尝试过的排查步骤。
  • 源码学习 ：项目采用Go语言开发，结构清晰。如果你想深度定制或了解实现原理，阅读源码是最好的方式。特别是 bff-service （后端聚合层）和各个微服务的代码，能让你理解平台内部的数据流和业务逻辑。

万悟AI Agent平台作为一个新兴但架构清晰、功能全面的开源项目，为企业落地AI应用提供了一个强有力的“工具箱”。它的价值不仅在于其开箱即用的功能，更在于其开放、可扩展的架构，让企业能够在此基础上，构建真正贴合自身业务需求的智能系统。从我的实践经验来看，在项目初期利用这样的平台快速完成原型验证和概念落地，能极大节省时间和人力成本，让团队更专注于业务逻辑本身。当然，任何平台都无法解决所有问题，深入理解其原理，根据实际情况进行调优和定制，才是成功的关键。希望这篇超详细的解析，能成为你探索AI Agent世界的一块坚实垫脚石。

# RAG
Logo
龙虾开发者社区

小龙虾开发者社区是 CSDN 旗下专注 OpenClaw 生态的官方阵地，聚焦技能开发、插件实践与部署教程，为开发者提供可直接落地的方案、工具与交流平台，助力高效构建与落地 AI 应用

更多推荐

cover

ClawSDK 沙箱逃逸面治理：从镜像供应链到宿主机边界的五个关键检查点

avatar 龙虾开发者社区
cover

Agent 自动化登录态管理：沙箱隔离与凭据安全实践

avatar 龙虾开发者社区
cover

Agent长任务状态管理：从断点续跑到幂等键设计的工程实践

avatar 龙虾开发者社区