DroneMind/voicellmcloud/docs/QUICKSTART.md

快速入门指南

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

📋 前置要求

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

🚀 步骤 1: 安装依赖

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

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

📦 步骤 2: 下载 Piper TTS 模型

# 下载中文模型（约 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: 配置环境

# Windows 用户
copy .env.example .env

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

▶️ 步骤 4: 启动服务

# 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: 测试服务

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

python test_client.py

测试客户端会依次发送：

1. 闲聊: "你好，今天天气怎么样？"
2. 飞控: "起飞然后在前方十米悬停"
3. 返航: "返航"
4. 降落: "降落"

你会看到：

• 服务端返回的意图识别结果
• TTS 音频数据
• 自动播放的语音回复

🔍 步骤 6: 验证健康检查

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

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

预期响应：

{
  "status": "ok",
  "active_sessions": 0,
  "llm_provider": "dashscope",
  "tts_provider": "piper"
}

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

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

# 在 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 下载

解决:

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

Q2: 服务启动失败

问题: ModuleNotFoundError

解决:

# 确认依赖已安装
pip install -r requirements.txt --upgrade

Q3: LLM 调用超时

问题: LLM_TIMEOUT

解决:

# 增加超时时间（编辑 .env）
LLM_TIMEOUT=60

Q4: TTS 无声

问题: 播放无声

解决:

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

Q5: 鉴权失败

问题: UNAUTHORIZED 错误

解决:

# 确认 .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 端口

---

祝你使用愉快！🚀