# 春晚舞蹈机器人复刻：完整实战记录（2026 版）

本文档记录本仓库从安装、排错到最终可运行的关键步骤，目标是让新同学尽量少踩坑。

视频教程（官网）：https://www.datawhale.cn/learn/content/258/6228

视频教程（B站）：https://www.bilibili.com/video/BV1gBfCBpEEb

视频教学补充:  https://www.bilibili.com/video/BV1mjcXzLEGC/?share_source=copy_web&vd_source=cc2570142da6f3f02e6aba37bd88f313

补充文档:https://my.feishu.cn/docx/OzdvdvZ3LoSUfSxziNCcFWYFnqa?from=from_copylink

## 一、项目目标

- 输入：文本动作描述或已有视频
- 输出：机器人动作（`robot_motion*.pkl`）与可视化（Web/viser/MuJoCo）
- 支持多人轨迹（all tracks）与多机器人 MuJoCo 录制

## 二、核心流程

```text
Prompt / Video -> PromptHMR -> SMPL-X -> GMR -> Robot Motion
```

常用命令：

```bash
python scripts/generate_video.py --model seedance --action "动作序列：角色向前走四步"
python scripts/extract_pose.py --project data/video_001
python scripts/convert_to_robot.py --project data/video_001 --all-tracks
python scripts/visualize.py --project data/video_001 --robot-viser --robot-all
```

## 三、环境安装（推荐）

### 0) 新机器复刻（先做这一步）

```bash
git clone https://github.com/datawhalechina/every-embodied.git
cd every-embodied/07-机器人操作、运动控制/Locomotion/video2robot
cd third_party
# 3. 克隆 GMR 
git clone --depth 1 https://github.com/taeyoun811/GMR.git GMR
# 4. 克隆 PromptHMR 
git clone --depth 1 https://github.com/taeyoun811/PromptHMR.git PromptHMR
cd ..
```

说明：

- 本章节所有命令默认在 `every-embodied/07-机器人操作、运动控制/Locomotion/video2robot` 目录执行。

如果你拿到的是 patch 交付包，再应用 3 个 patch：

```bash
git apply patches/main.patch
git -C third_party/PromptHMR apply ../../patches/prompthmr.patch
git -C third_party/GMR apply ../../patches/gmr.patch
```

然后用 YAML 一键创建环境：

```bash
conda env create -f envs/gmr.yml
conda config --add envs_dirs /root/gpufree-data/conda_envs
# 第一个环境安装在系统盘，第二个安装在数据盘，避免超过磁盘负荷（系统和数据盘分别为30G和50G）
conda env create -f envs/phmr.yml
```

若环境名已存在：

```bash
conda env update -n gmr -f envs/gmr.yml --prune
conda env update -n phmr -f envs/phmr.yml --prune
```



### 1) GMR 环境

```bash
conda create -n gmr python=3.10 -y
conda activate gmr
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot
pip install -e .
# gmr下还需要安装

pip install loop-rate-limiters
pip install smplx
pip install imageio
pip install mink
pip install rich
pip install imageio[ffmpeg]
```

### 2) PromptHMR 环境（4090 场景）

```bash
conda create -n phmr python=3.10 -y
conda activate phmr
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR
# bash scripts/install.sh --pt_version=2.4 不推荐使用默认一键安装，bug较多
```

如果自动安装失败，可用手动方案（见下文“手动配置方案”）。

## 四、Web UI 启动（稳定版）

```bash
conda activate phmr
python -m pip install -U fastapi "uvicorn[standard]" jinja2 python-multipart

pkill -f "video2robot/visualization/robot_viser.py"
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot
export VISER_FIXED_PORT=8789
python -m uvicorn web.app:app --host 0.0.0.0 --port 8000
```

如果在 GPFree 或后台任务中出现 `conda run -n phmr` 找不到环境、无写权限或环境名解析异常，可改用环境绝对路径：

```bash
VISER_FIXED_PORT=8789 /root/gpufree-data/conda_envs/phmr/bin/python -m uvicorn web.app:app --host 0.0.0.0 --port 8000
```

访问：`http://localhost:8000`

启动后建议先用接口确认 Web 服务确实可用，不要只看 `uvicorn` 是否启动：

```bash
curl http://127.0.0.1:8000/health
curl http://127.0.0.1:8000/
curl http://127.0.0.1:8000/api/projects
curl http://127.0.0.1:8000/api/viser/status
```

