# ai-roleplay-platform

**Repository Path**: fakerlove/ai-roleplay-platform

## Basic Information

- **Project Name**: ai-roleplay-platform
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: MulanPSL-2.0
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2025-09-22
- **Last Updated**: 2025-09-28

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# AI角色扮演平台

一个支持语音交互的AI角色扮演网站，用户可以选择预设的AI智能体（如面试猫、虚拟女友、苏格拉底），通过自然语音进行实时对话。



<iframe 
    height=450 
    width=800 
    src="https://fakerlove.oss-cn-beijing.aliyuncs.com/meeting_01.mp4" 
    frameborder=0 
    allowfullscreen>
</iframe>



<video url="https://fakerlove.oss-cn-beijing.aliyuncs.com/meeting_01.mp4"></video>

## 在线演示

http://cosplay.jokerak.com/

## 浏览器语音权限设置

使用语音功能需要解除HTTP限制：

### Chrome浏览器
访问地址：`chrome://flags/#unsafely-treat-insecure-origin-as-secure`

### Edge浏览器
访问地址：`edge://flags/#unsafely-treat-insecure-origin-as-secure`

**设置步骤：**
1. 将对应标志项改为"已启用"
2. 在输入框中添加网站地址：`http://cosplay.jokerak.com/`
3. 重启浏览器生效

![设置示例](picture/e2770ee4bbcd4974ac7eab6e75d7d8bb.png)

![网址输入](picture/29d5de4f69b34474899d20239e707064.png)

---

## 🏗️ 系统架构设计

### 整体架构图

```mermaid
graph TB
    subgraph "前端层 Frontend"
        A[Vue 3 + TypeScript]
        B[Element Plus UI]
        C[WebSocket Client]
        D[Audio API]
    end
    
    subgraph "网关层 Gateway"
        E[Nginx/负载均衡]
    end
    
    subgraph "后端服务层 Backend Services"
        F[Spring Boot 3.5.6]
        G[WebSocket Handler]
        H[REST API Controllers]
        I[Business Services]
    end
    
    subgraph "数据层 Data Layer"
        J[MySQL 8.0]
        K[MyBatis Plus]
    end
    
    subgraph "外部服务 External Services"
        L[七牛云 ASR/TTS]
        M[阿里云 OSS]
        N[OpenAI/LLM API]
        O[知识库向量搜索]
    end
    
    A --> E
    B --> E
    C --> E
    D --> E
    E --> F
    F --> G
    F --> H
    H --> I
    I --> K
    K --> J
    I --> L
    I --> M
    I --> N
    I --> O
```

### 技术栈详情

#### 后端技术栈
- **框架**: Spring Boot 3.5.6
- **语言**: Java 17
- **数据库**: MySQL 8.0
- **ORM**: MyBatis Plus 3.5.12
- **AI集成**: LangChain4J 1.5.0
- **实时通信**: WebSocket
- **文件存储**: 阿里云OSS
- **语音服务**: 七牛云ASR/TTS
- **文档**: Swagger 3 (OpenAPI)
- **工具库**: Hutool 5.8.29

#### 前端技术栈
- **框架**: Vue 3.5.18
- **语言**: TypeScript 5.8.0
- **构建工具**: Vite 7.0.6
- **UI组件**: Element Plus 2.11.4
- **状态管理**: Pinia 3.0.3
- **路由**: Vue Router 4.5.1
- **HTTP客户端**: Axios 1.12.2
- **音频处理**: Web Audio API

---

## 📊 核心业务流程图

### 1. 语音对话完整流程

```mermaid
sequenceDiagram
    participant U as 用户浏览器
    participant F as 前端Vue
    participant W as WebSocket
    participant B as 后端服务
    participant A as ASR服务
    participant L as LLM服务
    participant T as TTS服务
    participant O as OSS存储
    
    U->>F: 选择AI智能体
    F->>W: 建立WebSocket连接
    W->>B: 连接成功，获取sessionId
    B->>F: 返回连接确认
    
    U->>F: 按下录音按钮
    F->>F: 开始录音(Web Audio API)
    F->>W: 发送录音开始消息
    
    U->>F: 松开录音按钮
    F->>F: 停止录音，生成音频文件
    F->>W: 发送音频数据(Binary)
    W->>B: 接收音频数据
    
    B->>O: 上传音频文件
    O->>B: 返回音频URL
    B->>A: 调用ASR识别
    A->>B: 返回识别文本
    
    B->>B: 构建对话上下文
    B->>L: 调用LLM生成回复
    L->>B: 返回AI回复文本
    
    B->>T: 调用TTS合成语音
    T->>B: 返回音频数据
    B->>O: 上传AI回复音频
    
    B->>W: 发送音频数据给前端
    W->>F: 接收音频数据
    F->>U: 播放AI语音回复
```

