OpenDuckMini 是一个开源桌面机器人项目中文社区通常把它叫做“开源机器鸭”树莓派 4B 版本的核心体验之一是语音控制。用户按下手中按钮鸭子就能录音把语音转成文字交给大模型生成回答再把回答合成为语音播放出来同时让头部舵机配合摆动作。整个过程不再是“手机 APP 远程命令”式的控制而是本地设备直接参与采集、推理调度和动作输出。如果你手里已经有一套 OpenDuckMini 机器鸭的套件或者准备用树莓派 4B 复刻一个这篇内容会围绕“语音控制”这条主线展开先讲清楚这套系统的软硬件链路再拆解音频设备、I2C 舵机驱动、Python 运行环境和模型接口最后跑通一个从录音、识别、大模型对话到 TTS 播放的最小闭环并给出常见问题排查方法。需要先说明一点OpenDuckMini 目前有多个分支和社区版本不同作者的源码目录、依赖包名、启动命令不完全一致。本文按树莓派 4B 的常见开发流程组织实际操作到具体文件时请以官方仓库、中文知识库和随套件附带文档为准。1. 先理解 OpenDuckMini 的工作方式再看树莓派 4B 在语音链路里的位置1.1 机器鸭到底是一台什么设备OpenDuckMini 并不是一个单纯的“语音助手外壳”它更像一个桌面机器人原型。外形是 3D 打印的小鸭子内部用树莓派作主控外接麦克风、扬声器、摄像头和多路舵机。软件层通过语音、视觉和运动控制三个模块协作实现类似“和人对话时看着你、听到问题后点头”的交互体验。中文网络上的“同济子豪兄 openduckmini 开源机器鸭”相关内容通常会整理中文文档、CAD 图纸、套件及整机购买渠道。这类资料的好处是把硬件清单、拼装步骤和软件烧录串在一起但真正开始调语音时问题往往不是鸭子装不起来而是麦克风没有进声、大模型 API 不通、扬声器不响、舵机乱抖这些底层环节。所以不要把 OpenDuckMini 看成“一个树莓派程序”而要理解成一条实时数据流水线。树莓派 4B 的角色是枢纽它负责采集音频调用识别模型拼装大模型对话请求播放语音再根据文本内容或情绪生成舵机动作。任何一个环节断了语音控制都会表现出不同形式的“失灵”。1.2 树莓派 4B 适合做机器人主控的原因树莓派 4B 相比更小的 Zero 系列有明显的算力和接口优势。语音识别如果在本地跑需要 CPU 转录大模型虽然多数走远程 API但网络协议栈、HTTP 请求、音频流处理也需要稳定性能摄像头做视觉时还会占用编码和解码资源。树莓派 4B 的典型配置是四核 Cortex-A72 处理器内存有 2GB、4GB、8GB 版本。OpenDuckMini 这类项目建议优先选 4GB 以上版本。2GB 版本也能跑最小对话但本地 Whisper 转录、浏览器调试页面、后台日志同时开启时内存很容易吃满表现为识别卡顿、TTS 播放断断续续、SSH 响应慢。从接口角度看树莓派 4B 提供 USB 3.0、USB 2.0、GPIO、I2C、UART 和摄像头 MIPI 接口。USB 麦克风可以直接插到 USB 口舵机驱动板可以接到 GPIO 的 I2C 或 PWM 引脚摄像头既可以用 USB 摄像头也可以用 CSI 排线摄像头。对新手来说USB 外设比排线接口更容易排查问题。1.3 一次语音控制的完整数据流按逻辑可以把一次完整交互分成七个阶段触发用户按物理按键或说唤醒词告诉树莓派“准备开始听”。录音树莓派从 USB 麦克风采集若干秒音频保存为 WAV。ASR自动语音识别把 WAV 转成文本。语义把文本作为用户消息发送给大模型服务。应答大模型返回回复文本。TTS文本转语音生成音频文件并播放。动作根据回复内容或用户消息控制舵机点头、摇头或摆头。项目初期的架构调整通常发生在第 1 步和第 3 步。很多版本默认用“实体按键触发”而不是“语音唤醒词”因为树莓派 4B 一直在跑本地唤醒词会增加 CPU 和麦克风误唤醒负担。实体按键方式更稳定也更容易调试按一下按键日志开始录音录音结束进入识别整个过程的所有节点都有明确边界。2. 硬件准备与系统初始化先解决供电、接口和默认音频设备2.1 树莓派 4B 版硬件清单与选型注意点如果购买的是成品套件硬件清单以套件说明书为准如果自己采购散件复刻可按以下表格核对核心部件部件作用常见选型注意事项树莓派 4B系统主控4GB 或 8GB 版本内存版本影响本地模型并发TF 卡系统盘32GB 以上A1 或 A2 速度劣质卡会导致系统随机卡死USB 麦克风采集语音USB 免驱麦克风不支持免驱的声卡会非常难调扬声器或功放播放 TTSUSB 小音箱或 I2S 功放优先选 USB 音频设备接线少舵机驱动板控制鸭子头部PCA9685 或同类 I2C 驱动板先查 I2C 地址再控制舵机舵机头部动作SG90、MG90S 或 MG996R注意扭矩和供电电流USB 摄像头视觉输入免驱 UVC 摄像头可选不影响最小语音闭环按键和 LED触发和状态提示轻触开关、发光二极管GPIO 接法必须加限流电阻电源整机供电5V 3A 以上稳压电源舵机不能和主控共用一路易波动电源最容易出问题的不是树莓派本身而是供电。SV 舵机在启动时会瞬间拉高电流如果舵机和树莓派共用同一路电源且电源余量不足会造成树莓派掉电重启、USB 麦克风掉线、USB 声卡不出声。推荐做法是树莓派用一路 5V 3A 电源舵机驱动板单独用 5V 或 6V 稳压电源两者只共地不共用电压轨。2.2 烧录操作系统并打开必要接口语音控制项目不需要桌面图形界面建议使用 Raspberry Pi OS Lite 64 位版本减少系统资源占用。用 Raspberry Pi Imager 烧录时可以在“设置”里预先打开 SSH、设置用户名和密码、配置 Wi-Fi。烧录完成后插入 TF 卡启动并通过 SSH 登录。首先做一次系统更新sudo apt update sudo apt full-upgrade -y随后安装基础工具和音频依赖sudo apt install -y git python3-pip python3-venv \ libportaudio2 mpg123 espeak-ng接下来打开树莓派需要启用的接口。在终端执行sudo raspi-config按菜单顺序处理Interface Options - I2C - Enable开启 I2C。Interface Options - SSH - Enable保持远程登录。Interface Options - Camera - Enable如果计划使用摄像头。System Options - Boot / Auto Login建议选择无桌面自动登录或 SSH 登录。重启后确认 I2C 设备是否出现sudo reboot登录后执行i2cdetect -y 1。如果舵机驱动板和所有外设都正常连接通常会在地址表格中看到类似0x40或0x60的十六进制地址。没有看到地址时不要急着运行项目先检查舵机驱动板的 VCC、GND、SDA、SCL 四条线。2.3 固定音频设备和网络地址树莓派同时插入 USB 麦克风和 USB 音箱时系统会把它们编号为声卡 0、1、2。USB 设备每次插拔顺序变化声卡编号可能变化直接写死hw:1,0往往重启后失效。先查询当前识别的声卡arecord -l aplay -l输出会列出类似card 1: Microphone [USB Microphone], device 0: USB Audio的信息。更稳的方法是写一个/etc/asound.conf把默认录音设备指向麦克风、默认播放设备指向扬声器pcm.!default { type asym capture.pcm plughw:1,0 playback.pcm plughw:0,0 } ctl.!default { type hw card 0 }上面示例假设声卡 0 是扬声器声卡 1 是麦克风。实际数字以arecord -l和aplay -l查询结果为准。只做最小语音闭环时也可以在 Python 录音命令里直接写plughw:card,device先不配置全局默认。固定 IP 可以由路由器 DHCP 保留地址完成也可以在树莓派系统里配置静态地址。对机器人来说SSH 地址固定能显著减少调试成本避免每次重启都要去路由器后台找新 IP。3. 搭建代码与环境克隆源码、创建虚拟环境、配置模型密钥3.1 克隆 OpenDuckMini 源码并确认目录结构在项目目录下克隆官方仓库。命令里的仓库地址要替换成你实际使用的源码地址mkdir -p ~/projects cd ~/projects git clone 仓库地址 openduckmini cd openduckmini如果当前网络环境不方便使用 git 协议也可以直接下载源码 zip 包解压后放到~/projects/openduckmini。克隆完成后不要盲目运行python main.py。先看仓库根目录ls -la cat README.md不同版本目录通常包含openduckmini/ ├── configs/ # 配置文件 ├── docs/ # 官方文档 ├── services/ # 音频、识别、对话、动作服务 ├── models/ # 本地模型存放目录 ├── tests/ # 测试和自检脚本 ├── requirements.txt # Python 依赖 ├── .env.example # 环境变量示例 └── main.py # 主程序入口如果看到pyproject.toml而不是requirements.txt说明项目使用较新的 Python 打包方式依赖安装命令也需要相应调整。这时按 README 里的安装命令执行即可。3.2 创建虚拟环境并安装依赖Python 环境不建议直接装在系统全局因为树莓派系统由 apt 管理软件包全局 Python 被覆盖或升级后可能导致系统工具损坏。使用虚拟环境可以把项目依赖隔离在目录内python3 -m venv .venv source .venv/bin/activate pip install --upgrade pip pip install -r requirements.txt如果仓库没有requirements.txt而是使用 pyproject可以尝试pip install -e .安装过程可能比较长因为 faster-whisper、numpy、opencv 等依赖体积较大。安装完成后可以把项目目录内所有 Python 包列出来确认核心依赖是否在安装列表里pip list | grep -Ei openai|whisper|edge|flask|gpio|pyserial|pyaudio在这一步最容易踩的坑是项目依赖同时包含pyaudio和portaudio系统库但两个包先后安装顺序不对导致pyaudio编译时找不到头文件。解决方式是先安装系统包libportaudio2和portaudio19-dev再安装 Python 包pyaudio顺序不要颠倒。3.3 配置环境变量密钥、模型名和硬件参数语音链路的模型调用通常通过 API 完成。项目会读取环境变量把大模型服务的地址、密钥、模型名提供给你调用的代码。先看是否有模板文件cp .env.example .env如果没有模板可以手动创建.env文件内容结构大致如下# 大模型服务配置字段名以项目 README 为准 LLM_BASE_URLhttps://api.example.com/v1 LLM_API_KEYyour-api-key-here LLM_MODELyour-model-name # 音频设备配置 AUDIO_DEVICEplughw:1,0 # 按钮 GPIO 编号BCM 编码 BUTTON_PIN17 # TTS 语音参数 TTS_VOICEzh-CN-XiaoxiaoNeural需要注意.env里面是真实的密钥信息必须加入.gitignore不要提交到公开仓库。代码运行时通过python-dotenv读取这个文件也可以写成在启动脚本里手动 export。最不推荐的做法是把密钥直接硬编码到 Python 源码里原因是源码一旦被分发、上传、备份密钥就会泄露。如果项目没有内置“对话服务”就需要自己补上大模型调用逻辑下一章会给出一个最小闭环示例。对于树莓派本地执行 ASR 的场景还要确认下载的 Whisper 模型文件路径并注意首次运行会联网下载模型可能耗时较长。4. 跑通最小语音对话闭环录音、ASR、大模型、TTS、动作输出4.1 先验证录音和回放在写代码之前用系统命令验证麦克风和扬声器。先执行录音命令arecord -D plughw:1,0 -f S16_LE -r 16000 -c 1 -d 5 /tmp/robot.wav命令说明-D plughw:1,0指定录音设备。-f S16_LE16 位小端 PCM 格式。-r 16000采样率 16k适合中文语音识别。-c 1单声道。-d 5录音 5 秒。录音完成后回放aplay -D plughw:0,0 /tmp/robot.wav如果回放能听到自己的声音说明音频硬件链路已经通。如果回放是空白或杂音优先检查麦克风是否被静音、声卡默认设备是否设置正确、USB 麦克风是否被系统识别。树莓派部分版本默认使用 PulseAudio 或 PipeWire会出现直接调用arecord时静音、但桌面端录音正常的情况。可以在命令前加pasuspender --临时绕过音频服务pasuspender -- arecord -D plughw:1,0 -f S16_LE -r 16000 -c 1 -d 5 /tmp/robot.wav这类环境差异在 OpenDuckMini 不同镜像版本上经常出现所以先从最底层命令验证最稳妥。4.2 写一个按键触发录音脚本语音助手不建议做成“永不停止监听”这样既浪费 CPU也容易把环境噪声误识别成命令。最小可行方案是 GPIO 按键触发。# button_demo.py import time import RPi.GPIO as GPIO BUTTON_PIN 17 GPIO.setmode(GPIO.BCM) GPIO.setup(BUTTON_PIN, GPIO.IN, pull_up_downGPIO.PUD_UP) print(按住按钮测试中CtrlC 退出) try: while True: if GPIO.wait_for_edge(BUTTON_PIN, GPIO.FALLING, timeout1000): print(按钮被按下) time.sleep(0.3) except KeyboardInterrupt: GPIO.cleanup()说明GPIO.PUD_UP启用内部上拉按下时引脚变成低电平所以监听FALLING。time.sleep(0.3)做简单消抖防止机械开关抖动导致一次按下列表触发多次。如果树莓派上RPi.GPIO安装失败可以改用gpiod库语法略有不同但排查思路一致。运行测试python button_demo.py按下按钮后终端如果输出“按钮被按下”说明 GPIO 通路正常。4.3 本地 ASR用 faster-whisper 把 WAV 变成文本树莓派 4B 不适合直接部署超大语音模型但 faster-whisper 的 tiny 或 base 模型可以勉强在本地跑。后者更准确但响应时间更长。下面使用 tiny 模型做功能验证# asr_demo.py from faster_whisper import WhisperModel model WhisperModel(tiny, devicecpu, compute_typeint8) segments, info model.transcribe( /tmp/robot.wav, languagezh, vad_filterTrue, ) text .join(seg.text for seg in segments) print(识别结果:, text.strip())其中compute_typeint8用整数计算降低 CPU 压力。vad_filterTrue过滤静音片段避免把无声时长也转成无用文本。tiny 模型体积小、速度快但中文识别准确率一般如果设备有一定余量可以换“base”或“small”。如果本地转录太慢可以把音频文件传给在线 ASR 服务。OpenDuckMini 源码里如果集成了 ASR 服务商会封装一个recognize()函数项目只需要把本地结果替换成云端服务返回值即可。关键是保持函数输入输出一致输入是音频路径输出是字符串。4.4 接入大模型服务获取回复大模型调用采用 OpenAI 兼容接口是常见做法。就算服务商不是 OpenAI也可以使用自建 vLLM、Ollama 等提供兼容/v1/chat/completions的接口。# llm_demo.py import os from dotenv import load_dotenv from openai import OpenAI load_dotenv() client OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), ) response client.chat.completions.create( modelos.getenv(LLM_MODEL), messages[ { role: system, content: 你是 OpenDuckMini 机器鸭说话要简短、亲切像一个桌面宠物。, }, { role: user, content: 请介绍一下你自己。, }, ], temperature0.7, ) print(response.choices[0].message.content)这个示例的关键点base_url决定了请求发到哪里可以是https://api.example.com/v1也可以是内网地址。对话历史如果一直无限追加请求体越来越长响应变慢。项目里通常会用一个固定长度的消息列表超过 N 条就丢弃最早的历史。temperature控制随机程度。对话机器人可以设成 0.7但如果希望鸭子每次回复更稳定可以调低到 0.3 到 0.5。运行前先确认.env中LLM_BASE_URL、LLM_API_KEY、LLM_MODEL都没问题。能打印出大模型回复链路就从“文字”到了“语义理解”这一环。4.5 TTS文本转语音并播放TTS 有多种选择。edge-tts 使用微软在线语音合成中文音色自然但需要联网espeak-ng 完全离线稳定但音质机械。OpenDuckMini 中文语音体验通常会用更好的神经网络音色调试阶段可以先用 espeak-ng 验证扬声器通路再切换 edge-tts。espeak-ng 快速验证espeak-ng -v zh 你好我是机器鸭 --stdout | aplay如果这一句能播放中文说明从系统音频到扬声器的通路没问题。使用 edge-tts 得到更自然的声音# tts_demo.py import asyncio import edge_tts TEXT 你好我是机器鸭很高兴见到你。 VOICE zh-CN-XiaoxiaoNeural OUTPUT /tmp/robot_voice.mp3 async def main(): communicate edge_tts.Communicate(TEXT, VOICE) await communicate.save(OUTPUT) asyncio.run(main())运行完用播放器播放 mp3mpg123 /tmp/robot_voice.mp3edge-tts 依赖网络请求微软语音服务如果网络不稳定或代理异常可能返回 403 或超时。这种场景下直接把 TTS 换成本地模型或用树莓派系统自带的 pico2wave/离线语音方案先保住链路可用再优化音质。4.6 组合成一个最小完整链路下面把录音、ASR、大模型、TTS 拼接成一个只有核心逻辑的脚本。代码去掉了复杂状态机和配置读取用来演示数据如何流动# robot_mini.py import os import subprocess import numpy import RPi.GPIO as GPIO from faster_whisper import WhisperModel from openai import OpenAI import edge_tts import asyncio BUTTON_PIN 17 AUDIO_IN plughw:1,0 AUDIO_OUT plughw:0,0 WAV_PATH /tmp/robot.wav MP3_PATH /tmp/robot.mp3 asr WhisperModel(tiny, devicecpu, compute_typeint8) llm OpenAI( api_keyos.getenv(LLM_API_KEY), base_urlos.getenv(LLM_BASE_URL), ) # 对话历史 messages [ { role: system, content: 你是机器鸭。回答要简短不超过三句话。, } ] def record(): subprocess.run( [ arecord, -D, AUDIO_IN, -f, S16_LE, -r, 16000, -c, 1, -d, 5, WAV_PATH, ], checkFalse, ) def recognize(): segments, _ asr.transcribe(WAV_PATH, languagezh, vad_filterTrue) return .join(seg.text for seg in segments).strip() def ask(text): messages.append({role: user, content: text}) resp llm.chat.completions.create( modelos.getenv(LLM_MODEL), messagesmessages, ) answer resp.choices[0].message.content.strip() messages.append({role: assistant, content: answer}) return answer async def speak(text): tts edge_tts.Communicate(text, zh-CN-XiaoxiaoNeural) await tts.save(MP3_PATH) def play(): subprocess.run([mpg123, MP3_PATH], checkFalse) GPIO.setmode(GPIO.BCM) GPIO.setup(BUTTON_PIN, GPIO.IN, pull_up_downGPIO.PUD_UP) print(OpenDuckMini 最小语音链路已启动按下按钮说话) try: while True: if GPIO.wait_for_edge(BUTTON_PIN, GPIO.FALLING, timeout1000): record() user_text recognize() if not user_text: continue print(用户说:, user_text) answer ask(user_text) print(机器鸭回答:, answer) asyncio.run(speak(answer)) play() finally: GPIO.cleanup()这个脚本演示的是“可理解的最小闭环”没有处理超时、异常和并发也不建议直接作为生产入口。实际 OpenDuckMini 的 main.py 会包含状态机、日志、异常恢复、动作映射等服务。把这个脚本跑通的最大价值是确认每个环节都能独立工作如果按钮按下后没有输出问题在 GPIO如果录音后识别为空问题在麦克风如果识别有文字但没有回答问题在大模型配置如果有回答但没有声音问题在 TTS 和播放器。5. 运行验证与日志机制从现象定位到具体组件5.1 用自检清单代替“边试边猜”树莓派机器人出问题时最忌讳的现象是“我按了按钮鸭子没反应”。这句话能覆盖的故障范围太广可能是按钮没接好、程序没启动、麦克风没识别、程序崩溃、扬声器静音、大模型密钥过期等各种原因。建议在整个开发阶段维护一张自检清单按顺序检查检查项操作方法预期结果对应组件电源稳定观察开机和舵机动作时是否重启鸭子不重启、屏幕不闪断电源项目进程运行ps aux | grep robot能看到 python 主进程主程序GPIP 按键触发运行按键测试脚本按下时终端有输出按键声卡识别arecord -l、aplay -l列出 USB 麦克风和扬声器USB 音频录音文件存在录音后执行ls -l /tmp/robot.wav文件不是 0 字节麦克风ASR 转文字执行python asr_demo.py能打印中文文本Whisper大模型回复执行python llm_demo.py能打印回复API/网络TTS 文件生成执行python tts_demo.pymp3 文件存在TTS 服务扬声器播放mpg123 /tmp/robot.mp3能听到中文声音功放/声卡舵机动作运行官方舵机测试脚本头部能按预设角度转动I2C/舵机每完成一个检查项就把它从“可能原因”列表里划掉。最后剩下的范围通常就是真正的问题。5.2 给每个关键节点增加结构化日志程序只在运行正常时有 print 是不够的因为语音控制链路经常出间歇性问题。比如运行 10 次只有一次识别错误没有日志就很难判断是网络超时还是识别模型把“你好”听成“你号”。在代码里给每个阶段输出带时间戳和阶段名的日志例如2025-01-06 10:00:01 [record] start 2025-01-06 10:00:06 [record] saved /tmp/robot.wav size88044 2025-01-06 10:00:11 [asr] text你好 2025-01-06 10:00:13 [llm] start 2025-01-06 10:00:15 [llm] answer你好我是机器鸭 2025-01-06 10:00:15 [tts] start 2025-01-06 10:00:17 [tts] saved mp3 2025-01-06 10:00:17 [play] start如果主程序不使用日志库至少用 Python 的logging模块输出到文件import logging logging.basicConfig( format%(asctime)s %(levelname)s %(name)s %(message)s, levellogging.INFO, ) logger logging.getLogger(robot) logger.info(record start)日志文件的路径建议放在/tmp/robot.log或项目目录下的logs/。用journalctl管理时系统服务会捕获 stdout/stderr可以直接用journalctl -u robot -f查看。5.3 从每个异常现象反推组件常见现象可以快速对照处理按钮按下后录音开始但识别结果为空麦克风采集到的基本是静音检查声卡编号、录音音量、是否接了正确 USB 口。识别有文本但大模型不回答执行 llm_demo.py观察是否有 HTTP 错误检查密钥、模型名、余额/权限。大模型能回答但播放没声音检查 aplay 默认声卡和 TTS 生成文件不要直接用aplay播放 mp3mp3 需要 mpg123。播放声音正常但鸭子头不转舵机系统单独验证与语音链路无关。整个链路流程很慢从按下按钮到说话超过 15 秒最常见是本地 ASR 模型太大或网络请求跨地域延迟高或每次录音时长设置过长。这些现象都能通过日志和自检清单映射到具体组件。坚持“只改一处、验证一次”的原则不要同时换模型、换声卡、换代码否则一旦故障消失根本无法判断是哪一步修复的。6. 树莓派 4B 常见问题排查音频、I2C、供电和依赖6.1 音频问题排查清单现象可能原因检查方式处理建议录音文件非常大但没有声音USB 麦克风未工作查看文件大小和波形测试另一个声卡编号播放 TTS 无声声卡默认设备错误aplay -l对比修改