Open_Duck_Mini_Interact/Open Duck Mini技术文档.md

Open Duck Mini技术文档

一、项目概述

1.1 项目简介

本项目是一款基于树莓派的智能机器人控制系统，支持语音唤醒、语音指令识别、运动控制、图像识别、实时语音反馈等核心功能。系统采用模块化设计，便于维护与扩展。

1.2 核心功能

功能模块	具体能力
语音唤醒	通过 “小黄鸭” 唤醒词激活机器人，进入指令接收状态
语音识别	识别中文指令（如 “前进 3 秒”,“这是什么”,“增大音量”）
运动控制	控制机器人前进、后退、左转、右转（基于 ONNX 运动模型）
图像识别	拍摄图像并通过火山方舟 API 识别物体，实时语音播报结果
物品追踪	实时捕获图像,上传大模型分析并返回结果,再将决策转换为运动指令
语音反馈	通过百度 TTS 实现中文语音反馈，支持 “边生成文字边播报” 的实时交互体验
音量控制	调节系统音量（增大、减小、最大、最小）

二、环境准备

2.1 硬件要求

硬件设备	规格要求
主控板	树莓派 4B/5（建议 4GB 以上内存）
摄像头	树莓派官方摄像头（或兼容 USB 摄像头）
麦克风	USB 麦克风（支持 16kHz 采样率）
扬声器	树莓派兼容扬声器（GPIO或 USB）
电源	5V/3A 直流电源（确保运动时供电稳定）

2.2 软件依赖

2.2.1 系统环境:

• 操作系统：Raspberry Pi OS (Bookworm，64 位)
• Python 版本：3.10~3.11

2.2.2 必装依赖库:

通过以下命令安装所有依赖(在虚拟环境中安装)：

# 基础依赖
sudo apt-get update && sudo apt-get install -y ffmpeg portaudio19-dev libportaudio2

# Python库
pip install sounddevice pvporcupine websocket-client openai picamera2 pillow pyaudio pydub requests

2.2.3 特殊依赖:

1. 火山方舟 API：需注册火山引擎账号，创建 API 密钥（ARK_API_KEY）和模型 ID（ARK_MODEL_ID），参考main_scheduler.py。
2. 百度 TTS API：需注册百度智能云账号，创建应用获取BAIDU_TTS_API_KEY和BAIDU_TTS_SECRET_KEY。
3. 讯飞语音识别 API：需注册讯飞开放平台账号，创建应用获取APPID、ACCESS_KEY_ID、ACCESS_KEY_SECRET。
4. PicoVoice 唤醒词：需注册 PicoVoice 账号，获取ACCESS_KEY，并下载 “小黄鸭” 中文唤醒词文件（.ppn格式）以及porcupine_params_zh.pv文件。

三、部署流程:

• 创建虚拟环境时注意: python3 -m venv ~/duck --system-site-packages(否则无法找到libcamera)

• 启动虚拟环境: source ~/duck/bin/activate

• 项目路径: cd open_duck_mini_ws/OPEN_DUCK_MINI/Open_Duck_Mini_Runtime-2/scripts/

• 运行 main_scheduler.py 观察终端输出，确认模块初始化成功：

  ✅ 成功获取百度API访问令牌
  🔊 音量控制初始化成功（当前音量：40%）
  🤖 运动控制模块初始化成功
  📷 摄像头模块初始化成功
  ✅ API模块：初始化成功
  ✅ 语音识别模块：初始化成功
  🔍 正在测试语音输出...
  ✅ 语音播放完成: 系统初始化完成,等待语音唤醒...
  🎯 语音识别模块：唤醒词引擎就绪（采样率：16000）
  📢 语音识别模块：等待唤醒词「小黄鸭」
  

四、常见问题:

报错信息	排查方向
TTS初始化失败：无法获取百度API访问令牌	1. 检查百度 TTS 的API_KEY和SECRET_KEY是否正确；2. 树莓派是否能联网
运动控制失败：找不到v2_rl_walk_mujoco	1. 检查PROJECT_ROOT路径是否正确；2. 确认v2_rl_walk_mujoco.py已存在
摄像头失败：无法初始化Picamera2	1. 检查摄像头是否正确连接；2. 执行sudo raspi-config开启摄像头权限
找不到libcamera	https://blog.csdn.net/2301_78638152/article/details/145655038
其他问题	先把官方github仓库连接提交至豆包,作为参考进而排查问题

五、存在问题:

• 鸭子在启动后会乱动,关节会发生偏移,导致在执行前进后退时无法走直线
  • 解决方案:在每次执行运动指令前重新初始化标准站立位姿

六、//TODO

• 接入ai小智(mcp):https://www.ncnynl.com/archives/202509/6827.html