DreamSoul研究
源码与架构 /

Reachy Mini 平台 源码研究

固定源码 · 研究快照 2026-10-27Markdown 下载 ↓
本页为正式研究文档的网页阅读版。固定 GitHub 证据保留;本机研究底稿未发布,相关链接已改为文字说明。原文中的历史发布状态对应研究当时。

研究判断

Reachy Mini 适合作为较新的动作与语音交互平台参考。最值得抽取的是 Python 姿态与轨迹接口、动作播放器、说话与倾听时的动作协调、媒体与硬件服务分离,以及同一控制协议对应真机和仿真的结构。它还不是可直接交付的陪伴产品,用户关系、长期服务、内容安全、运行成本和整机可靠性仍需要产品化。源码中的对话、记忆和人格功能也不能直接作为这些能力已通过验收的依据。

纯数学与动作协议层可以优先复用。直接打包整个 SDK、底层控制依赖、机器人网格与现成应用,则需要分别处理许可和依赖边界。主仓库与对话应用有 Apache-2.0 正文,但本次检查的两个底层 Rust 依赖与独立舞蹈代码库没有找到明确许可,硬件 README 仍写有 NC,不能扩展为整套平台可商业复制。

证据深度:固定版本源码阅读,下载 265 个文本文件共 2,542,880 字节并记录 SHA-256,执行 9 组原始运动函数断言。未安装依赖,未启动 daemon、MuJoCo 或官方对话应用,未连接硬件、相机、麦克风或云服务。访问日期为 2026年10月27日。

版本与新旧定位

对象 固定版本与真实时间 判断与依据
主 SDK、daemon、仿真 main d3240b92f4bfbb5accffbf8b40fb5ca1e5b92acb,提交 2026-10-26 13:19:09 UTC,代码版本 1.14.0.dev0 仓库创建于 2025-05-13 16:22:27 UTC。当前是开发分支,不等于正式发行版。仓库元数据、提交、版本定义
SDK 近期正式版 v1.13.0,2026-10-26 10:41:15 UTC。此前 v1.12.0 为 2026-10-02,v1.11.0 为 2026-09-11 近期持续发布是软件维护证据,不代表这些日期推出了新一代硬件。v1.13.0、v1.12.0
官方对话应用 main b731ea1fd6ce53232f1b13609331271358e10bd9,提交 2026-10-26 10:32:23 UTC 仓库创建 2025-09-01 12:10:14 UTC。近期正式版 v1.1.1 发布于 2026-10-16 08:07:57 UTC。下文描述固定 main 的实际行为,不能假定 v1.1.1 全部具备。提交、发行版
Rust 运动学依赖 c76e0d6c7f27119ad9d2501185fd915cc40217da,2026-04-07 15:48:25 UTC,Cargo 版本 1.0.3 是 SDK 的依赖证据,不作为新增重点。版本
Rust 电机控制依赖 dff1c536a75735a950564e18240d6a67b056819c,2026-06-12 09:14:56 UTC,Cargo 版本 1.5.6 SDK 声明下界为 1.5.5,并非固定本文检查的 1.5.6。部署需使用锁定依赖重新验证。版本、SDK 依赖
独立舞蹈 Python 库 919a7f26c7bdce1655719fe21ce942ca1bda8d97,2025-12-17 16:09:51 UTC,0.2.1 较早的关联资产,作为动作组织参照。它与 Hugging Face 同名舞蹈数据集是不同资源。版本

Wireless 使用板载 Raspberry Pi CM4,Lite 由 USB 连接的电脑承担处理。二者的主机形态不同,不能把 SDK 更新、仓库创建日期和硬件代际混在一起。制造源文件、商业硬件授权与声学性能也不会因软件持续更新而自动补齐。硬件说明、官方 FAQ

真实执行链路

Python 应用
  ReachyMini.set_target / goto_target
    → WSClient + typed command/task
    → daemon / WSServer
    → Backend:动作求值、追踪与说话偏移合成、IK
       ├─ RobotBackend → Rust motor controller → 串口舵机
       ├─ MujocoBackend → MJCF 场景、动力学与虚拟相机
       └─ MockupSimBackend → 目标即当前状态,无物理

媒体通道
  daemon GstMediaServer
    ├─ 同机:摄像头 IPC + GStreamer 本地音频
    └─ 远端:WebRTC 摄像头与音频
  应用 MediaManager → 取帧 / 录音 / 播放

