254 lines
7.5 KiB
Markdown
254 lines
7.5 KiB
Markdown
# 项目结构说明
|
|
|
|
## 📁 完整目录树
|
|
|
|
```
|
|
voicellmcloud/
|
|
│
|
|
├── 📄 README.md # 完整项目文档
|
|
├── 📄 QUICKSTART.md # 快速入门指南
|
|
├── 📄 STRUCTURE.md # 本文件
|
|
├── 📄 requirements.txt # Python 依赖清单
|
|
├── 📄 .env.example # 环境配置示例
|
|
├── 📄 .env # 环境配置 (git 忽略)
|
|
├── 📄 .gitignore # Git 忽略规则
|
|
│
|
|
├── 🚀 start.sh # Linux/macOS 启动脚本
|
|
├── 🚀 start.bat # Windows 启动脚本
|
|
│
|
|
├── 🧪 test_client.py # 测试客户端
|
|
├── 🔌 cloud_voice_client.py # 香橙派客户端适配器
|
|
│
|
|
├── 📂 app/ # 主应用代码
|
|
│ ├── __init__.py
|
|
│ ├── main.py # FastAPI 应用入口
|
|
│ ├── config.py # 配置管理
|
|
│ │
|
|
│ ├── 📂 protocols/ # 协议层 (独立于业务)
|
|
│ │ ├── __init__.py
|
|
│ │ ├── models.py # 消息数据模型 (Pydantic)
|
|
│ │ └── validators.py # 协议验证逻辑
|
|
│ │
|
|
│ ├── 📂 websocket/ # WebSocket 管理
|
|
│ │ ├── __init__.py
|
|
│ │ ├── session.py # 会话状态管理
|
|
│ │ └── handler.py # 消息路由与处理
|
|
│ │
|
|
│ ├── 📂 services/ # 业务服务接口
|
|
│ │ ├── __init__.py
|
|
│ │ ├── llm_service.py # LLM 服务接口定义
|
|
│ │ ├── tts_service.py # TTS 服务接口定义
|
|
│ │ └── intent_service.py # 意图识别服务
|
|
│ │
|
|
│ ├── 📂 providers/ # 第三方服务实现
|
|
│ │ ├── __init__.py
|
|
│ │ ├── dashscope_llm.py # 阿里云百炼 LLM 实现
|
|
│ │ └── piper_tts.py # Piper TTS 本地实现
|
|
│ │
|
|
│ └── 📂 utils/ # 工具模块
|
|
│ ├── __init__.py
|
|
│ ├── audio.py # 音频处理工具
|
|
│ └── logger.py # 日志配置
|
|
│
|
|
├── 📂 models/ # TTS 模型文件 (git 忽略)
|
|
│ └── README.txt # 模型下载说明
|
|
│
|
|
└── 📂 client/ # 香橙派客户端参考代码
|
|
└── voice_drone_assistant/ # (原有项目代码)
|
|
```
|
|
|
|
## 🎯 模块职责
|
|
|
|
### 应用核心 (`app/`)
|
|
|
|
| 模块 | 职责 | 关键文件 |
|
|
|------|------|---------|
|
|
| **入口** | FastAPI 应用、生命周期管理 | `main.py` |
|
|
| **配置** | 环境变量、配置验证 | `config.py` |
|
|
|
|
### 协议层 (`app/protocols/`)
|
|
|
|
| 模块 | 职责 | 设计原则 |
|
|
|------|------|---------|
|
|
| **models.py** | 定义所有消息的数据结构 | 严格遵循协议文档 |
|
|
| **validators.py** | 验证消息格式和合法性 | 独立于业务逻辑 |
|
|
|
|
**为什么独立协议层？**
|
|
- 协议变更不影响业务逻辑
|
|
- 便于版本管理和向后兼容
|
|
- 客户端开发可参考此规范
|
|
|
|
### WebSocket 层 (`app/websocket/`)
|
|
|
|
| 模块 | 职责 | 功能 |
|
|
|------|------|------|
|
|
| **session.py** | 管理所有活跃连接 | 创建/关闭/发送消息 |
|
|
| **handler.py** | 消息路由和业务编排 | 处理每种消息类型 |
|
|
|
|
### 服务层 (`app/services/`)
|
|
|
|
| 模块 | 类型 | 说明 |
|
|
|------|------|------|
|
|
| **llm_service.py** | 接口定义 | LLM 服务的抽象接口 |
|
|
| **tts_service.py** | 接口定义 | TTS 服务的抽象接口 |
|
|
| **intent_service.py** | 工具函数 | 意图识别和解析逻辑 |
|
|
|
|
**为什么用接口？**
|
|
- 支持多种实现（阿里云/本地/其他）
|
|
- 便于测试和 Mock
|
|
- 符合依赖倒置原则
|
|
|
|
### 提供者层 (`app/providers/`)
|
|
|
|
| 模块 | 实现 | 特点 |
|
|
|------|------|------|
|
|
| **dashscope_llm.py** | 阿里云百炼 | 云端 API 调用 |
|
|
| **piper_tts.py** | Piper 本地 | 高效本地推理 |
|
|
|
|
**扩展新的提供者：**
|
|
1. 实现对应接口
|
|
2. 在 `main.py` 注册
|
|
3. 更新配置枚举
|
|
|
|
### 工具层 (`app/utils/`)
|
|
|
|
| 模块 | 功能 |
|
|
|------|------|
|
|
| **audio.py** | 音频处理 (重采样/归一化/增益) |
|
|
| **logger.py** | 日志格式化和输出 |
|
|
|
|
## 🔄 数据流
|
|
|
|
```
|
|
香橙派客户端
|
|
↓ (WebSocket)
|
|
app/main.py (FastAPI 入口)
|
|
↓
|
|
app/websocket/session.py (连接管理)
|
|
↓
|
|
app/websocket/handler.py (消息处理)
|
|
├── 验证: app/protocols/validators.py
|
|
├── LLM: app/services/llm_service.py
|
|
│ └→ app/providers/dashscope_llm.py
|
|
├── 意图: app/services/intent_service.py
|
|
└── TTS: app/services/tts_service.py
|
|
└→ app/providers/piper_tts.py
|
|
↓ (音频数据)
|
|
香橙派客户端
|
|
```
|
|
|
|
## 📊 调用时序
|
|
|
|
```
|
|
turn.text 消息处理流程:
|
|
|
|
1. handler._handle_turn_text()
|
|
├── 验证消息格式
|
|
├── 构建 LLM 消息
|
|
├── 调用 LLM (dashscope_llm.py)
|
|
├── 解析意图 (intent_service.py)
|
|
├── 发送 dialog_result
|
|
├── 流式 TTS (piper_tts.py)
|
|
│ └→ 循环: 发送音频块
|
|
└── 发送 turn.complete
|
|
```
|
|
|
|
## 🛠 扩展指南
|
|
|
|
### 添加新的 LLM 提供者
|
|
|
|
```python
|
|
# 1. 创建文件: app/providers/my_llm.py
|
|
from app.services.llm_service import LLMServiceInterface
|
|
|
|
class MyLLMService(LLMServiceInterface):
|
|
async def chat(...): ...
|
|
async def initialize(...): ...
|
|
async def shutdown(...): ...
|
|
|
|
# 2. 在 app/config.py 添加枚举
|
|
# LLM_PROVIDER: str = "my_llm"
|
|
|
|
# 3. 在 app/main.py 注册
|
|
if settings.LLM_PROVIDER == "my_llm":
|
|
llm_service = MyLLMService()
|
|
```
|
|
|
|
### 添加新的 TTS 提供者
|
|
|
|
同上，实现 `TTSServiceInterface` 接口即可。
|
|
|
|
### 添加新的消息类型
|
|
|
|
```python
|
|
# 1. 在 app/protocols/models.py 定义消息模型
|
|
class MyNewMessage(BaseModel):
|
|
type: str = "my_new_message"
|
|
# ... 其他字段
|
|
|
|
# 2. 在 app/protocols/validators.py 添加验证
|
|
def validate_my_new_message(data: dict): ...
|
|
|
|
# 3. 在 app/websocket/handler.py 处理消息
|
|
async def handle_my_new_message(...): ...
|
|
```
|
|
|
|
## 📝 开发规范
|
|
|
|
### 命名约定
|
|
|
|
- **文件名**: 小写下划线 `snake_case.py`
|
|
- **类名**: 大驼峰 `ClassName`
|
|
- **函数名**: 小写下划线 `function_name()`
|
|
- **常量**: 大写下划线 `CONSTANT_VALUE`
|
|
|
|
### 代码组织
|
|
|
|
- 每个模块单一职责
|
|
- 接口与实现分离
|
|
- 依赖注入 (通过 `main.py` 组装)
|
|
|
|
### 错误处理
|
|
|
|
- 使用 Pydantic 验证消息格式
|
|
- 捕获异常并返回协议定义的错误码
|
|
- 记录详细日志供调试
|
|
|
|
## 🚀 部署说明
|
|
|
|
### 开发环境
|
|
```bash
|
|
python -m uvicorn app.main:app --reload
|
|
```
|
|
|
|
### 生产环境
|
|
```bash
|
|
# 使用 gunicorn + uvicorn workers
|
|
gunicorn app.main:app \
|
|
-w 4 \
|
|
-k uvicorn.workers.UvicornWorker \
|
|
--bind 0.0.0.0:8765
|
|
```
|
|
|
|
### Docker (未来规划)
|
|
```dockerfile
|
|
FROM python:3.10-slim
|
|
WORKDIR /app
|
|
COPY requirements.txt .
|
|
RUN pip install -r requirements.txt
|
|
COPY . .
|
|
CMD ["uvicorn", "app.main:app", "--host", "0.0.0.0", "--port", "8765"]
|
|
```
|
|
|
|
## 📖 相关文档
|
|
|
|
- **协议规范**: `CLOUD_VOICE_PROTOCOL_v1_text_uplink.md`
|
|
- **完整文档**: `README.md`
|
|
- **快速入门**: `QUICKSTART.md`
|
|
- **香橙派客户端**: `client/voice_drone_assistant/`
|
|
|
|
---
|
|
|
|
**更新日期**: 2024-04-07
|
|
**维护者**: 无人机云端语音服务团队
|