技术调研] RuoYi AI —— 基于若依生态的企业级一站式AI应用开发框架

0 序

初体验

定位：基于 Spring Boot 3 + Langchain4j 构建，深度继承若依（RuoYi）企业级后台管理能力，提供多模型统一接入、本地化 RAG 知识库、MCP 工具调用、可视化工作流编排与多智能体协同的全栈开源 AI 应用开发平台。
LangChain4J
- https://github.com/langchain4j/langchain4j
- https://docs.langchain4j.dev/
- https://docs.langchain4j.com.cn/ （第三方中文网站）
- https://ossinsight.io/analyze/langchain4j/langchain4j#overview
先来瞅瞅本地私有化部署的效果

Ruoyi-AI v3.1.0 deploy by Docker Compose

核心结论

先说最重要的结论

作为 "AI 平台"（对标 Dify/FastGPT/RAGFlow 这类产品）：竞争力弱，不建议企业选型。

作为 "Java 技术栈团队的 AI 应用落地基座 / 学习参考"：有边界实用性，值得一用，但别当长期平台押注。

RuoYi AI 是个好用的 Java AI 应用脚手架，但不是个有竞争力的企业 AI 平台。用它做 MVP、做学习、做 Java 栈的快速验证都务实；把它当企业 AI 转型的长期底座，是拿个人项目的生命周期去赌公司的技术路线，不划算。真实战场上是 Dify/RAGFlow/Coze 这些生态玩家在说话。

原因1: 量级差距是客观事实

项目	GitHub Stars（2026 年中）	维护模式	工作流/RAG 成熟度
Dify	130k+	商业公司 + 社区	数十种工作流节点，生态最成熟
RAGFlow	75k~89k	商业化团队	深度文档理解/OCR/表格解析，行业标杆
FastGPT	27k+	商业化团队	专注 RAG，检索质量高
RuoYi AI	~5.5k	【个人主导(项目风险极大)】 + 约50贡献者	工作流仅5种左右节点，RAG 依赖 Langchain4j 基础能力

Star 差一个数量级，背后是团队资源、迭代速度、问题响应、插件生态、文档完整度的系统性差距。
个人项目达到 GVP 认证值得肯定，但"Gitee 人工智能赛道 Top3"和"全球 AI 平台竞争力"是两个概念——前者更多是 Gitee 站内同量级项目里的相对位置。

原因2:企业 AI 转型的真实胜负手，RuoYi AI 没有触到

企业 AI 转型真正难的从来不是"有没有一个 AI 平台"，而是三件事，RuoYi AI 都没解决：

存量业务系统的深度集成——AI 要进业务，靠的不是平台界面，而是把 ERP/CRM/审批流/主数据真正打通。这取决于你们自己的工程能力，平台只是壳。
数据治理与知识资产化——企业文档散落、格式混乱、权限不清，RAG 效果差 90% 的原因是上游数据没治理。RuoYi AI 的"文档解析"只是锦上添花。
长期演进与人才梯队——选型一个平台，是在赌它 3 年后还活着、还在迭代。个人维护项目在这条上的风险是硬伤，不是情绪问题。

一个 5.5k star 的个人项目，撑不起【企业级 AI 平台】的"平台"二字。
这句话不针对作者的能力，而是针对企业选型的风险底线。

那它的实用性到底在哪？

它确实有真实价值，只是边界很窄：

Java 栈 + 若依存量团队：这是它唯一的主场。如果你们团队全员 Java、已有若依体系、不想引入 Python 技术栈，它能让你一周内把模型接入、私有知识库、智能客服跑起来，交付速度是实打实的。这类场景下比从零写强得多，也比让 Java 团队去啃 Dify 的 Python 生态成本低。

做技术验证 / 简历 / 学习参考：社区里真实的二次开发案例（电商客服准确率、知识库检索等）证明它可跑、可改、可学。作为学习 Langchain4j + Spring AI 的完整落地范本，价值是明确的。

中小型、短期、私有化项目：如果项目周期短、数据不出域、对长期演进要求不高，拿它做基座是务实的。

务实建议

你是决策者，要为集团选一个 AI 平台底座 → 不选它。Dify 生态更安全，或基于 LangChain/LangGraph 自研。拿 5.5k star 个人项目当平台底座，技术选型答辩这一关都过不去。

你是 Java 团队，要快速交付内部知识库/客服 MVP，再评估要不要自研 → 值得试。用它两周验证业务价值，比花两个月论证选型更划算。但默认它是个"起步脚手架"，不是"终点平台"，要提前规划数据模型和接口层的可替换性。

个人开发者/学习者 → 强烈推荐研究。它是目前 Java 生态里最完整的 AI 应用开源范本，研究价值高于它的平台价值。

1 概述

产品介绍

RuoYi AI（若依 AI） 是一个面向企业级市场的一站式 AI 应用开发框架，旨在帮助企业与开发者零门槛快速构建安全、高效、可落地的 AI 智能体应用与行业解决方案。

