Conda 环境迁移说明

这份文档总结如何把另一台机器上已经能跑通 hanayo-pipeline 的
HunyuanDiT conda 环境迁移到当前机器。这里假设两台机器的 Docker

容器共享同一个 /workspace 目录，所以环境包可以直接放在 /workspace

下，不需要额外 scp。

推荐使用 conda-pack：在能跑通的源机器上把完整 conda 环境打成压缩包，

放到 /workspace，然后在目标机器解包。这样可以尽量避免手动猜
torch、diffusers、deepspeed、CUDA 相关库和 Hanayo 修改版

DeepSpeed 的版本组合。

前提

源机器上已经有一个可以跑通 hanayo-pipeline 的 conda 环境，环境名为
HunyuanDiT。
两台机器的 Docker 容器都能看到同一个 /workspace 目录。
目标机器上已经安装 conda。
Hanayo 仓库路径为 /workspace/hanayo-pipeline。

源机器：打包可用环境

以下命令在"已经能跑通 Hanayo 的机器"上执行。

bash 复制代码

conda activate HunyuanDiT

激活已经验证可用的 conda 环境。后续安装、检查和打包命令都会作用在这个

环境上。

bash 复制代码

conda install -c conda-forge conda-pack -y

安装 conda-pack。conda-pack 用来把 conda 环境打包成可以迁移的压缩包。

其中 -c conda-forge 表示从 conda-forge channel 安装，-y 表示自动确认

安装提示。

bash 复制代码

python -m pip list --editable

查看当前环境里有哪些 editable 包，也就是通过 pip install -e 安装的包。

这一步很重要，因为 conda-pack 默认不能打包包含 editable 包的环境。

bash 复制代码

conda pack -n HunyuanDiT -o /workspace/HunyuanDiT.tar.gz

尝试把名为 HunyuanDiT 的 conda 环境打包到
/workspace/HunyuanDiT.tar.gz。因为 /workspace 是两台机器共享的，所以

目标机器可以直接看到这个压缩包。

如果出现下面这个错误：

text 复制代码

CondaPackError: Cannot pack an environment with editable packages

改用：

bash 复制代码

conda pack -n HunyuanDiT \
  -o /workspace/HunyuanDiT.tar.gz \
  --ignore-editable-packages

这条命令表示打包环境时忽略 editable 包。对这个仓库来说，这通常是合适的，

因为 Hanayo 修改版 DeepSpeed 可以在目标机器上从
/workspace/hanayo-pipeline/DeepSpeed 重新安装。

目标机器：解包环境

以下命令在"当前缺少环境的机器"上执行。

bash 复制代码

mkdir -p /root/miniconda3/envs/HunyuanDiT

创建目标 conda 环境目录。-p 表示如果父目录不存在就一起创建；如果目录已经

存在，也不会因为这个命令直接报错。

bash 复制代码

tar -xzf /workspace/HunyuanDiT.tar.gz -C /root/miniconda3/envs/HunyuanDiT

把 /workspace/HunyuanDiT.tar.gz 解压到目标 conda 环境目录。

参数含义是：-x 解包，-z 处理 gzip 压缩，-f 指定压缩包文件，
-C 指定解压目标目录。

bash 复制代码

/root/miniconda3/envs/HunyuanDiT/bin/conda-unpack

修复环境内部记录的绝对路径。conda-pack 打出来的环境迁移到新位置或新机器

后，都应该执行一次 conda-unpack。

bash 复制代码

conda activate /root/miniconda3/envs/HunyuanDiT

通过绝对路径激活刚刚解包出来的环境。

重新安装 editable 包

如果源机器打包时用了 --ignore-editable-packages，目标机器上需要重新安装这些

editable 包。

对 Hanayo 来说，最关键的通常是仓库自带的修改版 DeepSpeed：

bash 复制代码

cd /workspace/hanayo-pipeline/DeepSpeed

进入 hanayo-pipeline 仓库里的本地 DeepSpeed 源码目录。

bash 复制代码

pip install -e . --no-build-isolation

以 editable 方式安装当前目录下的 DeepSpeed。这里不能简单用标准 PyPI 版

DeepSpeed 替代，因为 Hanayo 代码依赖自定义接口，例如
HanayoPipelineModule。--no-build-isolation 表示构建时使用当前 conda

环境里的依赖，而不是临时创建一个隔离构建环境。

如果源机器上执行 python -m pip list --editable 时还看到其他 editable 包，

也需要在目标机器上进入对应源码目录，使用类似命令重新安装。

验证环境

目标机器上激活环境后执行：

bash 复制代码

cd /workspace/hanayo-pipeline

进入项目根目录，确保本地导入和训练脚本里的相对路径都和预期一致。

bash 复制代码

python - <<'PY'
import torch
import diffusers
import deepspeed
from deepspeed.pipe import HanayoPipelineModule

print("torch", torch.__version__)
print("cuda available", torch.cuda.is_available())
print("diffusers", diffusers.__version__)
print("deepspeed", deepspeed.__version__)
print("HanayoPipelineModule OK")
PY

检查关键包是否能正常导入，PyTorch 是否能看到 CUDA，以及修改版 DeepSpeed

是否包含 HanayoPipelineModule。

再跑一个最小训练 smoke test：

bash 复制代码

deepspeed --include localhost:0 train_hunyuan_zero3.py \
  --steps 1 \
  --backend nccl \
  --micro_batch_size 1 \
  --zero_stage 3 \
  --model hunyuan_lite

用最小的 Hunyuan 配置启动一次单 GPU DeepSpeed 训练。这个测试不能代表完整

多 GPU 性能，但可以快速确认 Python 环境、模型导入、DeepSpeed 启动路径和

CUDA/NCCL 基础功能是否正常。

注意事项

不建议让两台机器直接共用同一个在线 conda 环境目录。共享
/workspace/HunyuanDiT.tar.gz 没问题；每台机器最好解包到自己的本地 conda
环境目录。
如果源机器和目标机器的 GPU driver 差异很大，仍然可能遇到 CUDA 兼容性问题。
当前目标机器上 nvidia-smi 显示 driver 为 535.161.07，CUDA runtime
compatibility 为 12.4。
对这个仓库来说，pip install deepspeed 不等价于安装
/workspace/hanayo-pipeline/DeepSpeed。Hanayo 依赖的是仓库中的修改版
DeepSpeed。