### 2. 系统模块交互图

```mermaid
graph LR
    subgraph "用户界面层"
        A1[智能体选择页面]
        A2[语音聊天页面]
        A3[聊天历史页面]
        A4[知识库管理页面]
    end
    
    subgraph "业务服务层"
        B1[智能体服务]
        B2[语音聊天服务]
        B3[聊天服务]
        B4[知识库服务]
        B5[用户服务]
        B6[OSS服务]
    end
    
    subgraph "数据访问层"
        C1[智能体Mapper]
        C2[聊天Mapper]
        C3[用户Mapper]
        C4[知识库Mapper]
    end
    
    subgraph "外部集成层"
        D1[语音识别工具]
        D2[语音合成工具]
        D3[LLM集成]
        D4[OSS存储]
    end
    
    A1 --> B1
    A2 --> B2
    A3 --> B3
    A4 --> B4
    
    B1 --> C1
    B2 --> C2
    B3 --> C2
    B4 --> C4
    B5 --> C3
    
    B2 --> D1
    B2 --> D2
    B2 --> D3
    B6 --> D4
```

### 3. WebSocket消息流转图

```mermaid
stateDiagram-v2
    [*] --> 连接建立
    连接建立 --> 初始化会话: init消息
    初始化会话 --> 等待录音: 会话创建成功
    
    等待录音 --> 录音中: voice_start
    录音中 --> 处理中: voice_end + 音频数据
    处理中 --> 播放中: 返回AI音频
    播放中 --> 等待录音: 播放完成
    
    等待录音 --> 连接关闭: 用户离开
    录音中 --> 连接关闭: 用户离开
    处理中 --> 连接关闭: 用户离开
    播放中 --> 连接关闭: 用户离开
    
    连接关闭 --> [*]
```

---

## 🗂️ 项目结构详解

```
ai-roleplay-platform/
├── ai-roleplay-platform-back/          # 后端项目
│   ├── src/main/java/com/joker/airoleplayplatformback/
│   │   ├── controller/                  # 控制器层
│   │   │   ├── AiAgentController.java   # AI智能体管理
│   │   │   ├── VoiceController.java     # 语音处理
│   │   │   ├── ChatController.java      # 聊天管理
│   │   │   └── AuthController.java      # 用户认证
│   │   ├── service/                     # 业务服务层
│   │   │   ├── impl/                    # 服务实现
│   │   │   ├── AiAgentService.java      # 智能体服务
│   │   │   ├── VoiceChatService.java    # 语音聊天服务
│   │   │   ├── ChatService.java         # 聊天服务
│   │   │   └── KnowledgeBaseService.java # 知识库服务
│   │   ├── domain/                      # 数据模型
│   │   │   ├── po/                      # 持久化对象
│   │   │   ├── dto/                     # 数据传输对象
│   │   │   ├── vo/                      # 视图对象
│   │   │   └── entity/                  # 实体类
│   │   ├── mapper/                      # 数据访问层
│   │   │   ├── AiAgentMapper.java       # 智能体数据访问
│   │   │   ├── ChatMessageMapper.java   # 消息数据访问
│   │   │   └── ChatSessionMapper.java   # 会话数据访问
│   │   ├── websocket/                   # WebSocket处理
│   │   │   └── VoiceChatWebSocketHandler.java
│   │   ├── listener/                    # 事件监听器
│   │   │   └── VoiceProcessingListener.java
│   │   ├── config/                      # 配置类
│   │   │   ├── WebSocketConfig.java     # WebSocket配置
│   │   │   ├── LLMConfig.java          # 大模型配置
│   │   │   └── SecurityConfig.java      # 安全配置
│   │   ├── utils/                       # 工具类
│   │   │   ├── SpeechRecognitionUtils.java # 语音识别工具
│   │   │   ├── TextToSpeechUtils.java   # 语音合成工具
│   │   │   └── AudioFormatConverter.java # 音频格式转换
│   │   └── task/                        # 定时任务
│   │       └── WebSocketHeartbeatTask.java
│   └── src/main/resources/
│       ├── application.yml              # 应用配置
│       └── db/init.sql                 # 数据库初始化脚本
│
├── ai-roleplay-platform-front/         # 前端项目
│   ├── src/
│   │   ├── views/                       # 页面组件
│   │   │   ├── AgentSelection.vue       # 智能体选择页面
│   │   │   ├── VoiceChat.vue           # 语音聊天页面
│   │   │   ├── ChatHistory.vue         # 聊天历史页面
│   │   │   └── KnowledgeBase.vue       # 知识库管理页面
│   │   ├── services/                    # 服务层
│   │   │   ├── websocket.ts            # WebSocket服务
│   │   │   └── voice.ts                # 语音服务
│   │   ├── api/                        # API接口
│   │   │   └── index.ts                # API定义
│   │   ├── types/                      # 类型定义
│   │   │   └── index.ts                # TypeScript类型
│   │   ├── stores/                     # 状态管理
│   │   │   └── user.ts                 # 用户状态
│   │   └── router/                     # 路由配置
│   │       └── index.ts                # 路由定义
│   ├── package.json                    # 依赖配置
│   └── vite.config.ts                  # 构建配置
│
└── README.md                           # 项目说明文档
```

