Hugging Face's logo

liuyibo
/
codiffact-full

docker
environment
codiffact
Model card Files
xet
 Community
codiffact-full / model_setup.md
liuyibo's picture
liuyibo
Add environment artifact: model_setup.md
b66bfc4 verified
preview code
|
Raw History Blame Contribute Delete
18.3 kB

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

例如在项目根目录执行：

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是本次查询的远端版本，不是本地历史权重哈希证明。

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 子目录的链接，或复制到这两个确切位置。链接目标必须在容器里也可见，不能保留原共享盘绝对目标。

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 的训练/推理超参数，用下面方式生成完整副本，避免覆盖原机器配置。路径是容器内路径；将你有的加工数据放到对应目录。

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。例如模型和参考数据准备好后：

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。上传完成标记和校验文件见仓库实际内容；未出现镜像文件前不要把目标地址当作已上传完成。

# 在已完成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

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

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/。在原开发机固定环境前缀下准备上下文：

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