产品定位：企业级 AI 助手平台 / AI 应用开发底座，而非单纯的聊天机器人。
诞生背景：项目作者 Ageerle 是一名拥有约六年经验的 Java 后端开发工程师。2023 年 GPT-3.5 发布后，他通宵完成了第一个基于流式对话的 Demo，随后逐步将其从简单的对话工具演进为覆盖知识库、智能体、工具调用、多智能体协作的企业级 AI 平台。作者以开源项目作为个人技术名片，在学历与履历不占优的情况下通过持续迭代建立了技术公信力。
解决的核心问题：
- 企业多厂商大模型的统一接入与管理问题；
- 企业内部文档的私有化知识库（RAG） 构建与检索问题；
- 已有业务系统接口封装为工具（MCP / Skills） 供智能体调用的问题；
- 复杂 AI 任务的可视化工作流编排与多智能体协同调度问题；
- AI 应用与企业原有权限体系、用户体系、后台管理的打通问题。
URL：
- GitHub 主仓库：https://github.com/ageerle/ruoyi-ai
- Gitee 镜像：https://gitee.com/ageerle/ruoyi-ai
- 在线演示（管理后台）：http://129.226.199.247:25666（admin / admin123）
- 在线演示（用户前端）：http://129.226.199.247:25137
- 商业版：https://web.ruoyiai.chat

发展历程

时间	里程碑
2023	项目启动，最初为基于 GPT-3.5 的简单流式对话 Demo，后续逐步加入 AI 生图、音乐生成、声音克隆、知识库等能力，从对话工具演进为多媒体 AI 助手。
2025.05	v2.0.5 发布，新增对 Coze、Dify、派欧云等第三方 AI 平台模型的调用支持。
2025.05.30	v2.1.0 稳定版发布，为开源版本首个稳定版；同时宣布 v2.0.5 后部分功能不再维护，聚焦核心能力。
2025.06.05	获得 Gitee G-Star 认证。
2025.10	获得 Gitee 2000 Star 奖杯。
2025.10.21	获得 Gitee GVP（Gitee 最有价值开源项目）认证。
2025.11	入选百大开源项目。
2026.01.30	进入 Gitee 2025 年度开源项目人工智能赛道 Top 3。
2026.08	v3.0.0 发布：升级 Langchain4j 至 1.13.0，新增 docx/pdf/xlsx 文档处理技能模块，添加演示模式配置与切面拦截，新增 SkillsAgent 支持文档智能处理，优化聊天服务与可观测性监听器。
2026.08（最新）	v3.1.0 为当前推荐部署版本，提供 GHCR 预构建镜像与一键 docker-compose 部署。

社区规模：截至 2026 年 8 月，微信群与 QQ 群合计社区成员超 4000 人，代码贡献者接近 50 人，Gitee Star 超 2000。项目主要由作者 Ageerle 维护，同时有社区伙伴参与贡献。

主要功能

RuoYi AI 的核心能力分为五大模块：

1. 模型管理（Model Management）

多模型统一接入：支持 DeepSeek、智谱 AI、MIMO（MiniMax）、阿里百炼、OpenAI 等国内外主流大模型；
多模态理解：支持文本、图像等多模态输入；
AI 平台集成：深度集成 Coze（扣子）、DIFY、FastGPT、RAGFlow 等主流 AI 平台，可统一纳管。

2. 知识管理（Knowledge Management）

本地化 RAG：基于 Langchain4j 框架实现纯 Java 方案的检索增强生成；
多向量库支持：兼容 Milvus、Weaviate、Qdrant 3种向量数据库；
中文向量模型：结合 BGE-large-zh-v1.5 本地向量化模型，针对中文语境优化；
文档解析：支持 PDF、Word（docx）、Excel（xlsx）、TXT 等多格式文档的自动解析与向量化存储；
智能问答：先从知识库检索相关内容再生成回答，有效缓解大模型幻觉问题。

3. 工具管理（Tool Management）

MCP 协议集成：支持 Model Context Protocol（MCP），可接入外部工具服务；
Skills 能力体系：内置可扩展的技能（Skills）生态，v3.0.0 起新增 docx/pdf/xlsx 文档处理技能（Word 批注与修订追踪、PDF 表单填充与图像转换、Excel 表格处理等）；
可扩展工具生态：支持将企业已有业务接口封装为工具供智能体调用。

4. 工作流编排（Workflow Orchestration）

可视化工作流设计器：拖拽式节点编排，降低 AI 流程构建门槛；
SSE 流式执行：工作流执行过程通过 SSE 实时推送，支持中间结果预览；
节点类型：当前支持模型调用、邮件发送、人工审核等节点，持续扩展中；
两种模式：支持传统节点编排和智能路由两种模式。

5. 多智能体（Multi-Agent）

基于 Langchain4j 的 Agent 框架：提供标准化的智能体开发能力；
Supervisor 模式编排：通过 Supervisor（协调者）模式实现多智能体的任务分发、上下文共享与结果汇总；
多种决策模型：支持灵活搭配不同的决策模型；
工具与技能组合：每个智能体可灵活绑定工具（Tools）与技能（Skills），实现角色化分工。

附加能力

AI 绘画：集成 Midjourney 等生图能力；
AI 音乐：支持音乐生成与下载；
声音克隆：语音克隆能力；
短剧生成：独立模块 ruoyi-drama；
编程 Copilot：独立模块 ruoyi-copilot；
小程序端：基于 uni-app 的 ruoyi-uniapp，覆盖移动端场景。

核心优势

