File size: 18,284 Bytes

b66bfc4

# CoDiffAct：公开模型下载、路径配置与纯环境镜像

## 1. 交付范围

环境镜像只含 Python、PyTorch/CUDA用户态库、F5-TTS等已安装软件包、音视频/OSMesa运行库和兼容修复。**不含项目源码、第三方仓库、预训练模型、本项目断点、SMPL-X/FLAME资产、数据集、HF密钥或用户缓存。**代码、模型和数据在运行时单独挂载。

- 镜像平台：Linux x86_64（linux/amd64）；不是ARM/Mac原生GPU镜像。
- Python 3.12.11、PyTorch/torchaudio 2.7.1+cu128、CUDA 12.8、NumPy 2.1.3、transformers 4.51.3、tokenizers 0.21.4、F5-TTS 1.1.22。
- 版本、文件哈希和兼容修复清单放在镜像的 `/opt/codiffact/`。这是当前已安装环境的固定前缀快照，不声称仅凭 `pip install -r requirements.snapshot.txt` 就能重建所有二进制。
- 本文截至2026-10-06核对了下列HF仓库及文件元数据。公开可下载不等于任意商业使用/再分发；保留各项目许可证。SMPL-X/FLAME按使用者取得的授权单独准备，本镜像不打包这些资产。
- Gelina及其需要编译的可选子项目未纳入主链镜像的功能保证；不要把整个 `third_party/*/requirements*` 混装，旧环境要求相互冲突。

## 2. 第三方源码

项目的 `.gitignore` 当前忽略 `third_party/`，只克隆主仓库不会自动取得它们。已有目录不能直接覆盖；新环境可以分别克隆以下项目，并尽量固定到本次使用的版本：

| 目标目录 | 上游 | 本次本地HEAD |
|---|---|---|
| `third_party/HY-Motion-1.0` | https://github.com/Tencent-Hunyuan/HY-Motion-1.0 | `4e426f5a1021cbcf7f375458c37b840ee7225229` |
| `third_party/DiffPoseTalk` | https://github.com/DiffPoseTalk/DiffPoseTalk | `2c761f174776ffe380cd89b875fc8eb49e90a5a1` |
| `third_party/EMAGE` | https://github.com/PantoMatrix/PantoMatrix | `c7356f35f8e39e469e510ccd1bf37e44adf8ec0e` |
| `third_party/Gelina`（可选） | https://github.com/TGuichoux/Gelina | `bd50c64661498855b41300fa3d3b983819d0175a` |

例如在项目根目录执行：

```bash
git clone https://github.com/Tencent-Hunyuan/HY-Motion-1.0.git third_party/HY-Motion-1.0
git -C third_party/HY-Motion-1.0 checkout 4e426f5a1021cbcf7f375458c37b840ee7225229
git clone https://github.com/DiffPoseTalk/DiffPoseTalk.git third_party/DiffPoseTalk
git -C third_party/DiffPoseTalk checkout 2c761f174776ffe380cd89b875fc8eb49e90a5a1
git clone https://github.com/PantoMatrix/PantoMatrix.git third_party/EMAGE
git -C third_party/EMAGE checkout c7356f35f8e39e469e510ccd1bf37e44adf8ec0e
```

这些是本地HEAD记录，不是已验证能从公网按SHA获取的保证；若上游不含该SHA，应另行导出当前源码/patch，不能静默替换成最新版后声称完全复现。本次HY工作树的 `stats/Mean.npy`、`stats/Std.npy`、`scripts/gradio/static/assets/dump_wooden/*.bin` 与HEAD有差异：其中包含Git LFS实体文件/本地资源，需按实际资产核对，不只拷贝LFS指针。进入第三方仓库后按它的LFS规则下载资源。

F5-TTS来自已安装的 `f5_tts` 包，不是此处的Git子仓库。镜像保留实际安装版本及包内容；本地兼容修复记录见环境清单。主仓库内 `third_party/syncnet` / `third_party/emage_evaltools` 若入口仍引用，也需保留源码，但不要将模型文件写进环境镜像。

## 3. 公开模型清单

建议模型统一挂载至 `/models`；下面的子目录名是本文约定。

