a. 安装操作系统与 NVIDIA 驱动

sudo apt update
sudo apt upgrade -y
ubuntu-drivers devices
# 测试通过版本为 535，可尝试更新版本（请勿使用 server 分支）
sudo apt install nvidia-driver-535
# 重启计算机
sudo reboot
# 验证驱动
nvidia-smi

b. 安装 NVIDIA Container Toolkit

sudo apt install curl
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
export NVIDIA_CONTAINER_TOOLKIT_VERSION=1.17.8-1
sudo apt-get install -y nvidia-container-toolkit=${NVIDIA_CONTAINER_TOOLKIT_VERSION} nvidia-container-toolkit-base=${NVIDIA_CONTAINER_TOOLKIT_VERSION} libnvidia-container-tools=${NVIDIA_CONTAINER_TOOLKIT_VERSION} libnvidia-container1=${NVIDIA_CONTAINER_TOOLKIT_VERSION}

c. 安装 Docker

sudo apt update
sudo apt install git
sudo apt install docker.io
# 配置 NVIDIA Runtime
nvidia-ctk
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
sudo docker info | grep -i runtime
# 输出中应包含 "nvidia" Runtime

• 官方指南：ROS Noetic 安装
• 国内加速源推荐：小鱼ROS

安装示例：

wget http://fishros.com/install -O fishros && . fishros
# 菜单选择：5 配置系统源 → 2 更换源并清理第三方源 → 1 添加ROS源
wget http://fishros.com/install -O fishros && . fishros
# 菜单选择：1 一键安装 → 2 不更换源安装 → 选择 ROS1 Noetic 桌面版

测试 ROS 安装：

roscore  # 新建终端
rosrun turtlesim turtlesim_node  # 新建终端
rosrun turtlesim turtle_teleop_key  # 新建终端

• 首先最好是换个源：

sudo vim /etc/docker/daemon.json

• 然后在这个json文件中写入一些镜像源：

{
    "registry-mirrors": [
        "https://docker.m.daocloud.io",
        "https://docker.imgdb.de",
        "https://docker-0.unsee.tech",
        "https://docker.hlmirror.com",
        "https://docker.1ms.run",
        "https://func.ink",
        "https://lispy.org",
        "https://docker.xiaogenban1993.com"
    ]
}

• 然后保存文件并退出后，重启docker服务：

sudo systemctl daemon-reload && sudo systemctl restart docker

• 现在开始创建镜像，首先建立Dockerfile：

mkdir /path/to/save/docker/ros/image
cd /path/to/save/docker/ros/image
vim Dockerfile

然后在Dockerfile文件中写入如下内容：

FROM ubuntu:20.04

ENV DEBIAN_FRONTEND=noninteractive

RUN sed -i 's|http://archive.ubuntu.com/ubuntu/|http://mirrors.tuna.tsinghua.edu.cn/ubuntu/|g' /etc/apt/sources.list && \
    sed -i 's|http://security.ubuntu.com/ubuntu/|http://mirrors.tuna.tsinghua.edu.cn/ubuntu/|g' /etc/apt/sources.list

RUN apt-get update && apt-get install -y locales tzdata gnupg lsb-release
RUN locale-gen en_US.UTF-8
ENV LANG=en_US.UTF-8 LANGUAGE=en_US:en LC_ALL=en_US.UTF-8

# 设置ROS的debian源
RUN sh -c 'echo "deb http://packages.ros.org/ros/ubuntu $(lsb_release -sc) main" > /etc/apt/sources.list.d/ros-latest.list'

# 添加ROS的Keys
RUN apt-key adv --keyserver 'hkp://keyserver.ubuntu.com:80' --recv-key C1CF6E31E6BADE8868B172B4F42ED6FBAB17C654