继承若依生态的企业级后台管理能力
基于成熟的 RuoYi-Vue-Plus 框架构建，自带完善的用户管理、角色权限、菜单管理、部门管理、字典管理、操作日志、登录日志等企业级后台基础设施。对于已使用若依体系的企业，可无缝对接原有权限与组织架构。
Java 技术栈原生友好
后端采用 Spring Boot 3.5.x + Langchain4j，是国内 Java 生态中少有的全栈 AI 应用平台。对于以 Java 为主力技术栈的企业（尤其是国企、金融、传统行业），无需引入 Python 技术栈即可构建 AI 应用，降低团队技术栈分裂与运维成本。
全栈开源、多端覆盖
提供完整的后端服务、管理后台、用户前端、小程序端、短剧模块、Copilot 模块，全部基于 MIT 协议开源，开箱即用。拉取源码配置参数即可运行，大幅缩短项目落地周期。
本地化 RAG 与数据安全
支持纯本地化的文档解析、向量化存储与检索，向量数据库可私有化部署，结合本地 LLM（如 Ollama）可实现完全离线的 AI 问答，满足国企、金融、政务等对数据隐私要求极高的场景。
多模型与多平台统一纳管
不仅支持多家大模型 API 的统一接入，还能深度集成 Coze、DIFY、FastGPT、RAGFlow 等第三方 AI 平台，企业可在一个后台中统一管理所有 AI 能力，避免平台碎片化。
多智能体协同（Supervisor 模式）
在单智能体工具调用之外，提供 Supervisor 模式的多智能体编排，支持任务拆解、角色分工、上下文共享与异常处理，更贴近企业复杂业务场景。这是 RuoYi AI 相比普通 AI 对话系统的核心差异化竞争力。
MIT 协议商业友好
采用 MIT 开源协议，允许商业使用、修改、分发，无传染性，企业可放心用于商业项目。

主要短板

核心维护者以个人为主，可持续性存在一定风险
项目主要由作者 Ageerle 一人主导维护，虽有近 50 位贡献者，但核心架构与重大版本迭代高度依赖个人精力。相比 Dify 等有商业公司与团队支撑的项目，其长期迭代节奏与问题响应速度存在不确定性。
社区规模与生态成熟度不及头部项目
Gitee Star 超 2000、社区成员 4000+，但与 Dify（GitHub 数万 Star）、FastGPT（24K+ Star）等头部项目相比，社区体量、插件生态、第三方教程资源仍有明显差距。
文档体系相对薄弱
官方文档不够系统完善，部分功能依赖社区博客与教程学习，二次开发的上手门槛相对较高。对于复杂功能（如多智能体编排、MCP 工具开发），缺乏详尽的开发者指南。
工作流编排能力仍在早期阶段
可视化工作流当前仅支持模型调用、邮件发送、人工审核等有限节点，与 Dify 成熟的工作流引擎（支持循环、条件分支、变量转换、代码执行等数十种节点）相比，功能丰富度差距较大。
海外生态与国际化支持较弱
项目主要面向国内市场，文档以中文为主，海外模型与平台的适配深度有限，国际化程度较低。

局限性

不涉及模型训练：RuoYi AI 定位为 AI 应用层框架，不提供大模型训练、微调、数据集管理等能力，底层模型依赖第三方 API 或本地部署的开源模型。
高级功能可能分流至商业版：作者明确将项目分为开源版与商业版
- 开源版提供基础能力（模型管理、知识库、工具调用、技能管理、记忆管理、多智能体协作等）;
- 商业版则提供面向具体业务场景的开箱即用解决方案（如开发智能体、垂直行业方案）。
  - 部分深度行业能力可能仅在商业版中提供。
向量库选型绑定：虽支持 Milvus/Weaviate/Qdrant 三种，但默认 docker-compose 部署使用 Weaviate，切换向量库需额外配置，尚不支持 Elasticsearch、PGVector 等更多向量存储方案。
非微服务架构：当前后端为单体应用架构（基于若依的模块化单体），对于超大规模、高并发的 AI 应用场景，水平扩展能力有限。

适用场景

场景类型	具体说明
企业私有知识库问答	将企业内部规章制度、产品手册、技术文档、FAQ 等导入知识库，构建私有化智能问答助手，适用于客服、内部培训、技术支持等场景。
企业 AI 应用快速搭建	基于若依已有后台管理体系，快速为现有业务系统叠加 AI 能力（智能客服、智能文档处理、AI 辅助决策等），无需从零搭建 AI 基础设施。
Java 技术栈企业的 AI 转型	以 Java 为主力技术栈的企业（国企、金融、政务、传统制造业），希望在不引入 Python 栈的情况下构建 AI 应用。
数据隐私要求高的离线场景	支持完全本地化部署（本地 LLM + 本地向量库 + 本地文档解析），满足政务、军工、金融等数据不出域的合规要求。
多智能体协同业务流程	需要多个角色化智能体分工协作完成复杂任务的场景，如自动化报告生成、多步骤业务审批、跨系统数据整合等。
AI 能力统一纳管平台	企业已使用多家大模型或多个 AI 平台（Coze/DIFY/FastGPT 等），需要统一管理、统一鉴权、统一监控的 AI 中台场景。
个人开发者与小团队原型验证	MIT 协议 + 全栈开源 + Docker 一键部署，适合个人开发者与小团队快速验证 AI 应用概念。

同类竞品 + 选型建议

