项目>Reachy Mini>三条开发路径:Python SDK、JS WebRTC 与 REST 怎么选

三条开发路径:Python SDK、JS WebRTC 与 REST 怎么选

摘要:按自己的目的在 Python 脚本、浏览器 Web 应用和 HTTP 接口之间选一条能跑起来的路径,并知道媒体后端与 GStreamer 的前置条件。

先按目的挑一条路

同一台机器人可以有三种完全不同的驱动方式:写 Python 脚本直连、做浏览器里的 Web 应用、或者用任意语言发 HTTP 请求。三者共用同一个 daemon,区别在客户端跑在哪、要不要拿音视频、以及各自的前置条件,按手头要做的事选一条能跑起来的就行。官方对新应用给出的推荐是走 web、JS 静态页经 WebRTC 驱动这一条。

路径 形态 前置条件 适合做什么
Python SDK 脚本直连 daemon,装 reachy-mini 包后用 with ReachyMini() as mini 本机装好包;要接管媒体时设 media_backend 重计算、离线 LAN、常驻无人值守、Home Assistant
JS WebRTC 浏览器静态页经 WebRTC 驱动,官方推荐的新应用路径 npm 包 @pollen-robotics/reachy-mini-sdk 并 pin 到最新稳定版;客户端装 GStreamer 新写的 Web、JS 交互应用
REST 加 HTTP 任意语言 HTTP 客户端直接打 daemon 的 8000 端口 能访问 daemon 的 8000 端口,先确认 8000/docs 打得开 接 AI 应用、生成任意语言客户端、甚至做自己的 MCP server

Python SDK 路径:把媒体后端选对

脚本路径最常用的前置是 media_backend,它决定摄像头和音频归谁管,四个取值行为不同:

取值 行为 什么时候用
default 自动在 LOCAL 与 WEBRTC 之间选 不确定时先用它
local 走本地媒体后端 脚本和机器在同一台电脑上
webrtc H.264 视频加 Opus 音频,经 WebRTC 传输 远端或浏览器客户端要拿音视频
no_media 把摄像头和音频释放给 OpenCV、sounddevice 等外部库,退出上下文自动收回 自己接管媒体管线

选 webrtc 时客户端要装 GStreamer:macOS 和 Windows 随 wheel 自带,Linux 需要手动安装,装不齐最典型的症状是视频流起不来。选 no_media 时 SDK 不碰摄像头和麦克风,可以把它们交给 OpenCV、sounddevice 这类库自己读,退出 with 上下文后资源会自动收回,不用手动还。

动作控制上,goto_target 平滑插值到目标,set_target 立即刷新目标适合实时跟踪,还有 start_head_tracking(weight=...) 做头部跟随、mini.media.get_DoA() 取声源方向。要接 AI 的话,官方 Conversation Demo 是 VAD 加 LLM 加 TTS 的组合;想换成自己的视觉或音频管线,就把 media_backend 设成 no_media,由外部库接管采集。核心概念官方页里只提到 Placo 这一种可选运动学引擎,需要额外装 reachy-mini[placo_kinematics] 并在启动时用 --kinematics-engine Placo 指定;至于把运动学引擎归纳成好几套的说法,冻结的官方页面里没有列全,这里不据此下结论。

JS WebRTC 路径:状态机与建连过程

做浏览器应用,先装 npm 包 @pollen-robotics/reachy-mini-sdk,官方要求 pin 到 npm 的最新稳定版,别用浮动版本。客户端状态机是 disconnected → connected → streaming 三段,autoConnect() 一键把 auth、connect、选机、建立 session、唤醒这几步串完;卡在中间某一状态时,对着这三段看停在哪一段,比整段重跑好定位。

WebRTC 的建连过程是分两段的:

阶段 路径 做什么
信令 浏览器到 HF Space 的 SSE、HTTP 在 HF Space 上校验 HF OAuth token,商量怎么建连
建连后 浏览器到机器人的点对点 视频、音频、指令直接点对点传,信令服务器不再在路径上

REST 路径:端点与调试入口

REST 由 FastAPI 加 pydantic 实现,官方明确说可以用它生成任意语言客户端、接 AI 应用,甚至做自己的 MCP server。常用端点挂在这些前缀下:

  • /api/apps
  • /api/daemon
  • /api/state
  • /api/move
  • /api/motors
  • /api/kinematics
  • /api/volume
  • /api/hf-auth

调试时先在浏览器打开 http://localhost:8000/docs 看 Swagger UI,能列出所有接口并直接试请求;要机器可读的描述取 http://localhost:8000/openapi.json 这份原始 OpenAPI。全量状态用 GET /api/state/full,需要持续推送就订阅 WebSocket 的 /api/state/ws/full 路径,例如 ws://localhost/api/state/ws/full。在 Reachy Mini Wireless 上把 localhost 换成 reachy-mini.local。如果 8000/docs 打不开,说明 daemon 没起来或端口没通,先回到起服务那一步,别在客户端里反复改代码。

国内网络与 HF 服务

访问 Hugging Face 服务受限时,官方 FAQ 给的做法是用镜像 https://hf-mirror.com/,并在环境里设 export HF_ENDPOINT=https://hf-mirror.com/。官方同时提示 PyPI 与 GitHub 可能也需要各自配置镜像。这些是 FAQ 里有据的条目,照着配即可;超出这几条的联网方案官方没有给出,这里不自行扩展。

资料来源

  • Python SDK 官方页
  • JavaScript SDK 官方页
  • REST 接口官方页
  • 集成官方页
  • AI 代理开发指南

相关内容

Reachy Mini 深拆:399 美元的开源桌面机器人实践