# 快速入门指南

本指南将帮助你在 10 分钟内启动云端语音服务并完成首次测试。

## 📋 前置要求

- Python 3.10 或更高版本
- 稳定的网络连接（访问阿里云）
- 至少 2GB 磁盘空间（用于 Piper 模型）

## 🚀 步骤 1: 安装依赖

```bash
# 进入项目目录
cd D:\project\flighter\voicellmcloud

# 安装 Python 依赖
pip install -r requirements.txt
```

## 📦 步骤 2: 下载 Piper TTS 模型

```bash
# 下载中文模型（约 60MB）
python -m piper.download_voice zh_CN-huayan-medium

# 确认模型文件已下载
dir models\zh_CN-huayan-medium.onnx
dir models\zh_CN-huayan-medium.onnx.json
```

如果 `piper.download_voice` 不可用，手动下载：

1. 访问: https://huggingface.co/rhasspy/piper-voices/tree/v1.0.0/zh_CN/huayan/medium
2. 下载 `zh_CN-huayan-medium.onnx` 和 `zh_CN-huayan-medium.onnx.json`
3. 将文件放到 `models/` 目录

## ⚙️ 步骤 3: 配置环境

```bash
# Windows 用户
copy .env.example .env

# 编辑 .env 文件，确认以下配置：
# BEARER_TOKEN=drone-voice-cloud-token-2024
# DASHSCOPE_API_KEY=sk-8ac47bb8a1f7497a922c52d905dd11dc
```

## ▶️ 步骤 4: 启动服务

```bash
# Windows 用户
start.bat

# 或直接运行
python -m uvicorn app.main:app --host 0.0.0.0 --port 8765 --reload
```

你应该看到类似输出：
```
云端无人机语音服务启动中...
DashScope LLM 初始化成功，模型: qwen-plus
正在加载 Piper 模型: zh_CN-huayan-medium
Piper TTS 初始化成功
监听地址: ws://0.0.0.0:8765/v1/voice/session
最大并发会话数: 4
```

## 🧪 步骤 5: 测试服务

打开**新的终端窗口**，运行测试客户端：

```bash
python test_client.py
```

测试客户端会依次发送：
1. 闲聊: "你好，今天天气怎么样？"
2. 飞控: "起飞然后在前方十米悬停"
3. 返航: "返航"
4. 降落: "降落"

你会看到：
- 服务端返回的意图识别结果
- TTS 音频数据
- 自动播放的语音回复

## 🔍 步骤 6: 验证健康检查

```bash
# 浏览器访问
http://localhost:8765/health

# 或使用 curl
curl http://localhost:8765/health
```

预期响应：
```json
{
  "status": "ok",
  "active_sessions": 0,
  "llm_provider": "dashscope",
  "tts_provider": "piper"
}
```

## 🎯 步骤 7: 集成到香橙派客户端

在你的香橙派项目中，修改代码以使用云端服务：

```python
# 在 main_app.py 中替换本地 LLM 调用
from cloud_voice_client import CloudVoiceClient

# 创建云端客户端
cloud_client = CloudVoiceClient(
    server_url="ws://192.168.1.100:8765/v1/voice/session",  # 你的云端 IP
    auth_token="drone-voice-cloud-token-2024",
    device_id="orange-pi-drone-001",
)

async def handle_voice_command(user_text: str):
    """处理语音指令（替换现有的本地 LLM 调用）"""
    async with cloud_client.connect():
        result = await cloud_client.send_text(user_text)
        
        if result.is_flight_intent():
            # 飞控指令
            print(f"飞控意图: {result.flight_intent}")
            actions = result.get_flight_actions()
            for action in actions:
                send_to_flight_controller(action)  # 发送到飞控板
        else:
            # 闲聊
            print(f"闲聊回复: {result.chat_reply}")
        
        # 播放 TTS
        await cloud_client.play_audio(result.audio_data)
```

## ❓ 常见问题

### Q1: Piper 模型下载失败

**问题**: 无法从 HuggingFace 下载

**解决**:
```bash
# 使用国内镜像（如阿里镜像）
# 或手动下载后放到 models/ 目录
```

### Q2: 服务启动失败

**问题**: `ModuleNotFoundError`

**解决**:
```bash
# 确认依赖已安装
pip install -r requirements.txt --upgrade
```

### Q3: LLM 调用超时

**问题**: `LLM_TIMEOUT`

**解决**:
```bash
# 增加超时时间（编辑 .env）
LLM_TIMEOUT=60
```

### Q4: TTS 无声

**问题**: 播放无声

**解决**:
```bash
# 检查音频数据是否正确接收
# 测试 Piper 模型
python -c "from piper import PiperVoice; v = PiperVoice.load('models/zh_CN-huayan-medium.onnx'); print('OK')"
```

### Q5: 鉴权失败

**问题**: `UNAUTHORIZED` 错误

**解决**:
```bash
# 确认 .env 中的 BEARER_TOKEN 与客户端 auth_token 一致
```

## 📊 性能参考

在正常网络条件下（香橙派与云端服务器同局域网）：

| 操作 | 延迟 |
|------|------|
| LLM 推理 | 1-3 秒 |
| TTS 首字节 | < 200ms |
| 总响应时间 | 2-4 秒 |

## 🎓 下一步

1. **阅读完整协议**: `CLOUD_VOICE_PROTOCOL_v1_text_uplink.md`
2. **查看架构文档**: `README.md` 中的架构设计部分
3. **自定义配置**: 编辑 `.env` 调整模型参数
4. **部署到生产环境**: 配置 TLS、监控、日志等

## 🆘 获取帮助

- 查看日志输出，寻找错误信息
- 设置 `LOG_LEVEL=DEBUG` 获取详细日志
- 检查 WebSocket 连接是否正常
- 确认防火墙未阻止 8765 端口

---

祝你使用愉快！🚀