文档首页/ 具身智能开发平台 CloudRobo/ 最佳实践/ 基于操作类模型体验把笔放入笔筒的真机推理调试

更新时间：2026-06-30 GMT+08:00

基于操作类模型体验把笔放入笔筒的真机推理调试

整体流程

本文档用于指导您将一台真实的SO-ARM101机械臂接入CloudRobo平台，并完成一个可重复调试的推理任务，如“抓起桌面上的笔并放入笔筒”。整体流程如下：

准备一台可上电、可通信的SO-ARM101机械臂。
搭建一个可重复布置的标准化任务场景（以“抓笔放笔筒”为例）。
安装LeRobot与本项目R2C SDK所需的软件环境。
在CloudRobo平台创建机器人。
使用R2C SDK将机器人接入CloudRobo平台。
真机执行任务并完成调试。

设备清单

SO-ARM101机械臂套件的主控设备配置、物料准备如下。

主控设备

表1 主控设备要求
主控设备	操作系统	配置	基础软件（共通）
台式机/笔记本电脑	Ubuntu 22.04+/Windows	CPU: 6核+，推荐8核	Python 3.10+、VS code、Git
		内存：16GB+，推荐32GB
		显卡：核显 / NVIDIA独显（本机推理必需），8GB+显存
		硬盘：1TB+，推荐NVMe/SSD
		USB：至少4到6个，或备个扩展坞

机器人
 请准备待接入的机器人，并完成组装。

机械臂套装

你可以通过以下两种方式获取机械臂套件：

整套购买：购买完整的SO-ARM101机械臂套件（含所有结构件、配套相机、电源、固定器等），推荐新手使用。
DIY组装：自行采购核心部件并3D打印结构件，适合有经验的用户。

用于“抓笔放笔筒”的推荐配置如下：

表2 推荐配置
必需项	推荐项
1台SO-ARM101机械臂 1个官方或兼容的电机控制板 1个匹配电压/电流规格的电源 1根稳定USB数据线 1台Linux主机 2路RGB相机第三视角相机1个（GC2083 2.5mm137度无畸变）腕部相机1个（GC2083 2.5mm137度无畸变） 1个第三视角相机支架（3D打印 print_third_cam_mount.stl） 1个腕部相机支架（3D打印 wrist_cam_mount.stl） 1张稳定桌面 1张桌布夹具或螺丝固定底座，避免机械臂工作时基座移动急停方案最低标准为“电源插头可立即断电” 更推荐使用独立电源开关或插座急停	顶部补光灯或稳定环境照明防滑桌垫尺子/定位板/贴纸，用于任务复位一台单独GPU推理主机

硬件环境搭建

SO-ARM101硬件固定至桌面的主要安装步骤如下：

桌布铺设。
- 图纸上已标出相机塔与机械从臂的安装位置，请根据图纸摆放。
- SO-ARM101从臂左右前孔位的中心点距左右边界的距离为39cm，距桌面底部是8.5cm，其次左右两孔连线的中点距第三视角相机中心点的距离是43cm。
- 针对“把笔放入笔筒”这个任务，建议笔筒底部中心点距SO-ARM101左右两孔连线的中点距离为26.5cm，该距离为SO-ARM101机械臂的可达范围，故笔的放置位置不应超过该范围。
桌布颜色推荐单一浅灰/白色/浅木色，不要使用强反光玻璃；背景避免复杂纹理桌布；光照推荐稳定常亮，不要忽明忽暗。

图1 铺设桌布图纸
相机摆放。

相机作为机械臂系统中的关键感知模块，其安装位置与姿态直接影响任务执行的准确性与稳定性。

请打印第三视角相机支架、腕部相机支架，将第三视角俯视相机放入图纸中的相机塔位置，并将腕部相机固定到机械臂。
机械臂摆放。

安装时，请将机械臂从臂放置在图纸中标注的位置，并确保底座与标记点精准重合。主臂则可安装在从臂旁边，大致对齐图纸边缘即可。

软件环境准备

安装LeRobot环境依赖

主要安装步骤参考如下操作，您也可以参考lerobot官方的安装指导文档。

