221 lines
4.9 KiB
Markdown
221 lines
4.9 KiB
Markdown
# 快速入门指南
|
||
|
||
本指南将帮助你在 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 端口
|
||
|
||
---
|
||
|
||
祝你使用愉快！🚀
|