| 用途 | 来源 | 所需文件 / 配置 |
|---|---|---|
| 动作骨干 | https://huggingface.co/tencent/HY-Motion-1.0 | `HY-Motion-1.0-Lite/config.yml`、`latest.ckpt`；`hy_config`、`hy_ckpt` |
| 自定义caption编码 | https://huggingface.co/Qwen/Qwen3-8B | 配置、tokenizer、safetensors索引及全部5个分片 |
| caption句向量 | https://huggingface.co/openai/clip-vit-large-patch14 | 配置、tokenizer及一套PyTorch/safetensors权重，不必重复下TF/Flax权重 |
| 语音骨干 | https://huggingface.co/SWivid/F5-TTS | `F5TTS_v1_Base/model_1250000.safetensors`、`vocab.txt`；`f5_ckpt_dir` |
| 声码器 | https://huggingface.co/charactr/vocos-mel-24khz | `config.yaml`、`pytorch_model.bin`；`vocos_ckpt_dir` |
| DPT音频编码器 | https://huggingface.co/facebook/hubert-base-ls960 | 模型、config、preprocessor_config，按HF缓存方式下载 |
| EMAGE基线（可选） | https://huggingface.co/H-Liu1997/emage_audio | 根模型及 `emage_vq/{face,upper,lower,hands,global}` 的配置和权重 |
| SyncNet评测（可选） | https://huggingface.co/lithiumice/syncnet | `syncnet_v2.model`；这是镜像仓库，不是官方发布者 |
| 音色评测（可选） | https://huggingface.co/microsoft/wavlm-base-plus-sv | 模型及feature extractor，HF缓存方式 |
| FGD/BC资源（可选） | https://huggingface.co/H-Liu1997/emage_evaltools | `AESKConv_240_100.bin`、`mean_vel_smplxflame_30.npy`；另需其预期SMPL-X资源 |

### 下载示例（有网络时运行；本次没有下载这些权重）

以下用Python API，兼容镜像中的 `huggingface_hub==0.34.4`，不依赖新版CLI参数。`revision`是本次查询的远端版本，**不是本地历史权重哈希证明**。

```python
from pathlib import Path
from huggingface_hub import snapshot_download, hf_hub_download

root = Path('/models')
root.mkdir(parents=True, exist_ok=True)

snapshot_download('tencent/HY-Motion-1.0', revision='620dd559f8d964aac2f82f1204fe6a35ad8ad14d',
                  allow_patterns=['HY-Motion-1.0-Lite/*'], local_dir=root / 'hy')
snapshot_download('SWivid/F5-TTS', revision='84e5a410d9cead4de2f847e7c9369a6440bdfaca',
                  allow_patterns=['F5TTS_v1_Base/model_1250000.safetensors', 'F5TTS_v1_Base/vocab.txt'],
                  local_dir=root / 'f5')
snapshot_download('charactr/vocos-mel-24khz', revision='0feb3fdd929bcd6649e0e7c5a688cf7dd012ef21',
                  allow_patterns=['config.yaml', 'pytorch_model.bin'], local_dir=root / 'vocos')
snapshot_download('Qwen/Qwen3-8B', revision='b968826d9c46dd6066d109eabc6255188de91218',
                  allow_patterns=['*.json', '*.safetensors', '*.txt', '*.jinja'], local_dir=root / 'Qwen3-8B')
snapshot_download('openai/clip-vit-large-patch14', revision='32bd64288804d66eefd0ccbe215aa642df71cc41',
                  allow_patterns=['*.json', '*.txt', 'model.safetensors'], local_dir=root / 'clip-vit-large-patch14')

# 构造DPT时硬编码from_pretrained(repo_id)，需进入同一个HF缓存，而非随意local_dir。
snapshot_download('facebook/hubert-base-ls960',
                  allow_patterns=['*.json', 'pytorch_model.bin'], cache_dir=root / 'hf_cache/hub')

# 只在需要EMAGE时下载。
snapshot_download('H-Liu1997/emage_audio', revision='b04466b83bdebd656844a2c416797d3131e34ede',
                  allow_patterns=['config.json', 'pytorch_model.bin', 'emage_vq/*'],
                  local_dir=root / 'emage_audio')

# 可选评测资源。
hf_hub_download('lithiumice/syncnet', 'syncnet_v2.model', local_dir=root / 'syncnet')
snapshot_download('microsoft/wavlm-base-plus-sv',
                  allow_patterns=['*.json', 'pytorch_model.bin'], cache_dir=root / 'hf_cache/hub')
snapshot_download('H-Liu1997/emage_evaltools',
                  allow_patterns=['AESKConv_240_100.bin', 'mean_vel_smplxflame_30.npy'],
                  local_dir=root / 'emage_evaltools')
```