说明：
- 固定 `VISER_FIXED_PORT` 是为了避免 iframe 随机端口拒绝连接
- Web 已支持中文界面、Seedance、上传视频、铁皮/彩色切换

- 豆包网页端生成机器人视频prompt：帮我生成图片：帮我生成图片：帮我优化prompt，生成中国武术视频，人物需要完全在视频范围内
- 上传视频执行即可，详见视频教程

- 运行时会自动下载一些torch的小模型，如果下载失败，尝试手动
  ```
  mkdir -p /root/.cache/torch/hub/checkpoints && rm -f /root/.cache/torch/hub/v0.10.0.zip.*.partial && wget -O /root/.cache/torch/hub/v0.10.0.zip https://github.com/pytorch/vision/zipball/v0.10.0 && wget -O /root/.cache/torch/hub/checkpoints/deeplabv3_resnet50_coco-cd0a2569.pth https://download.pytorch.org/models/deeplabv3_resnet50_coco-cd0a2569.pth && ls -lh /root/.cache/torch/hub/v0.10.0.zip /root/.cache/torch/hub/checkpoints/deeplabv3_resnet50_coco-cd0a2569.pth
  ```

## 五、多人轨迹与可视化

### 1) 生成多轨机器人动作

```bash
conda activate gmr
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot
python scripts/convert_to_robot.py --project data/video_001 --all-tracks
```

### 2) robot-viser 显示所有轨迹

```bash
python scripts/visualize.py --project data/video_001 --robot-viser --robot-all
```

## 六、MuJoCo 视频导出

### 单机器人

```bash
conda activate gmr
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/GMR
python scripts/vis_robot_motion.py \
  --robot unitree_g1 \
  --robot_motion_path /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/data/video_005/robot_motion.pkl \
  --record_video \
  --video_path /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/data/video_005/mujoco_robot.mp4
```

### 多机器人（新增脚本）

```bash
python scripts/vis_robot_motion_multi.py \
  --robot unitree_g1 \
  --robot_motion_paths \
    /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/data/video_005/robot_motion_track_1.pkl \
    /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/data/video_005/robot_motion_track_2.pkl \
  --record_video \
  --max_seconds 10 \
  --camera_azimuth 0 \
  --video_path /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/data/video_005/mujoco_multi_robot_10s_front.mp4
```

说明：
- 已修复“0秒/超短视频”问题，按帧数严格控制时长
- 已修复“画面只见地面看不到机器人”问题，相机会跟随多机器人中心

## 七、落地难点与 IsaacSim 仿真展望

### 实际落地难点
1. **动作映射精度**：从视频提取的 SMPL-X 姿态到机器人关节的映射（Retargeting）存在物理限制。
2. **环境感知缺失**：目前主要是开环动作复刻，缺乏对实际地面摩擦、碰撞和障碍物的实时反馈。
3. **动力学约束**：视频中的人类动作可能超出机器人的电机扭矩或平衡极限。例如在马年春晚武术机器人表演中，高难度的腾空与受力对伺服响应要求极高。

### IsaacSim 仿真优势
未来我们将引入 **IsaacSim** 进行强化学习训练：
- **优势**：极高的物理仿真精度，支持复杂的碰撞检测、摩擦力模型和传感器仿真。
- **价值**：本项目主要完成“动作映射”，IsaacSim 则负责“动作稳健性训练”。

## 八、常见问题速查与 Debug 记录

### Q1: `conda` 找不到（Web任务秒退）
已在主仓库任务运行器中修复，支持自动探测 `CONDA_EXE`。

### Q2: robot-viser 偶发 `localhost 拒绝连接`
优先使用固定端口：`export VISER_FIXED_PORT=8789`。

### Q3: MuJoCo 录制报 `imageio` backend 缺失
执行：`pip install -U "imageio[ffmpeg]"`。

### Q4: 编译错误（lietorch/droid_backends）
针对 PyTorch 2.4+，需将 `.type()` 修改为 `.scalar_type()`。

### Q5:遇到文件下载不了,在本地进行下载
1. 模型文件阶段（最核心问题）
在运行`python scripts/extract_pose.py --project data/video_001`容易反复遇到的报错本质是同一类：
- invalid load key, 'v'
- UnpicklingError
- weights_only ... Unsupported operand 118
- Cannot load file ... allow_pickle=False
表示下载下来的文件无法正常使用
2.本地下载并验证（示例）

