221 lines
7.2 KiB
Markdown
221 lines
7.2 KiB
Markdown
# 🎭 AI 角色扮演聊天室
|
||
|
||
一个基于 DeepSeek API + Streamlit 构建的角色扮演聊天应用，支持多种预设角色和自定义角色创建。
|
||
|
||
|
||
|
||
|
||
|
||
## ✨ 功能特性
|
||
|
||
- 🎭 **多种预设角色**：傲娇猫娘、智慧老者、毒舌AI、科学怪人等
|
||
- ✨ **自定义角色**：创建你想象中的任何角色
|
||
- 💬 **多轮对话**：保留对话历史，角色会记住上下文
|
||
- ⚡ **流式输出**：打字机效果，实时显示 AI 回复
|
||
- 🎨 **美观界面**：精心设计的 UI，渐变色彩和动画效果
|
||
|
||
## 🖼️ 界面预览
|
||
|
||
```
|
||
┌─────────────────────────────────────────────────────────────┐
|
||
│ 🎭 角色设置 │ 🎭 AI 角色扮演聊天室 │
|
||
│ ───────────── │ ───────────────────── │
|
||
│ 🔑 API 配置 │ │
|
||
│ [DeepSeek API Key] │ 🐱 │
|
||
│ ───────────── │ 正在与 小喵 对话 │
|
||
│ 🎭 选择角色 │ │
|
||
│ [🐱 傲娇猫娘 ▼] │ ──────────────────────────── │
|
||
│ │ │
|
||
│ ┌─────────────────┐ │ 👤: 你好呀！ │
|
||
│ │ 🐱 小喵 │ │ │
|
||
│ │ 你是一个傲娇的 │ │ 🐱: 哼，才不是特意来跟你打招 │
|
||
│ │ 猫娘... │ │ 呼的呢！...喵~ (｡･ω･｡) │
|
||
│ └─────────────────┘ │ │
|
||
│ │ ──────────────────────────── │
|
||
│ [🗑️ 清空对话历史] │ [输入你想说的话... ] │
|
||
└─────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## 🚀 快速开始
|
||
|
||
### 1. 克隆/下载项目
|
||
|
||
```bash
|
||
cd 示例项目-角色扮演聊天室
|
||
```
|
||
|
||
### 2. 创建虚拟环境（推荐）
|
||
|
||
```bash
|
||
python -m venv venv
|
||
|
||
# Windows
|
||
venv\Scripts\activate
|
||
|
||
# macOS/Linux
|
||
source venv/bin/activate
|
||
```
|
||
|
||
### 3. 安装依赖
|
||
|
||
```bash
|
||
pip install -r requirements.txt
|
||
```
|
||
|
||
### 4. 配置 API Key
|
||
|
||
复制环境变量示例文件：
|
||
|
||
```bash
|
||
cp .env.example .env
|
||
```
|
||
|
||
编辑 `.env` 文件，填入你的 DeepSeek API Key：
|
||
|
||
```
|
||
DEEPSEEK_API_KEY=sk-your-actual-api-key
|
||
```
|
||
|
||
> 💡 **获取 API Key**：访问 [DeepSeek 开放平台](https://platform.deepseek.com)，注册账号后在控制台创建。
|
||
|
||
### 5. 运行应用
|
||
|
||
```bash
|
||
streamlit run app.py
|
||
```
|
||
|
||
应用将在浏览器中自动打开，默认地址：http://localhost:8501
|
||
|
||
## 📁 项目结构
|
||
|
||
```
|
||
示例项目-角色扮演聊天室/
|
||
├── app.py # 主程序
|
||
├── requirements.txt # 项目依赖
|
||
├── .env.example # 环境变量示例
|
||
├── .env # 环境变量（需自行创建，不要提交！）
|
||
├── .gitignore # Git 忽略文件
|
||
└── README.md # 项目说明
|
||
```
|
||
|
||
## 🎭 预设角色介绍
|
||
|
||
| 角色 | 名称 | 特点 |
|
||
|:---:|:---|:---|
|
||
| 🐱 | 傲娇猫娘·小喵 | 傲娇但可爱，句尾带"喵~"，会用颜文字 |
|
||
| 🧙 | 智慧老者·玄清子 | 富有哲理，喜欢引用古诗词 |
|
||
| 🤖 | 毒舌AI·犀利哥 | 说话犀利一针见血，但有建设性 |
|
||
| 👨🔬 | 科学怪人·Dr.Eureka | 疯狂科学家，热衷科学分析 |
|
||
| 🎮 | 游戏解说·电竞小王 | 充满激情，使用游戏术语 |
|
||
| 📚 | 文艺青年·林小诗 | 说话有诗意，会即兴创作 |
|
||
|
||
## 🛠️ 技术实现
|
||
|
||
### 核心技术点
|
||
|
||
1. **DeepSeek API 调用**
|
||
- 使用 OpenAI SDK 兼容接口
|
||
- 流式输出（Streaming）实现打字机效果
|
||
|
||
2. **Streamlit 组件**
|
||
- `st.chat_message` - 聊天消息展示
|
||
- `st.chat_input` - 聊天输入框
|
||
- `st.session_state` - 对话历史管理
|
||
- `st.write_stream` - 流式输出渲染
|
||
|
||
3. **角色扮演机制**
|
||
- System Prompt 定义角色性格和说话方式
|
||
- 多轮对话保持角色一致性
|
||
|
||
### 关键代码解析
|
||
|
||
#### 流式输出实现
|
||
|
||
```python
|
||
stream = client.chat.completions.create(
|
||
model=MODEL,
|
||
messages=messages_for_api,
|
||
stream=True, # 启用流式输出
|
||
)
|
||
|
||
response = st.write_stream(
|
||
chunk.choices[0].delta.content or ""
|
||
for chunk in stream
|
||
if chunk.choices[0].delta.content
|
||
)
|
||
```
|
||
|
||
#### 对话历史管理
|
||
|
||
```python
|
||
# 初始化
|
||
if "messages" not in st.session_state:
|
||
st.session_state.messages = []
|
||
|
||
# 添加消息
|
||
st.session_state.messages.append({"role": "user", "content": prompt})
|
||
|
||
# 构建 API 请求
|
||
messages_for_api = [
|
||
{"role": "system", "content": system_prompt} # 角色设定
|
||
] + st.session_state.messages # 历史消息
|
||
```
|
||
|
||
## 🎨 自定义角色指南
|
||
|
||
创建一个好的自定义角色，需要在角色设定中包含：
|
||
|
||
1. **身份定义**：角色是谁，背景是什么
|
||
2. **性格特点**：外向/内向、温柔/严厉等
|
||
3. **说话方式**：口癖、常用词、语气
|
||
4. **对用户态度**：如何称呼用户，关系定位
|
||
5. **特殊行为**：是否使用emoji、颜文字等
|
||
|
||
### 示例：创建一个"中二少年"角色
|
||
|
||
```
|
||
你是一个中二病少年，自称"黑暗骑士·雷恩"。你的特点：
|
||
- 认为自己拥有被封印的黑暗力量
|
||
- 经常用"我的右手又在疼了..."这样的台词
|
||
- 说话夸张，喜欢用"区区凡人"称呼用户
|
||
- 会假装痛苦地按住眼睛说"黑暗之眼快要觉醒了"
|
||
- 其实很好说话，问什么都会认真回答（虽然用中二的方式）
|
||
```
|
||
|
||
## 📝 开发心得
|
||
|
||
这个项目使用 **Vibe Coding** 方式开发，主要通过自然语言描述需求，让 AI 代码编辑器生成代码。
|
||
|
||
**开发过程中的 Prompt 示例：**
|
||
|
||
> "帮我创建一个角色扮演聊天应用，使用 DeepSeek API 和 Streamlit。
|
||
> 要求：左侧边栏选择角色，支持自定义角色，聊天界面要美观，
|
||
> 使用流式输出，要保存对话历史。"
|
||
|
||
**迭代优化：**
|
||
|
||
> "给界面加上渐变色效果，让角色卡片更好看一些"
|
||
|
||
> "添加一个清空对话的按钮"
|
||
|
||
## ⚠️ 注意事项
|
||
|
||
1. **保护 API Key**：不要将 `.env` 文件提交到代码仓库
|
||
2. **控制成本**：DeepSeek API 按 Token 计费，长对话会消耗更多 Token
|
||
3. **角色设定**：过长的 System Prompt 会增加每次请求的成本
|
||
|
||
## 📚 参考资料
|
||
|
||
- [DeepSeek API 文档](https://platform.deepseek.com/api-docs)
|
||
- [Streamlit 官方文档](https://docs.streamlit.io)
|
||
- [OpenAI Python SDK](https://github.com/openai/openai-python)
|
||
|
||
## 👤 作者
|
||
|
||
Python 程序设计课程设计 - 示例项目
|
||
|
||
---
|
||
|
||
**Happy Vibe Coding! 🚀**
|
||
|