Python2025-CourseDesign/CourseDesignTemplate

Fork 0

sit002 b8bb6a24dd feat: add initial project README file

2025-12-31 14:41:33 +08:00

7.2 KiB

Raw Blame History

🎭 AI 角色扮演聊天室

一个基于 DeepSeek API + Streamlit 构建的角色扮演聊天应用，支持多种预设角色和自定义角色创建。

✨ 功能特性

🎭 多种预设角色：傲娇猫娘、智慧老者、毒舌AI、科学怪人等
✨ 自定义角色：创建你想象中的任何角色
💬 多轮对话：保留对话历史，角色会记住上下文
⚡ 流式输出：打字机效果，实时显示 AI 回复
🎨 美观界面：精心设计的 UI，渐变色彩和动画效果

🖼️ 界面预览

┌─────────────────────────────────────────────────────────────┐
│  🎭 角色设置                │  🎭 AI 角色扮演聊天室          │
│  ─────────────              │  ─────────────────────          │
│  🔑 API 配置                │                                  │
│  [DeepSeek API Key]         │  🐱                              │
│  ─────────────              │  正在与 小喵 对话                │
│  🎭 选择角色                │                                  │
│  [🐱 傲娇猫娘      ▼]       │  ────────────────────────────    │
│                             │                                  │
│  ┌─────────────────┐        │  👤: 你好呀！                    │
│  │ 🐱 小喵          │        │                                  │
│  │ 你是一个傲娇的   │        │  🐱: 哼，才不是特意来跟你打招   │
│  │ 猫娘...         │        │      呼的呢！...喵~ (｡･ω･｡)    │
│  └─────────────────┘        │                                  │
│                             │  ────────────────────────────    │
│  [🗑️ 清空对话历史]          │  [输入你想说的话...          ]   │
└─────────────────────────────────────────────────────────────┘

🚀 快速开始

1. 克隆/下载项目

cd 示例项目-角色扮演聊天室

2. 创建虚拟环境（推荐）

python -m venv venv

# Windows
venv\Scripts\activate

# macOS/Linux
source venv/bin/activate

3. 安装依赖

pip install -r requirements.txt

4. 配置 API Key

复制环境变量示例文件：

cp .env.example .env

编辑 .env 文件，填入你的 DeepSeek API Key：

DEEPSEEK_API_KEY=sk-your-actual-api-key

💡 获取 API Key：访问 DeepSeek 开放平台，注册账号后在控制台创建。

5. 运行应用

streamlit run app.py

应用将在浏览器中自动打开，默认地址：http://localhost:8501

📁 项目结构

示例项目-角色扮演聊天室/
├── app.py              # 主程序
├── requirements.txt    # 项目依赖
├── .env.example        # 环境变量示例
├── .env                # 环境变量（需自行创建，不要提交！）
├── .gitignore          # Git 忽略文件
└── README.md           # 项目说明

🎭 预设角色介绍

角色	名称	特点
🐱	傲娇猫娘·小喵	傲娇但可爱，句尾带"喵~"，会用颜文字
🧙	智慧老者·玄清子	富有哲理，喜欢引用古诗词
🤖	毒舌AI·犀利哥	说话犀利一针见血，但有建设性
👨‍🔬	科学怪人·Dr.Eureka	疯狂科学家，热衷科学分析
🎮	游戏解说·电竞小王	充满激情，使用游戏术语
📚	文艺青年·林小诗	说话有诗意，会即兴创作

🛠️ 技术实现

核心技术点

DeepSeek API 调用
- 使用 OpenAI SDK 兼容接口
- 流式输出（Streaming）实现打字机效果
Streamlit 组件
- st.chat_message - 聊天消息展示
- st.chat_input - 聊天输入框
- st.session_state - 对话历史管理
- st.write_stream - 流式输出渲染
角色扮演机制
- System Prompt 定义角色性格和说话方式
- 多轮对话保持角色一致性

关键代码解析

流式输出实现

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
)

对话历史管理

# 初始化
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  # 历史消息

🎨 自定义角色指南

创建一个好的自定义角色，需要在角色设定中包含：

身份定义：角色是谁，背景是什么
性格特点：外向/内向、温柔/严厉等
说话方式：口癖、常用词、语气
对用户态度：如何称呼用户，关系定位
特殊行为：是否使用emoji、颜文字等

示例：创建一个"中二少年"角色

你是一个中二病少年，自称"黑暗骑士·雷恩"。你的特点：
- 认为自己拥有被封印的黑暗力量
- 经常用"我的右手又在疼了..."这样的台词
- 说话夸张，喜欢用"区区凡人"称呼用户
- 会假装痛苦地按住眼睛说"黑暗之眼快要觉醒了"
- 其实很好说话，问什么都会认真回答（虽然用中二的方式）

📝 开发心得

这个项目使用 Vibe Coding 方式开发，主要通过自然语言描述需求，让 AI 代码编辑器生成代码。

开发过程中的 Prompt 示例：

"帮我创建一个角色扮演聊天应用，使用 DeepSeek API 和 Streamlit。要求：左侧边栏选择角色，支持自定义角色，聊天界面要美观，使用流式输出，要保存对话历史。"

迭代优化：

"给界面加上渐变色效果，让角色卡片更好看一些"

"添加一个清空对话的按钮"

⚠️ 注意事项

保护 API Key：不要将 .env 文件提交到代码仓库
控制成本：DeepSeek API 按 Token 计费，长对话会消耗更多 Token
角色设定：过长的 System Prompt 会增加每次请求的成本

📚 参考资料

👤 作者

Python 程序设计课程设计 - 示例项目

Happy Vibe Coding! 🚀

7.2 KiB Raw Blame History Unescape Escape