---

## 🔧 模块功能规格

### 1. 智能体管理模块
**负责人**: 后端开发
**功能**:
- 智能体CRUD操作
- 系统提示词管理
- 音色配置管理
- 智能体状态控制

**接口**:
- `GET /api/agents/list` - 获取智能体列表
- `POST /api/agents` - 创建智能体
- `PUT /api/agents` - 更新智能体
- `DELETE /api/agents/{id}` - 删除智能体

### 2. 语音处理模块
**负责人**: 后端开发 + 前端开发
**功能**:
- 实时语音录制
- 音频格式转换
- ASR语音识别
- TTS语音合成
- 音频文件存储

**核心类**:
- `VoiceController` - 语音接口控制器
- `VoiceProcessingListener` - 异步语音处理
- `SpeechRecognitionUtils` - 语音识别工具
- `TextToSpeechUtils` - 语音合成工具

### 3. WebSocket通信模块
**负责人**: 后端开发 + 前端开发
**功能**:
- 实时双向通信
- 连接状态管理
- 心跳检测机制
- 消息路由分发

**消息类型**:
- `init` - 初始化会话
- `voice_start` - 开始录音
- `voice_end` - 结束录音
- `voice_message` - 语音消息
- `heartbeat` - 心跳检测

### 4. 聊天会话模块
**负责人**: 后端开发
**功能**:
- 会话生命周期管理
- 消息持久化存储
- 对话历史查询
- 上下文构建

**数据表**:
- `t_chat_session` - 聊天会话表
- `t_chat_message` - 聊天消息表

### 5. 知识库模块
**负责人**: 后端开发
**功能**:
- 文档上传解析
- 向量化存储
- 语义搜索
- 上下文增强

**支持格式**:
- 文本文件 (.txt)
- PDF文档 (.pdf)
- Word文档 (.docx)

### 6. 用户界面模块
**负责人**: 前端开发
**功能**:
- 智能体选择界面
- 语音聊天界面
- 聊天历史界面
- 知识库管理界面
- 性能监控界面

---

## 🚀 快速开始

### 环境要求

- **JDK**: 17+
- **Node.js**: 20+
- **MySQL**: 8.0+
- **Maven**: 3.6+
- **PNPM**: 最新版本

### 后端启动

1. **配置数据库**
   ```sql
   CREATE DATABASE aigc CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci;
   ```

2. **更新配置文件**
   编辑 `ai-roleplay-platform-back/src/main/resources/application.yml`：
   ```yaml
   spring:
     datasource:
       url: jdbc:mysql://your-host:3306/aigc
       username: your-username
       password: your-password
   
   oss:
     endpoint: your-oss-endpoint
     keyid: your-access-key
     keysecret: your-secret-key
     bucketname: your-bucket-name
   
   # 七牛云API配置
   qiniu:
     oss:
       accessKey: your-qiniu-access-key
       secretKey: your-qiniu-secret-key
       bucketName: your-bucket-name
   
   # LLM API配置
   langchain4j:
     open-ai:
       chat-model:
         api-key: your-openai-api-key
         base-url: https://api.openai.com/v1
   ```

