[train] fix multimodal packing & padding_free (#4838)

Author: Jintao-Huang

docs/source/BestPractices/Qwen3最佳实践.md

@@ -61,7 +61,7 @@ I am Qwen, a large-scale language model developed by Alibaba Cloud. I am designe
 
 ```bash
 pip install ms-swift -U
-pip install transformers -U
+pip install transformers
 
 pip install deepspeed # 多GPU训练
 pip install liger-kernel # 节约显存资源

docs/source/Instruction/命令行参数.md

@@ -85,7 +85,7 @@
   - 注意：`swift pt`默认为False，使用generation模板。
 - 🔥padding_free: 将一个batch中的数据进行展平而避免数据padding，从而降低显存占用并加快训练。默认为False。当前支持CPT/SFT/DPO/GRPO/GKD。
   - 注意：使用padding_free请结合`--attn_impl flash_attn`使用且"transformers>=4.44"，具体查看[该PR](https://github.com/huggingface/transformers/pull/31629)。（同packing）
-  - 支持的多模态模型与多模态packing支持情况相同。相较于packing，padding_free不额外消耗时间和空间。
+  - 支持的多模态模型与多模态packing支持情况相同。相较于packing，padding_free不额外消耗时间和空间。注意：请使用"ms-swift>=3.6"，关注[此PR](https://github.com/modelscope/ms-swift/pull/4838)。
   - Megatron-SWIFT默认使用padding_free，即`qkv_format='thd'`，不需要额外设置。
 - padding_side: 当训练`batch_size>=2`时的padding_side，可选值为'left'、'right'，默认为'right'。（推理时的batch_size>=2时，只进行左padding）。
   - 注意：PPO和GKD默认设置为'left'。
@@ -379,7 +379,7 @@ Vera使用`target_modules`, `target_regex`, `modules_to_save`三个参数.
 - channels: 数据集包含的channel集合。默认为None。结合`--loss_type channel_loss`使用，可参考[这里](https://github.com/modelscope/ms-swift/blob/main/examples/train/plugins/channel_loss.sh)。
 - 🔥packing: 是否使用序列packing提升计算效率，默认为False。当前支持`swift pt/sft`。
   - 注意：使用packing请结合`--attn_impl flash_attn`使用且"transformers>=4.44"，具体查看[该PR](https://github.com/huggingface/transformers/pull/31629)。
-  - 支持的多模态模型参考：https://github.com/modelscope/ms-swift/blob/main/examples/train/packing/qwen2_5_vl.sh
+  - 支持的多模态模型参考：https://github.com/modelscope/ms-swift/blob/main/examples/train/packing/qwen2_5_vl.sh。注意：请使用"ms-swift>=3.6"，关注[此PR](https://github.com/modelscope/ms-swift/pull/4838)。
 - packing_cache: 指定 packing 缓存目录。默认值为`None`，表示缓存将存储在环境变量 `$MODELSCOPE_CACHE`所指定的路径下。在跨节点使用 packing 功能时，需确保所有节点的 packing 缓存路径共享且一致。你可以通过设置`MODELSCOPE_CACHE`环境变量，或在命令行中添加 `--packing_cache <shared_path>`参数来实现这一要求。
 - 🔥lazy_tokenize: 是否使用lazy_tokenize。若该参数设置为False，则在训练之前对所有的数据集样本进行tokenize（多模态模型则包括从磁盘中读取图片）。该参数在LLM训练中默认设置为False，而MLLM训练默认为True，节约内存。
 - use_logits_to_keep: 通过在`forward`中根据labels传入logits_to_keep，减少无效logits的计算与存储，从而减少显存占用并加快训练速度。默认为None，进行自动选择。

docs/source_en/BestPractices/Qwen3-Best-Practice.md

@@ -63,7 +63,7 @@ Before starting training, please ensure that your environment is properly config
 
 ```bash
 pip install ms-swift -U
-pip install transformers -U
+pip install transformers
 
 pip install deepspeed # for multi-GPU training
 pip install liger-kernel # to save GPU memory resources

docs/source_en/Instruction/Command-line-parameters.md

@@ -86,7 +86,7 @@ Hints:
   - Note: `swift pt` is set to False by default, using the generation template.
 - 🔥padding_free: Flattens the data in a batch to avoid padding, thereby reducing memory usage and accelerating training. Default is False. Currently supported in CPT/SFT/DPO/GRPO/GKD.
   - Note: When using `padding_free`, it should be combined with `--attn_impl flash_attn` and "transformers>=4.44". For details, see [this PR](https://github.com/huggingface/transformers/pull/31629). (Same as packing)
-  - The supported multimodal models are the same as those supported for multimodal packing. Compared to packing, padding_free does not consume additional time or space.
+  - The supported multimodal models are the same as those supported for multimodal packing. Compared to packing, padding_free does not consume additional time or space. Note: Please use "ms-swift>=3.6" and follow [this PR](https://github.com/modelscope/ms-swift/pull/4838).
   - Megatron-SWIFT uses `padding_free` by default, i.e., `qkv_format='thd'`, and no additional configuration is required.
 - padding_side: Padding side when `batch_size>=2` during training. Options are 'left' and 'right', with 'right' as the default. (For inference with batch_size>=2, only left padding is applied.)
   - Note: PPO and GKD are set to 'left' by default.
@@ -388,7 +388,7 @@ Training arguments include the [base arguments](#base-arguments), [Seq2SeqTraine
 - channels: Set of channels included in the dataset. Defaults to None. Used in conjunction with `--loss_type channel_loss`. Refer to [this example](https://github.com/modelscope/ms-swift/blob/main/examples/train/plugins/channel_loss.sh) for more details.
 - 🔥packing: Whether to use sequence packing to improve computational efficiency. The default value is False. Currently supports `swift pt/sft`.
   - Note: When using packing, please combine it with `--attn_impl flash_attn` and ensure "transformers>=4.44". For details, see [this PR](https://github.com/huggingface/transformers/pull/31629).
-  - Supported multimodal models reference: https://github.com/modelscope/ms-swift/blob/main/examples/train/packing/qwen2_5_vl.sh
+  - Supported multimodal models reference: https://github.com/modelscope/ms-swift/blob/main/examples/train/packing/qwen2_5_vl.sh. Note: Please use "ms-swift>=3.6" and follow [this PR](https://github.com/modelscope/ms-swift/pull/4838).
 - packing_cache: Specifies the directory for packing cache. The default value is `None`, which means the cache will be stored in the path defined by the environment variable `$MODELSCOPE_CACHE`. When using the packing feature across multiple nodes, ensure that all nodes share the same packing cache directory. You can achieve this by setting the `MODELSCOPE_CACHE` environment variable or by adding the `--packing_cache <shared_path>` argument in the command line.
 - 🔥lazy_tokenize: Whether to use lazy tokenization. If set to False, all dataset samples are tokenized before training (for multimodal models, this includes reading images from disk). This parameter defaults to False for LLM training, and True for MLLM training, to save memory.
 - use_logits_to_keep: Pass `logits_to_keep` in the `forward` method based on labels to reduce the computation and storage of unnecessary logits, thereby reducing memory usage and accelerating training. The default is `None`, which enables automatic selection.

examples/train/multimodal/omni/sft.sh

@@ -1,7 +1,5 @@
 # 4*35GB
 # A demo for four modalities that can be run directly
-pip install transformers -U
-
 nproc_per_node=4
 
 CUDA_VISIBLE_DEVICES=0,1,2,3 \

examples/train/packing/qwen2_5_omni.sh

@@ -2,8 +2,6 @@
 # Multimodal packing currently only supports qwen2_vl, qwen2_5_vl, qwen2_5_omni, internvl2_5/3
 # A demo for four modalities that can be run directly
 # For local datasets, it is recommended to use streaming: `--streaming true` (save memory)
-pip install transformers -U
-
 NPROC_PER_NODE=4 \
 ENABLE_AUDIO_OUTPUT=1 \
 CUDA_VISIBLE_DEVICES=0,1,2,3 \

swift/llm/template/base.py

@@ -309,7 +309,7 @@ def _extend_tokens(input_ids: List[int], labels: Optional[List[int]], replace_id
             added_tokens_len += token_len - 1
         return input_ids, labels
 
-    def compute_loss_context(self, model, inputs):
+    def training_step_context(self, model, inputs):
         return nullcontext()
 
     @staticmethod

swift/llm/template/template/internvl.py

@@ -56,14 +56,14 @@ def _encode(self, inputs: StdTemplateInputs) -> Dict[str, Any]:
         encoded['pixel_values'] = pixel_values
         return encoded
 
-    def compute_loss_context(self, model, inputs):
+    def training_step_context(self, model, inputs):
         model_name = model.language_model.__class__.__name__.lower()
         if self._packing and 'internlm2' in model_name:
             position_ids = inputs['position_ids']
             modeling_module = model.language_model.model.layers[0].attention.__class__
             return self._patch_flash_attention_forward(modeling_module, position_ids, use_new_func=True)
         else:
-            return super().compute_loss_context(model, inputs)
+            return super().training_step_context(model, inputs)
 
     def _post_encode(self, model: nn.Module, inputs: Dict[str, Any]) -> Dict[str, Any]:
         embedding = model.get_input_embeddings()

swift/llm/template/template/qwen.py

@@ -297,9 +297,9 @@ def _get_new_tokens(i):
         encoded['labels'] = labels
         return encoded
 
-    def compute_loss_context(self, model, inputs):
+    def training_step_context(self, model, inputs):
         if 'real_position_ids' not in inputs:
-            return super().compute_loss_context(model, inputs)
+            return super().training_step_context(model, inputs)
         if self.version == 'v2':
             from transformers.models.qwen2_vl import modeling_qwen2_vl as modeling_module
         elif self.version == 'v2_5':

swift/trainers/rlhf_trainer/dpo_trainer.py

@@ -56,9 +56,10 @@ def concatenated_forward(
             batch['output_router_logits'] = True
         if self.is_encoder_decoder:
             batch['labels'] = labels
-        position_ids = batch.get('position_ids')
-        with self.template.compute_loss_context(self.model, batch):
-            outputs = model(**batch, use_cache=False)
+        position_ids = batch.pop('_position_ids', None)
+        if position_ids is None:
+            position_ids = batch.get('position_ids')
+        outputs = model(**batch, use_cache=False)
         all_logits = outputs.logits
 
         if all_logits.shape[1] != labels.shape[1]:
@@ -121,3 +122,8 @@ def get_per_token_logps(
         per_token_logps = selective_log_softmax(logits, labels)
         per_token_logps[~loss_mask] = 0
         return per_token_logps, logits.mean(-1), loss_mask
+
+    def training_step(self, model, inputs, *args, **kwargs):
+        inputs['_position_ids'] = inputs.get('position_ids')
+        with self.template.training_step_context(self.model, inputs):
+            return super().training_step(model, inputs, *args, **kwargs)