用 PPIO 派欧云 API 为 RuoYi AI 接入大模型并跑通全栈应用

RuoYi AI 是一套开箱即用的全栈式 AI 应用开发框架，前端应用、后台管理、小程序应用都包含在内，采用 MIT 协议，可以自由修改与分发。它解决的是「从零搭一个 AI 应用」这件事里最耗时的部分：微服务骨架、多轮对话管理、意图识别、知识库接入这些模块不用自己从头写。适合想快速验证 AI 产品形态的开发者、需要一套可二次开发底座的小团队，以及想学习 AI 应用完整链路的前后端工程师。框架本身只提供骨架，真正让应用「会说话」的是背后的大模型服务，本文用 PPIO 派欧云的模型 API 来完成这一步接入。整套流程分四步：装后端、装管理端、装用户端、在后台配置模型。

准备工作

在动手之前，先把本机环境对齐。版本不匹配是这套项目最常见的启动失败原因，建议逐项核对后再开始。

组件	版本要求	用途
JDK	17	后端编译与运行
MySQL	5.7 或 8.0	业务数据存储
Redis	5.x 及以上	缓存与会话
Maven	3.8 及以上	后端依赖管理
Node.js	20 及以上	管理端与用户端构建
pnpm	与管理端项目匹配的版本	管理端包管理

除环境之外，还需要准备两样东西：

项目源码：后端、管理端、用户端是三个独立仓库，需要分别获取。
PPIO 派欧云账号：用于创建 API 密钥、调用模型。注册登录后进入 API 密钥管理页面即可创建。

另外建议提前确认本机端口占用情况。后端、管理端、用户端会各占一个端口，Redis 与 MySQL 也各自监听默认端口，如果本机已经跑着别的服务，先腾出端口再启动，能省掉大量排查时间。

操作步骤

第一步：安装并启动后端

后端是整个系统的基础，管理端和用户端都要连它，所以先把它跑通。

1. 获取项目源码

从代码托管平台下载后端项目，解压到本地工作目录。

2. 用 IDEA 导入项目

打开 IntelliJ IDEA，选择导入已存在的项目，指向刚才解压出来的目录，等待 IDEA 识别 Maven 结构。

3. 配置 Maven

进入「文件 - 设置」，在左上角搜索框输入 maven，选中 Maven 安装目录，然后配置 settings.xml。下面是一份可直接使用的配置示例，其中本地仓库路径与镜像地址按自己的实际情况调整：

<?xml version="1.0" encoding="UTF-8"?>
<settings xmlns="http://maven.apache.org/SETTINGS/1.0.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/SETTINGS/1.0.0
                              https://maven.apache.org/xsd/settings-1.0.0.xsd">
  <localRepository>D:/dev/apache-maven-3.9.9/repository</localRepository>
  <mirrors>
    <mirror>
      <id>aliyunmaven</id>
      <mirrorOf>*</mirrorOf>
      <name>阿里云公共仓库</name>
      <url>https://maven.aliyun.com/repository/public</url>
    </mirror>
  </mirrors>
  <profiles>
    <profile>
      <id>jdk-17</id>
      <activation>
        <activeByDefault>true</activeByDefault>
        <jdk>17</jdk>
      </activation>
      <properties>
        <maven.compiler.source>17</maven.compiler.source>
        <maven.compiler.target>17</maven.compiler.target>
        <maven.compiler.compilerVersion>17</maven.compiler.compilerVersion>
      </properties>
    </profile>
  </profiles>
</settings>

这段配置做了两件事：把本地仓库指到一个固定目录，避免依赖散落；把编译级别锁定在 JDK 17，与项目要求一致。

4. 初始化数据库

在 MySQL 中创建数据库，然后执行项目自带的初始化脚本，把表结构和基础数据导入。脚本通常位于项目的 SQL 目录下，按脚本内的注释顺序执行即可。

5. 启动 Redis

按本机操作系统下载并启动 Redis，确认服务处于运行状态。Redis 版本必须不低于 5.x，低版本会导致连接或数据结构相关的问题。

6. 启动项目

回到 IDEA，确认数据库连接信息（地址、端口、库名、用户名、密码）与 Redis 连接信息都已改成自己的配置，然后运行后端主启动类。控制台出现启动成功日志、且没有报错堆栈，说明后端已经就绪。

第二步：安装管理端

管理端是运营和配置的入口，后面配置模型就在这一端完成。

1. 获取项目源码

下载管理端项目并解压。

2. 安装依赖

pnpm install

3. 运行项目

pnpm dev

4. 打包

需要部署时执行：

pnpm build

5. 修改配置项

管理端有两处配置需要按实际情况调整：

后台接口地址：位于 /apps/web-antd/vite.config.mts，把代理目标指向第一步启动的后端服务。
其他配置：位于 /apps/web-antd/.env.development，包括标题、接口前缀等环境变量。

改完配置后重启 pnpm dev，浏览器打开开发服务器地址，能看到登录页即说明管理端已连通后端。

第三步：安装用户端

用户端是最终用户实际使用的界面，安装方式与管理端类似，但包管理器不同，注意不要混用。

1. 获取项目源码

下载用户端项目并解压。

2. 安装依赖

npm install

3. 运行项目

npm run dev

4. 打包