3. **启动后端服务**
   ```bash
   cd ai-roleplay-platform-back
   mvn clean install
   mvn spring-boot:run
   ```

   服务将在 `http://localhost:8080` 启动

   **API文档**: http://localhost:8080/swagger-ui.html

### 前端启动

1. **安装依赖**
   ```bash
   cd ai-roleplay-platform-front
   pnpm install
   ```

2. **启动开发服务器**
   ```bash
   pnpm dev
   ```

   前端将在 `http://localhost:5173` 启动

### 数据库初始化

首次启动时，数据库表会自动创建，并插入默认的AI智能体数据：

- **面试猫**: 专业的面试模拟助手
- **虚拟女友**: 温柔体贴的聊天伴侣
- **苏格拉底**: 古希腊哲学家，启发式对话

---

## 📱 使用说明

### 1. 选择智能体
- 访问首页，浏览可用的AI智能体
- 查看智能体描述和特色
- 点击"开始对话"进入聊天界面

### 2. 语音对话
- 点击"开始通话"建立WebSocket连接
- 系统会自动检测语音输入
- 支持连续对话，无需重复连接
- 实时显示对话状态和音频可视化

### 3. 聊天历史
- 查看所有历史对话记录
- 支持按智能体筛选
- 可以继续之前的对话
- 支持删除单个会话

### 4. 知识库管理
- 上传文档增强AI回复能力
- 支持多种文档格式
- 自动向量化和索引
- 智能语义搜索

---

## 🔌 API接口文档

### 智能体管理
- `GET /api/agents/list` - 获取所有启用的智能体
- `GET /api/agents/{id}` - 获取智能体详情
- `GET /api/agents/key/{agentKey}` - 根据key获取智能体
- `POST /api/agents` - 创建智能体
- `PUT /api/agents` - 更新智能体
- `DELETE /api/agents/{id}` - 删除智能体
- `GET /api/agents/voice-list` - 获取可用音色列表

### 聊天管理
- `POST /api/chat/session/create` - 创建新会话
- `GET /api/chat/session/list` - 获取用户会话列表
- `GET /api/chat/messages/{sessionId}` - 获取会话消息
- `DELETE /api/chat/session/{sessionId}` - 删除会话

### 语音处理
- `POST /api/voice/upload` - 上传语音文件
- `POST /api/voice/process-mp3` - 处理MP3文件

### 知识库管理
- `POST /api/knowledge/upload/text` - 上传文本
- `POST /api/knowledge/upload/file` - 上传文件
- `GET /api/knowledge/list` - 获取知识库列表
- `DELETE /api/knowledge/{id}` - 删除知识库条目

### WebSocket接口
- `ws://localhost:8080/ws/voice-chat` - 语音聊天WebSocket连接

---

## 🎯 核心特性

### 🎤 实时语音交互
- 基于WebSocket的实时通信
- 支持语音端点检测
- 低延迟音频传输
- 多种音色选择

### 🤖 智能对话系统
- 集成LangChain4J框架
- 支持多种大语言模型
- 上下文感知对话
- 个性化角色扮演

### 📚 知识库增强
- 文档智能解析
- 向量化语义搜索
- 动态上下文注入
- 多格式文件支持

### 🔄 流式处理
- 异步语音处理流水线
- 事件驱动架构
- 性能监控和优化
- 错误恢复机制

### 🎨 现代化界面
- Vue 3 + TypeScript
- Element Plus组件库
- 响应式设计
- 音频可视化效果

---

## 🔧 开发指南

### 添加新的AI智能体

1. **数据库操作**
   ```sql
   INSERT INTO t_ai_agent (agent_key, name, description, system_prompt, default_voice_type, status, sort_order)
   VALUES ('new-agent', '新智能体', '描述信息', '系统提示词', 'qiniu_zh_female_xyqxxj', 1, 100);
   ```

2. **前端自动加载**
   - 智能体列表会自动刷新
   - 无需修改前端代码

### 自定义语音处理

- **ASR服务**: 修改 `SpeechRecognitionUtils.java`
- **TTS服务**: 修改 `TextToSpeechUtils.java`
- **音频格式**: 修改 `AudioFormatConverter.java`

