Skip to main content

Reachy Mini 豆包语音对话应用

Reachy Mini 语音对话应用

License: Apache 2.0Python Versionreachy_mini SDKPlatform

语音对话 · 豆包 LLM 工具调用 · 声源定位 · 手部跟随 · 仿真/真机镜像 · Gradio Web UI

Reachy Mini Conversation 是一个开源的对话式机器人应用，为 Pollen Robotics 的 Reachy Mini 设计。它把豆包大语言模型（豆包方舟 Ark）、豆包流式语音识别 WebSocket API、Edge TTS 三者串联起来，通过 Reachy Mini SDK 提供完整的语音对话体验。Web UI 基于 Gradio，支持 MuJoCo 仿真与真机镜像、声源定位驱动头部、MediaPipe 手部跟随。

Star on GitHub4.4k
tip

本 wiki 仅以豆包大语言模型 Doubao-Seed-Character 与豆包流式语音识别 2.0 为案例，再次提醒 Reachy Mini 本身支持接入任意一款国内外模型，也支持本地部署且以服务化 API 公开的模型。

项目特点​

  1. 语音对话：说中文 → 豆包 ASR 实时识别 → 豆包 LLM 回复（可调用动作工具）→ Edge TTS 播音，动作与语音并行执行。
  2. 身体动作：LLM 主动调用工具（dance / move_head / play_emotion / idle_sway 等），后台线程执行，不阻塞对话。
  3. 声源定位：麦克风阵列检测说话人方向，自动转头（默认关闭，可手动开启）。
  4. 手部跟随：MediaPipe 检测手掌，头部实时跟随（对话中说「开始手部跟随」或使用 UI 开关）。
  5. 真机 ↔ 仿真镜像：左侧 three.js 交互式 3D 视图 + MuJoCo 渲染对照，右侧真机摄像头实时画面。
  6. 待机微动：空闲时呼吸式头部微动 + 天线摆动（官方 BreathingMove 移植），说话时自动切换为音频驱动的摆头。
  7. Gradio Web UI：浏览器打开 localhost:7860 即可使用，深色主题。

适用硬件：Reachy Mini Lite（有线 USB）与无线版（RPi CM4 本体）；仿真模式无需硬件。三种形态一条命令隔离：--sim / --wired / --robot。

效果展示​

📺 演示视频
点击观看 Bilibili 演示视频
📺 点击前往 Bilibili 观看完整演示视频

环境要求​

前置要求 — 请先完成 Reachy Mini SDK 安装

开始本教程前，请务必先完成 Reachy Mini 的 Python SDK 安装，具体流程请参考 Reachy Mini Python SDK 安装指南。

项目要求
Python3.12（推荐通过 conda 安装）
操作系统Ubuntu 22.04 / Debian，或 Windows 11
硬件（可选）Reachy Mini Lite（有线 USB）/ 无线版（内置树莓派 CM4）
网络需访问火山引擎 API；语音对话需配置 API Key

三种配置方式，按你的环境选一条：

你的情况走哪条
有线版机器人 + Ubuntu PC👉 方式 A：Ubuntu
有线版机器人 + Windows PC👉 方式 B：Windows
无线版机器人（内置树莓派 CM4）👉 方式 C：无线版
还没买机器人，先体验仿真任选 A / B 的纯仿真模式，无需硬件

三者的配置 API Key、局域网访问、故障排查是共用的，见各自方式之后的公共章节。

快速上手​

前置：Ubuntu / Debian 系统，Python 3.12（conda 提供），sudo 权限。已在 Ubuntu 22.04 全新环境实测通过（290 测试全过 + 真机全链路验收）。

1

克隆仓库

第 1 步

git clone https://github.com/TheMoonAstronaut/Reachy_Mini_conversation.git
cd Reachy_Mini_conversation
2

安装系统依赖（cairo / gstreamer / ffmpeg）

第 2 步

sudo ./scripts/install_deps.sh
3

创建并激活 conda 环境

第 3 步

conda env create -f environment.yml
conda activate reachy
4

安装 Python 包 + SDK 降级补丁

第 4 步

pip install -e ".[dev]"
./scripts/patch_sdk_p7b.sh
为什么需要 patch_sdk_p7b.sh

Ubuntu 22.04 必需：官方仓库没有 gst-plugins-rs，webrtcsink 缺失时 SDK 原版直接抛错导致整个应用起不来；补丁降级为"仅本地 IPC"。脚本幂等，重建 conda 环境 / 升级 reachy-mini 后重跑一次即可。

5

（可选，推荐）防止机器人 USB 频繁掉线：禁用 autosuspend

第 5 步 · 可选

sudo cp scripts/udev/50-reachy-mini-usb.rules /etc/udev/rules.d/
sudo udevadm control --reload && sudo udevadm trigger
6

配置 API Key

第 6 步 · 语音对话必需

见下方 配置 API Key 章节。

7

（可选）下载手部跟随模型（~8 MB）

第 7 步 · 可选

不装则「手部跟随」不可用：

mkdir -p ~/.cache/reachymini
curl -L -o ~/.cache/reachymini/hand_landmarker.task \
  https://storage.googleapis.com/mediapipe-models/hand_landmarker/hand_landmarker/float16/latest/hand_landmarker.task
# 国内访问不通时换 GitHub 镜像:
# curl -L -o ~/.cache/reachymini/hand_landmarker.task \
#   "https://gh-proxy.com/https://raw.githubusercontent.com/google-ai-edge/mediapipe-samples/main/examples/hand_landmarker/ios/HandLandmarker/hand_landmarker.task"
8

启动（三种形态一条命令隔离，各自独立日志）

第 8 步