主 SDK 构造与媒体配置位于 ReachyMini,命令调用位于 set_target / goto_target,服务状态与媒体所有权位于 Daemon。FastAPI 提供管理与查询接口,Python 控制走 WebSocket,浏览器应用还可通过 WebRTC DataChannel 调用,不应把 REST 轮询当成唯一实时控制机制。

可直接阅读和抽取的 Python 资产

资产与符号 实际契约 复用方式与改造点
utils.create_head_pose 输出 4×4 齐次姿态,mm=True 将位移转米,degrees=True 将欧拉角按度解释 最小可抽取函数之一。与自己的坐标系约定一起保留,不能只复制参数名。源码
time_trajectory、minimum_jerk、linear_pose_interpolation linear、minjerk、ease_in_out、cartoon 时间曲线。位移线性插值,旋转通过相对旋转向量插值,可将 yaw 作为带符号标量处理 适合头部、触角、身体的表达性运动。cartoon 有意超调,需要与机械约束分开。时间与姿态插值
Move、GotoMove.evaluate(t) duration 与 evaluate(t) → (head, antennas, body_yaw),各目标可为 None,Goto 的 None 保持起始状态 可以把“点头”“倾听”“呼吸”等动作统一为小型接口。内部 Goto 本身不验证 duration 正数,外部 SDK 有验证,抽取时应保留边界检查。接口、实现
RecordedMove、RecordedMoves JSON 的 time 与 set_target_data 存轨迹,head 支持 4×4 或展平 16 元素。按时间二分查区间,分别插值关节与姿态,声音为旁侧资源 适合建立自有动作格式与播放器。保留时间、坐标、音频关联和输入校验。默认先用 HF 缓存,缺缓存时会联网下载。求值、加载
Backend.play_move 默认 100 Hz 求值,动作互斥,轮询取消标记,支持音频领先/滞后,取消时停止伴随声音 可参考动作取消与音频同步逻辑。100 Hz 是软件调度设定,不等于实测电机更新率或音画同步保证。源码
对话应用 MovementManager 通过命令队列协调动作,空闲时呼吸,倾听时冻结触角,结束后渐变恢复,统一发 set_target 比单纯随机摇头更有复用价值。保留单线程动作状态所有权,再适配自有电机自由度和状态机。状态设计、监听冻结
MediaManager get_frame、start_recording、get_audio_sample、start_playing、push_audio_sample、close 可直接学习接口分层。底层依赖 GStreamer、设备格式与 WebRTC,迁移到 MCU 或自己的音频硬件需要实现适配器。接口
ReachyMiniApp.run(reachy_mini, stop_event) App 生命周期与设备 SDK 注入 适合开发者插件应用,产品端应另设权限、资源和更新策略。入口

一个最小控制片段如下,属于接口示例,本轮未运行 SDK 连接及真机运动:

from reachy_mini import ReachyMini
from reachy_mini.utils import create_head_pose

with ReachyMini(media_backend="no_media") as robot:
    robot.goto_target(
        head=create_head_pose(z=10, roll=10, mm=True, degrees=True),
        antennas=[0.2, -0.2],
        body_yaw=None,
        duration=1.0,
    )

body_yaw=None 表示保持当前 yaw。默认 0.0 有不同含义,移植时不应省略后再假定身体保持原位。示例需要已经就绪的 daemon 和合适的电机状态,no_media 只关闭媒体初始化,并不等于无连接或纯仿真。goto_target

运动安全的真实边界

路径 源码证据 实现与限制
Python SDK 输入 set_target、goto_target 检查空目标、head 形状、触角数量、body_yaw 类型,goto 检查 duration > 0。不能将这些检查概括成所有数值和所有传输入口均有机械安全约束
默认解析 IK AnalyticalKinematics.ik 自动 body yaw 开启时,传 max_relative_yaw=65°、max_body_yaw=160° 给 Rust safe IK。关闭自动 body yaw 时改走直接 IK
Rust safe IK inverse_kinematics_safe 先根据头身相对 yaw 调整身体,再夹限 body yaw。它不是通用的全姿态碰撞安全证明
碰撞选项 解析 IK 参数说明、daemon 默认、Placo 约束 默认 check_collision=False。解析 IK 不使用该参数,Placo 另有碰撞约束。不能认为启动任意后端并加同名开关就获得同等检查
不可达目标 Backend IK、RobotBackend 更新 发现 None/NaN 求解结果抛 ValueError,机器人循环捕获并记录 IK 错误。未实测极端姿态、近奇异位姿及关节碰撞
上电避免跳动 enable_motors 先把目标固定到当前关节与姿态,再启用 torque。迁移时应保留该顺序
失联与诊断 控制循环 Python 机器人循环设 50 Hz,记录平均频率、最大间隔和错误。读电机连续 1 秒无响应会抛错停止,硬件错误按周期读取。这些不是功能安全认证