安装Miniforge。
- Windows系统：https://mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/LatestRelease/Miniforge3-Windows-x86_64.exe
  下载完后，双击安装，按照默认选项安装即可。
- linux系统：https://mirrors.tuna.tsinghua.edu.cn/github-release/conda-forge/miniforge/LatestRelease/Miniforge3-Linux-x86_64.sh
  执行以下命令安装：
```
sh Miniforge3-Linux-x86_64.sh
source ~/.bashrc
```
对于后续步骤的命令，无特殊声明时，windows系统在Miniforge Prompt中运行（可在已安装应用列表中找到），linux系统在终端中运行。

配置conda国内源（可选）。

为加快conda环境安装速度，可选择配置国内源。

Windows系统

在Miniforge Prompt中运行以下命令。

# 添加清华大学的conda-forge镜像
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
# 设置搜索时显示通道地址，方便确认是否用上了国内源
conda config --set show_channel_urls yes
# 移除默认的国外conda-forge通道（可选，但推荐，确保只走国内镜像）
conda config --remove channels conda-forge

Linux (Ubuntu) 系统

打开终端，运行以下命令。

# 添加清华大学的conda-forge镜像
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/
# 设置搜索时显示通道地址，方便确认是否用上了国内源
conda config --set show_channel_urls yes
# 移除默认的国外conda-forge通道（可选，但推荐，确保只走国内镜像）
conda config --remove channels conda-forge

清除缓存使配置生效
修改完文件后，运行以下命令。
```
conda clean -i
```

验证配置

执行以下命令查看当前的channels是否已更换。

conda config --show channels
# 输出应该包含有 https://mirrors.tuna.tsinghua.edu.cn/anaconda/cloud/conda-forge/

创建虚拟环境。
运行如下命令，对于创建环境中conda的判定请求，按照日志提示回复accept或y。
```
conda create -n lerobot python=3.12
conda activate lerobot
```
后续再次进入环境，只需要执行 “conda activate lerobot” 即可。
配置Python pypi国内源（可选）。

为了加快安装Python包时依赖包下载速度，可配置pypi的国内源。

自动配置命令（跨平台通用）。

执行以下命令，即可一键将pip默认源设置为华为源。
```
pip config set global.index-url https://repo.huaweicloud.com/repository/pypi/simple
pip config set global.trusted-host repo.huaweicloud.com
```
获取lerobot代码。
- 方式一：如果本地有配置git，可以直接克隆代码库。如果没有git，可先自行安装git，或采用方式二。
  
  克隆保存的路径，不能有中文字符，否则可能导致运行时找不到Python库的路径。
  
  LeRobot的官方代码仓库更新频繁，选择tag为0.5.1版本，本文档匹配lerobot-v0.5.1版本。
  
  Windows系统：
```
set GIT_LFS_SKIP_SMUDGE=1
git clone https://gitee.com/mirrors/lerobot.git
cd lerobot 
git checkout -b v051 v0.5.1
```
  linux系统：
```
GIT_LFS_SKIP_SMUDGE=1 
git clone https://gitee.com/mirrors/lerobot.git
cd lerobot 
git checkout -b v051 v0.5.1
```
- 方式二：在浏览器打开lerobot仓库，并下载v0.5.1版本。将压缩包放到个人工作目录下并解压。
进入lerobot目录，安装lerobot的依赖包并指定添加飞特舵机相关的驱动。
```
pip install -e ".[feetech]"
```
安装ffmpeg。
- linux下需要安装，执行以下命令。
```
conda install ffmpeg -c conda-forge
```
- Windows系统不需要安装。

安装R2C SDK软件环境

登录CloudRobo控制台。
在左侧导航栏选择“运行管理 > R2C SDK”，下载R2C SDK软件包，如hw_r2c_sdk-0.1.62.tar.gz，并放至工作目录。
进入conda的lerobot环境。
```
conda activate lerobot
```

在工作目录下，解压软件包。

tar -zxvf hw_r2c_sdk-0.1.62.tar.gz 
cd r2c_sdk_python

安装R2C SDK软件包。
```
pip install -e .
```

验证安装：输出有版本号（如0.1.62）即表示安装成功。

linux下执行：

python3 -c "import r2c_sdk; print(r2c_sdk.__version__)"

windows下执行：

