正在连接信源…

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 可视化

文档