官方 FAQ 仍描述 body yaw ±180°、head pitch/roll ±40° 等限制,但固定默认解析 IK 明确使用 body 160°。本文以实际代码调用值描述实现,不把 FAQ 当作全部后端自动统一夹限的证明。FAQ

应用互斥也有边界:RobotAppLock 协调受管理的本地 App 与远程 WebRTC 会话,源码明确写直接连 daemon 的 SDK 客户端绕过该锁。产品若允许多个控制来源,应补充命令所有权、过期丢弃与取消策略。锁的适用范围

媒体、应用与仿真

媒体分离

当前实现以 daemon 的 GstMediaServer 为媒体基础设施,同机客户端通过 IPC 取得摄像头图像并用 GStreamer 打开本地音频,远端使用 WebRTC 同时承载音视频。SDK 的自动选择规则首先处理 no_media,其次判断同机 IPC 可用性,再选择远程 WebRTC。旧的 sounddevice/OpenCV 后端枚举映射为 LOCAL,并发出弃用警告,不宜按旧示例理解当前架构。MediaManager 说明与别名、SDK 选择逻辑

这个分层适合把行为代码从采集设备细节中移出,但 GStreamer、USB 音频控制、硬件 AEC、相机参数仍是实际部署依赖。将模型服务放到远端也不会消除传输延迟和播放缓冲。本轮只读相关路径,未验证设备格式、帧率、回声抑制或 Windows 媒体设备兼容。

应用发现、安装、启动

阶段 真实实现 复用判断
发现 官方应用白名单与 HF Spaces API 拉取,社区列表按 tag 过滤,读取 card metadata 与分页 可参考目录协议,商业产品的可安装名单、版本固定与审核不能直接由“发现了 Space”替代。hf_space
安装 Python App snapshot_download(repo_type="space") 下载,再调用 uv/pip 安装 Python 包 本轮未执行安装。安装逻辑没有把下载 revision 固定为本文 commit,后续下载内容可变化。下载路径
环境 桌面应用模式与 Wireless 使用与 daemon 分开的共享 apps_venv,多个 App 共用此环境 是依赖环境分离,不是逐 App 容器或权限沙箱。一个 App 更新可能影响其他 App 的共享依赖。共享环境、安装
运行 从 reachy_mini_apps entry point 找模块,以子进程启动,管理 stdout/stderr、状态、停止与机器人占用 生命周期与异常恢复可复用,仍需自有权限和发布机制。模块发现、start_app
Web App README 当前推荐 JS/WebRTC 应用,静态网页连接机器人 是与 Python App 并存的新入口,不能与“将 Python 包安装到机器人”混写。README

三种无硬件验证层次

模式 覆盖范围 明确不覆盖
本轮函数级验证 实际执行姿态生成、旋转、时间曲线、Goto 输出与非法时间检查 没有 SDK 连接、服务协议、运动学求解、物理、媒体和模型
--mockup-sim 保留 daemon、FK/IK 与状态发布,50 Hz 循环把目标直接设成当前状态 无物理、无负载/摩擦/电流/碰撞响应,单电机 torque 操作为 no-op。不是全部依赖都可省略。MockupSimBackend、循环
--sim / MuJoCo MJCF 场景、关节状态、物理步进、相机渲染。代码设仿真 timestep 0.002 s,控制 decimation 10,渲染/流发送 0.04 s 设定的 500/50/25 Hz 不是本轮性能实测。不覆盖真实串口、舵机误差、结构噪声、电池、真实硬件 AEC。初始化、步进与渲染

固定实现中,MuJoCo 的虚拟摄像头 rendering thread 在 not self.headless 分支启动,不能假定 headless 模式仍提供相同虚拟视频。仿真说明还明确使用电脑系统麦克风/扬声器与软件 AEC,不能用它证明机器人 XMOS 声学链路效果。渲染启动条件、仿真说明

官方对话应用的实际云链路

截至固定提交,配置只支持 Hugging Face backend,旧的 BACKEND_PROVIDER、MODEL_NAME 被警告并忽略。它仍导入 OpenAI Python SDK,但这是调用兼容实时协议的客户端,不足以证明请求发送到 OpenAI 云。后端选择、客户端构造

