第 03 课 · 装好工具箱:git、uv 和第一个里程碑

这一课解决什么问题:在自己的电脑上跑通官方现成策略——不需要 GPU,一个下午够。这是阶段 B 的第一个里程碑:从此鸭子不只活在浏览器里,活在你机器上。

前置:第 02 课。需要一台 Mac/PC、稳定网络和命令行。

1. 为什么是 uv,不是 pip

uv 是一个 Python 包管理器——管的事和 pip 一样(装依赖),但用法更省心。最直接的理由只有一条:官方项目用它管理一切依赖,照官方的来,少发明环节。两个高频命令:

uv sync:按项目里的依赖清单,自动建好虚拟环境并装齐所有包,版本精确对齐;
uv run xxx:在这个项目自己的环境里运行某个命令——你不用手动"激活环境",它替你进。

类比:pip 像自己拿着购物清单满超市找货;uv 像"菜谱 + 配好的一整箱食材"——照着官方菜谱做,出错概率最小。

git 这里只干两件事:把仓库下载到本地(git clone),以及固定版本(git checkout 某个 commit)。第二件事很多新手忽略,但它决定你的实验能不能复现。

2. Clone 哪两个仓库

git clone https://github.com/pollen-robotics/microduck_rl
git clone https://github.com/pollen-robotics/microduck

分工:microduck_rl 是训练与仿真仓(阶段 B 的主角,训练、回放、导出都在这里敲);microduck 是官方运行时仓,自带训练好的策略文件(如 policies/alpha_walking.onnx)——你第一步要跑的"现成大脑"就在里面。

要做正式实验就固定到 OpenMicroDuck 校对过的基线 commit:

cd microduck_rl && git checkout 29e887ecfbf5d37144759e5a9f8a176dfb83d547
cd ../microduck  && git checkout 2c61dcc1f03440541cdc0729f7a375b2a9ea3005

平时探索可以跟最新分支,但发表或对比结果时必须记录 commit——这是这门课"结论必须有出处"铁律的技术版。

3. 装依赖(第一次会比较久)

cd microduck_rl
export UV_HTTP_TIMEOUT=600   # 依赖多,防下载超时
uv sync

第一次会下载很多东西,属正常,喝口水。关键认知:这一步只是 CPU 推理的依赖,不需要训练 GPU——没有 N 卡的 Mac 用户全程无障碍。

4. 第一个里程碑:跑通现成策略

uv run scripts/infer_policy.py \
  --walking   ../microduck/policies/alpha_walking.onnx \
  --standing  ../microduck/policies/alpha_stand.onnx \
  --sitstand  ../microduck/policies/alpha_sitstand.onnx \
  --roulade   ../microduck/policies/roulade.onnx \
  --new-cmd-obs

会弹出 MuJoCo 视窗,鸭子按你的指令走、站、翻滚。默认走 BAM 执行器模型(比理想电机更接近真机舵机的仿真方式,第 15 课会回扣)。

5. 验收标准:不是"会动"就算

教程原话的要求,逐条核对:

MJCF(机器人身体文件)加载成功;
ONNX(策略文件)加载成功;
61 维观测被正确接受,14 维动作顺序没错;
机器人不是因接口错误而崩——是自己在动,不是报错前的抽搐;
你记录了 commit 和实际命令。

"看起来挺可爱、会走了"不是技术验收标准——"跑起来了"和"跑对了"是两回事。

6. 训练环境自检(还不是真训练)

再跑一次 5 迭代冒烟,确认训练链路也是通的:

uv run train Mjlab-Velocity-Flat-MicroDuck --env.scene.num-envs 64 --agent.max-iterations 5

它只验证:环境能构建、能 step、没有 NaN、观测和奖励正常。**过了它,你的仿真 + 训练环境才算搭好。**具体每个参数什么意思、Mac 上的两个坑,第 05 课展开。

动手练习(30–45 分钟)

完整跑一遍第 2–4 步,然后写四行记录:两个 commit 号、你敲的命令、屏幕上发生了什么、一句话结论。这四行就是你实验日志的第一页——以后每课都这么记。

自查清单

[ ] 我能说清 uv sync 和 uv run 各干什么
[ ] 我知道 clone 了哪两个仓库、各自的分工
[ ] 我的鸭子在本地 MuJoCo 视窗里按指令走起来了
[ ] 我能背出 5 条验收标准,而不是只看"会动"

全部打勾,进入第 04 课:61 → 14。

下一课预告

第 04 课拆解你刚跑起来的这个"大脑":61 维观测由什么组成、14 维动作怎么排、50 Hz 控制环怎么转——以及为什么这套数字契约一个都不能乱动。

延伸资源

进阶学习文档第 1 节(本课命令的出处):docs/进阶学习文档-训练仿真与部署.md
OpenMicroDuck《先做仿真》完整教程:open-microduck/docs/zh-CN/getting-started/simulation-first.md
卡住了先别慌:第 07 课整课讲排错;也可先查 open-microduck/docs/zh-CN/getting-started/troubleshooting.md

什么鸭 WHATDUCK · 复刻学习笔记 ← 全部手册 · 首页