竞品	定位	核心优势	与 RuoYi AI 的主要差异
Dify	开源 LLM 应用开发平台	工作流编排成熟、社区生态大、国际化好、有商业公司支撑	基于 Python 技术栈，后台管理能力弱于若依体系；RuoYi AI 胜在 Java 生态与企业级后台集成。
FastGPT	开源 AI 知识库平台	RAG 检索精度高、中文优化好、轻量易部署、专注知识库问答	功能相对单一，核心聚焦 RAG，缺乏多智能体协同与工作流编排；RuoYi AI 能力更全面且自带后台管理。
Coze（扣子）	字节跳动 AI 应用搭建平台	托管式零代码、C 端体验好、插件生态丰富、字节生态集成深	闭源托管，数据存储在字节云端，不支持私有化部署；RuoYi AI 可完全私有化且开源可定制。
RAGFlow	开源 RAG 引擎	深度文档理解（表格、版式、OCR）、检索质量高	专注 RAG 引擎，不提供完整的后台管理与多智能体能力；RuoYi AI 可集成 RAGFlow 作为知识库后端。
LangChain / LangGraph	AI 应用开发框架（Python/JS）	生态最成熟、灵活性最高、社区最大	是开发框架而非成品平台，需要自行搭建前端、后台、权限体系；RuoYi AI 是开箱即用的全栈平台。
Langchain4j	Java 版 AI 应用开发框架	Java 原生、与 Spring 生态集成好	是底层框架，RuoYi AI 正是基于 Langchain4j 构建的上层成品平台。

选型建议：

若团队以 Java 为主且已有若依体系，优先考虑 RuoYi AI；

若需要 最成熟的工作流编排与国际化社区，选 Dify；

若仅需 高质量知识库问答且追求轻量，选 FastGPT、RAGFlow；

若追求 零代码快速上线 C 端应用且不介意托管，选 Coze。

发展趋势

开源社区活跃趋势

Star 增长：2025 年 10 月突破 Gitee 2000 Star，此后持续稳步增长，项目热度在国内 Java AI 开源领域处于上升期。
版本迭代节奏：2025 年 5 月发布首个稳定版 v2.1.0，2026 年 8 月即迭代至 v3.1.0，大版本间隔约半年，小版本与功能更新频繁，整体迭代节奏稳定。
社区贡献：贡献者从早期个人维护发展到近 50 人参与，社区微信群与 QQ 群合计超 4000 人，用户基数持续扩大。
行业认可：一年内连续获得 G-Star、GVP、百大开源项目、Gitee 人工智能赛道 Top 3 等多项认证，行业认可度快速提升。

项目发展方向

开源版 + 商业版双轨并行：开源版持续夯实基础能力（模型管理、知识库、工具调用、多智能体等），商业版沉淀垂直行业解决方案（开发智能体、企业知识库方案等）。
业务类智能体深化：作者明确后续重点方向为编程智能体与知识图谱，聚焦让 AI 真正理解企业真实业务、框架与代码，而非通用智能体。
MCP 与 Skills 生态扩展：持续深化 MCP 协议集成与 Skills 技能体系，v3.0.0 已新增文档处理技能模块，未来将扩展更多行业技能。
多智能体协同能力增强：Supervisor 模式编排与多种决策机制将持续优化，提升复杂任务的可配置性与可观测性。

总结：RuoYi AI 正从"基于若依的 AI 对话工具"快速演进为"Java 生态下企业级 AI 应用开发底座"，凭借若依后台管理能力与 Java 原生优势，在国内企业级 AI 开源赛道中占据差异化生态位，长期趋势向好，但需关注个人维护模式下的可持续性风险。

2 工作原理与架构

概念术语

术语	说明
RAG（Retrieval-Augmented Generation）	检索增强生成。先从知识库中检索与用户问题相关的文档片段，再将检索结果作为上下文传入大模型生成回答，有效减少幻觉并提升回答准确性。
向量数据库（Vector DB）	专门存储高维向量（如文本嵌入向量）并支持相似度检索的数据库。RuoYi AI 支持 Milvus、Weaviate、Qdrant 三种。
Embedding（嵌入/向量化）	将文本转换为高维数值向量的过程。RuoYi AI 默认使用 BGE-large-zh-v1.5 中文向量模型。
MCP（Model Context Protocol）	由 Anthropic 提出的模型上下文协议，标准化大模型与外部工具/数据源的连接方式。RuoYi AI 通过 MCP 接入外部工具服务。
Skills（技能）	RuoYi AI 中可复用的能力单元，每个 Skill 封装一组特定功能（如文档处理、邮件发送），可被智能体灵活调用。
Agent（智能体）	基于大模型的自主决策实体，能理解用户意图、规划步骤、调用工具并返回结果。RuoYi AI 基于 Langchain4j 实现 Agent 框架。
Supervisor 模式	多智能体编排模式，由一个 Supervisor（协调者）智能体负责任务拆解、分发、上下文管理与结果汇总，下属多个专业智能体分工执行。
SSE（Server-Sent Events）	服务器推送事件，一种基于 HTTP 的单向实时通信协议。RuoYi AI 使用 SSE 实现对话与工作流执行过程的流式推送。
Langchain4j	专为 Java 生态设计的 LLM 应用开发框架，提供模型接入、工具调用、RAG、Agent 等能力，是 RuoYi AI 的 AI 层核心依赖。
Sa-Token	轻量级 Java 权限认证框架，RuoYi AI 用其实现登录认证、权限校验、会话管理等安全能力。