python -c "import r2c_sdk; print(r2c_sdk.__version__)"

机器人标定

本章节以标定SO-ARM101机械臂为例，其他型号机械臂标定可参考官方文档。

关键标定步骤如下：

手动标定Follower臂。

确保Follower臂连接电源和USB信号线之后，请执行如下命令查看并记录端口号。
```
lerobot-find-port
```
请根据界面提示拔出Follower臂USB信号线并在界面单击“Enter”键，可查看到Follower臂的端口号。
运行如下命令启动标定。
```
lerobot-calibrate  --robot.type=so101_follower  --robot.port=/dev/ttyACM0  --robot.id=my_follower_arm
```

robot.type=so101_follower机械臂类型，可根据需要修改。
robot.port=/dev/ttyACM0修改为查询到的端口号，Linux一般默认为dev/ttyACM0，Windows一般为COM1，命令需要修改为robot.port=COM1。
robot.id=my_follower_arm可根据需要修改，保持唯一即可。

首先是Middle Position，然后是各关节都旋转到最大最小限位。

表3 Middle position
关节角	中间角度示例
Middle position	命令行窗口输出“Move so101_follower to the middle of its range of motion and press ENTER....” 后，机械臂摆成如图所示形态（动爪朝上，固定爪朝下），再按回车键。

表4 各关节最大最小张开角度
各关节限位	最大张开角度	最小张开角度
6号关节
5号关节
4号关节
3号关节
2号关节
1号关节

最终的参数大概在这个范围，当MIN、MAX达到最终状态不再变化之后，按回车保存。

图2 标定参数范围

标定好的参数文件保存为： ~/.cache/huggingface/lerobot/calibration/robots/so101_follower/my_follower_arm.json

手动标定Leader臂。

请勿断开Follower臂，并确保Leader臂连接电源和USB信号线之后，请执行如下命令查看并记录端口号。
```
lerobot-find-port
```
请根据界面提示拔出Leader臂USB信号线并在界面单击“Enter”键，可查看到Leader臂的端口号。
运行如下命令启动标定。
```
lerobot-calibrate --teleop.type=so101_leader --teleop.port=dev/ttyACM1 --teleop.id=my_leader_arm
```

teleop.type=so101_leader机械臂类型，可根据需要修改。
teleop.port=dev/ttyACM1修改为查询到的端口号，Linux一般默认为dev/ttyACM1，Windows一般为COM2，命令需要修改为teleop.port=COM2。
teleop.id=my_leader_arm可根据需要修改，保持唯一即可。

首先是Middle Position，然后是各关节都旋转到最大最小限位。(张开角度与Follower类似)

表5 Middle position
关节角	角度示例
Middle position	命令行窗口输出 “Move so101_leader to the middle of its range of motion and press ENTER....” 之后，机械臂摆成如图所示形态，再按回车键。图3 Middle position

标定好的参数文件保存为： ~/.cache/huggingface/lerobot/calibration/teleoperators/so101_leader/my_leader_arm.json

在CloudRobo平台创建机器人

登录CloudRobo控制台。
在左侧导航栏单击“运行管理 > 机器人”，进入机器人管理界面。
单击“接入机器人”，填写机器人名称、描述，在机器人类型选择机械臂、厂家选择开源、型号选择SO-ARM101，单击“立即接入”。

图4 创建机器人
创建完成后会弹出下载配置文件提示，请单击“下载”，将配置文件保存到本地。

创建机器人后，如果R2C SDK侧未完成配置，机器人状态为待激活；R2C SDK侧完成配置后，机器人状态会刷新为在线。