镜像默认离线。下载阶段启动容器时设置 `-e HF_HUB_OFFLINE=0`；下载完成后恢复 `HF_HUB_OFFLINE=1`，并设置 `HF_HOME=/models/hf_cache`。不要把HF token写入下载脚本或Dockerfile。

### Qwen/CLIP本地查找目录

HY加载时会切换到 `hy_root`；当前 `USE_HF_MODELS=0` 时读该目录下的 `ckpts/Qwen3-8B` 和 `ckpts/clip-vit-large-patch14`。在项目卷中准备到上述 `/models` 子目录的链接，或复制到这两个确切位置。链接目标必须在容器里也可见，不能保留原共享盘绝对目标。

```bash
mkdir -p third_party/HY-Motion-1.0/ckpts
ln -s /models/Qwen3-8B third_party/HY-Motion-1.0/ckpts/Qwen3-8B
ln -s /models/clip-vit-large-patch14 third_party/HY-Motion-1.0/ckpts/clip-vit-large-patch14
```

已有链接请检查后再调整，不覆盖。预计算文本embedding的评测不一定调用两个文本模型；自定义新caption通常需要。

## 4. 非HF官方发布的资源

### Gelina（可选、独立环境）

官方仓库 https://github.com/TGuichoux/Gelina 的README提供权重及必要文件：
https://drive.google.com/file/d/1JnfyYCH0TQ6JpQl1duL6XN4hlj07iYmd/view

按上游结构解压到 `third_party/Gelina/`，并检查 `configs/infer.yaml` / 对应推理配置指向的位置。其Python 3.11、causal-conv1d、Matcha-TTS、WavTokenizer等安装要求不同；本次Python 3.12主链环境镜像不宣称已支持Gelina，需按其README另建环境。链接来自当前本地上游说明，本次未下载或验证整套Gelina推理。

### DiffPoseTalk

官方说明：https://github.com/DiffPoseTalk/DiffPoseTalk 。下载入口：
https://drive.google.com/drive/folders/1pOwtK95u8O1qG_CiRdD8YcvuKSlFEk-b

使用有头部版本 `1-with_head/DPT/head-SA-hubert-WM/checkpoints/iter_0110000.pt`，不要混用无头部或不同迭代版本。保存到 `/models/dpt/...` 并配置完整文件路径。

还需要**匹配这套训练定义的** `stats_train.npz`；当前原文件位于 `/apdcephfs_cq11/share_4502729/dataset/Face_Datasets/HDTF_TFHP-lmdb/stats_train.npz`。请从DPT配套资料获取，或在具备授权时从原环境复制；本次未确认可直接下载它的独立公开URL，不编造链接。该统计量影响脸系数解码，不能换成任意同名文件。

基础调用使用模型内部空style条件，不强制额外下载风格编码器；如果使用DPT原生风格提取流程，另按官方说明获取SE权重。

### SMPL-X / FLAME

- SMPL-X：https://smpl-x.is.tue.mpg.de/ 。本项目需要中性SMPL-X模型；文件名中2020不等于改变内部系数定义。
- FLAME：https://flame.is.tue.mpg.de/ 。下载FLAME2020的 `generic_model.pkl` 和配套 `landmark_embedding.npy`。
- FLAME放在 `third_party/DiffPoseTalk/models/data/FLAME2020/generic_model.pkl`、`third_party/DiffPoseTalk/models/data/landmark_embedding.npy`。基础无纹理渲染无需albedo。
- `smplx.create(model_path=..., model_type='smplx')` 会自动附加 `smplx/SMPLX_NEUTRAL.npz`。例如配置 `smplx_model: /models/body_models/smplx2020/SMPLX_NEUTRAL_2020.npz` 时，需同时提供 `/models/body_models/smplx2020/smplx/SMPLX_NEUTRAL.npz`（可以是指向同一文件的有效链接）。
- HY还使用其自带 `stats/Mean.npy`、`stats/Std.npy` 与 `scripts/gradio/static/assets/dump_wooden/` 网格二进制。不要漏掉上游LFS资产。
- 本项目 `src/hybrid_utils.py` 对加工动作做反归一化时，另读取HY兄弟目录 `third_party/hy_stats/Mean.npy`、`Std.npy`。必须从对应加工数据/原工程一起准备这两个文件；不能未经核对拿HY官方统计量替代。容器里对应 `/app/third_party/hy_stats/`。