架构与运行原理

整体架构分层（必读）

RuoYi AI 采用经典的前后端分离架构，后端为基于 Spring Boot 的模块化单体应用，整体可分为以下几层：

┌─────────────────────────────────────────────────────────┐
│                      客户端层（Clients）                   │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐   │
│  │ 管理后台   │ │ 用户前端  │ │ 小程序端   │ │ 第三方系统   │   │
│  │ruoyi-    │ │ruoyi-    │ │ruoyi-    │ │  (API 调用) │   │
│  │admin     │ │web       │ │uniapp    │ │            │   │
│  └────┬─────┘ └────┬─────┘ └────┬─────┘ └─────┬──────┘   │
│       │              │              │               │    │
└───────┼──────────────┼──────────────┼───────────────┼────┘
        │              │              │               │
        ▼              ▼              ▼               ▼
┌─────────────────────────────────────────────────────────┐
│                   API 网关 / 控制器层                      │
│        Spring MVC Controller · Sa-Token 鉴权 · JWT       │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                     业务服务层（Services）                 │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │ 模型管理  │ │ 知识库/RAG │ │ 工具/MCP │ │ 工作流引擎    │  │
│  └──────────┘ └──────────┘ └──────────┘ └────────────┘  │
│  ┌──────────┐ ┌──────────┐ ┌──────────┐ ┌────────────┐  │
│  │ 多智能体  │ │ Skills   │ │ 记忆管理   │ │ 对话服务     │  │
│  │ (Agent)  │ │ 技能管理  │ │           │ │            │  │
│  └──────────┘ └──────────┘ └──────────┘ └────────────┘  │
│         基于 Langchain4j 的 AI 能力编排层                  │
└──────────────────────────┬──────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                     数据与中间件层                         │
│  ┌─────────┐ ┌────────┐ ┌────────────┐ ┌─────────────┐  │
│  │ MySQL   │ │ Redis  │ │ 向量数据库   │ │ MinIO 对象   │  │
│  │ 8.0     │ │ 缓存    │ │ Milvus/    │ │ 存储         │  │
│  │ 业务数据 │ │ 会话    │ │ Weaviate/  │ │ 文档/图片     │  │
│  │         │ │        │ │ Qdrant     │ │             │  │
│  └─────────┘ └────────┘ └────────────┘ └─────────────┘  │
└─────────────────────────────────────────────────────────┘
                           │
┌──────────────────────────▼──────────────────────────────┐
│                   外部 AI 能力层                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │ 大模型 API：DeepSeek / 智谱 / 百炼 / OpenAI / ...      │ │
│  │ AI 平台：Coze / DIFY / FastGPT / RAGFlow             │ │
│  │ 本地 LLM：Ollama 等                                  │ │
│  └─────────────────────────────────────────────────────┘ │
└──────────────────────────────────────────────────────────┘

核心技术栈（必读）

分类	技术选型
后端基础框架	Spring Boot 3.5.8、Java 17+
AI 开发框架	Langchain4j 1.13.0+
前端框架	Vue 3、Vben Admin、element-plus-x
关系型数据库	MySQL 8.0
缓存	Redis
向量数据库	Milvus / Weaviate / Qdrant（默认 Weaviate）
对象存储	MinIO
安全框架	Sa-Token + JWT 双层安全
实时通信	WebSocket、SSE（Server-Sent Events）
文档处理	PDF / Word / Excel 解析、智能图像分析
容器化	Docker、Docker Compose
基础底座	RuoYi-Vue-Plus（若依快速开发框架）

多仓库模块结构

RuoYi AI 采用多仓库组织方式，各模块独立维护：

模块	仓库名	说明
🔧 后端服务	`ruoyi-ai`	核心后端，包含所有 AI 能力与业务接口
🎨 用户前端	`ruoyi-web`	面向终端用户的 AI 对话与应用前端
🛠️ 管理后台	`ruoyi-admin`	运营管理后台，模型/知识库/工具/用户/权限管理
🎬 短剧	`ruoyi-drama`	AI 短剧生成模块
🤖 Copilot	`ruoyi-copilot`	编程智能体模块
📱 小程序	`ruoyi-uniapp`	基于 uni-app 的移动端小程序

关键运行流程

流程一：知识库 RAG 问答

文档导入：用户在管理后台上传 PDF/Word/Excel/TXT 文档，系统将文档存储至 MinIO 对象存储；
文档解析：后端调用文档解析组件提取文本内容，按策略进行智能分段（Chunking）；
向量化：使用 BGE-large-zh-v1.5 模型将每个文本片段转换为向量，写入向量数据库（Weaviate/Milvus/Qdrant）；
用户提问：用户在前端发起问题，请求经 Sa-Token 鉴权后到达对话服务；
检索召回：系统将用户问题同样向量化，在向量数据库中进行相似度检索，召回 Top-K 相关文档片段；
Prompt 组装：将召回的文档片段与用户问题组装为增强 Prompt，附带系统提示词与对话历史；
模型生成：调用配置的大模型 API（或本地 LLM）生成回答，通过 SSE 流式推送到前端；
结果返回：前端以打字机效果展示回答，可附带引用来源。

