LLaMA-Factory v1 怎么启用 padding_free 与 dynamic_batching 批处理策略-开发者社区

LLaMA-Factory v1 怎么启用 padding_free 与 dynamic_batching 批处理策略

【免费下载链接】LlamaFactoryUnified Efficient Fine-Tuning of 100+ LLMs & VLMs (ACL 2024)项目地址: https://gitcode.com/GitHub_Trending/ll/LlamaFactory

在 LLaMA-Factory v1 中做 SFT 训练时，batching_strategy字段控制数据如何被组织成训练 batch：默认值normal按固定条数组 batch 并做常规 padding，而padding_free与dynamic_batching则是两种针对变长样本的批处理策略，分别通过「无 padding 拼接」和「按 token 预算动态组 batch」减少无效计算。本文基于仓库自带的示例配置与源码中的限制条件，给出在 v1 中启用这两种策略的完整配置、启动方式、验证方法和边界说明，示例以 Qwen3-0.6B + FSDP2 全参 SFT 为例，可换成任意仓库支持的其他模型与数据集。

前置条件

按 docs/zh/getting-started.md 准备环境：

必需依赖至少包含 python 3.11、torch 2.7.1、transformers 5.0.0、peft 0.18.1；
从源码安装：git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git后执行pip install -e .（也可pip install llamafactory）；
若配置中启用flash_attn: flash_attention_2，需额外安装pip install flash-attn --no-build-isolation（NVIDIA GPU）。

v1 入口需要通过环境变量启用：

export USE_V1=1

三种策略与配置字段

batching_strategy的取值定义在 BatchingStrategy，共有四种：normal、padding_free、dynamic_batching、dynamic_padding_free；TrainingArguments 中默认值为normal，另有一个batching_workers（默认 16）控制 batching 的 worker 数。相关示例配置都位于 examples/v1/train_batching_strategy/：

策略	示例配置
`normal`（默认）	train_full_fsdp2_batching_normal.yaml
`padding_free`	train_full_fsdp2_padding_free.yaml
`dynamic_batching`	train_full_fsdp2_dynamic_batching.yaml
`dynamic_padding_free`（可选分支）	train_full_fsdp2_dynamic_padding_free.yaml

两种策略的组织方式（依据 batching.py 中的实现）：

padding_free：把每个 micro batch 的样本（各自先按cutoff_len截断）拼接成一条无 padding 的连续序列，依赖 FlashAttention-2 处理变长输入；
dynamic_batching：按 token 预算（预算 =cutoff_len×micro_batch_size，见 _get_dynamic_micro_batch_sizes）动态决定每个 micro batch 装多少条样本，组完 batch 后 pad 到 batch 内最长样本长度，而不是 pad 到cutoff_len。

启用 padding_free

基于 train_full_fsdp2_padding_free.yaml 的最小配置，需要关注的字段如下（model、train_dataset、output_dir按实际环境替换）：

model: Qwen/Qwen3-0.6B model_class: llm dist_config: name: fsdp2 ### data train_dataset: data/v1_sft_demo.yaml ### training output_dir: outputs/test_fsdp2 micro_batch_size: 4 batching_strategy: padding_free flash_attn: flash_attention_2 # 必选，padding_free 强依赖 cutoff_len: 2048 learning_rate: 1.0e-4 max_steps: 10 ### sample sample_backend: hf max_new_tokens: 128

kernel_config: name: auto与quant_config: null为示例中的默认项，可按需增删。

启用 dynamic_batching

基于 train_full_fsdp2_dynamic_batching.yaml：

model: Qwen/Qwen3-0.6B model_class: llm dist_config: name: fsdp2 ### data train_dataset: data/v1_sft_demo.yaml ### training output_dir: outputs/test_fsdp2 micro_batch_size: 2 batching_strategy: dynamic_batching cutoff_len: 2048 learning_rate: 1.0e-4 max_steps: 10 # 必选，见下文限制 ### sample sample_backend: hf max_new_tokens: 128

示例中没有写flash_attn字段，说明dynamic_batching不像padding_free那样强制要求 FlashAttention-2。

可选分支：dynamic_padding_free示例（train_full_fsdp2_dynamic_padding_free.yaml）结合了两者，同样配置了flash_attn: flash_attention_2。

启动训练

export USE_V1=1 llamafactory-cli sft examples/v1/train_batching_strategy/train_full_fsdp2_padding_free.yaml

将命令末尾的 yaml 换成你实际使用的配置文件（dynamic 版则换成train_full_fsdp2_dynamic_batching.yaml）。llamafactory-cli sft与llamafactory-cli train等价；在多 GPU 环境下，v1 入口会经 torchrun 自动拉起分布式进程，详见 launcher.py 的启动逻辑。

验证策略已生效与常见报错

启动时 BatchGenerator 会打印初始化日志，确认batching strategy一项为所选策略，以及 global batch size、micro batch size、num micro batch、cutoff len 是否符合预期（文档示例的日志格式）：

Init unified data loader with global batch size ..., micro batch size ..., num micro batch ..., cutoff len 2048, batching workers ..., batching strategy padding_free.

启动或组 batch 阶段可能遇到的错误（均由源码显式抛出，见 TrainingArguments.__post_init__ 与 base_trainer.py）：

padding_free未配置flash_attn: flash_attention_2时：ValueError: `padding_free` requires `flash_attn: flash_attention_2`.
dynamic_batching未设置max_steps时：ValueError: `dynamic_batching` requires `max_steps` because it is step-driven.
dynamic_batching与save_epochs同时设置时：ValueError: `save_epochs` is not supported with `dynamic_batching`; use `save_steps` instead.
非normal策略（含padding_free与dynamic_batching）遇到多模态数据时抛出NotImplementedError：batching_strategy=... does not support multimodal data; use the NORMAL strategy for image/video training.图像/视频训练必须改用normal策略。

另外，样本超过cutoff_len且监督 token 全部落在截断范围之外时，日志会一次性告警Dropping training sample(s) whose supervised tokens fall entirely beyond cutoff_len=...，此时应调大cutoff_len。

限制

dynamic_batching是 step 驱动：必须提供max_steps，且只能用save_steps而不是save_epochs控制存档。
padding_free/dynamic_padding_free依赖 FlashAttention-2，需安装flash-attn并在配置中显式开启。
两类动态策略都不支持多模态数据，多模态训练请使用默认normal策略。

【免费下载链接】LlamaFactoryUnified Efficient Fine-Tuning of 100+ LLMs & VLMs (ACL 2024)项目地址: https://gitcode.com/GitHub_Trending/ll/LlamaFactory

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考