# 基于操作类模型体验把笔放入笔筒的真机推理调试 #### 整体流程 本文档用于指导您将一台真实的SO-ARM101机械臂接入CloudRobo平台，并完成一个可重复调试的推理任务，如"抓起桌面上的笔并放入笔筒"。整体流程如下： 1. 准备一台可上电、可通信的SO-ARM101机械臂。 2. 搭建一个可重复布置的标准化任务场景（以"抓笔放笔筒"为例）。 3. 安装LeRobot与本项目R2C SDK所需的软件环境。 4. 在CloudRobo平台接入机器人。 5. 使用R2C SDK将机器人接入CloudRobo平台。 6. 真机执行任务并完成调试。 #### 设备清单 SO-ARM101机械臂套件的主控设备配置、物料准备如下。 - 主控设备 表1主控设备要求 | **主控设备** | **操作系统** | **配置** | **基础软件（共通）** | |:---|:---|:---|:---| | 台式机/笔记本电脑 | Ubuntu 22.04+/Windows | CPU: 6核+，推荐8核 | Python 3.10+、VS code、Git | | 台式机/笔记本电脑 | Ubuntu 22.04+/Windows | 内存：16GB+，推荐32GB | Python 3.10+、VS code、Git | | 台式机/笔记本电脑 | Ubuntu 22.04+/Windows | 显卡：核显 / NVIDIA独显（本机推理必需），8GB+显存 | Python 3.10+、VS code、Git | | 台式机/笔记本电脑 | Ubuntu 22.04+/Windows | 硬盘：1TB+，推荐NVMe/SSD | Python 3.10+、VS code、Git | | 台式机/笔记本电脑 | Ubuntu 22.04+/Windows | USB：至少4到6个，或备个扩展坞 | Python 3.10+、VS code、Git | - 机器人 请准备待接入的机器人，并完成组装。 - 机械臂套装 你可以通过以下两种方式获取机械臂套件： - 整套购买：购买完整的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硬件固定至桌面的主要安装步骤如下： 1. 桌布铺设。 - 图纸上已标出相机塔与机械从臂的安装位置，请根据图纸摆放。 - SO-ARM101从臂左右前孔位的中心点距左右边界的距离为39cm，距桌面底部是8.5cm，其次左右两孔连线的中点距第三视角相机中心点的距离是43cm。 - 针对"把笔放入笔筒"这个任务，建议笔筒底部中心点距SO-ARM101左右两孔连线的中点距离为26.5cm，该距离为SO-ARM101机械臂的可达范围，故笔的放置位置不应超过该范围。 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/public_sys-resources/note_3.0-zh-cn.png) 桌布颜色推荐单一浅灰/白色/浅木色，不要使用强反光玻璃；背景避免复杂纹理桌布；光照推荐稳定常亮，不要忽明忽暗。 图1铺设桌布图纸 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002622747367.png "点击放大") 2. 相机摆放。 相机作为机械臂系统中的关键感知模块，其安装位置与姿态直接影响任务执行的准确性与稳定性。 请打印第三视角相机支架、腕部相机支架，将第三视角俯视相机放入图纸中的相机塔位置，并将腕部相机固定到机械臂。 3. 机械臂摆放。 安装时，请将机械臂从臂放置在图纸中标注的位置，并确保底座与标记点精准重合。主臂则可安装在从臂旁边，大致对齐图纸边缘即可。 #### 软件环境准备 **安装LeRobot环境依赖** 主要安装步骤参考如下操作，您也可以参考[lerobot官方的安装指导文档](https://huggingface.co/docs/lerobot/installation)。 1. 安装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 ``` ![](https://support.huaweicloud.com/bestpractice-cloudrobo/public_sys-resources/note_3.0-zh-cn.png) 对于后续步骤的命令，无特殊声明时，windows系统在Miniforge Prompt中运行（可在已安装应用列表中找到），linux系统在终端中运行。 2. 配置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/ ``` 3. 创建虚拟环境。 运行如下命令，对于创建环境中conda的判定请求，按照日志提示回复accept或y。 ``` conda create -n lerobot python=3.12 conda activate lerobot ``` 后续再次进入环境，只需要执行 "conda activate lerobot" 即可。 4. 配置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 ``` 5. 获取lerobot代码。 - **方式一** ：如果本地有配置git，可以直接克隆代码库。如果没有git，可先自行安装git，或采用方式二。 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/public_sys-resources/note_3.0-zh-cn.png) 克隆保存的路径，不能有中文字符，否则可能导致运行时找不到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仓库](https://gitee.com/mirrors/lerobot/tags)，并下载v0.5.1版本。将压缩包放到个人工作目录下并解压。 6. 进入lerobot目录，安装lerobot的依赖包并指定添加飞特舵机相关的驱动。 ``` pip install -e ".[feetech]" ``` 7. 安装ffmpeg。 - linux下需要安装，执行以下命令。 ``` conda install ffmpeg -c conda-forge ``` - Windows系统不需要安装。 **安装R2C SDK软件环境** 1. [登录CloudRobo控制台](https://console.huaweicloud.com/cloudrobo/)。 2. 在左侧导航栏选择"运行管理 \> R2C SDK"，下载R2C SDK软件包，如hw_r2c_sdk-*0.1.62*.tar.gz，并放至工作目录。 3. 进入conda的lerobot环境。 ``` conda activate lerobot ``` 4. 在工作目录下，解压软件包。 ``` tar -zxvf hw_r2c_sdk-0.1.62.tar.gz cd r2c_sdk_python ``` 5. 安装R2C SDK软件包。 ``` pip install -e . ``` 6. 验证安装：输出有版本号（如*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机械臂为例，其他型号机械臂标定可参考官方文档。 关键标定步骤如下： 1. 手动标定Follower臂。 1. 确保Follower臂连接电源和USB信号线之后，请执行如下命令查看并记录端口号。 ``` lerobot-find-port ``` 2. 请根据界面提示拔出Follower臂USB信号线并在界面单击"Enter"键，可查看到Follower臂的端口号。 运行如下命令启动标定。 ``` lerobot-calibrate --robot.type=so101_follower --robot.port=/dev/ttyACM0 --robot.id=my_follower_arm ``` ![](https://support.huaweicloud.com/bestpractice-cloudrobo/public_sys-resources/note_3.0-zh-cn.png) - robot.type=so101_follower机械臂类型，可根据需要修改。 - robot.port=/dev/ttyACM0修改为查询到的端口号，Linux一般默认为dev/ttyACM0，Windows一般为COM1，命令需要修改为robot.port=COM1。 - robot.id=my_follower_arm可根据需要修改，保持唯一即可。 首先是Middle Position，然后是各关节都旋转到最大最小限位。 表3Middle position | 关节角 | 中间角度示例 | |:---|:---| | Middle position | 命令行窗口输出"Move so101_follower to the middle of its range of motion and press ENTER...." 后，机械臂摆成如图所示的形态（动爪朝上，固定爪朝下），再按回车键。 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002622907239.png "点击放大") | 表4各关节最大最小张开角度 | 各关节限位 | 最大张开角度 | 最小张开角度 | |:---|:---|:---| | 6号关节 | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592587720.png "点击放大") | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592587718.png "点击放大") | | 5号关节 | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592587710.png "点击放大") | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592427798.png "点击放大") | | 4号关节 | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002622907237.png "点击放大") | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592587700.png "点击放大") | | 3号关节 | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592427792.png "点击放大") | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002622907243.png "点击放大") | | 2号关节 | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002622747371.png "点击放大") | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592427790.png "点击放大") | | 1号关节 | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592587706.png "点击放大") | ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002622747375.png "点击放大") | 最终的参数大概在这个范围，当MIN、MAX达到最终状态不再变化之后，按回车保存。 图2标定参数范围 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592587712.png "点击放大") 标定好的参数文件保存为： \~/.cache/huggingface/lerobot/calibration/robots/so101_follower/my_follower_arm.json 2. 手动标定Leader臂。 1. 请勿断开Follower臂，并确保Leader臂连接电源和USB信号线之后，请执行如下命令查看并记录端口号。 ``` lerobot-find-port ``` 2. 请根据界面提示拔出Leader臂USB信号线并在界面单击"Enter"键，可查看到Leader臂的端口号。 运行如下命令启动标定。 ``` lerobot-calibrate --teleop.type=so101_leader --teleop.port=dev/ttyACM1 --teleop.id=my_leader_arm ``` ![](https://support.huaweicloud.com/bestpractice-cloudrobo/public_sys-resources/note_3.0-zh-cn.png) - teleop.type=so101_leader机械臂类型，可根据需要修改。 - teleop.port=dev/ttyACM1修改为查询到的端口号，Linux一般默认为dev/ttyACM1，Windows一般为COM2，命令需要修改为teleop.port=COM2。 - teleop.id=my_leader_arm可根据需要修改，保持唯一即可。 首先是Middle Position，然后是各关节都旋转到最大最小限位。(张开角度与Follower类似) 表5Middle position | 关节角 | 角度示例 | |:---|:---| | Middle position | 命令行窗口输出 "Move so101_leader to the middle of its range of motion and press ENTER...." 之后，机械臂摆成如图所示的形态，再按回车键。 图3Middle position ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002592427800.png "点击放大") | 标定好的参数文件保存为： \~/.cache/huggingface/lerobot/calibration/teleoperators/so101_leader/my_leader_arm.json #### 在CloudRobo平台接入机器人 1. [登录CloudRobo控制台](https://console.huaweicloud.com/cloudrobo/)。 2. 在左侧导航栏单击"运行管理 \> 机器人"，进入机器人管理界面。 3. 单击"接入机器人"，填写机器人名称、描述，在机器人类型选择机械臂、厂家选择开源、型号选择SO-ARM101，单击"立即接入"。 图4接入机器人 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002661277893.png "点击放大") 4. 创建完成后会弹出下载配置文件提示，请单击"下载"，将配置文件保存到本地。 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/public_sys-resources/note_3.0-zh-cn.png) 接入机器人后，如果R2C SDK侧未完成配置，机器人状态为待激活；R2C SDK侧完成配置后，机器人状态会刷新为在线。 图5下载配置文件提示 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002631364164.png "点击放大") - 勾选开启"私钥加密密码"，输入"加密密码"和"确认密码"后，单击"下载"按钮，将配置文件保存到本地。 - 加密密码校验规则：支持使用英文大小写字母、数字、特殊字符 (例如,.+-_#) 等，长度为1-32个字符。 - 确认密码校验规则：支持使用英文大小写字母、数字、特殊字符 (例如,.+-_#) 等，长度为1-32个字符。 #### 使用R2C SDK接入机器人 当前R2C SDK已内置有SO-ARM101等机械臂的相关配置，请将在CloudRobo平台下载的配置文件放置到r2c_sdk_python/config目录下，可快速接入机械臂。 1. 进入r2c_sdk_python目录下。 2. 进入conda的lerobot环境。 ``` conda activate lerobot ``` 3. 配置so101机械臂参数。 1. 查看Follower臂的port并记录。 ``` lerobot-find-port ``` 请根据界面提示拔出Follower臂USB信号线并在界面单击"Enter"键，可查看到Follower臂的端口号。 linux系统下，端口类似： ``` /dev/ttyACM0 ``` windows系统下，端口类似： ``` COM1 ``` 2. 查看相机的设备号并记录。在当前运行命令的路径下会生成outputs/captured_images文件夹，可查看图片确定相机对应端口号。 ``` lerobot-find-cameras opencv ``` linux系统下，端口类似： ``` /dev/video0 ``` windows系统下，端口类似： ``` 0 ``` 3. 在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 ``` 4. 执行如下命令完成机器人接入。 ``` python -m r2c_sdk.cloudroboclient --bundle config/配置文件名.zip --robot-config config/robot_so101_lerobot_config.yaml ``` 如无报错，即表示机器人接入CloudRobo平台成功，在CloudRobo平台的机器人列表页，可查看到该机器人状态变为在线。 #### 真机调试说明 - 使用智能体调试真机时，模型服务需处于运行中状态，机器人需在线。 - 同一本体，支持切换不同的模型服务进行技能调试，方便您选择效果更优的模型服务。 - 部分模型仅支持执行固定的模型技能，不支持泛化技能；其他模型可执行泛化技能，您可根据需要输入需要执行的Prompt，验证模型的泛化性。 #### 部署模型服务 1. 单击导航栏"运行管理-模型部署"，进入模型部署作业管理页面，单击右上角"部署模型服务"按钮，开始创建任务。 2. 输入基础信息，选择部署SO101可使用的模型（如LeRobot-ACT-把笔插进笔筒-so101真机），并选择资源配置，单击立即部署。在模型部署界面可单击刷新按钮，等待模型服务部署完成。 图6部署在线模型服务 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002631024456.png "点击放大") #### 调试模型技能 1. 在机器人界面，选择状态为在线的SO-ARM101机械臂，单击"智能体调试"，进入技能调试界面。 图7技能调试界面 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002661118021.png "点击放大") 2. 单击选择模型技能，选择处于运行中的模型服务，如LeRobot-ACT-把笔插进笔筒-so101真机，技能选择把笔插进笔筒，单击确定。 3. 在智能体调试界面，单击发送按钮，开始技能调试。 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/public_sys-resources/note_3.0-zh-cn.png) 模型推理的默认步数为60 steps。如果已经达到最大推理的步数，但实际任务并未完成，您可重新发送Prompt，会重新执行任务。您也可以在参数配置中适当调大技能最大推理步数。该参数调整后仅对该机器人和当前选择的模型服务生效。 #### 切换模型服务 在智能体界面底部，可单击模型服务名称，切换其他模型服务来验证模型技能。您可记录两个模型的执行结果。 图8切换模型服务 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002622907253.png "点击放大") #### 执行泛化技能 在选择模型服务和模型技能时，如模型技能中有泛化技能选项，表示该模型支持自定义prompt执行泛化技能。 图9执行泛化技能 ![](https://support.huaweicloud.com/bestpractice-cloudrobo/figure/zh-cn_image_0000002622907231.png "点击放大") 选择泛化技能后，在输入框中可自定义输入Prompt，验证模型的泛化性。