Reachy Mini 开源桌面机器人：10 分钟跑通你的第一个 AI 应用-迪斯科星球

Reachy Mini 开源桌面机器人：10 分钟跑通你的第一个 AI 应用

【免费下载链接】reachy_miniReachy Mini's SDK项目地址: https://gitcode.com/GitHub_Trending/re/reachy_mini

想要一个会歪头看你、能听声音、还能接上大模型的桌面机器人，最先卡住人的往往不是算法，而是底盘那 9 个电机怎么控制、头部怎么防止自碰撞、相机和麦克风流怎么管。Reachy Mini 的 SDK（reachy_mini）把这些硬件细节压进一个后台常驻的 daemon 进程，应用端只写业务逻辑。这篇文章按"装环境 → 跑通最小 demo → 看懂指令背后的数据流 → 做相机和大模型应用"的顺序带你走完一遍。

🤖 为什么值得先试这个

它和"买一块开发板自己写驱动"的路线不同，价值集中在四件事：

形态	硬件	适合场景
Wireless	Raspberry Pi CM4 + 电池 + WiFi，自带 IMU	完全离线的自主运行
Lite	USB 连接你的电脑，市电供电	开发调试
Simulation	无硬件，MuJoCo 仿真	没有机器人也能写代码

一套 API 三种形态：仿真、Lite、Wireless 共用同一个ReachyMini客户端，代码不用改，换的只是 daemon 的启动方式。
客户端-服务端分离：AI 推理可以跑在任何有算力的电脑上，电机、传感器和安全检查留在 daemon 里，这是它敢把 API 做得这么薄的底气。
安全限制内置：头部俯仰/侧倾被钳在 ±40°、偏航 ±180° 等范围内，SDK 会自动把越界的目标位姿夹回合法区间，详见 docs/source/SDK/core-concept.md。
应用生态：社区应用基于 Hugging Face Spaces 分发，机器人端可以一键安装，也可以自己用 JS 写一个浏览器应用通过 WebRTC 控制它。

🚀 最快跑通路径：安装 + 8 行 demo

安装（Linux / macOS / Windows 均可，需要 Python 3.11+ 和 git-lfs）：

装好uv后执行uv python install 3.12 --default
执行uv pip install reachy-mini[all]（[all]会带上仿真、Placo 运动学等可选依赖）
没有机器人？直接跑仿真 daemon：reachy-mini-daemon --sim；有 Lite 就执行reachy-mini-daemon，Wireless 则通电即自带 daemon

验证：浏览器打开本机localhost:8000/docs（Wireless 是reachy-mini.local:8000/docs），看到 API 文档就说明 daemon 活着。

最小 demo，另开一个终端保存为first_run.py并运行python first_run.py：

from reachy_mini import ReachyMini with ReachyMini() as bot: bot.wake_up() # 离开睡眠姿态，电机上电 bot.goto_target(antennas=[0.4, -0.4], duration=0.6) # 天线张开打招呼 bot.goto_target(antennas=[0.0, 0.0], duration=0.6) bot.goto_sleep() # 回到收纳姿态

ReachyMini()的构造参数不用记：它会自动探测本机 daemon 还是走网络 mDNS 发现（见 src/reachy_mini/utils/discovery.py），连 Lite 还是 Wireless 也不用手动指定。

🔍 一条指令背后发生了什么

以bot.goto_target(...)为例，数据是这样流的：

SDK 编码：reachy_mini.py把目标位姿打包成SetTargetCmd等命令类型（定义在 src/reachy_mini/io/protocol.py）；
WebSocket 下发：命令经WSClient发给 daemon，REST API 同样挂在 8000 端口，非 Python 栈也能调；
运动学解算：daemon 里的后端（robot / mujoco / mockup_sim 三选一，见 src/reachy_mini/daemon/backend/）做逆运动学，把"头要摆到什么姿态"翻译成 6 条斯图尔特支杆 + 颈部关节的电机角度。运动学引擎有三种，都在 src/reachy_mini/kinematics/ 下：

引擎	实现	特点
Analytical	Rust 绑定的解析法（`analytical_kinematics.py`）	默认引擎，计算最快
NN	ONNX 网络推理（`nn_kinematics.py`）	有 INT8 量化模型，嵌入式开销低
Placo	物理引擎（`placo_kinematics.py`）	支持重力补偿和碰撞检查，`pip install reachy-mini[placo_kinematics]`启用