图5 下载配置文件提示
- 勾选开启“私钥加密密码”，输入“加密密码”和“确认密码”后，单击“下载”按钮，将配置文件保存到本地。
  - 加密密码校验规则：支持使用英文大小写字母、数字、特殊字符 (例如,.+-_#) 等，长度为1-32个字符。
  - 确认密码校验规则：支持使用英文大小写字母、数字、特殊字符 (例如,.+-_#) 等，长度为1-32个字符。

使用R2C SDK接入机器人

当前R2C SDK已内置有SO-ARM101等机械臂的相关配置，请将在CloudRobo平台下载的配置文件放置到r2c_sdk_python/config目录下，可快速接入机械臂。

进入r2c_sdk_python目录下。
进入conda的lerobot环境。
```
conda activate lerobot
```

配置so101机械臂参数。

查看Follow臂的port并记录。
```
lerobot-find-port 
```
请根据界面提示拔出Follow臂USB信号线并在界面单击“Enter”键，可查看到Follower臂的端口号。

linux系统下，端口类似：
```
/dev/ttyACM0
```
windows系统下，端口类似：
```
COM1
```
查看相机的设备号并记录。在当前运行命令的路径下会生成outputs/captured_images文件夹，可查看图片确定相机对应端口号。
```
lerobot-find-cameras opencv
```
linux系统下，端口类似：
```
/dev/video0
```
windows系统下，端口类似：
```
0
```

在R2C SDK主目录下，打开机器人配置文件config/robot_so101_lerobot_config.yaml，修改机器人当前相机设备号和so101从臂的id和port。

linux系统下：

hardware:
   lerobot_config:
     type: so101_follower
     id: follower_arm              --修改成标定时设备的机械臂id
     calibration_dir: null
     # Replace with the actual serial device used by your SO101 robot.
    port: /dev/ttyACM0           --修改成查到的port
     cameras:
       front:
         type: opencv
         index_or_path: /dev/video3       --修改成查到顶部相机的设备号
         width: 640
         height: 480
         fps: 30       --修改为相机实际的fps,如不知道或没显示就保持默认30
      wrist:
         type: opencv
         index_or_path: /dev/video0         --修改成查到的腕部相机的设备号
         width: 640
         height: 480
         fps: 30       --修改为相机实际的fps,如不知道或没显示就保持默认30

windows系统下：

hardware:
   lerobot_config:
     type: so101_follower
     id: follower_arm              --修改成标定时设备的机械臂id
     calibration_dir: null
     # Replace with the actual serial device used by your SO101 robot.
    port: COM1           --修改成查到的port
     cameras:
       front:
         type: opencv
         index_or_path: 0      --修改成查到顶部相机的设备号
         width: 640
         height: 480
         fps: 30       --修改为相机实际的fps,如不知道或没显示就保持默认30
      wrist:
         type: opencv
         index_or_path: 2         --修改成查到的腕部相机的设备号
         width: 640
         height: 480
         fps: 30       --修改为相机实际的fps,如不知道或没显示就保持默认30

执行如下命令完成机器人接入。
```
python -m r2c_sdk.cloudroboclient --bundle config/配置文件名.zip --robot-config config/robot_so101_lerobot_config.yaml
```
如无报错，即表示机器人接入CloudRobo平台成功，在CloudRobo平台的机器人列表页，可查看到该机器人状态变为在线。

真机调试说明

使用智能体调试真机时，模型服务需处于运行中状态，机器人需在线。
同一本体，支持切换不同的模型服务进行技能调试，方便您选择效果更优的模型服务。
部分模型仅支持执行固定的模型技能，不支持泛化技能；其他模型可执行泛化技能，您可根据需要输入需要执行的Prompt，验证模型的泛化性。

部署模型服务

单击导航栏“运行管理-模型部署”，进入模型部署作业管理页面，单击右上角“部署模型服务”按钮，开始创建任务。
输入基础信息，选择部署SO101可使用的模型（如LeRobot-ACT-把笔插进笔筒-so101真机），并选择资源配置，单击立即部署。在模型部署界面可单击刷新按钮，等待模型服务部署完成。

图6 部署在线模型服务

调试模型技能

在机器人界面，选择状态为在线的SO-ARM101机械臂，单击“智能体调试”，进入技能调试界面。

图7 技能调试界面
单击选择模型技能，选择处于运行中的模型服务，如LeRobot-ACT-把笔插进笔筒-so101真机，技能选择把笔插进笔筒，单击确定。
在智能体调试界面，单击发送按钮，开始技能调试。

模型推理的默认步数为60 steps。如果已经达到最大推理的步数，但实际任务并未完成，您可重新发送Prompt，会重新执行任务。您也可以在参数配置中适当调大技能最大推理步数。该参数调整后仅对该机器人和当前选择的模型服务生效。