# AIRolePlay

**Repository Path**: jyadll/airole-play

## Basic Information

- **Project Name**: AIRolePlay
- **Description**: 开发一个利用 AI 来做角色扮演的网站，用户可以搜索自己感兴趣的角色例如哈利波特、苏格拉底等并可与其进行语音聊天。
- **Primary Language**: Unknown
- **License**: Not specified
- **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

# AIRolePlay

#### 介绍
开发一个利用 AI 来做角色扮演的网站，用户可以搜索自己感兴趣的角色例如哈利波特、苏格拉底等并可与其进行语音聊天。

#### 软件架构
软件架构说明
- **前端**: React + TypeScript + Vite + Tailwind CSS + daisyUI
- **后端**: FastAPI + Python
- **AI服务**: 七牛云兼容接口 （调用DeepSeek-v3）
- **语音**: 浏览器原生 Web Speech API（ASR 语音识别 + TTS 语音合成)
- **功能**: 角色扮演 + 语音对话 + 记忆功能

架构总览（组件容器图）：
![架构总览（组件容器图）](%E6%9E%B6%E6%9E%84%E6%80%BB%E8%A7%88%EF%BC%88%E7%BB%84%E4%BB%B6%E5%AE%B9%E5%99%A8%E5%9B%BE%EF%BC%89%20(3).png)

时序图（一次消息的全链路）：
![时序图（一次消息的全链路）](%E6%97%B6%E5%BA%8F%E5%9B%BE%EF%BC%88%E4%B8%80%E6%AC%A1%E6%B6%88%E6%81%AF%E7%9A%84%E5%85%A8%E9%93%BE%E8%B7%AF%EF%BC%89.png)

#### Demo视频
见项目根目录demo视频
网站界面如下：
![网站首页](%E9%A6%96%E9%A1%B5.png)
聊天界面：
![聊天界面](%E8%81%8A%E5%A4%A9%E7%95%8C%E9%9D%A2.png)

#### 开发计划与架构设计
见项目根目录 开发计划与架构设计.pdf

#### 环境要求
- Python 3.8+
- Node.js 18+
- Git

#### 安装教程

1. 克隆项目
```bash
git clone <repository-url>
cd airole-play
```

2. 后端环境配置
```bash
cd backend
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/Mac
source venv/bin/activate
pip install -r requirements.txt
```

3. 前端环境配置
```bash
cd frontend
npm install
```

#### 使用说明

1. **启动后端服务**
```bash
cd backend
# 方式1：使用uvicorn直接启动
uvicorn main:app --reload --host 0.0.0.0 --port 8000
# 方式2：使用Python启动
python main.py
```
后端将在 http://localhost:8000 运行

2. **启动前端服务**
```bash
cd frontend
npm install  # 如果已安装，可以跳过
npm run dev
```
前端将在 http://localhost:5173 运行

3. **访问应用**
- 前端界面: http://localhost:5173
- 后端API: http://localhost:8000
- API文档: http://localhost:8000/docs


#### 故障排除
- 端口被占用：修改端口号或关闭占用进程
- 依赖安装失败：检查Python/Node.js版本
- API调用失败：检查API密钥配置


#### 参与贡献

| ID  | 贡献内容  |
|---|---|
| jyadll  | 总体架构设计、前端、文档撰写  |
| Tomato  | 后端、demo录制、文档撰写  |

#### 其他事项

本项目参与2026七牛云秋季校园招聘（产研专场），设计文档与作品说明如下：

# 🎭 AI 角色扮演语音对话平台 — 作品说明书

## 1. 用户定位、痛点与用户故事

### 目标用户

* **年轻群体 / 学生**：喜欢哈利波特、二次元角色、历史人物，想要更沉浸式的互动体验。
* **学习者**：希望通过与“苏格拉底”等历史人物对话的方式学习哲学、历史、文学。
* **娱乐爱好者**：对虚拟伴侣、对话陪伴感兴趣。

### 用户痛点

* 缺少能让他们 **沉浸式体验角色** 的交互方式。
* 传统聊天机器人个性化不足，无法准确还原角色语气与设定。
* 市面上大多数产品仅支持文字聊天，**缺少自然语音交互**，沉浸感不足。

### 用户故事

* 小明是一名大学生，他在学习哲学时，想象如果能和苏格拉底辩论会怎样。他打开应用，选择“苏格拉底”，通过语音直接与其进行问答与辩论。
* 小芳是哈利波特迷，她希望体验与哈利一起讨论魔法世界的感觉。她搜索“哈利波特”，进入语音聊天，AI 用魔法少年的口吻与她交谈，并能带她进入魔法课堂的场景。
* 阿强孤单时想要找人陪伴，他选择一个虚拟朋友角色，AI 记住了他的偏好，并用声音陪伴他日常聊天。

---

## 2. 功能设计与优先级

### 功能清单

1. **角色搜索与选择**（高优先级）

   * 用户可输入关键词查找历史/虚拟角色。
   * 系统提供推荐角色列表。

2. **文本聊天**（高优先级）

   * 用户与角色以文字形式交流，确保基本功能可用。

3. **语音聊天**（高优先级）

   * 支持语音识别（ASR），将用户语音转换为文本输入。
   * 支持语音合成（TTS），将角色回复转换为语音播放。
   * 每个角色可设定不同的声音风格。

4. **AI 角色技能**（高优先级，本次开发核心）：

   * **知识问答**：基于角色背景回答问题。
   * **情景扮演**：带领用户进入特定对话场景。
   * **记忆技能**：在同一会话中记住用户的偏好和信息。

5. **角色个性设定**（中优先级）

   * 不同角色有预置 prompt，包括性格、语气、知识范围。

6. **用户登录与历史记录**（低优先级，未来扩展）

   * 保存聊天历史。

### 本次开发范围

* 角色搜索与选择
* 文本聊天 + 语音聊天
* AI 角色技能（知识问答、情景扮演、记忆）
* 简单前端界面（选择角色 + 聊天框 + 语音按钮）

---


## 3. AI 角色技能设计

本项目中，AI 角色不仅能语音聊天，还具备以下 3 项核心技能：

1. **知识问答（Expert Q\&A）**

   * AI 角色基于其身份回答问题。例如：

     * “哈利波特”可回答魔法世界相关问题。
     * “苏格拉底”用哲学反问的方式回应问题。

2. **情景扮演（Role-Play Scenarios）**

   * 用户可进入某个场景，如：

     * “和哈利一起上魔法课”。
     * “与苏格拉底进行哲学辩论”。
   * 系统在 prompt 中注入“场景设定”，让角色引导对话氛围。

3. **记忆技能（Session Memory）**

   * AI 在会话中保留上下文：

     * 如果用户告诉“哈利”自己是格兰芬多的学生，后续对话 AI 会延续这一设定。
     * 苏格拉底会记住用户之前的论点，持续反问和展开辩论。

---

# ✅ 提交须知（项目规则）

* **作品方向**：符合“AI 角色扮演 + 语音聊天”的议题要求。
* **独立完成**：需由团队或个人自主开发。
* **提交截止时间**：

  * 首批截止：**2025 年 9 月 28 日 23:59**
  * 嵌入式方向延长至 **2025 年 9 月 30 日 23:59**
* **提交方式**：

  * 上传至 GitHub / Gitee，包含：

    * 源代码
    * 运行说明
    * 架构设计文档（模块规格 + 分工）
    * Demo 视频
* **团队要求**：

  * 需有多人 commit 记录；
  * 开发过程需持续提交代码，不允许最后一天一次性提交。