Stanford Pupper v3 复刻全流程
Stanford Pupper v3 从采购、打印、组装到装软件、标定和训练的 105 个步骤,附物料表、购买链接与官方出处。
文档称自制约 2000 美元;BOM 表合计约 2,158.91 美元(最低 1,785.91 美元,其中 12 个 GIM4305 关节约 1,320 美元)。Present Perfection 全套件 3,400 美元、整机 3,800 美元(2026‑10‑31,不含税运)
采购
- 按物料清单采购零件
从零构建 Pupper 时,参阅文档链接的物料清单并逐一购买所需零件。
- 购买 Pupper 套件
也可以直接购买文档列出的套件。
- 单独采购两块定制 PCB
若不购买套件而单独采购两块定制 PCB,流程较为复杂。
- 准备 Pupper v3 控制板
准备 Pupper v3 控制板,以及运行 Ubuntu 22.04 和 ROS2 Humble 的 Raspberry Pi 4。推荐的实时系统镜像为 22.04.1_v5.15.39-rt42-raspi_ros2_humble。
组装
- 复制 CSV 动画文件
将 csv 文件复制到 ros2_ws/src/animation_controller_py/launch/animations。
软件与固件
- 安装 Docker 引擎
在构建 Pupper 操作系统镜像前,先安装 Docker Desktop 或其他 Docker 引擎。
- 更新 Docker 版本
确保 Docker 已更新;升级 MacOS 后,旧版 Docker 将无法运行。
- 创建本地环境配置
在 `pupper_image_builder` 目录中根据 `.env.example` 创建 `.env.local`,并加入 Github 个人访问令牌(PAT),以便可靠使用 Git LFS。
- 构建基础 PiOS 镜像
运行基础 PiOS 镜像构建脚本。
- 构建完整 PiOS 镜像
运行完整 PiOS 镜像构建脚本。
- 构建 PiOS AI 镜像
运行 AI 镜像构建脚本。
- 将云端 AI 密钥写入镜像
如需开箱即用地使用聊天 AI 功能,将相关的云端 AI 密钥添加到 `.env.local`。
- 构建包含密钥的完整镜像
使用 `--include-keys` 参数运行完整镜像构建脚本,将 `.env.local` 中的云端 AI 密钥写入镜像。
- 启用自动登录
可选:在 `/etc/gdm3/custom.conf` 中启用 `pi` 用户开机自动登录。
- 禁用 DualSense 控制器音频
编辑 /etc/modprobe.d/blacklist.conf,并添加 blacklist snd_usb_audio,以解决 PiOS 上 Pupper 扬声器无声的问题。
- 提高 Docker Desktop 内存限制
在 Docker Desktop 的设置中打开资源选项并提高 RAM 内存限制;构建 PiOS 上的 ROS 时主要需要此设置。
- 禁用 NetworkManager 在线等待服务
实际 RPi 启动后运行该命令,禁用会增加一分钟启动时间的 NetworkManager-wait-online.service。
- 配置 PiOS 启动命令行
将给出的整行内容写入 cmdline.txt。该设置选择 HDMI-A-1 的 720x720M@60D 模式和 270 度旋转,设置 JP 无线监管域,并在启动时运行 /boot/firstrun.sh,成功后重新启动。
- 创建 PiOS 首次启动脚本
将给出的脚本保存为 /boot/firstrun.sh。它将主机名设为 pupper 并更新 /etc/hosts,启用 SSH,将首个用户设置为 pi 并配置所示密码哈希和 /home/pi,调整自动登录与 sudo 设置,再设置无线 SSID、密码和 JP。
- 配置轮次检测器
将 `version` 设置为 `v1` 可使用完整的 LiveKit Inference 模型,设置为 `v1-mini` 可在本地 CPU 上运行;省略该参数时系统会自动选择。也可以将 `unlikely_threshold` 设置为标量或按语言代码组织的字典,并使用 `local_fallback` 控制从 `v1` 回退到 `v1-mini`,其默认值为 `True`。
- 强制设置检测器语言
在 STT 模型中配置所需语言,使轮次检测器应用对应语言的阈值。例如,使用 `language="es"` 或 `language: 'es'` 配置西班牙语。
- 在 Python 中使用检测器
创建一个带有 inference.TurnDetector() 的 AgentSession,并将实时模型的 turn_detection 设置为 None。不要添加 STT 插件。
- 在 Node.js 中使用检测器
创建一个带有 new inference.TurnDetector() 的 voice.AgentSession。将实时模型的 turnDetection 属性设置为 null。
- 选择合适的智能体计算资源
当自托管智能体运行 v1-mini 时,使用 AWS c6i 或 c7i 等计算优化实例。避免使用 AWS t3 或 t4g 等突发实例,以降低 CPU 额度限制导致推理超时的风险。
- 安装 Python 插件
使用 uv 从 PyPI 安装 turn-detector 插件。
- 安装 Node.js 插件
使用 pnpm 从 npm 安装 LiveKit agents turn-detector 插件。
- 初始化 Python AgentSession
创建 AgentSession,使用 MultilingualModel 进行轮次检测,并使用 LiveKit Inference 进行多语言 STT。
- 初始化 Node.js AgentSession
创建 voice AgentSession,使用 LiveKit MultilingualModel 轮次检测器,并使用 LiveKit Inference 进行多语言 STT。
- 为实时模型提供 STT
使用实时模型和文本轮次检测器时,必须为 `AgentSession` 提供 STT 插件。
- 禁用实时模型内置轮次检测
禁用实时模型内置的轮次检测,避免其与 LiveKit 轮次检测器发生冲突。
- 使用 Python 配置实时会话
使用 `alloy` 语音配置 `AgentSession`,其中包含 `TurnHandlingOptions`、`MultilingualModel`、Silero VAD、Deepgram STT 和 `openai.realtime.RealtimeModel`。将内置轮次检测和输入音频转录设置为 `None`。
- 使用 Node.js 配置实时会话
使用 `alloy` 语音配置 `voice.AgentSession`,其中包含 `livekit.turnDetector.MultilingualModel`、Silero VAD、Deepgram STT 和 `openai.realtime.RealtimeModel`。将内置轮次检测和输入音频转录设置为 `null`。
- 克隆仓库并安装依赖
进入 `agent-starter-python` 目录,并使用 `uv sync` 将依赖安装到虚拟环境中。
- 创建本地环境文件
将 `.env.example` 复制为 `.env.local`,然后填写所需的环境变量值。
- 设置 LiveKit URL
将 `LIVEKIT_URL` 设置为 LiveKit Cloud 地址,或自行托管的 LiveKit 服务地址。
- 设置 LiveKit API 密钥
在 `.env.local` 中填写 `LIVEKIT_API_KEY`。
- 设置 LiveKit API 密钥
在 `.env.local` 中填写 `LIVEKIT_API_SECRET`。
- 配置 OpenAI 密钥
在 `.env.local` 中填写 `OPENAI_API_KEY`,也可以使用偏好的 LLM 提供商。
- 配置 Deepgram 密钥
在 `.env.local` 中填写 `DEEPGRAM_API_KEY`,也可以使用偏好的 STT 提供商。
- 配置 Cartesia 密钥
在 `.env.local` 中填写 `CARTESIA_API_KEY`,也可以使用偏好的 TTS 提供商。
- 自动加载 LiveKit 环境
使用 LiveKit CLI 从 `.env.local` 自动加载 LiveKit 环境。
- 下载首次运行所需模型
首次运行前,下载 Silero VAD 和 LiveKit turn detector 等所需模型。
- 刷写 Raspberry Pi 5 镜像
按照链接中的软件安装说明,使用项目的自定义镜像刷写 Raspberry Pi 5。
- 安装开发依赖
安装 git-lfs,初始化 Git LFS,克隆包含子模块的 monorepo,并运行 install_dev_dependencies.sh。
- 构建 ROS 2 工作区
进入 ros2_ws 目录并执行 build.sh 来构建工作区。
标定与测试
- 设置 VAD 静音时长
为音频轮次检测器启用 VAD,并将 `min_silence_duration` 设置为至少 `0.25` 秒(250 毫秒)。Silero VAD 的默认值 `0.55` 秒已经满足此要求。
- 使用默认英语阈值
未配置 STT 时(例如使用实时模型),轮次检测器会使用英语阈值。检测器支持英语、阿拉伯语、德语、西班牙语、法语、印地语、印尼语、意大利语、日语、韩语、荷兰语、葡萄牙语、土耳其语和中文。
- 设置 Python 全局阈值
创建 Python `TurnDetector` 时,将 `unlikely_threshold` 设置为 `0.5`。较低的值会让检测器更快响应,较高的值会让检测器更耐心。
- 设置 Node.js 全局阈值
创建 Node.js `TurnDetector` 时,将 `unlikelyThreshold` 设置为 `0.5`。较低的值会让检测器更快响应,较高的值会让检测器更耐心。
- 设置 Python 单语言阈值
提供 `unlikely_threshold` 映射以覆盖英语和日语阈值;未映射的语言保留默认值。如果会话从 `v1` 回退到 `v1-mini`,覆盖值会重新缩放,以保持其与当前模型校准默认值之间的关系。
- 设置 Node.js 单语言阈值
提供 `unlikelyThreshold` 映射以覆盖英语和日语阈值;未映射的语言保留默认值。如果会话从 `v1` 回退到 `v1-mini`,覆盖值会重新缩放,以保持其与当前模型校准默认值之间的关系。
- 选择检测器模型版本
不设置 version,让检测器根据环境选择版本。将 version 明确设置为例如 "v1",以在自托管智能体中使用完整模型,或在所有环境中固定同一版本。
- 配置完整模型认证
使用完整模型时,提供 LiveKit Cloud 项目的 LIVEKIT_API_KEY 和 LIVEKIT_API_SECRET。自托管或本地使用完整模型会计入每月开发额度。
- 检查默认轮次检测
省略 turn_detection 时,AgentSession 默认使用 TurnDetector。例外情况是实时 LLM 自带服务器端轮次检测。
- 使用固定端点计时
将端点模式设为 fixed,使配置的 min_delay 和 max_delay 决定延迟。默认模式为 fixed。
- 使用动态端点计时
将端点模式设为 dynamic,根据会话暂停统计数据在 min_delay 和 max_delay 范围内调整延迟;这些统计数据基于话语间和轮次间暂停的指数移动平均。
- 设置最小端点延迟
设置 min_delay,默认值为 0.5 秒,表示检测到最后一次语音后至少等待的时间。使用动态端点时它是下限;在 VAD 模式下相当于 max(VAD silence, min_delay),在 STT 模式下则应用于 STT 端点信号之后,并叠加在 STT 提供方的端点延迟之上。
- 设置最大端点延迟
设置 max_delay,默认值为 3.0 秒,表示终止轮次前最多等待的时间。它可防止代理无限等待用户继续说话。
- 记录默认登录凭据
默认主机名为 `pupper`,用户名为 `pi`,密码为 `rhea123`。
- 减少首次启动等待时间
禁用 `NetworkManager-wait-online.service`,将启动时间从约 90 秒减少到约 30 秒;使用 AI 时不要执行此操作。
- 配对蓝牙手柄
通过蓝牙配对 PS4 或 PS5 手柄。
- 连接无线网络
可选:连接无线网络。
- 自定义摇杆按钮
启动记录节点时,将开始记录按钮设置为 4,将停止记录按钮设置为 5。
- 自定义输出目录
启动记录节点时,将 bag 文件输出目录设置为 /custom/path/bags。
- 配置记录参数
record_start_button 是开始记录的摇杆按钮索引,默认值为 6;record_stop_button 是停止记录的摇杆按钮索引,默认值为 7。bag_output_dir 是保存 bag 文件的目录,默认值为 ~/bags。
- 在本地与智能体对话
在本地与新建的智能体进行对话。
- 使用模拟用户测试
使用模拟用户测试智能体。
- 调整摄像头帧率
摄像头默认帧率为 10hz。可以在 ros2_ws/src/neural_controller/launch/config.yaml 中使用 FrameDurationLimits: [100000, 100000] 参数进行调整。
- 同步动画帧率和淡出时间
如果编辑动画帧率或淡出时间,必须同时编辑 config.yaml 和 pupster.yaml。
- 配置 ros2_control 实时运行
按照链接的 ros2_control Controller Manager 文档,将 ros2_control 配置为实时运行。
- 配置 ros2_control 硬件接口
在 `test_state_publisher.urdf.xacro` 中使用 `control_board_hardware_interface/ControlBoardHardwareInterface` 插件,将 IMU 的 yaw、pitch、roll 安装角均设为 0;示例关节使用 CAN 通道 1、CAN ID 1 和 cheetah 协议。位置、速度、力矩、kp、kd 的缩放值依次为 95.5、30.0、18.0、500.0、5.0,方向为 -1、偏移为 0.0,并设置位置范围 -1.0 至 1.0、速度上限 1.0、力矩上限 1.0、kp 上限 1.0、kd 上限 1.0,以及位置、速度、力矩、kp、kd 命令接口和位置、速度、力矩状态接口;IMU 提供方向、角速度和线性加速度状态接口。
- 测试配置
运行 test_config.py 测试配置。
采数据与训练
- 开始录制动画数据
按住 L1,直到 BAG 状态图标变绿,表示正在录制 mcap bag。
- 移动 Pupper 演示动作
移动 Pupper,使其完成想要的动作。
- 停止录制
按下 R1 停止录制。
- 在 Foxglove 中验证动画
在 Foxglove 中查看录制的 mcap 文件,以验证动画。
- 保存录制数据包
将录制得到的 bag 移到 pupperv3-monorepo/bags。
- 将 mcap 转换为 CSV
在机器人上运行 scripts/mcap_to_csv.py,指定 mcap 路径、绝对开始时间和绝对结束时间,将其转换为 csv。
- 运行基础训练
运行 pupper_mjx_rl_training.py 开始基础训练。
- 减少训练时间步数
通过 training.ppo.num_timesteps=100000000 设置较少的训练时间步数。
- 使用更小的网络
通过 policy.hidden_layer_sizes=[128,64,64,64] 使用更小的网络。
- 启用高度场
通过 training.height_field_random=true 启用高度场。
- 从检查点加载
通过 training.checkpoint_run_number=238 从指定检查点加载。
- 读取智能体会话
读取智能体的会话以查找并修复问题。
用起来
- 在终端中与代理对话
运行该命令,直接在终端中与代理交谈。
- 为前端或电话运行代理
使用 `dev` 命令运行代理,以供前端或电话服务使用。
- 在生产环境中启动代理
在生产环境中,使用 `start` 命令运行代理。
- 过滤原始图像主题
记录器排除包含 image_raw、camera/image_raw、rgb/image_raw 或 depth/image_raw 的主题,以节省存储空间。
物料
- 12 个 Steadywin GIM4305 关节(4005 无刷电机 + 10:1 行星减速,峰值约 3.5 N·m、持续约 1.0 N·m、约 30 rad/s)
- 树莓派 5 8GB,M.2 槽可加 AI 加速卡(BOM 选配 Raspberry Pi AI Kit)
- 自制 Pi HAT 控制板与配电板(JLCPCB 贴片,BNO086 需经全球代购)
- 4 英寸 LCD 表情屏、3W 扬声器、IMX296 鱼眼摄像头、耳朵 9g 舵机
- 得伟 20V PowerStack 1.7Ah 电池 ×2、PS5 手柄
- PETG 与 TPU 打印结构件、M2.5 热熔螺母、壁球做足端
工具
- 3D 打印机(PETG 与 TPU)
- 烙铁(250°C 压入热熔螺母)
- 电动螺丝刀与强力胶(BOM)
技能
- 电机驱动与控制板固件烧录
- PCB 贴片下单(JLCPCB 全球代购 + PCBA)
- ROS 2 与 Linux(SSH、编译工作区)
- 强化学习与 MuJoCo/MJX 仿真(CS 123 课程)
软件
- pupperv3-monorepo(ROS 2 控制、神经网络步态、AI 代理)
- pupperv3-mjx(MJX 强化学习训练)
- pupOS 树莓派镜像(full 版与 AI 版)
- Foxglove Studio 可视化