./scripts/start.sh --sim        # 纯仿真（默认，跑在 PC）
./scripts/start.sh --wired      # 有线真机：PC + USB 接入的机器人（启动即自动连）
./scripts/start.sh --robot      # 无线版唯一形态：跑在机器人树莓派本体（SSH 上去执行）
# 日志：logs/start-<模式>-<时间戳>.log

启动后浏览器打开 http://localhost:7860。切换调试模式：Ctrl+C 停掉换命令重启（sim daemon 健康实例自动复用）。

🐧 Ubuntu 自检

装完可先跑 python -m pytest tests/ 自检（期望 290 全过，skip 为无硬件相关）；更多细节见仓库 docs/INSTALL.md Linux 章节。

火山引擎（豆包）API 申请​

LLM 模型 API 接入​

  1. 进入火山引擎方舟管理控制台官网

  2. 在 API Key 管理中进行模型 API 申请

进行 API Key 申请设置 API 名称并创建
API Key 申请确认创建
  1. 进入体验中心，选择合适的模型
体验中心选择模型
  1. 选择自己所需要的文本生成模型
选择文本生成模型
  1. 选择之前创建好的 API Key，完成模型 API 接入
选择 API Key 完成接入
  1. 创建完成，可以根据开发需求查看 API 调用的小 demo 代码
查看 API 调用 demo

如果需要关闭 LLM 模型服务，可以在开通管理中进行模型服务管理

模型服务管理

语音识别模型 API 申请​

  1. 进入豆包语言界面

  2. 选择语音识别模型并进行 API 调用

选择语音识别模型
  1. 创建新的 API Key 并选择，完成模型 API 接入
创建语音识别 API Key
warning

注意这里的 API Key 和之前的 LLM 模型使用的 API Key 不同，需要创建新的 API Key。

如果需要关闭 Voice 模型服务，可以在开通管理中进行模型服务管理

语音模型服务管理

配置 API Key（三种方式共用）​

把 API Key 写到 ~/.reachymini/env.json（用户级配置，不入 git）：

mkdir -p ~/.reachymini
cat > ~/.reachymini/env.json <<'EOF'
{
  "doubao_llm": {
    "api_key": "your-ark-api-key",
    "model": "doubao-seed-character-251128"
  },
  "doubao_asr": {
    "api_key": "your-asr-api-key"
  },
  "edge_tts": {
    "voice": "zh-CN-XiaoxiaoNeural"
  }
}
EOF
chmod 600 ~/.reachymini/env.json

也可以在 UI 里展开「⚙️ 设置（API Key / Model）」在线编辑保存（UI 保存后新对话立即生效；直接改文件需重启进程）。

申请地址：

全部配置项见仓库 docs/CONFIG.md。

启动与使用​

启动​

按上文方式 A / B / C 选择对应命令启动后，浏览器打开 http://localhost:7860 即可使用 Gradio Web UI。

局域网访问（三种方式共用）​

UI 监听 0.0.0.0，同一 WiFi 下的手机/平板/其他电脑直接用 http://<本机局域网IP>:7860 打开即可（启动时控制台会打印，如 http://192.168.x.x:7860；无线版用 http://reachy-mini.local:7860）；视频流、3D 视图、语音播报会自动跟随访问用的 IP，无需任何配置。

⚠️ 安全提示

局域网链接意味着同网络的任何人都能控制机器人，请只在可信 WiFi 下使用，不要在公共网络开放。

📱 手机浏览器提示

输入链接时请带 http:// 前缀（部分浏览器默认升级 https 会报"连接不安全"）。

系统架构（简版）​

┌──────────────────────────────────────┐
│  Web UI (Gradio @ localhost:7860)    │
│  ┌─────────────┐ ┌─────────────────┐ │
│  │ 3D 视图+视频 │ │  对话 / 配置面板 │ │
│  └─────────────┘ └─────────────────┘ │
└──────────────────────────────────────┘
                 ↕
┌──────────────────────────────────────┐
│  App 进程                             │
│  MirrorOrchestrator │ VoicePipeline   │
│  ├ sim + real 镜像   │ ASR→LLM→TTS    │
│  SoundLocalizer │ HandFollower        │
│  IdleBreath（待机微动）               │
└──────────────────────────────────────┘
                 ↕
┌──────────────────────────────────────┐
│  reachy_mini SDK (1.10.0)             │
└──────────────────────────────────────┘
                 ↕
┌──────────────────────────────────────┐
│  硬件 / 仿真                          │
│  reachy-mini-daemon --sim / 真机      │
└──────────────────────────────────────┘

详细架构见仓库 docs/ARCHITECTURE.md。

故障排查​

遇到问题先查仓库 docs/TROUBLESHOOTING.md。

常见问题：

  • 找不到 conda：安装 Miniconda
  • 端口被占（7860/7861/8000/8001）：lsof -i :7860 找占用进程杀掉再启动
  • 浏览器听不到声音：页面上先点任意处（浏览器自动播放策略），或检查 🔊 音量滑条
  • 录音没声音：确认系统默认输入源是活麦克风（pactl info | grep 默认源），部分机器默认是哑设备
  • 真机连不上：确认已通电、USB 线插紧（有线版）；日志看 /tmp/reachy-daemon.log
  • Ubuntu 应用起不来报 WebRTC 连接拒绝：漏跑 ./scripts/patch_sdk_p7b.sh
  • 机器人 USB 频繁掉线/真机画面卡死：装 scripts/udev/50-reachy-mini-usb.rules（方式 A 第 5 步）

参考文档​

许可证：Apache 2.0（与 reachy_mini 一致）。

技术支持与产品讨论​

感谢您选择我们的产品！我们为您提供不同的支持，以确保您与我们的产品体验尽可能顺畅。我们提供多种沟通渠道以满足不同的偏好和需求。

Loading Comments...