bytedance--lance/train_zh.md

Lance 训练脚本使用说明

本文档说明以下训练脚本的用途和常见用法：

• scripts/sft_lance_unified.sh
• scripts/sft_lance_generation.sh
• scripts/sft_lance_understand.sh

这三个脚本最终都会通过 accelerate launch 启动 train/unified_train.py。主要区别在于默认数据配置和 VISUAL_GEN 开关。

1. 环境安装

本次训练代码发布在原推理环境的基础上新增了一些依赖。如果你在微调代码发布前已经安装过环境，请基于更新后的 requirements.txt 重新安装依赖：

pip install -r requirements.txt

2. 数据准备

训练读取本地 parquet 文件。请从 Hugging Face 下载示例数据集，并放到本地 ./datasets 目录下。

期望的本地目录结构如下：

datasets/
├── image2image/
├── image2text/
├── text2image/
├── text2video/
├── video2text/
└── video2video/

可直接使用的本地配置位于 config/train_local/，例如：

任务	配置
t2i	config/train_local/t2i_local.yaml
t2v	config/train_local/t2v_local.yaml
i2i	config/train_local/i2i_local.yaml
v2v	config/train_local/v2v_local.yaml
i2t	config/train_local/i2t_local.yaml
v2t	config/train_local/v2t_local.yaml

关于 parquet schema、支持的任务类型和自定义数据集构建方式，请参考 train_dataset_zh.md。

3. 训练脚本

准备好环境、模型权重和示例数据后，可以启动下面的训练脚本。

默认情况下，脚本会使用当前机器上 nvidia-smi 可见的全部 GPU。如果需要少卡启动，可以在命令前设置 ARNOLD_WORKER_GPU，例如 ARNOLD_WORKER_GPU=1 bash scripts/sft_lance_unified.sh。 对于资源较少的本地机器，也可以降低 dataloader worker 数，例如 NUM_WORKERS=2 ARNOLD_WORKER_GPU=1 bash scripts/sft_lance_unified.sh。

3.1 统一混合训练

bash scripts/sft_lance_unified.sh

3.2 生成任务训练

bash scripts/sft_lance_generation.sh

本地 t2v 训练可以通过环境变量覆盖数据配置和实验名：

DATASET_CONFIG_FILE=config/train_local/t2v_local.yaml \
VAL_DATASET_CONFIG_FILE=config/train_local/t2v_local.yaml \
WANDB_NAME=t2v_local_debug \
bash scripts/sft_lance_generation.sh

3.3 理解任务训练

bash scripts/sft_lance_understand.sh

本地 v2t 训练可以通过环境变量覆盖数据配置和实验名：

DATASET_CONFIG_FILE=config/train_local/v2t_local.yaml \
VAL_DATASET_CONFIG_FILE=config/train_local/v2t_local.yaml \
WANDB_NAME=v2t_local_debug \
bash scripts/sft_lance_understand.sh

注意：训练脚本默认使用 MODEL_PATH=./downloads/Lance_3B_Video，即支持视频任务的统一 checkpoint。若只微调图像类任务，例如 t2i、i2i 或 i2t，可以在启动前将 MODEL_PATH 切换为 ./downloads/Lance_3B。

4. 训练脚本选择

这些脚本会将 shell 变量展开为命令行参数，并传给 train/unified_train.py。实际使用时，应先确定这次要训练的任务类型。

脚本	默认配置	默认开关	适用场景	常见需要修改的字段
scripts/sft_lance_unified.sh	config/train_local/unified.yaml	VISUAL_UND=True, VISUAL_GEN=True	理解 + 生成混合训练	DATASET_CONFIG_FILE, VAL_DATASET_CONFIG_FILE, WANDB_NAME
scripts/sft_lance_generation.sh	config/train_local/multi_gen.yaml	VISUAL_UND=True, VISUAL_GEN=True	t2i、t2v、i2i、v2v 等生成任务	DATASET_CONFIG_FILE, VAL_DATASET_CONFIG_FILE, WANDB_NAME
scripts/sft_lance_understand.sh	config/train_local/multi_und.yaml	VISUAL_UND=True, VISUAL_GEN=False	i2t、v2t 等理解任务	DATASET_CONFIG_FILE, VAL_DATASET_CONFIG_FILE, WANDB_NAME

5. 优先确认的关键参数

下面这些参数是大多数训练前都需要优先确认的内容，可以理解为最常需要调整的一层配置。

参数	作用	什么时候修改	建议
DATASET_CONFIG_FILE	指定训练集 yaml	几乎每次训练都需要确认	指向本次真正要训练的数据配置
VAL_DATASET_CONFIG_FILE	指定验证集 yaml	当前验证暂不支持	保持默认值
WANDB_NAME	设置实验名	几乎每次训练都需要修改	包含任务名、数据集名和日期
VISUAL_UND	启用视觉理解分支	通常不常修改	理解任务和大多数生成任务都保持 True
VISUAL_GEN	启用视觉生成分支	在理解/生成任务切换时必须确认	理解任务设为 False，生成任务设为 True
SAVE_EVERY	checkpoint 保存间隔	调试和正式训练都常修改	调试时可设小，长训时建议设大
CKPT_DEBUG_STEPS	早期 debug checkpoint	调试时常修改	不需要早期 debug checkpoint 时设为 -1
VALIDATION_STEP	验证间隔	当前验证暂不支持	保持 -1，不要设为正整数
NUM_SHARD	FSDP shard 数	调整并行策略时修改	结合 GPU 数量和显存预算一起调整
NUM_REPLICATE	replica 数	通常随 NUM_SHARD 变化	由 TOTAL_RANK / NUM_SHARD 计算得到

6. 容易配错的两个开关

6.1 VISUAL_GEN

VISUAL_GEN 控制是否启用视觉生成分支，包括 VAE latent、flow matching 和 MSE 路径。

• 生成任务常见设置：

  • VISUAL_UND=True
  • VISUAL_GEN=True

• 理解任务常见设置：

  • VISUAL_UND=True
  • VISUAL_GEN=False

如果理解任务误设为 VISUAL_GEN=True，但 batch 中没有生成分支需要的 latent 字段，Lance.forward(...) 可能会进入错误分支并失败。

6.2 VALIDATION_STEP

三个脚本默认都是：

VALIDATION_STEP=-1

这表示：

• 不准备固定验证集
• 训练循环中不会触发 validate_on_fixed_batch(...)

训练脚本中的 validation 逻辑目前尚未完整检查。当前不支持设置正数来启用验证，因此不要设置 VALIDATION_STEP=100 这类值，保持 -1 即可。

7. 使用建议

1. 纯理解任务优先使用 sft_lance_understand.sh。
2. 纯生成任务优先使用 sft_lance_generation.sh。
3. 确实需要混合任务训练时再使用 sft_lance_unified.sh。
4. 调试阶段优先修改：
   • DATASET_CONFIG_FILE
   • WANDB_NAME
   • VISUAL_GEN
   • SAVE_EVERY
   • CKPT_DEBUG_STEPS
   • VALIDATION_STEP
5. 本地 parquet 训练时，优先确认：
   • yaml 确实指向本地 parquet 文件
   • _local 数据集类和 parquet schema 对齐
   • 理解任务没有误设为 VISUAL_GEN=True