机器人或电脑麦克风
  → MediaManager.get_audio_sample
  → 独立 reader thread / async queue
  → HuggingFaceRealtimeHandler.receive
  → deployed:HF Space /session 申请 connect_url
       或 local:指定 HF_REALTIME_WS_URL
  → OpenAI-compatible realtime WebSocket
  ← transcript / audio / tool-call events
  → 20 ms 音频分块 + playback epoch 检查 → push_audio_sample
  → 动作工具 → MovementManager → set_target

默认 deployed 的会话代理地址写在 config。申请会话时可以携带明确配置的 HF token 或本机缓存登录 token,并尝试从 daemon 取得 hardware_id。local 模式只使用显式配置的 token,不走这个分配流程。源码通过服务返回的 connect_url 建立连接,实际部署的模型与服务实现可由代理改变,本文没有调用服务验证其当前模型、资费或可用性。会话分配

语音输入、播放、工具与动作并不是一个阻塞大循环。录音线程把 SDK 帧交给异步队列,播放循环将音频按每秒 50 块调度,并用 playback_epoch 丢弃已被打断的旧响应。该逻辑值得借鉴,但仍依赖设备缓冲和 SDK 传输时延。录放音循环

能力 实际可复用处 边界
倾听反应与打断 本地 Silero VAD 处理 16 kHz、每块 512 样本。至少 160 ms 语音判定,400 ms 静音释放,并有上下文清理 本地 VAD 让肢体尽快反应,不能把它等同本地 ASR/LLM/TTS。模型未在本轮下载或运行。local_vad
说话时避让用户 本地候选语音先降低播放增益,服务端确认后中断,epoch 过滤旧音频 官方 README 将这一路径标为 experimental,回声、电机噪声与 CPU 仍需真机测试。应用说明、打断代码
视觉工具 camera 工具取图片,工具结果中的图像通过实时会话提交 默认云链路可能外发图像,不能把有摄像头工具写成离线视觉。需要产品端明确触发、权限与数据政策。图像工具结果处理
人格与记忆 本地配置、profile、remember/forget 和会话 instructions 可作为应用样例,长期记忆质量、删除验证和用户隔离未验证。配置入口、memory.py
自建后端 README 指向 huggingface/speech-to-speech,可以指定本机或局域网 WebSocket 这是后端替换接口,不是把一项设置改成 local 就自动具备离线推理。需另行选择、授权、部署 ASR/LLM/TTS/VLM 与权重。本地配置

源码注释提到 Qwen3-ASR / Qwen3-TTS,兼容会话配置又保留 gpt-4o-transcribe 字段。这些客户端字符串不能证明实时服务正在使用哪个确定模型版本。可确认的是 HF 兼容协议与动态会话分配机制,模型权重许可和服务条款必须随实际部署再次固定。语言与声线目录、兼容会话配置

分层许可与商业使用边界

以下是公开声明的核对结果,不把仓库首页的单一标签扩展到外部依赖、硬件、权重和内容资产。

层 取得的证据 可用边界与缺口
主仓库 Python / TypeScript 软件 根 Apache-2.0 正文,另有 ts/LICENSE 纯 Python 函数与软件结构可按其许可复用并保留必要声明。整个依赖闭包仍需独立核查
官方对话应用软件 Apache-2.0 正文 不自动授权云服务使用、所有模型权重或下游工具资源
硬件设计与网格 README License 原文为 Creative Commons BY-SA-NC,未写版本。固定完整树中有 159 个 STL 路径,未发现 .step/.stp 商业复制硬件不能依据主软件许可。未取得单独硬件协议全文与确切版本,不擅自写成 CC BY-NC-SA-4.0。仿真内机器人网格、URDF/MJCF 的商业再分发也需要确认硬件设计声明的适用范围
完整制造文件 固定目录树,官方 FAQ 仍说 full STEP planned 未确认完整可编辑制造源交付。当前没有足够证据把 STL 等同可量产制造资料
Rust 运动学 固定树无 LICENSE/COPYING,README、Cargo.toml、pyproject 均未发现明示许可 默认 SDK 依赖。授权待确认,不将其默认为 Apache-2.0
Rust 电机控制 固定树无 LICENSE/COPYING,README、Cargo.toml、pyproject 均未发现明示许可 真机核心依赖。商业复制/再分发前需补授权或替换实现
独立舞蹈代码库 固定树无 LICENSE/COPYING,README、pyproject 无明示许可 对话应用直接依赖。不能用 HF 同名数据集的许可替代代码库许可
官方 emotion 动作与配套音轨数据集 固定 SHA 873ae49f0b89114b7e535eff0c1f7560d21d9357 的 dataset card 声明 Apache-2.0,说明 50 Hz 轨迹配 mono Ogg/Opus 取得的是数据集级声明,没有逐音轨来源链核验。可优先作为有明示许可的动作资产候选,商业内容来源仍按拟用文件核对
官方 dance 动作数据集 固定 SHA 3564295e72d41c1271f46bf5540a3fcad9d5f669 的 dataset card 声明 Apache-2.0,明确只有动作无音轨 与独立 Python 舞蹈代码库分开处理。当前 card 可作为授权声明依据,本轮未下载动作数据
本地 VAD 权重 应用固定 Silero commit 7e30209a3e901f9842f81b225f3e93d8199902b1,模型与 LICENSE 均有 SHA-256。已读该 MIT LICENSE 下载/加载代码有校验,权重未下载、未运行。固定模型路径与校验
SDK 内附 ONNX 运动学模型 主仓库树含 fknetwork、iknetwork 等 4 个 ONNX 文件,默认解析 IK 不用它们 本轮未发现独立模型卡、训练来源或逐模型许可说明,仅根许可。无需为抽取纯运动函数引入这些权重
HF 实时服务与远端模型 动态会话接口可确认,远端权重版本与完整部署许可未取得 不写“默认完全离线”或“永久免费”。自建需要另做模型与服务许可核对

