AI 角色扮演 API

基于 FastAPI 的高性能 AI 角色扮演后端系统，支持角色管理、智能对话和 AI 生成。

✨ 特性

• 高性能: 异步架构，支持 100-500 QPS
• 角色管理: 完整的 CRUD、导入导出、世界信息系统
• 智能对话: SSE 流式响应、提示词动态构建、历史记录
• AI 生成: 支持 7 种风格（通用/动漫/现实/奇幻/科幻/历史/现代）
• Redis 会话: 多 worker 共享会话、持久化存储
• 开箱即用: Docker 支持、自动 API 文档、Prometheus 监控

🚀 快速开始

1. 安装依赖

pip install -r requirements.txt

2. 配置环境

cp env.example .env
# 编辑 .env 文件，配置以下必需项：
# OPENAI_API_KEY=your-api-key
# OPENAI_BASE_URL=https://api.siliconflow.cn/v1
# CHARACTERS_DIR=../characters

3. 启动服务

# 开发模式
uvicorn app.main:app --port 8081 --reload

# 生产模式
uvicorn app.main:app --host 0.0.0.0 --port 8000 --workers 4

# Docker 部署
docker-compose up -d

4. 访问服务

• API 文档: http://localhost:8000/docs
• 健康检查: http://localhost:8000/health
• 监控指标: http://localhost:8000/metrics

📋 API 端点

角色管理 /api/v1/characters

方法	端点	说明
GET	/characters	获取角色列表
GET	/characters/{id}	获取角色详情
POST	/characters	创建角色
PUT	/characters/{id}	更新角色
DELETE	/characters/{id}	删除角色
POST	/characters/import	导入角色
GET	/characters/{id}/export	导出角色

对话系统 /api/v1/chat

方法	端点	说明
POST	/chat/start	开始对话
POST	/chat/message	发送消息（非流式）
POST	/chat/stream	发送消息（SSE 流式）
GET	/chat/history/{session_id}	获取对话历史
POST	/chat/reset	重置会话

AI 生成 /api/v1/generate

方法	端点	说明
POST	/generate/basic	生成基础信息
POST	/generate/dialogue	生成对话示例
POST	/generate/worldinfo	生成世界信息
POST	/generate/advanced	生成高级设置
POST	/generate/complete	完整生成角色

📁 项目结构

fastapi/
├── app/
│   ├── api/v1/              # API 路由
│   │   ├── characters.py    # 角色 API
│   │   ├── chat.py          # 对话 API
│   │   └── generator.py     # 生成 API
│   ├── core/                # 核心逻辑
│   │   ├── prompts.py       # 提示词模板
│   │   ├── prompt_builder.py        # 提示词构建
│   │   ├── world_info_processor.py  # 世界信息处理
│   │   └── chat_engine.py           # 聊天引擎
│   ├── models/              # 数据模型
│   ├── services/            # 服务层
│   ├── utils/               # 工具函数
│   ├── config.py            # 配置管理
│   └── main.py              # 应用入口
├── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── env.example

🔧 配置说明

主要配置项（.env 文件）：

# API 配置
API_TITLE=AI Roleplay API
API_VERSION=1.0.0
DEBUG=false
ENVIRONMENT=production

# 服务器配置
HOST=0.0.0.0
PORT=8000
WORKERS=4
LOG_LEVEL=info

# OpenAI 配置
OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.siliconflow.cn/v1
OPENAI_MODEL=deepseek-ai/DeepSeek-V3.1

# Redis 配置
REDIS_URL=redis://localhost:6379/0
SESSION_TTL=86400

# 性能配置
MAX_CONCURRENT_REQUESTS=100
REQUEST_TIMEOUT=300
STREAM_TIMEOUT=600
MAX_CACHE_SIZE=100
CACHE_TTL=3600

# CORS 配置
CORS_ORIGINS=["http://localhost:3000"]

📊 技术栈

组件	版本	用途
Python	3.12+	运行环境
FastAPI	0.115+	Web 框架
Pydantic	2.9+	数据验证
uvicorn	0.30+	ASGI 服务器
aiofiles	24.1+	异步文件操作
httpx	0.27+	异步 HTTP 客户端
orjson	3.10+	高性能 JSON
structlog	24.4+	结构化日志
openai	1.50+	OpenAI SDK
redis	5.2+	会话存储

🐳 Docker 部署

使用 Docker Compose（推荐）

Docker Compose 会自动启动 FastAPI 和 Redis 服务：

# 启动服务（包括 Redis）
docker-compose up -d

# 查看日志
docker-compose logs -f

# 停止服务
docker-compose down

手动构建

# 构建镜像
docker build -t fastapi-roleplay-api .

# 运行容器
docker run -d \
  -p 8000:8000 \
  --env-file .env \
  --name roleplay-api \
  fastapi-roleplay-api

🧪 测试

健康检查

curl http://localhost:8000/health

创建角色

curl -X POST http://localhost:8000/api/v1/characters \
  -H "Content-Type: application/json" \
  -d '{
    "name": "测试角色",
    "description": "这是一个测试角色的详细描述...",
    "personality": "友善、聪明、幽默",
    "scenario": "在一个舒适的环境中...",
    "first_mes": "你好！很高兴见到你！",
    "tags": ["测试", "示例"]
  }'

流式对话

curl -N -X POST http://localhost:8000/api/v1/chat/stream \
  -H "Content-Type: application/json" \
  -d '{
    "session_id": "test_session",
    "message": "你好"
  }'

🔍 常见问题

Q: 如何修改端口？

# 方式1：环境变量
export PORT=8001
python -m app.main

# 方式2：.env 文件
PORT=8001

# 方式3：命令行参数
uvicorn app.main:app --port 8001

Q: OpenAI API 密钥配置

在 .env 文件中配置：

OPENAI_API_KEY=your-api-key
OPENAI_BASE_URL=https://api.siliconflow.cn/v1  # 可选
OPENAI_MODEL=deepseek-ai/DeepSeek-V3.1         # 可选

Q: 角色文件目录配置

# .env 文件
CHARACTERS_DIR=../characters  # 相对路径
# 或
CHARACTERS_DIR=/path/to/characters  # 绝对路径

Q: 启用调试模式

# .env 文件
DEBUG=true
LOG_LEVEL=debug

📈 性能指标

指标	目标	说明
响应时间 (P99)	< 500ms	非流式接口
吞吐量	100-500 QPS	并发请求处理
内存占用	< 512MB	单 worker
启动时间	< 5s	冷启动
SSE 延迟	< 100ms	流式响应

🛠️ 开发指南

添加新的 API 端点

1. 在 app/models/ 中定义数据模型
2. 在 app/services/ 中实现业务逻辑
3. 在 app/api/v1/ 中创建路由
4. 在 app/main.py 中注册路由

代码质量检查

# 格式化代码
black app/

# 代码检查
ruff check app/

# 类型检查
mypy app/

📝 待优化项

• Redis 会话存储 ✅ 已完成
• API 速率限制
• 完整单元测试覆盖
• WebSocket 支持
• 用户认证系统

📄 License

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

---

版本: 1.0.0
状态: ✅ 生产就绪
更新: 2025-10-10