# 安装ROS Noetic
# 设置键盘布局为 Chinese
RUN apt-get update && \
    apt-get install -y keyboard-configuration apt-utils && \
    echo 'keyboard-configuration keyboard-configuration/layoutcode string cn' | debconf-set-selections && \
    echo 'keyboard-configuration keyboard-configuration/modelcode string pc105' | debconf-set-selections && \
    echo 'keyboard-configuration keyboard-configuration/variant string ' | debconf-set-selections && \
    apt-get install -y ros-noetic-desktop-full && \
    apt-get install -y python3-rosdep python3-rosinstall python3-rosinstall-generator python3-wstool build-essential && \
    rm -rf /var/lib/apt/lists/*

# 初始化rosdep
RUN rosdep init

写入完毕后保存退出。

• 执行ubuntu20.04 + ROS Noetic镜像的构建：

sudo docker build -t ubt2004_ros_noetic .

• 构建完成后进入镜像即可，初次启动容器加载镜像：

sudo docker run -it --name ubuntu_ros_container ubt2004_ros_noetic /bin/bash
# 或 GPU 启动（推荐）
sudo docker run -it --gpus all --runtime nvidia --name ubuntu_ros_container ubt2004_ros_noetic /bin/bash
# 可选，挂载本地目录路径等
# sudo docker run -it --gpus all --runtime nvidia --name ubuntu_ros_container -v /path/to/your/code:/root/code ubt2004_ros_noetic /bin/bash

之后每次加载：

sudo docker start ubuntu_ros_container
sudo docker exec -it ubuntu_ros_container /bin/bash

• 或者：自定义启动加载文件，launch_docker.sh, 注意，由于涉及挂载python环境，请在第4步完成后再使用这种sh方式！

#!/bin/bash

# Paths
CODE_DIR=/path/to/code
PYTHON_DIR=/path/to/python_env
DATA_DIR=/path/to/data
IMAGE=ros:noetic
CONTAINER=ros_noetic

# Create container if it doesn't exist
if ! docker ps | grep -q "$CONTAINER"; then
    echo "🛠  Creating container $CONTAINER ..."
    docker create --name=$CONTAINER $IMAGE
fi

# Run container with mounts and environment
echo "🚀 Starting container $CONTAINER ..."
docker run \
    -i -t \
    -v $CODE_DIR:/code \
    -v $DATA_DIR:/data \
    -v $PYTHON_DIR:$PYTHON_DIR \
    --env PATH=/path/to/python_venv/kdc_dev/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin \
    $CONTAINER /bin/bash

• 进入镜像后，初始化ros环境变量，然后启动roscore

source /opt/ros/noetic/setup.bash
roscore

无误的话，ubuntu20.04 + ros noetic的docker配置方式就结束了。

• ananconda配置：

conda create -n kdc_dev python=3.10
conda activate kdc_dev

• 或， 源码安装Python3.10.18，再用venv创建虚拟环境

⚠️ 注意：ppa:deadsnakes 在2025年6月后不能在ubuntu20.04上提供了，下述安装方式不一定成功：

sudo apt update
sudo apt install -y software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install -y python3.10 python3.10-venv python3.10-dev

可以尝试下，不行请使用源码安装：

sudo apt update
sudo apt install -y build-essential libssl-dev zlib1g-dev libncurses5-dev libncursesw5-devlibreadline-dev libsqlite3-dev libgdbm-dev libdb5.3-dev libbz2-dev libexpat1-dev liblzma-dev tk-dev libffi-dev uuid-dev wget

wget https://www.python.org/ftp/python/3.10.18/Python-3.10.18.tgz
tar -xzf Python-3.10.18.tgz
cd Python-3.10.18
./configure --prefix=$HOME/python3.10 --enable-optimizations
make -j$(nproc)
sudo make install

然后创建venv环境：

python3.10 -m venv kdc_dev
source kdc_dev/bin/activate

查看和确保安装正确：

python  # 查看python版本，看到确认输出为3.10.xxx（通常是3.10.18）
# 输出示例：
# Python 3.10.18 (main, Jun  5 2025, 13:14:17) [GCC 11.2.0] on linux
# Type "help", "copyright", "credits" or "license" for more information.
# >>> 

pip --version # 查看pip对应的版本，看到确认输出为3.10的pip
# 输出示例：pip 25.1 from /path/to/your/env/python3.10/site-packages/pip (python 3.10)

5. 安装依赖：

source /opt/ros/noetic/setup.bash  # 进入python环境先source好ros自带的python库，建议这行写入~/.bashrc

pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple  # 建议首先换源，能加快下载安装速度

# 算力服务器
pip install -r requirements_ilcode.txt   # 无需ROS Noetic，但只能使用kuavo_train模仿学习训练代码，kuavo_data（数转）及 kuavo_deploy（部署代码）均依赖ROS
# 或
pip install -r requirements_total.txt    # 需确保 ROS Noetic 已安装 (推荐)

# 机器人上位机 AGX orin
pip install -r requirements_total_agxorin.txt    # 需确保 ROS Noetic 已安装 (推荐)

安装完打印下检查下lerobot版本：2025年11月20日为0.4.2版本

pip show lerobot

若不是 0.4.2：

cd third_party/lerobot
git fetch
git reset --hard 0f551df8f4bad4c504e395ea3df74fc5f714016f
cd ../../

重新pip install -r requirement即可。

如果pip安装完毕但运行训练代码时报ffmpeg或torchcodec的错：

conda install ffmpeg==6.1.1

# 或

# pip uninstall torchcodec

数据集来源

• 从 LET开源数据集 下载 rosbag 数据集
• 使用 gym工具 下载数采平台云端 rosbag 数据集，参考 gym工具使用说明 。

将 Kuavo 原生 rosbag 数据转换为 Lerobot 框架可用的 parquet 格式：

##### Kuavo 5
python kuavo_data/CvtRosbag2Lerobot.py \
  --config-path=../configs/data/ \
  --config-name=KuavoRosbag2Lerobot_kuavo5.yaml \
  rosbag.rosbag_dir=/path/to/rosbag \
  rosbag.lerobot_dir=/path/to/lerobot_data

##### Kuavo 4pro
python kuavo_data/CvtRosbag2Lerobot.py \
  --config-path=../configs/data/ \
  --config-name=KuavoRosbag2Lerobot_kuavo4pro.yaml \
  rosbag.rosbag_dir=/path/to/rosbag \
  rosbag.lerobot_dir=/path/to/lerobot_data

说明：

• rosbag.rosbag_dir：原始 rosbag 数据路径
• rosbag.lerobot_dir：转换后的lerobot-parquet 数据保存路径，通常会在此目录下创建一个名为lerobot的子文件夹
• configs/data/KuavoRosbag2Lerobot.yaml：配置文件

配置文件

使用KuavoRosbag2Lerobot.yaml进行配置，关键配置项说明：

使用转换好的数据进行模仿学习训练：

python kuavo_train/train_policy.py \
  --config-path=../configs/policy/ \
  --config-name=diffusion_config.yaml \
  task=your_task_name \
  method=your_method_name \
  root=/path/to/lerobot_data/lerobot \
  training.batch_size=32 \
  policy_name=diffusion

说明：

• --config-name: 配置文件，对应policy_name填写diffusion_config.yaml或act_config.yaml
• task：自定义，任务名称（最好与数转中的task定义对应），如pick and place
• method：自定义，方法名，用于区分不同的训练，如diffusion_bs128_usedepth_nofuse等
• root：训练数据的本地路径，注意加上lerobot，与1中的数转保存路径需要对应，为：/path/to/lerobot_data/lerobot
• training.batch_size：批大小，可根据 GPU 显存调整
• policy_name：使用的策略，用于策略实例化的，目前支持diffusion和act
• 其他参数可详见yaml文件说明，推荐直接修改yaml文件，避免命令行输入错误

配置文件

使用diffusion_config.yaml或act_config.yaml进行配置，关键配置项说明：

2.1 模仿学习训练：单机多卡模式

安装 accelerate 库： pip install accelerate (一般安装lerobot时已经安装)

accelerate launch kuavo_train/train_policy_with_accelerate.py \
  --config_file configs/accelerate/accelerate_config.yaml \
  --config-path=../configs/policy \
  --config-name=diffusion_config.yaml

说明：

• --config-name: 配置文件，对应policy_name填写diffusion_config.yaml或act_config.yaml参数配置参考上面2. 模仿学习训练详细参数说明

配置文件

使用accelerate_config.yaml进行配置，关键配置项说明：

完成训练后调用模型进行真机部署：
修改配置文件 kuavo_env.yaml，env_name为Kuavo-Real，其他如eef_type，obs_key_map等按需修改，即可在真机上部署测试。

• 如果是4pro机器人，选择配置文件 kuavo_env_kuavo4pro.yaml；如果是5代人形，选择配置文件 kuavo_env_kuavo5.yaml

• 边侧机推理请见 边侧机通信配置方案

配置文件

关键配置项说明：

⚠️ 注意：

1. 模型部署 配置文件中的参数需与 数据格式转换 或 数采平台导出 配置参数一致
2. 代码将在outputs/train/<task>/<method>/<timestamp>/epoch<epoch>中load policy的模型参数

3.1 硬件启动

机器人正常站立后，调用 /enable_wbc_arm_trajectory_control ROS 服务，启用 WBC（Whole Body Control，全身控制）手臂轨迹控制，并将控制模式设置为 1（自动摆臂模式）:

rosservice call /enable_wbc_arm_trajectory_control "control_mode: 1"

3.2 真机推理部署脚本

• 启动真机推理部署脚本：

  python kuavo_deploy/eval_kuavo.py
  

命令行弹出提示：

=== Kuavo机器人控制示例 ===
此脚本展示如何使用命令行参数控制不同的任务
-e 支持暂停、继续、停止功能

  📋 控制功能说明:
  🔄 暂停/恢复: 发送 SIGUSR1 信号 (kill -USR1 <PID>)
  ⏹️  停止任务: 发送 SIGUSR2 信号 (kill -USR2 <PID>)
  📊 查看日志: tail -f log/kuavo_deploy/kuavo_deploy.log

1. 显示帮助信息:
python kuavo_deploy/src/scripts/script.py --help

2. 干运行模式 - 查看将要执行的操作:
python kuavo_deploy/src/scripts/script.py --task go --dry_run --config /path/to/custom_config.yaml

3. 到达工作位置:
python kuavo_deploy/src/scripts/script.py --task go --config /path/to/custom_config.yaml

4. 从当前位置直接运行模型:
python kuavo_deploy/src/scripts/script.py --task run --config /path/to/custom_config.yaml

5. 插值至bag的最后一帧状态开始运行:
python kuavo_deploy/src/scripts/script.py --task go_run --config /path/to/custom_config.yaml

6. 从go_bag的最后一帧状态开始运行:
python kuavo_deploy/src/scripts/script.py --task here_run --config /path/to/custom_config.yaml

7. 回到零位:
python kuavo_deploy/src/scripts/script.py --task back_to_zero --config /path/to/custom_config.yaml

8. 仿真中自动测试模型，执行eval_episodes次:
python kuavo_deploy/src/scripts/script_auto_test.py --task auto_test --config /path/to/custom_config.yaml

9. 启用详细输出:
python kuavo_deploy/src/scripts/script.py --task go --verbose --config /path/to/custom_config.yaml

=== 任务说明 ===
go          - 先插值到bag第一帧的位置，再回放bag包前往工作位置
run         - 从当前位置直接运行模型
go_run      - 到达工作位置直接运行模型
here_run    - 插值至bag的最后一帧状态开始运行
back_to_zero - 中断模型推理后，倒放bag包回到0位
auto_test   - 仿真中自动测试模型，执行eval_episodes次

请选择要执行的示例: 1. 显示普通测试帮助信息 2. 显示自动测试帮助信息 3. 进一步选择示例
1. 执行: python kuavo_deploy/src/scripts/script.py --help
2. 执行: python kuavo_deploy/src/scripts/script_auto_test.py --help
3. 进一步选择示例
请选择要执行的示例 (1-3) 或按 Enter 退出:

在命令行输入3，按 Enter ，弹出提示

请输入自定义配置文件路径:

输入自定义配置文件路径，默认配置文件参考configs/deploy/kuavo_env_kuavo4pro.yaml；如果是5代，输入路径 configs/deploy/kuavo_env_kuavo5.yaml，弹出提示

📁 配置文件路径: configs/deploy/kuavo_env.yaml
🔍 正在解析配置文件...
📋 模型配置信息:
   Task: your_task
   Method: your_methof
   Timestamp: your_timestamp
   Epoch: 300
📂 完整模型路径: your_path
✅ 模型路径存在
可选择要执行的示例如下:
1. 先插值到bag第一帧的位置，再回放bag包前往工作位置(干运行模式)
执行: python kuavo_deploy/src/scripts/script.py --task go --dry_run --config /path/to/config.yaml
2. 先插值到bag第一帧的位置，再回放bag包前往工作位置
执行: python kuavo_deploy/src/scripts/script.py --task go --config /path/to/config.yaml
3. 从当前位置直接运行模型
执行: python kuavo_deploy/src/scripts/script.py --task run --config /path/to/config.yaml
4. 到达工作位置并直接运行模型
执行: python kuavo_deploy/src/scripts/script.py --task go_run --config /path/to/config.yaml
5. 插值至bag的最后一帧状态开始运行
执行: python kuavo_deploy/src/scripts/script.py --task here_run --config /path/to/config.yaml
6. 回到零位
执行: python kuavo_deploy/src/scripts/script.py --task back_to_zero --config /path/to/config.yaml
7. 先插值到bag第一帧的位置，再回放bag包前往工作位置(启用详细输出)
执行: python kuavo_deploy/src/scripts/script.py --task go --verbose --config /path/to/config.yaml
8. 仿真中自动测试模型，执行eval_episodes次
执行: python kuavo_deploy/src/scripts/script_auto_test.py --task auto_test --config /path/to/config.yaml
9. 退出
请选择要执行的示例 (1-9)

• 选择需要的功能，一般先输入 2 前往工作位置，再输入 3 启动真机同步推理程序，p 暂停推理，s / ctrl+c停止推理

3.3 真机异步推理

步骤同 3.2 真机推理部署脚本，输入 2 前往工作位置后，执行下面真机异步推理程序

##### Kuavo 4pro
python kuavo_deploy/eval_kuavo_async_no_lock_kuavo4pro.py --kuavo-config-path /your_working_dir/configs/data/KuavoRosbag2Lerobot_kuavo4pro.yaml --device=cuda --fps=10 --task="tiaojiu" --duration=300

##### Kuavo 5
python kuavo_deploy/eval_kuavo_async_no_lock_kuavo5.py --kuavo-config-path /your_working_dir/configs/data/KuavoRosbag2Lerobot_kuavo5.yaml --device=cuda --fps=10 --task="pick fruit" --duration=300

⚠️⚠️⚠️ 首次执行需小心，可将机器人身旁物品先移开，观察到达工作位置和运行模型是否正常，符合预期

• 以ACT算法为例

4.1 同步推理

ACT 策略在每次取动作前会按配置决定「用整段 chunk 还是只取前几步」「是否做时间集成」。以下参数在 configs/policy/act_config.yaml 的 policy 下配置，影响平滑性、实时性与推理频率。

• 实现与约束：逻辑在 third_party/lerobot/src/lerobot/policies/act/modeling_act.py 的 ACTPolicy.select_action()

4.2 异步推理

异步推理（eval_kuavo_async_no_lock_kuavo.py）通过动作缓冲区 + 推理线程 + 执行线程解耦推理与执行，影响平滑性、实时性、推理频率与断档风险。

• 实现文件：kuavo_deploy/eval_kuavo_async_no_lock_kuavo.py

4.3 模型输出与动作平滑

模型输出的关节目标会经过裁剪(关节末端范围限制)、首帧插值、帧间插值、低通滤波再下发给机器人。以下参数目前均在代码中固定，仅作说明；若需调节平滑性与响应速度，可尝试修改对应代码与默认值。

• 实现文件：
  动作执行在 kuavo_deploy/kuavo_env/KuavoBaseRosEnv.py（step()、exec_action()）
  低通滤波器在 kuavo_deploy/kuavo_env/lowpass_filter.py（LowPassFilter：cutoff_hz / tau、dt、alpha）。

📡 ROS 话题说明

📁 代码输出结构

输出/
├── train/<task>/<method>/run_<timestamp>/ # 训练模型与参数
├── eval/<task>/<method>/run_<timestamp>/ # 测试日志与视频

📂 核心代码结构

KUAVO-DATA-CHALLENGE/
├── configs/ #配置文件
├── kuavo_data/ # 数据处理转换模块
├── kuavo_deploy/ # 部署脚本（模拟器/真机）
├── kuavo_train/ # 模仿学习训练代码
├── lerobot_patches/ # Lerobot 运行补丁
├──outputs/ # 模型与结果
├──third_party/ # Lerobot 依赖
└──requirements_xxx.txt #依赖列表
└── README.md # 说明文档