补充核对了三个缺明示许可依赖的当前 PyPI JSON:1.0.3、1.5.6、0.2.1 的 license 和 license_expression 均为空。没有发现可以用发行元数据补全仓库许可的证据。该结论是“本轮未取得授权声明”,不是断言作者拒绝商业授权。运动学发行元数据、电机控制发行元数据、舞蹈库发行元数据

本轮实测与后续最小验证

已完成的真实代码验证

验证脚本通过 importlib 与只含包路径的 namespace stub 跳过 SDK 顶层初始化,加载原始 utils、rotation、interpolation、Move、GotoMove,没有复制或重写被测算法。Python 3.12.14、NumPy 2.3.5、Windows 11,未安装新依赖。

检查 结果
毫米与角度转换 10 mm → 0.01 m,yaw 90° 将 x 单位向量转向 y,断言通过
4 种时间曲线起点与终点 均为 0 与 1,断言通过
非法归一化时间 -0.01 与 1.01 均抛 ValueError
minjerk 101 点采样 单调不减
yaw 从 +170° 到 -170° 标量 yaw 中点为 0°,默认最短旋转中点绝对值为 180°,符合两种路径语义
Goto 终点 头姿态、触角和身体 yaw 三类输出均到目标
Goto 的 None 目标 三类输出均保持初值
minimum_jerk 超过 duration 保持目标位置
cartoon 1001 点采样 范围约 [-0.1001505925, 1.1001505925],证实有约 10% 超调

这些结果说明可抽取的数值层能够在当前 Python 环境独立执行,不说明整机、控制时序、姿态可达性、音频同步或对话体验已跑通。低层 GotoMove 的 duration 等约束依赖调用者,应用移植时应由外部入口拒绝非法输入。

验证文件:

建议的下一步验证,不视为已完成

最小步骤 可测指标 通过后能支持的判断
固定 SDK 与完整依赖,在隔离环境启动 --mockup-sim --no-media,执行 goto、状态读取、取消与重连 任务完成率、取消到不再更新目标的时间、状态延迟、错误是否可恢复 SDK 到 daemon 的无物理集成可用
在已取得所需许可的环境运行 MuJoCo 最小场景,扫描有限姿态集合 IK 失败率、头身 yaw 约束、轨迹误差、循环最大间隔、headless 视频差异 应用控制与该仿真模型的一致性
替换实际云服务为本地协议测试服务,回放人工构造音频/工具事件 旧 epoch 音频丢弃率、取消后残留播放块数、队列积压、动作冲突数 事件与取消编排正确,不涉及模型质量
上真机后测试说话、用户打断、动作和听觉并发 首音延迟 P50/P95、打断延迟、说话动作偏移、回声误触发率、电机噪声影响、温升与长时错误数 可用于产品体验与稳定性的实测证据

优先投入应是“纯运动函数 + 自有动作协议 + 语音/动作取消协调”的小范围验证。整体 SDK、底层驱动、HF 应用市场和硬件资产可作为研究参照,在授权、版本和真机指标补齐后再决定集成范围。