具身智能入门：用 Python 让 MicroDuck 机器狗学会走路

写给只会 Python 的初学者：本文不要求任何硬件/机器人知识，用通俗比喻解读每一行代码在做什么。

---

一、整体流程概览

这个 Notebook 演示了一个完整的**具身智能（Embodied AI）**控制流程：

环境配置 → 加载策略模型 → 创建仿真环境 → 单步测试 → 闭环控制循环 → 录制视频 → 数据分析

通俗理解：就像教一只机器狗学会走路。我们不直接控制每个关节怎么动，而是给它一个"大脑"（策略模型），告诉它"往前走"、"左转"、"停下"，让它自己决定每个关节该怎么动。

---

二、逐步骤解读

步骤 1：环境配置与依赖检查

import os
import sys
import subprocess
from pathlib import Path
from importlib.util import find_spec
from importlib.metadata import version

专业库解读：

库/模块	通俗解释
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) for x in sim.session.get_inputs()])
print("模型输出:", [(x.name, x.shape) for x in sim.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 _ in range(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）

通俗比喻：

1. 观测：机器狗"感觉"自己现在的姿势
2. 推理：翻"走路秘籍"，决定下一步怎么动
3. 执行：把关节转到目标位置
4. 仿真推进：让物理引擎计算重力、摩擦力等效果，看看新姿势是否稳定

---

步骤 5：闭环控制循环

VIDEO_PATH = OUTPUT / "microduck_forward_turn_stop.mp4"
writer = imageio.get_writer(VIDEO_PATH, fps=50, codec="libx264", ...)
trace = []

def run_for_seconds(seconds, phase, realtime=False):
    steps = round(seconds / sim.control_dt)
    for step in range(steps):
        obs = sim.observation()
        actions = sim.session.run(...)[0]
        sim.data.ctrl[:] = sim.default_pose + sim.action_scale * actions[0]
        for _ in range(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 函数在做什么：

1. 计算需要运行多少步（秒数 ÷ 每步时间）
2. 每一步：
   • 读取当前观测
   • 策略推理得到动作
   • 应用到仿真器
   • 推进物理仿真
   • 记录状态到 trace
   • 渲染画面并写入视频
3. 如果机器人失稳（高度太低或身体太倾斜），立即停止并报错

通俗比喻：就像让机器狗按指令走一段时间，同时用摄像机记录全过程，并记下每一步的详细数据。

---

步骤 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 度/秒）

速度指令的三个分量：

1. vx：前后速度（正=前进，负=后退）
2. vy：左右速度（正=左移，负=右移）
3. yaw_rate：转向速度（正=左转，负=右转）

通俗比喻：就像遥控玩具狗，你按"前进"、"左转"、"停止"按钮，机器狗的策略模型会自动决定每个关节该怎么配合。

---

步骤 7：数据分析与验证

report = save_report(OUTPUT / "control_report.json", trace, POLICY)
assert report["phases"]["forward"]["dx_m"] > 0.3
assert report["phases"]["turn_left"]["yaw_change_rad"] > 0.3
assert report["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：可视化图表

import matplotlib.pyplot as plt
t = np.asarray([row["time_s"] for row in trace])
fig, axes = plt.subplots(3, 1, figsize=(9, 7), sharex=True)
axes[0].plot(t, [row["command"][0] for row in trace], label="command vx", linestyle="--")
axes[0].plot(t, [row["vx_m_s"] for row in trace], label="measured vx")

专业库解读：

库	通俗解释
matplotlib	Python 最常用的绘图库，类似 MATLAB 的绘图功能
plt.subplots(3, 1)	创建 3 行 1 列的子图布局
plot()	绘制折线图

三张图分别展示：

1. 速度对比图：虚线是"指令速度"，实线是"实际速度"，看机器狗是否跟上了指令
2. 朝向变化图：展示机器狗转了多少角度
3. 位置轨迹图：展示机器狗在 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 展示了具身智能的核心流程：感知 → 决策 → 执行 → 反馈 。你不需要懂电机、减速器、传感器等硬件知识，只需要理解策略模型的输入输出，就能让机器狗完成各种动作。这就是现代具身智能的魅力：用软件定义硬件行为。

附：原始 Notebook 参考

• 📓 00_MuJoCo策略控制_HelloWorld.ipynb --- 在 GitHub 上查看原始 Notebook，可对照代码逐行学习。