流程二：多智能体 Supervisor 协同

任务接收：用户提交复杂任务，Supervisor 智能体接收并理解任务目标；
任务拆解：Supervisor 根据任务复杂度，将其拆解为若干子任务，并为每个子任务分配合适的专业 Agent（如文档处理 Agent、数据查询 Agent、代码生成 Agent 等）；
并行/串行执行：各专业 Agent 依据依赖关系并行或串行执行，每个 Agent 可调用绑定的 Tools（MCP 工具）与 Skills（技能）；
上下文共享：执行过程中，各 Agent 的中间结果通过 Supervisor 维护的共享上下文传递，确保信息一致性；
异常处理：若某个 Agent 执行失败，Supervisor 根据策略决定重试、降级或人工介入；
结果汇总：所有子任务完成后，Supervisor 汇总各 Agent 的结果，生成最终回答并通过 SSE 流式返回。

流程三：可视化工作流执行

流程设计：用户在管理后台的可视化设计器中拖拽节点（模型调用、邮件发送、人工审核等），连接节点并配置参数；
流程保存与发布：工作流定义保存至 MySQL，发布后可供触发；
触发执行：通过 API 调用或手动触发启动工作流实例；
节点执行：工作流引擎按拓扑顺序依次执行节点，每个节点执行结果作为后续节点的输入；
SSE 实时推送：执行过程中每个节点的状态与中间结果通过 SSE 实时推送到前端，支持进度预览；
人工审核节点：遇到人工审核节点时，工作流暂停，等待审核人员在后台操作后继续；
完成与记录：工作流执行完成后，完整执行日志与结果保存至数据库，可供回溯审计。

3 使用指南

安装部署

环境要求

组件	最低要求	推荐配置
操作系统	Windows 10+ / Linux（CentOS 7+、Ubuntu 20.04+）	Linux（Ubuntu 22.04 / CentOS Stream 9）
Docker	Docker Engine 20.10+、Docker Compose V2	最新稳定版
CPU	4 核	8 核及以上
内存	8 GB	16 GB 及以上（使用本地 LLM 需更高）
磁盘	50 GB 可用空间	100 GB SSD
Java（源码部署）	JDK 17+	JDK 17 / 21
Maven（源码部署）	Maven 3.8+	Maven 3.9+
Node.js（前端构建）	Node.js 18+	Node.js 20 LTS

方式一：Docker 一键部署（推荐、亲测）

使用官方提供的 docker-compose-all.yaml 一键启动所有服务（后端、管理后台、用户前端及依赖组件），镜像从 GHCR 拉取，无需登录。

# 1. 克隆指定版本（以 v3.1.0 为例）
git clone --depth 1 --branch v3.1.0 https://github.com/ageerle/ruoyi-ai.git
cd ruoyi-ai

# 2. 复制环境变量配置文件并固定版本
cp docs/docker/ruoyi-ai/.env.example docs/docker/ruoyi-ai/.env
# Linux / macOS：
sed -i 's/^RUIYI_VERSION=.*/RUIYI_VERSION=v3.1.0/' docs/docker/ruoyi-ai/.env
# Windows PowerShell：
# (Get-Content docs/docker/ruoyi-ai/.env) -replace '^RUIYI_VERSION=.*', 'RUIYI_VERSION=v3.1.0' | Set-Content docs/docker/ruoyi-ai/.env

# 3. 启动 docker 后台服务
（略）

# 4. 拉取预构建镜像
docker compose --env-file docs/docker/ruoyi-ai/.env -f docs/docker/ruoyi-ai/docker-compose-all.yaml pull

# 5. 启动所有服务
docker compose --env-file docs/docker/ruoyi-ai/.env -f docs/docker/ruoyi-ai/docker-compose-all.yaml up -d

# 6. 查看服务状态
docker compose --env-file docs/docker/ruoyi-ai/.env -f docs/docker/ruoyi-ai/docker-compose-all.yaml ps
docker compose --env-file docs/docker/ruoyi-ai/.env -f docs/docker/ruoyi-ai/docker-compose-all.yaml ps -a

启动后访问地址（将 SERVER_IP 替换为实际服务器地址）：

服务	地址	默认账号
管理后台	`http://SERVER_IP:25666`	admin / admin123
用户前端	`http://SERVER_IP:25137`	admin / admin123
后端 API	`http://SERVER_IP:26039`	—

生产环境注意事项：默认 Compose 文件还会暴露 MySQL（23306）、Redis（26379）、Weaviate（28080）、MinIO（29000/29090）端口。生产部署时务必修改默认 MySQL 和 MinIO 密码，并通过防火墙或反向代理仅暴露应用端口。

版本升级：更新 docs/docker/ruoyi-ai/.env 中的 RUIYI_VERSION，然后重新执行 docker compose pull 与 docker compose up -d。切勿使用 docker compose down -v，除非有意删除持久化数据卷。

方式二：分步源码构建部署

适用于需要修改源码、自定义构建的场景。

步骤 1：部署后端服务

cd ruoyi-ai
# 源码构建并启动后端（含 MySQL、Redis、Weaviate、MinIO 等依赖）
docker-compose up -d --build
# 查看后端启动日志
docker-compose logs -f backend

步骤 2：部署管理后台