### Whisper与评测

ASR评测用OpenAI Whisper `large-v3`，该库从其官方模型下载地址取得 `large-v3.pt`，不是transformers的模型目录。可在有网络阶段用 `whisper.load_model('large-v3', download_root='/models/whisper')` 预取；评测入口中仍有 `/root/.cache/whisper/large-v3.pt` 的历史硬编码，使用前将其显式改为准备好的文件路径。

FGD/BC旧加载代码有独立 `wget` 回退；HF的离线环境变量不阻止它或Whisper urllib。完整评测离线时必须预备文件，缺失应直接报错，不应依赖联网回退。环境镜像未附SyncNet/Whisper/WavLM/FGD模型。

## 5. 本项目训练断点与数据

| 方法 | Stage1 | Adapter |
|---|---|---|
| Ours | `checkpoints/stage1_both/ckpt/stage1_ep049.pt` | `checkpoints/stage2_lip_lip_3c15/ckpt/adapter_ep059.pt` |
| Cascade+FT | `checkpoints/stage1_none/ckpt/stage1_ep049.pt` | 不使用adapter，使用真实音频特征提取器 |
| Ours−bridge | `checkpoints/stage1_none/ckpt/stage1_ep049.pt` | `checkpoints/stage2_lip_3c15_bridge_none/ckpt/adapter_ep059.pt` |

这些是增量断点，不能代替公开专家权重。当前已本地LFS提交，但**GitHub上传仍被认证阻断**；拿到代码不代表远端已有这些对象。可先从原共享目录复制选定断点，或在远端上传完成后执行LFS下载。

BEAT2公开入口 https://huggingface.co/datasets/H-Liu1997/BEAT2 不是本项目加工后的 `Beat2Dataset`。还需已有加工数据、`split.json`、`ref_map.json`及参考语音/台词。`src/run_custom_prompt.py`仍借用数据集参考样本，未改为任意WAV输入。训练另外需要rollout、teacher、SUSU等资源；环境镜像不包含数据，不承诺拉镜像就能从零训练。

## 6. 为容器生成独立配置

保留 `src/config.yml` 的训练/推理超参数，用下面方式生成完整副本，避免覆盖原机器配置。路径是容器内路径；将你有的加工数据放到对应目录。

```python
from pathlib import Path
import yaml
cfg = yaml.safe_load(Path('/app/src/config.yml').read_text())
cfg.update(
    hy_root='/app/third_party/HY-Motion-1.0',
    hy_config='/models/hy/HY-Motion-1.0-Lite/config.yml',
    hy_ckpt='/models/hy/HY-Motion-1.0-Lite/latest.ckpt',
    f5_ckpt_dir='/models/f5/F5TTS_v1_Base',
    vocos_ckpt_dir='/models/vocos',
    dpt_root='/app/third_party/DiffPoseTalk',
    dpt_ckpt='/models/dpt/1-with_head/DPT/head-SA-hubert-WM/checkpoints/iter_0110000.pt',
    dpt_stats='/models/dpt/stats_train.npz',
    syncnet_model='/models/syncnet/syncnet_v2.model',
    smplx_model='/models/body_models/smplx2020/SMPLX_NEUTRAL_2020.npz',
    beat2_hf='/data/beat2_hf', beat2_ref_map='/data/ref_map.json',
    beat2_split='/data/split.json', susu_hf_dataset='/data/susu_hf',
    stage2_rollout_dir='/data/beat2_rollout', stage2_teacher_dir='/data/beat2_teacher_cond',
    result_root='/outputs',
)
Path('/outputs/config.container.yml').write_text(yaml.safe_dump(cfg, sort_keys=False))
```

设置 `CODIFFACT_CONFIG=/outputs/config.container.yml`；未设置时仍读取 `src/config.yml`。另设 `EMAGE_WEIGHTS=/models/emage_audio`。这两项新增的是路径覆盖，不改变训练/推理算法。

不要直接执行有历史硬编码的 `scripts/custom_prompt_demo.py`；优先明确传参给CLI。例如模型和参考数据准备好后：

