写给只会 Python 的初学者:本文不要求任何硬件/机器人知识,用通俗比喻解读每一行代码在做什么。
一、整体流程概览
这个 Notebook 演示了一个完整的**具身智能(Embodied AI)**控制流程:
环境配置 → 加载策略模型 → 创建仿真环境 → 单步测试 → 闭环控制循环 → 录制视频 → 数据分析通俗理解:就像教一只机器狗学会走路。我们不直接控制每个关节怎么动,而是给它一个"大脑"(策略模型),告诉它"往前走"、“左转”、“停下”,让它自己决定每个关节该怎么动。
二、逐步骤解读
步骤 1:环境配置与依赖检查
importosimportsysimportsubprocessfrompathlibimportPathfromimportlib.utilimportfind_specfromimportlib.metadataimportversion专业库解读:
| 库/模块 | 通俗解释 |
|---|---|
os/sys | Python 标准库,用来获取操作系统和 Python 环境信息 |
subprocess | 用来在 Python 里执行命令行指令,就像你在终端里敲命令 |
pathlib.Path | 处理文件路径的现代方式,比传统的字符串拼接更安全 |
importlib.util.find_spec | 检查某个 Python 包是否已安装 |
importlib.metadata.version | 查看已安装包的版本号 |
这段代码在做什么:
- 检查
mujoco、onnxruntime、numpy等关键依赖是否安装 - 打印版本号,确保环境配置正确
- 创建输出目录
outputs/control_helloworld/,用来存放后面生成的视频和数据
通俗比喻:就像做菜前先检查厨房有没有锅碗瓢盆和食材。
步骤 2:加载策略模型(Policy)
POLICY=prepare_policy()print("行走模型已就绪,SHA-256:",sha256(POLICY))专业概念解读:
| 概念 | 通俗解释 |
|---|---|
| 策略(Policy) | 机器狗的"大脑"。它是一个训练好的神经网络,输入是机器狗当前的状态(姿势、速度等),输出是每个关节应该动到什么位置 |
| ONNX | 一种通用的模型格式,就像 PDF 文档可以在不同设备上打开一样,ONNX 模型可以在不同框架下运行 |
| SHA-256 | 文件的"指纹",用来验证模型文件是否完整、没有被篡改 |
通俗比喻:策略模型就像一本"走路秘籍",机器狗遇到不同情况时翻这本秘籍,就知道该怎么动了。
步骤 3:创建仿真环境
sim=WalkingSimulation(PLAYGROUND,POLICY)print("模型输入:",[(x.name,x.shape)forxinsim.session.get_inputs()])print("模型输出:",[(x.name,x.shape)forxinsim.session.get_outputs()])专业库/概念解读:
| 概念 | 通俗解释 |
|---|---|
| MuJoCo | 一个物理仿真引擎,用来模拟真实世界的物理规律(重力、摩擦力、碰撞等)。就像游戏引擎,但更注重物理真实性 |
| WalkingSimulation | 自定义的封装类,把 MuJoCo 仿真器、策略模型、渲染器等打包成一个好用的对象 |
| session.get_inputs() | 查看策略模型"需要什么信息"(输入) |
| session.get_outputs() | 查看策略模型"会给出什么结果"(输出) |
模型输入/输出解读:
- 输入:机器狗当前的状态(关节角度、速度、身体姿态等),共 51 个数字
- 输出:14 个关节的目标位置,告诉机器狗每个关节应该转到什么角度
通俗比喻:仿真环境就像一个"虚拟训练场",机器狗在这里练习走路,摔倒了也不会真的损坏。
步骤 4:单步测试 —— 观测 → 推理 → 执行
sim.stop()observation=sim.observation()action=sim.session.run([sim.output_name],{sim.input_name:observation})[0]target=sim.apply_action(action)for_inrange(4):mujoco.mj_step(sim.model,sim.data)专业函数解读:
| 函数/方法 | 通俗解释 |
|---|---|
sim.stop() | 发送"停止"命令,此时速度指令为 [0, 0, 0],表示不走动、不转向 |
sim.observation() | 获取机器狗当前的"感知":关节角度、速度、身体姿态等 51 个数字 |
sim.session.run() | ONNX Runtime 的核心方法:把观测数据喂给策略模型,得到动作指令 |
sim.apply_action() | 把策略输出的 14 个关节目标应用到仿真器 |
mujoco.mj_step() | MuJoCo 的核心方法:推进仿真时间一步,计算物理效果(重力、碰撞等) |
为什么循环 4 次mj_step?
- 策略模型每秒运行 25 次(25Hz)
- MuJoCo 仿真每秒运行 100 次(100Hz)
- 所以每次策略推理后,需要推进 4 步仿真(100 ÷ 25 = 4)
通俗比喻:
- 观测:机器狗"感觉"自己现在的姿势
- 推理:翻"走路秘籍",决定下一步怎么动
- 执行:把关节转到目标位置
- 仿真推进:让物理引擎计算重力、摩擦力等效果,看看新姿势是否稳定
步骤 5:闭环控制循环
VIDEO_PATH=OUTPUT/"microduck_forward_turn_stop.mp4"writer=imageio.get_writer(VIDEO_PATH,fps=50,codec="libx264",...)trace=[]defrun_for_seconds(seconds,phase,realtime=False):steps=round(seconds/sim.control_dt)forstepinrange(steps):obs=sim.observation()actions=sim.session.run(...)[0]sim.data.ctrl[:]=sim.default_pose+sim.action_scale*actions[0]for_inrange(4):mujoco.mj_step(sim.model,sim.data)trace.append({...})frame=sim.render()writer.append_data(frame)专业概念解读:
| 概念 | 通俗解释 |
|---|---|
| 闭环控制(Closed-loop Control) | 每一步都先"观测当前状态"→"决策"→"执行"→"再观测",形成循环。就像人走路时不断调整平衡 |
| imageio | Python 的图像处理库,用来把每一帧画面合成视频 |
| fps=50 | 每秒 50 帧,视频播放速度 |
| libx264 | H.264 视频编码格式,常见的 MP4 编码 |
| trace | 记录每一步的数据(时间、位置、速度、关节角度等),用于后续分析 |
run_for_seconds函数在做什么:
- 计算需要运行多少步(秒数 ÷ 每步时间)
- 每一步:
- 读取当前观测
- 策略推理得到动作
- 应用到仿真器
- 推进物理仿真
- 记录状态到 trace
- 渲染画面并写入视频
- 如果机器人失稳(高度太低或身体太倾斜),立即停止并报错
通俗比喻:就像让机器狗按指令走一段时间,同时用摄像机记录全过程,并记下每一步的详细数据。
步骤 6:三段式演示 —— 站稳 → 前进 → 左转 → 停止
# 阶段 1:站稳sim.stop()run_for_seconds(1.0,"settle")# 阶段 2:前进sim.forward(speed=0.30)run_for_seconds(4.0,"forward")# 阶段 3:左转sim.turn(yaw_rate=0.50)run_for_seconds(3.0,"turn_left")# 阶段 4:停止sim.stop()run_for_seconds(3.0,"stop")控制命令解读:
| 命令 | 参数 | 通俗解释 |
|---|---|---|
sim.stop() | 无 | 速度指令 [0, 0, 0]:不走动、不横向移动、不转向 |
sim.forward(speed=0.30) | speed=0.30 m/s | 速度指令 [0.30, 0, 0]:以 0.3 米/秒的速度前进 |
sim.turn(yaw_rate=0.50) | yaw_rate=0.50 rad/s | 速度指令 [0, 0, 0.50]:以 0.5 弧度/秒的速度左转(约 28.6 度/秒) |
速度指令的三个分量:
- vx:前后速度(正=前进,负=后退)
- vy:左右速度(正=左移,负=右移)
- yaw_rate:转向速度(正=左转,负=右转)
通俗比喻:就像遥控玩具狗,你按"前进"、“左转”、"停止"按钮,机器狗的策略模型会自动决定每个关节该怎么配合。
步骤 7:数据分析与验证
report=save_report(OUTPUT/"control_report.json",trace,POLICY)assertreport["phases"]["forward"]["dx_m"]>0.3assertreport["phases"]["turn_left"]["yaw_change_rad"]>0.3assertreport["phases"]["stop"]["last_second_mean_abs_vx_m_s"]<0.08验证逻辑解读:
| 断言 | 通俗解释 |
|---|---|
dx_m > 0.3 | 前进阶段确实移动了超过 0.3 米 |
yaw_change_rad > 0.3 | 左转阶段确实转了超过 0.3 弧度(约 17 度) |
last_second_mean_abs_vx_m_s < 0.08 | 停止阶段最后 1 秒的平均速度小于 0.08 m/s,说明确实停下来了 |
通俗比喻:就像考试后的检查环节,验证机器狗是否真的按要求完成了动作。
步骤 8:可视化图表
importmatplotlib.pyplotasplt t=np.asarray([row["time_s"]forrowintrace])fig,axes=plt.subplots(3,1,figsize=(9,7),sharex=True)axes[0].plot(t,[row["command"][0]forrowintrace],label="command vx",linestyle="--")axes[0].plot(t,[row["vx_m_s"]forrowintrace],label="measured vx")专业库解读:
| 库 | 通俗解释 |
|---|---|
| matplotlib | Python 最常用的绘图库,类似 MATLAB 的绘图功能 |
| plt.subplots(3, 1) | 创建 3 行 1 列的子图布局 |
| plot() | 绘制折线图 |
三张图分别展示:
- 速度对比图:虚线是"指令速度",实线是"实际速度",看机器狗是否跟上了指令
- 朝向变化图:展示机器狗转了多少角度
- 位置轨迹图:展示机器狗在 X-Y 平面上的移动轨迹
通俗比喻:就像汽车的仪表盘,实时显示速度、方向和位置。
步骤 9:保存 GIF 和视频
ASSETS=TOPIC/"01-任务资料/07-RDK端侧与网页部署/assets/hello_world"GIF_PATH=save_gif(VIDEO_PATH,ASSETS/"forward_turn_stop.gif")display(Video("outputs/control_helloworld/microduck_forward_turn_stop.mp4",...))专业概念解读:
| 概念 | 通俗解释 |
|---|---|
| GIF | 动态图片格式,适合在网页/文档中展示简短动画 |
| MP4 | 标准视频格式,画质更好,适合完整记录 |
| RDK | 瑞芯微(Rockchip)的开发套件,这段代码把生成的素材复制到部署目录,方便后续在硬件上展示 |
三、核心概念总结
1. 什么是"策略(Policy)"?
策略就是一个从状态到动作的映射函数:
策略(当前状态) → 关节目标位置这个策略是通过强化学习训练出来的。训练时,机器狗在仿真环境中尝试各种动作,走得远就奖励,摔倒就惩罚,经过数百万次尝试后学会了走路。
2. 什么是"闭环控制"?
观测 → 决策 → 执行 → 再观测 → 再决策 → 再执行 → ...就像人走路:眼睛看路(观测)→ 大脑决定迈哪只脚(决策)→ 腿执行(执行)→ 再看路是否走偏了(再观测)…
3. 为什么用仿真而不是真机?
| 仿真 | 真机 |
|---|---|
| 摔倒了不会损坏 | 摔倒了可能坏 |
| 可以加速运行 | 受限于物理时间 |
| 可以无限次重置 | 电池会耗尽 |
| 成本低 | 成本高 |
仿真验证通过后,再把策略部署到真机上。
4. MuJoCo 是什么?
MuJoCo(Multi-Joint dynamics with Contact)是一个物理仿真引擎,能精确模拟:
- 重力
- 关节运动
- 碰撞和摩擦
- 柔体和刚体
它被广泛用于机器人研究和强化学习训练。
5. ONNX Runtime 是什么?
ONNX(Open Neural Network Exchange)是一种通用的模型格式。ONNX Runtime 是运行 ONNX 模型的引擎,特点是:
- 跨平台(Windows/Mac/Linux/手机/嵌入式)
- 高效(针对各种硬件优化)
- 轻量(不需要安装 PyTorch/TensorFlow 等训练框架)
四、关键参数速查表
| 参数 | 值 | 含义 |
|---|---|---|
| 策略频率 | 25 Hz | 每秒做 25 次决策 |
| 仿真频率 | 100 Hz | 每秒推进 100 步物理仿真 |
| 关节数 | 14 | MicroDuck 有 14 个可控关节 |
| 观测维度 | 51 | 策略输入 51 个数字 |
| 动作维度 | 14 | 策略输出 14 个关节目标 |
| 前进速度 | 0.30 m/s | 约每秒 30 厘米 |
| 转向速度 | 0.50 rad/s | 约每秒转 28.6 度 |
总结:这个 Notebook 展示了具身智能的核心流程:感知 → 决策 → 执行 → 反馈。你不需要懂电机、减速器、传感器等硬件知识,只需要理解策略模型的输入输出,就能让机器狗完成各种动作。这就是现代具身智能的魅力:用软件定义硬件行为。