Lyrria 技术框架总结
项目概述
| 项目名称 |
Lyrria 语音助手 |
| 类型 |
英语学习 AI 语音对话应用 |
| 架构 |
前后端分离 + WebSocket 实时通信 |
| 核心功能 |
实时语音对话（STT → LLM → TTS 流水线） |
前端技术栈
核心框架
| 技术 |
版本 |
用途 |
| React |
18.2.0 |
UI 框架 |
| TypeScript |
5.3.3 |
类型安全 |
| Vite |
5.0.8 |
构建工具 |
| Ant Design |
5.12.0 |
UI 组件库 |
状态管理
| 技术 |
用途 |
| Zustand 4.4.7 |
全局状态管理 |
样式方案
| 技术 |
配置 |
说明 |
| Tailwind CSS |
4.1.16 |
CSS 框架 |
| postcss-px-to-viewport |
1.1.1 |
移动端适配（375×812 基准，px → vw） |
| postcss + Autoprefixer |
8.5.6 / 10.4.21 |
CSS 后处理 |
音频处理
| 技术 |
用途 |
| recorder-core 1.2.23100900 |
录音功能 |
| lottie-web 5.12.2 |
GIF 动画渲染 |
| video.js 8.23.4 |
视频/音频播放 |
通信与路由
| 技术 |
用途 |
| React Router DOM 7.9.4 |
路由管理 |
| reconnecting-websocket 4.4.0 |
WebSocket 断线重连 |
开发工具
| 技术 |
用途 |
| @vitejs/plugin-react 4.2.1 |
React 插件 |
后端技术栈
核心框架
| 技术 |
版本 |
用途 |
| FastAPI |
0.110.0 |
Web 框架 |
| Uvicorn |
0.27.1 |
ASGI 服务器 |
| Python |
3.11+ |
开发语言 |
WebSocket
| 技术 |
用途 |
| websockets 12.0 |
WebSocket 协议实现 |
配置与日志
| 技术 |
用途 |
| python-dotenv 1.0.1 |
环境变量加载 |
| pydantic 2.6.1 |
数据验证 |
| pydantic-settings 2.2.1 |
配置管理 |
| loguru 0.7.2 |
日志记录 |
异步网络
| 技术 |
用途 |
| httpx 0.27.0 |
异步 HTTP 客户端（支持 HTTP/2 连接池） |
数据库
| 技术 |
用途 |
| SQLAlchemy 2.0.36 |
ORM（异步支持） |
| aiomysql 0.2.0 |
MySQL 异步驱动 |
| PyMySQL 1.1.0 |
MySQL 客户端 |
| redis 5.0.0+ |
缓存与会话存储（异步支持） |
测试
| 技术 |
用途 |
| pytest 8.2.1 |
测试框架 |
| pytest-asyncio 0.23.7 |
异步测试支持 |
| aiosqlite 0.20.0 |
SQLite 异步支持 |
AI 服务集成
DashScope（阿里云）
| 服务 |
模型 |
用途 |
| STT |
qwen3-asr-flash-realtime |
实时语音识别 |
| LLM |
qwen-flash / qwen-plus |
对话生成 |
| TTS |
cosyvoice-v3-flash / qwen3-tts-flash |
语音合成 |
核心服务文件
| 文件 |
功能 |
ai_service.py |
AI 服务封装（STT/LLM/TTS） |
stt_service.py |
语音识别服务 |
websocket_handler.py |
WebSocket 处理器（实时对话流水线） |
目录结构
Lyrria/
├── backend/ # 后端服务
│ ├── main.py # FastAPI 入口
│ ├── config.py # 配置管理（pydantic-settings）
│ ├── ai_service.py # AI 服务集成
│ ├── stt_service.py # STT 服务
│ ├── websocket_handler.py # WebSocket 处理器
│ ├── database.py # 数据库初始化
│ ├── http_pool.py # HTTP 连接池管理
│ ├── services/ # 业务服务层
│ │ ├── user_service.py # 用户服务
│ │ ├── message_service.py # 消息服务
│ │ ├── context_service.py # 上下文服务
│ │ ├── summary_service.py # 总结服务
│ │ ├── energy_stone_service.py # 能量石服务
│ │ ├── redis_cache_service.py # Redis 缓存
│ │ └── wechat_jsapi_service.py # 微信 JSSDK
│ └── models_db.py # 数据库模型
│
├── frontend/ # 前端应用
│ ├── src/
│ │ ├── pages/ # 页面组件（20+ 页面）
│ │ ├── components/ # 通用组件
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── store/ # Zustand 状态管理
│ │ ├── router/ # 路由配置
│ │ ├── types/ # TypeScript 类型定义
│ │ └── utils/ # 工具函数
│ ├── vite.config.ts # Vite 配置
│ ├── tailwind.config.js # Tailwind 配置
│ └── postcss.config.js # PostCSS 配置
│
├── memory_summaries/ # 记忆总结服务
├── sendmsg/ # 消息发送服务（邮件/短信）
└── 项目文档/ # 技术文档
部署配置
生产环境
| 组件 |
技术 |
| 反向代理 |
Nginx |
| SSL 证书 |
Let's Encrypt / 自签名 |
| 进程管理 |
systemd |
| 数据库 |
MySQL + Redis |
环境变量管理
| 文件 |
说明 |
backend/.env |
后端配置（API Key、数据库连接等） |
| Vite 环境变量 |
前端通过 VITE_* 前缀加载 |
核心配置项
# AI 服务
DASHSCOPE_API_KEY # 阿里云 API Key
STT_MODEL # 语音识别模型
LLM_MODEL # 语言模型
TTS_MODEL # 语音合成模型
# 数据库
MYSQL_HOST/PORT/USER/PASSWORD/DATABASE
REDIS_HOST/PORT/DB
# 服务
HOST/PORT # 服务监听地址
CORS_ORIGINS # 跨域白名单
性能优化
后端优化
| 优化项 |
实现 |
| HTTP/2 连接池 |
http_pool.py 管理 |
| TTS 连接预热 |
启动时后台预热 |
| 异步 I/O |
全程 async/await |
| 数据库连接池 |
SQLAlchemy 异步连接池 |
| Redis 连接复用 |
单例模式 |
前端优化
| 优化项 |
实现 |
| 移动端适配 |
postcss-px-to-viewport |
| 音频流式播放 |
边接收边播放 |
| WebSocket 重连 |
reconnecting-websocket |
| 组件懒加载 |
React.lazy |
| 响应式排版 |
clamp() + vw/vh |
第三方集成
| 平台 |
功能 |
| 微信开放平台 |
OAuth 登录 |
| 微信公众平台 |
JSSDK 分享 |
| QQ 开放平台 |
OAuth 登录 + 分享 |
技术特点
- 实时语音对话：STT → LLM → TTS 全流水线异步处理
- 移动端优先：响应式设计，px 自动转 vw
- 严格类型：Python 类型提示 + TypeScript 严格模式
- 高性能：HTTP/2 连接池 + 数据库连接池 + Redis 缓存
- 容错机制：TTS 重试 + WebSocket 重连 + 健康检查
