DroneMind/voicellmcloud/docs/STRUCTURE.md

项目结构说明

📁 完整目录树

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 提供者

# 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 接口即可。

添加新的消息类型

# 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 验证消息格式
• 捕获异常并返回协议定义的错误码
• 记录详细日志供调试

🚀 部署说明

开发环境

python -m uvicorn app.main:app --reload

生产环境

# 使用 gunicorn + uvicorn workers
gunicorn app.main:app \
    -w 4 \
    -k uvicorn.workers.UvicornWorker \
    --bind 0.0.0.0:8765

Docker (未来规划)

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
维护者: 无人机云端语音服务团队