cd ruoyi-admin
docker-compose up -d --build
# 访问：http://localhost:5666

步骤 3：部署用户前端（可选）

cd ruoyi-web
docker-compose up -d --build
# 访问：http://localhost:5137

方式三：脚本一键部署（旧版本兼容）

部分版本提供 shell 部署脚本，适合 Linux 环境快速部署：

git clone https://gitcode.com/ageerle/ruoyi-ai.git
cd ruoyi-ai/script/deploy/one-step-script
chmod +x deploy-cn.sh
./deploy-cn.sh   # 中文界面部署脚本
# 或 ./deploy-en.sh  # 英文界面部署脚本

方式四：本地源码直接运行（开发调试）

适用于开发人员本地调试：

# 1. 初始化数据库
# 执行 script/sql/ 目录下的 ruoyi-ai.sql 及相关升级脚本

# 2. 修改配置文件
# 编辑 ruoyi-admin/src/main/resources/application-dev.yml
# 配置 MySQL、Redis、向量数据库连接信息及大模型 API Key

# 3. 编译后端
mvn clean package -Dmaven.test.skip=true

# 4. 启动后端
java -jar ruoyi-admin/target/ruoyi-admin.jar

# 5. 启动前端（管理后台 / 用户前端）
cd ruoyi-admin   # 或 ruoyi-web
npm install
npm run dev

离线部署方案

对于无网络环境，可预先在有网环境下载所有 Docker 镜像与依赖，导出为 tar 包后拷贝至离线服务器加载：

# 有网环境：导出镜像
docker save -o ruoyi-ai-images.tar \
  ageerle/ruoyi-ai:v3.1.0 \
  mysql:8.0 \
  redis:7 \
  semitechnologies/weaviate:1.30.0 \
  minio/minio:latest

# 离线环境：导入镜像
docker load -i ruoyi-ai-images.tar

# 启动服务（使用本地镜像，不执行 pull）
docker compose --env-file docs/docker/ruoyi-ai/.env \
  -f docs/docker/ruoyi-ai/docker-compose-all.yaml up -d

服务端口对照表

服务	一键部署端口	分步部署端口	说明
管理后台	25666	5666	运营管理后台访问
用户前端	25137	5137	终端用户 AI 对话界面
后端服务	26039	6039	后端 API 服务
MySQL	23306	23306	关系型数据库
Redis	26379	6379	缓存服务
Weaviate	28080	28080	向量数据库（默认）
MinIO API	29000	9000	对象存储 API
MinIO Console	29090	9090	对象存储管理控制台

关键操作（必读）

1. 配置大模型 API Key

登录管理后台后，进入 AI 管理 → 模型管理，新增模型配置：

选择模型厂商（DeepSeek / 智谱 / 百炼 / OpenAI 等）；
填入对应 API Key 与 API Base URL；
设置模型名称、最大 Token 数、温度等参数；
保存后可在对话或智能体中选择使用。

也可通过环境变量在 .env 文件中配置：

AI_OPENAI_API_KEY=sk-xxxxxxxxxxxxxxxx
AI_DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxx
AI_ZHIPU_API_KEY=xxxxxxxxxxxxxxxx

2. 构建私有知识库

进入 AI 管理 → 知识库管理，点击"新增知识库"；
填写知识库名称、描述，选择关联的向量数据库与 Embedding 模型；
进入知识库详情，上传文档（支持 PDF、Word、Excel、TXT）；
系统自动解析文档、分段、向量化并写入向量库；
在知识库中进行"测试问答"，验证检索与回答效果；
在对话或智能体配置中绑定该知识库，即可实现基于私有知识的问答。

3. 创建智能体（Agent）

进入 AI 管理 → 智能体管理，新增智能体；
配置智能体基本信息：名称、头像、描述、系统提示词（System Prompt）；
选择决策模型（大模型）与温度参数；
绑定知识库（可选，用于 RAG 增强）；
绑定工具（Tools）与技能（Skills），定义智能体可调用的能力；
若使用多智能体模式，配置 Supervisor 与下属 Agent 的关系；
保存后在用户前端即可与该智能体对话。

4. 编排可视化工作流

进入 AI 管理 → 工作流管理，点击"新建工作流"；
在可视化设计器中拖拽节点（模型调用、邮件发送、人工审核等）到画布；
连接节点，定义执行顺序与数据流向；
逐个配置节点参数（如模型调用节点选择模型与 Prompt 模板）；
点击"试运行"验证工作流执行效果，SSE 实时展示执行过程；
验证通过后发布工作流，可通过 API 或手动触发执行。

5. 配置 MCP 工具

进入 AI 管理 → 工具管理，选择 MCP 配置；
填入 MCP 服务器地址（URL）与认证信息；
系统自动发现该 MCP 服务器暴露的工具列表；
选择需要启用的工具，保存配置；
在智能体配置中绑定已启用的 MCP 工具，智能体即可在对话中自主调用。

Z FAQ

Q: RuoYi AI 和若依（RuoYi）官方框架是什么关系？

RuoYi AI 是社区开发者基于 RuoYi-Vue-Plus（若依的社区增强版）二次开发的 AI 应用平台，并非若依官方出品。它深度继承了若依的后台管理体系（用户、角色、权限、菜单、字典、日志等），并在此基础上叠加了大模型接入、知识库 RAG、智能体、工作流等 AI 能力。若依官方文档的"项目扩展"页面也收录了 ruoyi-ai 作为社区扩展项目。