### 扩展功能开发

- **新增页面**: 在 `src/views/` 目录添加Vue组件
- **新增API**: 在 `controller/` 目录添加控制器
- **新增服务**: 在 `service/` 目录添加业务逻辑
- **数据库表**: 更新 `init.sql` 脚本

---

## ⚠️ 注意事项

### 浏览器兼容性
- **推荐**: Chrome 88+, Edge 88+, Firefox 85+
- **必需**: 支持WebSocket和Web Audio API
- **权限**: 需要麦克风访问权限

### 网络要求
- **带宽**: 建议上行1Mbps以上
- **延迟**: 建议RTT < 200ms
- **稳定性**: 需要稳定的网络连接

### API配置
- **七牛云**: 确保API密钥有效且有足够配额
- **OpenAI**: 配置正确的API密钥和基础URL
- **OSS**: 确保存储桶权限配置正确

### 存储空间
- **音频文件**: 平均每分钟对话约2-5MB
- **数据库**: 建议预留足够的存储空间
- **日志文件**: 定期清理应用日志

---

## 🐛 故障排除

### 常见问题

#### 1. WebSocket连接失败
**症状**: 无法建立语音连接
**解决方案**:
- 检查后端服务是否启动 (端口8080)
- 确认防火墙设置允许WebSocket连接
- 检查浏览器控制台错误信息

#### 2. 语音识别失败
**症状**: 录音后无响应或识别为空
**解决方案**:
- 检查七牛云API密钥配置
- 确认网络连接正常
- 验证音频文件格式和大小
- 检查麦克风权限设置

#### 3. 音频播放问题
**症状**: AI回复无声音或播放异常
**解决方案**:
- 检查浏览器音频权限
- 确认音频文件URL可访问
- 验证TTS服务配置
- 检查音频格式兼容性

#### 4. 数据库连接错误
**症状**: 后端启动失败或数据操作异常
**解决方案**:
- 验证数据库连接配置
- 检查数据库服务状态
- 确认用户权限设置
- 查看数据库日志

### 调试工具

#### 后端调试
```bash
# 查看应用日志
tail -f logs/application.log

# 检查JVM状态
jps -l

# 监控数据库连接
show processlist;
```

#### 前端调试
- 浏览器开发者工具 (F12)
- Network面板查看API请求
- Console面板查看错误信息
- Application面板检查WebSocket连接

---

## 📈 性能优化

### 后端优化
- **连接池**: 配置合适的数据库连接池大小
- **缓存**: 使用Redis缓存热点数据
- **异步处理**: 语音处理采用异步事件驱动
- **资源管理**: 及时清理临时文件

### 前端优化
- **懒加载**: 路由和组件按需加载
- **音频缓存**: 缓存常用音频文件
- **状态管理**: 优化Pinia状态更新
- **内存管理**: 及时释放音频资源

### 网络优化
- **CDN**: 静态资源使用CDN加速
- **压缩**: 启用Gzip压缩
- **HTTP/2**: 使用HTTP/2协议
- **WebSocket**: 复用WebSocket连接

---

## 🤝 贡献指南

### 开发流程
1. Fork 项目到个人仓库
2. 创建特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 创建 Pull Request

### 代码规范
- **Java**: 遵循阿里巴巴Java开发手册
- **TypeScript**: 使用ESLint和Prettier
- **提交信息**: 使用约定式提交格式
- **文档**: 及时更新相关文档

### 测试要求
- **单元测试**: 核心业务逻辑需要单元测试
- **集成测试**: API接口需要集成测试
- **端到端测试**: 关键用户流程需要E2E测试

---

## 📄 许可证

本项目采用 [MIT License](LICENSE) 开源协议。

---

## 📞 联系方式

- **项目地址**: https://gitee.com/fakerlove/ai-roleplay-platform

---

## 🙏 致谢

感谢以下开源项目和服务提供商：

- [Spring Boot](https://spring.io/projects/spring-boot) - 后端框架
- [Vue.js](https://vuejs.org/) - 前端框架
- [LangChain4J](https://github.com/langchain4j/langchain4j) - AI集成框架
- [Element Plus](https://element-plus.org/) - UI组件库
- [七牛云](https://www.qiniu.com/) - 语音服务
- [阿里云](https://www.aliyun.com/) - 云存储服务

---

**最后更新**: 2025年9月28日