轨迹插值：目标点之间按 src/reachy_mini/utils/interpolation.py 生成平滑轨迹，goto_target支持minjerk（默认，最小加加速度，动得最自然）、linear、ease_in_out、cartoon四种；
状态回流：daemon 持续把关节、IMU 等状态广播回 WebSocket，SDK 端的imu、get_state()读到的就是这份数据。

另外注意两套坐标系：goto_target用头部基座标系（head frame），look_at_world用相对机器人底座的固定世界坐标系（world frame），混用是最常见的"机器人看向奇怪方向"的原因。

🧩 进阶：相机、麦克风和大模型接在一起

媒体能力统一挂在bot.media上，不需要你碰 GStreamer：

media.get_frame()：取一帧相机画面，返回(H, W, 3)的 uint8 numpy 数组；
media.start_recording()+get_audio_sample()：拿 16kHz 双声道麦克风数据，get_DoA()能算出声源方向；
media.push_audio_sample()：播放音频（非阻塞，播放时长要自己按采样数算）；
look_at_image(x, y)：让头转向画面里的某一点，配合 OpenCV 就能做"点到哪看到哪"的交互（完整写法见 examples/look_at_image.py）。

人脸跟随是几行代码就能上线的功能，weight控制追踪和应用动作的混合比例（1.0 完全交给追踪，0.0 暂停检测但不停服务）：

with ReachyMini() as bot: frame = bot.media.get_frame() # 供你的视觉/LLM 管线使用 bot.start_head_tracking(weight=0.8) # 追踪与应用动作各占一部分权重 face = bot.get_tracked_face() # 最近的一张脸的归一化坐标

把 LLM 接上则走 App 体系：用官方 CLI 生成标准应用骨架（会自动处理元数据和入口），再发布到 Hugging Face Spaces，机器人端即可一键安装：

reachy-mini-app-assistant create my_app_name ./apps/

两个补充：

不想装 Python 环境的人，官方推荐的路径是 JS 网页应用：静态页面通过 WebRTC 驱动机器人，浏览器打开即用，见 docs/source/SDK/javascript-sdk.md；
用 AI 编码助手开发时，仓库根目录的 AGENTS.md 和 skills/ 是给 agent 读的"开发手册"，包含 SDK 模式和goto_target与set_target的选择原则，直接喂给 agent 即可。

⚠️ 别踩这些坑

安全相关

先wake_up()再动，结束goto_sleep()。睡眠姿态是预设的收纳位姿，直接跳过它会让电机从零位强行拉扯。
越界目标会被自动钳位而不是报错，调试"为什么没转到预期角度"时先检查是否撞了角度上限。
需要重力补偿（手扶着头不跟手）只有 Placo 引擎支持，默认配置没有这个能力，别在仿真里试完换真机发现接口行为不同。

性能与调试

一次性位移用goto_target（带插值）；100Hz 级别的实时控制循环改用set_target（绕过插值直接下发），参考 examples/minimal_demo.py 的正弦摆动写法。
同一时刻只允许一个 App 运行；App 由 daemon 作为子进程拉起，退出时发SIGINT，不要在应用里自建硬件连接。
macOS 上 MuJoCo 与uv偶有兼容问题，仿真相关的包建议直接用pip安装。
push_audio_sample()是异步的，返回不代表播完，需要按采样数 / 采样率自己 sleep。
daemon 终端关掉机器人就"没电"了——脚本和 daemon 是两个进程，新手最常忘记这一点。

继续深入去哪看

环境搭建细节：docs/source/SDK/installation.md
快速上手与常见问题：docs/source/SDK/quickstart.md
架构、坐标系、安全限制：docs/source/SDK/core-concept.md
可运行的示例集（TTS、DoA、手势跟随、Rerun 可视化等 17 个）：examples/
分步教学 Notebook（连接、运动、相机、音频）：docs/notebooks/

下一步可以做的事：git clone https://gitcode.com/GitHub_Trending/re/reachy_mini，起一个reachy-mini-daemon --sim，然后跑examples/minimal_demo.py——不接硬件，也能先把手感和 API 摸熟。

【免费下载链接】reachy_miniReachy Mini's SDK项目地址: https://gitcode.com/GitHub_Trending/re/reachy_mini

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析