Q: RuoYi AI 可以完全离线运行吗？

可以。RuoYi AI 支持完全本地化部署方案：使用 Ollama 部署本地开源大模型（如 Qwen、Llama 等）作为推理后端，向量数据库（Weaviate/Milvus/Qdrant）私有化部署，BGE 向量模型本地运行，文档解析在本地完成，所有数据不出域。官方也提供了专门的离线部署文档与 Docker Compose 配置。但需注意，本地 LLM 的推理效果与速度取决于服务器硬件配置（尤其是 GPU）。

Q: RuoYi AI 支持哪些向量数据库？如何切换？

当前支持 Milvus、Weaviate、Qdrant 三种向量数据库。默认 Docker 一键部署使用 Weaviate。切换向量库需要：1）部署对应向量数据库服务；2）在后端配置文件（application-*.yml）或环境变量中修改向量数据库的连接配置与类型；3）已有的知识库数据不会自动迁移，需在新向量库中重新导入文档并向量化。目前不支持 Elasticsearch、PGVector 等其他向量存储方案。

Q: 开源版和商业版有什么区别？

根据作者公开说明，两者定位不同：

开源版：提供企业 AI 应用的基础能力，包括模型管理、知识库 RAG、工具调用（MCP）、技能管理（Skills）、记忆管理、多智能体协作（Supervisor 模式）、可视化工作流等，帮助企业快速搭建自己的 AI 应用和智能体平台。
商业版：更偏向具体业务场景，将定制开发和客户合作中沉淀的能力整理为开箱即用的解决方案，如面向开发场景的编程智能体、企业知识库方案、垂直行业能力等。
简单来说：开源版解决"怎么搭建 AI 能力"，商业版解决"怎么把 AI 用到具体业务里"。 商业版访问地址为 https://web.ruoyiai.chat。

Q: RuoYi AI 的 MIT 协议允许商业使用吗？

Q: 部署后管理后台登录不上去怎么办？

常见排查步骤：

确认服务全部启动：执行 docker compose ps 检查所有容器状态是否为 healthy 或 Up，尤其关注 MySQL、Redis、后端服务；
查看后端日志：docker compose logs -f backend，检查是否有数据库连接失败、Redis 连接失败、端口冲突等报错；
确认数据库初始化：检查 MySQL 中是否已创建 ruoyi-ai 数据库及表结构，若未初始化需手动执行 SQL 脚本；
检查端口映射：确认管理后台端口（默认 25666 或 5666）未被其他程序占用，且服务器防火墙/安全组已放行该端口；
默认账号：管理员账号为 admin，密码为 admin123，注意区分大小写。

Q: RuoYi AI 支持多租户吗？

当前开源版本主要基于若依的部门（Dept）+ 角色（Role） 数据权限体系实现数据隔离，并非严格意义上的 SaaS 多租户架构。可通过部门划分实现不同团队/组织的数据隔离，每个部门的用户只能访问本部门及子部门的数据。若需要完整的多租户（租户隔离、独立数据库、独立计费等）能力，可能需要二次开发或关注商业版。

Q: 如何升级 RuoYi AI 版本而不丢失数据？

Docker 部署的升级步骤：

备份数据：升级前务必备份 MySQL 数据卷与向量数据库数据卷，可使用 docker cp 或 mysqldump 导出；
修改版本号：编辑 docs/docker/ruoyi-ai/.env，将 RUIYI_VERSION 改为目标版本；
拉取新镜像：docker compose --env-file .env -f docker-compose-all.yaml pull；
滚动更新：docker compose --env-file .env -f docker-compose-all.yaml up -d，Compose 会自动重建变更的容器，数据卷不会被删除；
执行升级 SQL：若版本说明中提到数据库变更，需手动执行对应升级脚本；
切勿使用 docker compose down -v：-v 参数会删除所有数据卷，导致数据丢失。仅使用 docker compose down（不带 -v）停止服务是安全的。

Q: RuoYi AI 的对话支持流式输出吗？

支持。RuoYi AI 使用 SSE（Server-Sent Events） 实现对话的流式输出，前端以打字机效果实时展示大模型的生成内容，降低用户等待感知。工作流的执行过程也通过 SSE 实时推送中间结果。此外，系统还支持 WebSocket 用于其他实时通信场景。

Q: 我可以在 RuoYi AI 中接入自己的业务系统接口吗？

可以，有两种主要方式：

MCP 协议：将你的业务系统接口封装为 MCP 服务器，在 RuoYi AI 的工具管理中配置 MCP 服务器地址，系统自动发现并暴露工具，智能体即可自主调用。这是推荐的标准化方式。
自定义 Skills：基于 RuoYi AI 的 Skills 体系开发自定义技能模块，在 Java 代码中调用你的业务接口，注册为可被智能体调用的技能。这种方式灵活性更高，但需要 Java 开发能力。

Y 推荐文献

以下为学习 RuoYi AI 及相关技术栈推荐的文献与资源。

20260827: 5.7k star / 1.4k fork

Dify
- https://github.com/langgenius/dify

X 参考文献

posted @ 2026-08-28 01:43 数据知音阅读(15) 评论(0) 收藏举报

刷新页面返回顶部