wehub-resource-sync
173 lines
6.7 KiB
Markdown
173 lines
6.7 KiB
Markdown
# 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` 重新安装依赖：
|
|
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
|
|
## 2. 数据准备
|
|
|
|
训练读取本地 parquet 文件。请从 [Hugging Face](https://huggingface.co/datasets/bytedance-research/Lance_example_dataset) 下载示例数据集，并放到本地 `./datasets` 目录下。
|
|
|
|
期望的本地目录结构如下：
|
|
|
|
```text
|
|
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](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
|
|
bash scripts/sft_lance_unified.sh
|
|
```
|
|
|
|
### 3.2 生成任务训练
|
|
|
|
```bash
|
|
bash scripts/sft_lance_generation.sh
|
|
```
|
|
|
|
本地 `t2v` 训练可以通过环境变量覆盖数据配置和实验名：
|
|
|
|
```bash
|
|
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
|
|
bash scripts/sft_lance_understand.sh
|
|
```
|
|
|
|
本地 `v2t` 训练可以通过环境变量覆盖数据配置和实验名：
|
|
|
|
```bash
|
|
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`
|
|
|
|
三个脚本默认都是：
|
|
|
|
```bash
|
|
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`
|