```bash
python src/run_custom_prompt.py --methods ours --seconds 12 --seed 0 \
  --ref-filename 10_kieks_0_81_81_seg004 \
  --text "It is good to see everyone here today, and before we start I would like to show you a simple example that explains how the whole process works." \
  --caption "A person stands upright and explains with natural hand gestures." \
  --stage1-ckpt /app/checkpoints/stage1_both/ckpt/stage1_ep049.pt \
  --adapter-ckpt /app/checkpoints/stage2_lip_lip_3c15/ckpt/adapter_ep059.pt \
  --out /outputs/demo
```

`configs/eval_tristream.yaml`、部分评测/历史脚本还有独立路径配置，运行对应入口前另行更新。本文没有把它们悄悄批量改写。

## 7. 环境镜像：下载、加载、运行

HF目标：私有模型仓库 https://huggingface.co/liuyibo/codiffact-environment 。这里存的是**Docker save归档文件**，不是可以直接 `docker pull huggingface.co/...` 的通用registry，也不是在线Space。

镜像标签：`codiffact-env:20261006-cu128`。上传完成标记和校验文件见仓库实际内容；未出现镜像文件前不要把目标地址当作已上传完成。

```bash
# 在已完成HF登录的主机上下载归档与校验文件。
hf download liuyibo/codiffact-environment --local-dir ./codiffact-environment
cd codiffact-environment
sha256sum -c SHA256SUMS
cat codiffact-env_20261006-cu128.tar.gz.part-* | gzip -dc | docker load

# 无网络、无任何模型挂载的环境验收。
docker run --rm --network none codiffact-env:20261006-cu128 python /opt/codiffact/smoke_test.py
# 宿主机需有兼容CUDA 12.8的NVIDIA驱动和NVIDIA Container Toolkit。
docker run --rm --network none --gpus all codiffact-env:20261006-cu128 python /opt/codiffact/smoke_test.py --gpu
```

挂载运行示例（先把宿主机路径改成实际路径）：

```bash
docker run --rm -it --gpus all --shm-size 8g --network none \
  -v /absolute/path/hybrid-motion:/app:ro \
  -v /absolute/path/models:/models:ro \
  -v /absolute/path/processed-data:/data:ro \
  -v /absolute/path/output:/outputs \
  -e CODIFFACT_CONFIG=/outputs/config.container.yml \
  -e EMAGE_WEIGHTS=/models/emage_audio \
  codiffact-env:20261006-cu128 bash
```

下载模型阶段需要联网且 `/models` 可写；运行阶段可以只读并断网。GPU驱动、宿主内核、GPU硬件不在镜像内；CUDA用户态库在镜像内。容器内部旧仓库路径有兼容链接到 `/app`，但不会伪造原共享模型/数据路径。

## 8. 本地构建与边界

构建输入见 `docker/environment/`。在原开发机固定环境前缀下准备上下文：

```bash
/opt/conda/envs/hybrid/bin/python docker/environment/prepare_environment.py --out artifacts/env-context
docker build -t codiffact-env:20261006-cu128 artifacts/env-context
```

构建上下文不是整个仓库，只包含净化后的环境归档、Dockerfile、包版本/哈希清单和环境验收脚本。密钥文件已列入 `.gitignore`，不会COPY进入镜像或上传目录。未提交或上传整个Conda工作目录、HF缓存、`.git`或原始项目。

已实测的兼容处理：保留安装环境中的NumPy别名补丁，并在镜像的chumpy包入口补充Python 3.12的 `inspect.getargspec` 兼容；OSMesa/LLVM需要 `GLIBCXX_3.4.30`，因此只在镜像内让Conda的 `libstdc++.so.6` 使用Ubuntu同SONAME的6.0.30版本。没有将libffi不同ABI强行互链，也没有修改宿主Conda。H.264编码使用imageio自带libx264版FFmpeg，系统FFmpeg提供其他工具。

验收只证明依赖导入、CUDA基本运算、无头几何渲染和H.264/AAC正常；**没有在新镜像中重新生成论文全部样本、训练模型或验证所有可选项目**。pyrender声明要求旧PyOpenGL，但当前环境使用兼容的3.1.10，属于已知版本元数据例外，应结合真实渲染验收，而不是声称 `pip check` 必然零错误。