1) 下载（HF 单文件）
```bash
$env:HF_ENDPOINT="https://hf-mirror.com"
$env:HF_HUB_DISABLE_XET="1"

python - << 'PY'
from huggingface_hub import hf_hub_download
p = hf_hub_download(
    repo_id="Datawhale/spring-festival-wushu-robot-replication-model",
    filename="data/pretrain/phmr/checkpoint.ckpt",
    repo_type="model",
    local_dir=r"E:\...\model_tmp",
    force_download=True
)
print("saved:", p)
PY
```
本地运行可能无法正常运行上述python代码,需要另起一个文件
```python
from huggingface_hub import hf_hub_download
p = hf_hub_download(
    repo_id="Datawhale/spring-festival-wushu-robot-replication-model",
    filename="data/pretrain/phmr/checkpoint.ckpt",
    repo_type="model",
    local_dir=r"E:\...\model_tmp",
    force_download=True
)
print("saved:", p)
```
保存为test.py文件 python test.py
2) 本地验证（必须通过）
```python
import torch
p=r"E:\...\model_tmp\data\pretrain\phmr\checkpoint.ckpt"
with open(p,'rb') as f:
    print("first16:", f.read(16))
obj=torch.load(p, map_location='cpu', weights_only=False)
print("torch.load OK:", type(obj))
```
验证标准
- first16 不能是 b'version https://'
- torch.load OK 正常输出
3)服务器验证
和上述验证方法类似

### Q6: `git lfs clone` 很慢或反复失败
优先把长时间下载任务放进 `tmux` 后台，并确认下载目录正确。如果已经下载了半成品，进入对应模型仓库目录执行 `git lfs pull` 续传。国内网络不稳定时可尝试 `hf-mirror.com`，同时确认终端流量确实经过代理；有些代理软件只代理浏览器，不一定自动代理远程终端。

### Q7: Web UI 卡在 96%/99%
这不一定是前端问题。优先检查后端日志、任务进程、模型权重是否完整，以及项目输出文件是否已经生成。多人视频或模型权重缺失时，也可能表现为前端进度长时间不动。

### Q8: GPFree 环境中 `conda run -n phmr/gmr` 失败
如果环境实际位于 `/root/gpufree-data/conda_envs/phmr` 或 `/root/gpufree-data/conda_envs/gmr`，可使用绝对路径执行：

```bash
conda run -p /root/gpufree-data/conda_envs/phmr ...
conda run -p /root/gpufree-data/conda_envs/gmr ...
```


## 九、仓库组织建议（并入主仓，废弃旧仓）

建议将 `video2robot` 作为主仓内普通目录维护，不再使用 submodule（这是当前唯一推荐方案）。

原因：
- 旧仓 `hope5hope/video2robot` 即将废弃，继续 submodule 会增加失效风险。
- 团队希望“教程与代码同仓”，降低新同学切换仓库的成本。
- 后续修改可直接在主仓提交、评审和发布。


### 记录基线 commit
- 主仓库：`030f3410dac3cb15a2570376dca6a0f46c2d158c`
- PromptHMR：`4f8915c5b9603344c56e95fadb9a01a23ba2272d`
- GMR：`069b4fd48f440e813b2b4d69255c70f53e5f83fb`

## 十、仓库状态说明
`hope5hope/video2robot` 作为历史仓保留参考，不再作为主开发与交付仓库。

## 十一、YAML 导出与跨机复刻说明

在“源机器”导出：

```bash
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot
mkdir -p envs
conda env export -n gmr > envs/gmr.yml
conda env export -n phmr > envs/phmr.yml
```

在“目标机器”导入：

```bash
git clone https://github.com/datawhalechina/every-embodied.git
cd every-embodied/07-机器人操作、运动控制/Locomotion/video2robot
conda env create -f envs/gmr.yml
conda env create -f envs/phmr.yml
```

再应用 3 个 patch（如你的复刻依赖本地改动）：

```bash
git apply patches/main.patch
git -C third_party/PromptHMR apply ../../patches/prompthmr.patch
git -C third_party/GMR apply ../../patches/gmr.patch
```

说明：
- YAML 不会自动带上“未提交源码改动”和“模型权重文件”。
- 因此推荐：`YAML + patch + 模型下载脚本` 三件套一起交付，复刻成功率最高。

---

## 附录：手动配置方案参考(phmr环境)

