| # 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` 必然零错误。 |
|
|