npm run build

用户端同样需要确认接口地址指向后端。三端全部启动后，本机应同时运行着后端服务、管理端开发服务器、用户端开发服务器三个进程，外加 MySQL 与 Redis。

第四步：接入 PPIO 派欧云大模型

前三步只是把空壳跑起来，这一步才让应用具备对话与推理能力。

1. 创建 API 密钥

注册并登录 PPIO 派欧云控制台，打开 API 密钥管理页面，点击创建按钮，输入一个自定义的密钥名称，生成 API 密钥。

2. 保存密钥

密钥在服务端是加密存储的，生成之后必须立刻保存到安全的地方。如果遗失，无法找回原值，只能在控制台删除旧密钥并重新创建一个。建议把密钥存进密码管理器，不要直接写进代码仓库。

3. 确认 API Base URL

派欧云的 API Base URL 是固定的，配置时直接填入即可，不需要自己拼接路径。

4. 选择模型 ID

调用模型时需要填写模型 ID，而不是模型的中文名称。素材中给出的可用模型 ID 包括：

deepseek/deepseek-r1-turbo
deepseek/deepseek-v3-turbo
deepseek/deepseek-v3-0324
qwen/qwq-32b

其他模型 ID、最大上下文长度与价格，请以官网当前信息为准，模型列表会持续更新。

5. 在后台配置模型

回到 RuoYi AI 管理端，进入「运营管理 - 系统模型」页面，新增一条模型配置。各字段填写方式如下：

字段	填写内容
模型名称	要调用的模型 ID，例如 `qwen/qwen3-32b-fp8`
模型描述	与模型名称保持一致即可，便于后台识别
模型价格	按实际计费规则填写
计算类型	次数计费
请求地址	派欧云的 API Base URL
密钥	第 2 步保存下来的 API 密钥

保存后，在用户端发起一次对话，如果能够正常返回内容，说明整条链路已经打通。

一个完整示例

下面把四步串成一条从零到可用的最短路径，假设本机是 Windows，MySQL 与 Redis 已装好，项目都放在 D:/workspace 下。

阶段一：后端

把后端项目解压到 D:/workspace/ruoyi-ai，用 IDEA 导入。
按前文示例配置 settings.xml，本地仓库指向 D:/dev/apache-maven-3.9.9/repository，镜像使用阿里云公共仓库。
在 MySQL 中建库，执行项目 SQL 脚本完成初始化。
启动 Redis，确认端口可连通。
修改后端配置文件中的数据库与 Redis 连接信息，运行主启动类，等待启动成功日志。

阶段二：管理端

cd D:/workspace/ruoyi-ai-admin
pnpm install
pnpm dev

随后编辑 apps/web-antd/vite.config.mts，把后台接口代理指向后端地址；再按需修改 apps/web-antd/.env.development。保存后开发服务器会自动热更新。

阶段三：用户端

cd D:/workspace/ruoyi-ai-web
npm install
npm run dev

阶段四：配置模型

登录 PPIO 派欧云控制台，在 API 密钥管理页面创建密钥，名称填 ruoyi-ai-dev，生成后立即复制保存。
记下 API Base URL，并从模型列表里挑一个模型 ID，例如 deepseek/deepseek-v3-turbo。
打开管理端，进入「运营管理 - 系统模型」，新增模型：模型名称与模型描述都填 deepseek/deepseek-v3-turbo，计算类型选「次数计费」，请求地址填 API Base URL，密钥粘贴刚才保存的值。
保存后切到用户端，新建一个对话并发送一句测试消息。收到模型回复即表示配置成功。

如果这一步失败，按顺序排查：密钥是否复制完整、模型 ID 是否与官网列表一致、请求地址是否填成了完整的对话接口而非 Base URL、后端能否正常访问外网。

注意事项

版本是硬门槛：JDK 必须是 17，Redis 必须不低于 5.x，Maven 3.8 以上，Node.js 20 以上。任何一项低于要求，都可能在编译或启动阶段直接失败。
两个前端用的包管理器不同：管理端用 pnpm，用户端用 npm。混用会产生锁文件冲突和依赖解析差异，按各自文档执行。
密钥只显示一次：派欧云的 API 密钥在服务端加密存储，生成时没保存就只能删除重建。不要把密钥提交到 Git 仓库，也不要在前端代码里硬编码。
模型名称填 ID 不填中文名：后台配置里的模型名称需要与调用时使用的模型 ID 完全一致，写成中文名称会导致请求失败。
计算类型选「次数计费」：这是素材中给出的配置方式，若后续平台计费方式调整，以控制台与官网说明为准。
模型与价格会变：可用模型 ID、最大上下文长度、计费单价都属于易变信息，配置前请以 PPIO 派欧云官网当前信息为准，不要照抄旧列表。
三端要同时在线：管理端和用户端都依赖后端接口，只启动前端会看到大量请求失败，排查问题时先确认后端进程还活着。
MIT 协议不等于无约束：RuoYi AI 基于 MIT 协议，可自由修改和分发、支持商用，但分发时仍需保留原版权与许可声明。

全部分类

准备工作

操作步骤

第一步：安装并启动后端

第二步：安装管理端

第三步：安装用户端

第四步：接入 PPIO 派欧云大模型

一个完整示例

注意事项