```bash
# Clone main repo
git clone https://github.com/datawhalechina/every-embodied.git
cd every-embodied/07-机器人操作、运动控制/Locomotion/video2robot


conda create -n phmr python=3.10 -y
conda activate phmr
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR
pip install -r requirements.txt

mkdir -p python_libs
git clone https://github.com/Arthur151/chumpy python_libs/chumpy
python -m pip install -e python_libs/chumpy --no-build-isolation

# 在 bashrc 中加入
export PYTHONPATH=$PYTHONPATH:/root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR
echo 'export PYTHONPATH=$PYTHONPATH:/root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR' >> ~/.bashrc
source ~/.bashrc


conda install -c conda-forge eigen -y

# export CPATH="$CONDA_PREFIX/include/eigen3:${CPATH:-}" && cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR/pipeline/droidcalib && python setup.py install
# 编译droidcalib
source /opt/conda/etc/profile.d/conda.sh
conda activate phmr

conda install -c conda-forge eigen -y
export CPATH="$CONDA_PREFIX/include/eigen3:${CPATH:-}"

cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR/pipeline/droidcalib
python setup.py install

export LD_LIBRARY_PATH="/root/gpufree-data/conda_envs/phmr/lib/python3.10/site-packages/torch/lib:/usr/lib/x86_64-linux-gnu:/usr/local/cuda/lib64:/usr/lib64:/usr/local/lib"
# 上面这个加到bashrc

echo 'export LD_LIBRARY_PATH="/root/gpufree-data/conda_envs/phmr/lib/python3.10/site-packages/torch/lib:/usr/lib/x86_64-linux-gnu:/usr/local/cuda/lib64:/usr/lib64:/usr/local/lib"' >> ~/.bashrc
source ~/.bashrc

# 编译 lietorch
mkdir -p python_libs
cd python_libs
git clone https://github.com/princeton-vl/lietorch.git
cd lietorch
git submodule update --init --recursive
python setup.py install
cd ../..

# 安装 detectron2
git clone https://github.com/facebookresearch/detectron2.git
cd /root/gpufree-data/detectron2
pip install -e . --no-build-isolation

# 安装 SAM2
git clone https://github.com/facebookresearch/segment-anything-2.git
cd segment-anything-2
pip install -e . --no-build-isolation

# 适配代码
sed -i 's/load_video_frames, load_video_frames_from_np/load_video_frames/g' /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR/pipeline/detector/sam2_video_predictor.py

补充pip包

python -m pip install -U torch-scatter --no-build-isolation #这个命令运行较久，请耐心等待
python -m pip install -U xformers
```



更新一下下载脚本：
https://github.com/hope5hope/video2robot/blob/main/%E6%96%87%E4%BB%B6%E6%9B%B4%E6%96%B0%E8%AF%B4%E6%98%8E.md

下载相关模型权重（推荐方案）：
```bash
git-lfs install
git lfs clone https://huggingface.co/Datawhale/spring-festival-wushu-robot-replication-model
或者国内镜像
git lfs clone https://hf-mirror.com/Datawhale/spring-festival-wushu-robot-replication-model
```

大模型下载时间较长，推荐放到 `tmux` 后台执行，避免终端断开导致下载中断。下载前也要确认当前目录是：

```bash
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR
tmux new-session -d -s phmr_lfs_download 'git lfs clone https://hf-mirror.com/Datawhale/spring-festival-wushu-robot-replication-model'
tmux attach -t phmr_lfs_download
```

如果仓库已经下载了一部分但 LFS 文件不完整，不要直接删除重下，可进入模型仓库目录后续传：

```bash
git lfs pull
```

下载相关模型权重（替代方案）：
```bash
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot/third_party/PromptHMR
bash scripts/fetch_smplx.sh
bash scripts/fetch_data.sh
```

注意：`fetch_smplx.sh` 不是只下载 SMPL-X。脚本还会下载 SMPL 和 supplementary files。仅看到 `data/body_models/smplx/SMPLX_NEUTRAL.npz` 存在，不代表全部模型文件已经完成。

### 合并 Patch 命令（快速同步改动）
如果你是在原始仓库基础上进行同步，可以使用以下命令合并补丁：

```bash
cd /root/gpufree-data/every-embodied/07-机器人操作、运动控制/Locomotion/video2robot

# 1. 确保子模块已初始化
git submodule update --init --recursive

# 2. 应用主仓库补丁
git apply patches/main.patch

# 3. 应用 PromptHMR 补丁
git -C third_party/PromptHMR apply ../../patches/prompthmr.patch

# 4. 应用 GMR 补丁
git -C third_party/GMR apply ../../patches/gmr.patch
```