chore: import upstream snapshot with attribution

2026-07-13 13:34:58 +08:00
commit a203934033
1368 changed files with 175001 additions and 0 deletions
@@ -0,0 +1,321 @@
+# AMD GPU 支持
+
+## 1. 环境配置
+### 1.1 基础环境
+拉取适配了 AMD ROCm 生态的 ms-swift 镜像，并参照以下命令启动容器。
+
+如果用户需要运行更新版本的 ms-swift，可以使用 pip 升级或基于源码安装更新（建议安装时添加 `--no-deps` 选项以避免自动升级其他依赖可能引起的问题）。
+
+```bash
+IMAGE_NAME=amdagi/modelscope:ubuntu22.04-rocm7.2.0-py312-torch2.10.0-vllm0.18.1-modelscope1.35.1-swift4.1.0
+docker pull ${IMAGE_NAME}
+
+CONTAINER_NAME=swift_test
+docker run -it --network=host --ipc=host --privileged --group-add video \
+    --device=/dev/dri --device=/dev/kfd \
+    --shm-size 512G --ulimit memlock=-1 \
+    --security-opt seccomp=unconfined --cap-add SYS_PTRACE \
+    --name ${CONTAINER_NAME} \
+    ${IMAGE_NAME} \
+    /bin/bash
+```
+
+### 1.2 环境检查
+
+- 确认 container 环境中 pytorch 正确识别 AMD GPU。
+
+```bash
+python -c "import torch;print(torch.cuda.is_available())"  # output: True
+```
+
+- 检查 GPU 的拓扑连接及 NUMA：`rocm-smi --showtopo`
+
+```
+============================ ROCm System Management Interface ============================
+WARNING: AMD GPU device(s) is/are in a low-power state. Check power control/runtime_status
+
+================================ Weight between two GPUs =================================
+       GPU0         GPU1         GPU2         GPU3         GPU4         GPU5         GPU6         GPU7
+GPU0   0            15           15           15           15           15           15           15
+GPU1   15           0            15           15           15           15           15           15
+GPU2   15           15           0            15           15           15           15           15
+GPU3   15           15           15           0            15           15           15           15
+GPU4   15           15           15           15           0            15           15           15
+GPU5   15           15           15           15           15           0            15           15
+GPU6   15           15           15           15           15           15           0            15
+GPU7   15           15           15           15           15           15           15           0
+
+================================= Hops between two GPUs ==================================
+       GPU0         GPU1         GPU2         GPU3         GPU4         GPU5         GPU6         GPU7
+GPU0   0            1            1            1            1            1            1            1
+GPU1   1            0            1            1            1            1            1            1
+GPU2   1            1            0            1            1            1            1            1
+GPU3   1            1            1            0            1            1            1            1
+GPU4   1            1            1            1            0            1            1            1
+GPU5   1            1            1            1            1            0            1            1
+GPU6   1            1            1            1            1            1            0            1
+GPU7   1            1            1            1            1            1            1            0
+
+=============================== Link Type between two GPUs ===============================
+       GPU0         GPU1         GPU2         GPU3         GPU4         GPU5         GPU6         GPU7
+GPU0   0            XGMI         XGMI         XGMI         XGMI         XGMI         XGMI         XGMI
+GPU1   XGMI         0            XGMI         XGMI         XGMI         XGMI         XGMI         XGMI
+GPU2   XGMI         XGMI         0            XGMI         XGMI         XGMI         XGMI         XGMI
+GPU3   XGMI         XGMI         XGMI         0            XGMI         XGMI         XGMI         XGMI
+GPU4   XGMI         XGMI         XGMI         XGMI         0            XGMI         XGMI         XGMI
+GPU5   XGMI         XGMI         XGMI         XGMI         XGMI         0            XGMI         XGMI
+GPU6   XGMI         XGMI         XGMI         XGMI         XGMI         XGMI         0            XGMI
+GPU7   XGMI         XGMI         XGMI         XGMI         XGMI         XGMI         XGMI         0
+
+======================================= Numa Nodes =======================================
+GPU[0]          : (Topology) Numa Node: 0
+GPU[0]          : (Topology) Numa Affinity: 0
+GPU[1]          : (Topology) Numa Node: 0
+GPU[1]          : (Topology) Numa Affinity: 0
+GPU[2]          : (Topology) Numa Node: 0
+GPU[2]          : (Topology) Numa Affinity: 0
+GPU[3]          : (Topology) Numa Node: 0
+GPU[3]          : (Topology) Numa Affinity: 0
+GPU[4]          : (Topology) Numa Node: 1
+GPU[4]          : (Topology) Numa Affinity: 1
+GPU[5]          : (Topology) Numa Node: 1
+GPU[5]          : (Topology) Numa Affinity: 1
+GPU[6]          : (Topology) Numa Node: 1
+GPU[6]          : (Topology) Numa Affinity: 1
+GPU[7]          : (Topology) Numa Node: 1
+GPU[7]          : (Topology) Numa Affinity: 1
+================================== End of ROCm SMI Log ===================================
+```
+
+- 查看 GPU 利用率及显存占用等信息（`rocm-smi` 或者 `rocm-smi -u --showmeminfo vram`）
+
+```
+# output of 'rocm-smi'
+============================================ ROCm System Management Interface ============================================
+====================================================== Concise Info ======================================================
+Device  Node  IDs              Temp        Power     Partitions          SCLK    MCLK    Fan  Perf  PwrCap  VRAM%  GPU%
+              (DID,     GUID)  (Junction)  (Socket)  (Mem, Compute, ID)
+==========================================================================================================================
+0       2     0x74a2,   1017   43.0°C      155.0W    NPS1, SPX, 0        94Mhz   900Mhz  0%   auto  650.0W  0%     0%
+1       3     0x74a2,   47713  41.0°C      155.0W    NPS1, SPX, 0        91Mhz   900Mhz  0%   auto  650.0W  0%     0%
+2       4     0x74a2,   37449  45.0°C      159.0W    NPS1, SPX, 0        95Mhz   900Mhz  0%   auto  650.0W  0%     0%
+3       5     0x74a2,   11217  41.0°C      155.0W    NPS1, SPX, 0        95Mhz   900Mhz  0%   auto  650.0W  0%     0%
+4       6     0x74a2,   41880  44.0°C      160.0W    NPS1, SPX, 0        91Mhz   900Mhz  0%   auto  650.0W  0%     0%
+5       7     0x74a2,   6656   42.0°C      157.0W    NPS1, SPX, 0        95Mhz   900Mhz  0%   auto  650.0W  0%     0%
+6       8     0x74a2,   12840  45.0°C      160.0W    NPS1, SPX, 0        96Mhz   900Mhz  0%   auto  650.0W  0%     0%
+7       9     0x74a2,   35760  43.0°C      158.0W    NPS1, SPX, 0        107Mhz  900Mhz  0%   auto  650.0W  0%     0%
+==========================================================================================================================
+================================================== End of ROCm SMI Log ===================================================
+
+# output of 'rocm-smi -u --showmeminfo vram'
+============================ ROCm System Management Interface ============================
+=================================== % time GPU is busy ===================================
+GPU[0]          : GPU use (%): 0
+GPU[0]          : GFX Activity: 3862538534
+GPU[1]          : GPU use (%): 0
+GPU[1]          : GFX Activity: 4053246251
+GPU[2]          : GPU use (%): 0
+GPU[2]          : GFX Activity: 3114103535
+GPU[3]          : GPU use (%): 0
+GPU[3]          : GFX Activity: 4026776444
+GPU[4]          : GPU use (%): 0
+GPU[4]          : GFX Activity: 1224255679
+GPU[5]          : GPU use (%): 0
+GPU[5]          : GFX Activity: 1191191242
+GPU[6]          : GPU use (%): 0
+GPU[6]          : GFX Activity: 1184652679
+GPU[7]          : GPU use (%): 0
+GPU[7]          : GFX Activity: 2145209382
+==========================================================================================
+================================== Memory Usage (Bytes) ==================================
+GPU[0]          : VRAM Total Memory (B): 206141652992
+GPU[0]          : VRAM Total Used Memory (B): 297611264
+GPU[1]          : VRAM Total Memory (B): 206141652992
+GPU[1]          : VRAM Total Used Memory (B): 297623552
+GPU[2]          : VRAM Total Memory (B): 206141652992
+GPU[2]          : VRAM Total Used Memory (B): 297623552
+GPU[3]          : VRAM Total Memory (B): 206141652992
+GPU[3]          : VRAM Total Used Memory (B): 297623552
+GPU[4]          : VRAM Total Memory (B): 206141652992
+GPU[4]          : VRAM Total Used Memory (B): 297623552
+GPU[5]          : VRAM Total Memory (B): 206141652992
+GPU[5]          : VRAM Total Used Memory (B): 297623552
+GPU[6]          : VRAM Total Memory (B): 206141652992
+GPU[6]          : VRAM Total Used Memory (B): 297623552
+GPU[7]          : VRAM Total Memory (B): 206141652992
+GPU[7]          : VRAM Total Used Memory (B): 297623552
+==========================================================================================
+================================== End of ROCm SMI Log ===================================
+```
+
+## 2. 运行示例
+
+### 2.1 使用 Megatron-Swift 全量微调 Qwen3.5 模型
+AMD GPU 显存相对较大，因此可以通过同时对以下参数进行联合调优，以提升训练吞吐性能。
+- 并行度调优（TP/PP/EP等）：GPU 单卡显存较大使得用户可以尽可能减小并行度切分带来的通信开销（优先级 PP/EP > TP）
+- 显存允许的情况下关闭 optimizer cpu offload：设置 `--optimizer_cpu_offload false`
+- 显存允许的情况下调整 activation/gradient checkpointing：设置 `--recompute_granularity none`，或者 `--recompute_granularity selective` 配合 `--recompute_modules` 进行细粒度的控制
+- 对于 MoE 模型，建议设置 `export NVTE_USE_GROUPED_GEMM_TRITON=1` 以使用 triton 实现的 grouped gemm kernel
+- 对于带有 GatedDeltaNet 结构的模型，建议设置 `USE_MCORE_GDN=1` 使用 mcore 的实现版本
+- 为避免在某些 AMD GPU 上可能出现的问题，保证性能更稳定，建议设置 `export HSA_NO_SCRATCH_RECLAIM=1`
+
+单机训练：
+
+```bash
+export HSA_NO_SCRATCH_RECLAIM=1
+export NVTE_USE_GROUPED_GEMM_TRITON=1
+
+output_dir=${PWD}/megatron_output/Qwen3.5-35B-A3B
+mkdir -p ${output_dir}
+current_time=$(date "+%Y.%m.%d-%H.%M.%S")
+log_file=${output_dir}/"1node_full_megatron_Qwen3.5-35B-A3B_${current_time}.log"
+
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+NPROC_PER_NODE=8 \
+MAX_PIXELS=1003520 \
+VIDEO_MAX_PIXELS=50176 \
+FPS_MAX_FRAMES=12 \
+SKIP_MULTIMODAL_MTP_VALIDATION=1 \
+USE_MCORE_GDN=1 \
+megatron sft \
+    --model Qwen/Qwen3.5-35B-A3B \
+    --dataset 'AI-ModelScope/LongAlpaca-12k' \
+    --save_safetensors true \
+    --load_from_cache_file true \
+    --tuner_type full \
+    --add_non_thinking_prefix true \
+    --split_dataset_ratio 0.01 \
+    --tensor_model_parallel_size 1 \
+    --pipeline_model_parallel_size 1 \
+    --expert_model_parallel_size 8 \
+    --sequence_parallel true \
+    --moe_permute_fusion true \
+    --moe_grouped_gemm true \
+    --moe_shared_expert_overlap true \
+    --moe_aux_loss_coeff 1e-6 \
+    --moe_expert_capacity_factor 2 \
+    --micro_batch_size 1 \
+    --global_batch_size 8 \
+    --recompute_granularity selective \
+    --recompute_modules core_attn mlp moe \
+    --gradient_accumulation_fusion false \
+    --num_train_epochs 500 \
+    --group_by_length true \
+    --finetune true \
+    --freeze_llm false \
+    --freeze_vit false \
+    --freeze_aligner false \
+    --cross_entropy_loss_fusion true \
+    --lr 1e-5 \
+    --lr_warmup_fraction 0.05 \
+    --min_lr 1e-6 \
+    --weight_decay 0.1 \
+    --adam_beta2 0.95 \
+    --eval_steps 500 \
+    --save_steps 500 \
+    --save_total_limit 10 \
+    --logging_steps 1 \
+    --max_length 16384 \
+    --dataloader_num_workers 8 \
+    --dataset_num_proc 8 \
+    --no_save_optim true \
+    --no_save_rng true \
+    --optimizer_cpu_offload false \
+    --attention_backend flash \
+    --padding_free false \
+    --output_dir ${output_dir} \
+    2>&1 | tee ${log_file}
+```
+
+多机训练：
+
+```bash
+export NNODES=2  # 此处以 2 节点为例
+export NODE_RANK=0  # 主节点设置为 0，从节点设置为 1
+export MASTER_ADDR=<MASTER_NODE_IP>  # 根据主节点 ip 设置
+export MASTER_PORT=29500  # 设置通信端口
+export NCCL_SOCKET_IFNAME=ens50f1np1  # 根据机器实际通信网口名设置，可通过 ifconfig 查看
+export GLOO_SOCKET_IFNAME=ens50f1np1  # 根据机器实际通信网口名设置，可通过 ifconfig 查看
+export NCCL_IB_HCA=mlx5_0,mlx5_1,mlx5_2,mlx5_3  # 根据实际IB网卡名设置，可通过 ibv_devices 查看
+export NCCL_IB_GID_INDEX=3
+
+# 训练脚本主体：参照单机训练脚本
+...
+```
+
+### 2.2 使用 Megatron-Swift 对 Qwen3.5 模型做强化学习训练
+
+```bash
+# 单机训练样例
+export HSA_NO_SCRATCH_RECLAIM=1
+export NVTE_USE_GROUPED_GEMM_TRITON=1
+
+SYSTEM_PROMPT="""You are a helpful math assistant. Solve the problem step by step and put your final answer within \\boxed{}."""
+
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+NPROC_PER_NODE=8 \
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+megatron rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen3.5-35B-A3B \
+    --save_safetensors true \
+    --enable_thinking false \
+    --merge_lora true \
+    --context_parallel_size 1 \
+    --tensor_model_parallel_size 1 \
+    --expert_model_parallel_size 8 \
+    --pipeline_model_parallel_size 1 \
+    --moe_permute_fusion true \
+    --dataset open-r1/DAPO-Math-17k-Processed \
+    --system "$SYSTEM_PROMPT" \
+    --num_train_epochs 1 \
+    --global_batch_size 64 \
+    --micro_batch_size 1 \
+    --steps_per_generation 2 \
+    --num_generations 8 \
+    --reward_funcs accuracy \
+    --use_vllm true \
+    --vllm_mode colocate \
+    --vllm_gpu_memory_utilization 0.5 \
+    --vllm_tensor_parallel_size 2 \
+    --vllm_max_model_len 9192 \
+    --max_length 1000 \
+    --max_completion_length 8192 \
+    --tuner_type lora \
+    --target_modules all-linear \
+    --lr 5e-5 \
+    --bf16 true \
+    --beta 0.00 \
+    --epsilon 0.2 \
+    --epsilon_high 0.28 \
+    --dynamic_sample false \
+    --overlong_filter true \
+    --loss_type grpo \
+    --sleep_level 1 \
+    --offload_model true \
+    --offload_bridge false \
+    --offload_optimizer true \
+    --logging_steps 1 \
+    --recompute_granularity none \
+    --gradient_accumulation_fusion false \
+    --finetune \
+    --dataloader_num_workers 8 \
+    --dataset_num_proc 8 \
+    --no_save_optim \
+    --no_save_rng \
+    --save_steps 20 \
+    --attention_backend flash \
+    --moe_expert_capacity_factor 2 \
+    --temperature 1.0 \
+    --padding_free false \
+    --sequence_parallel true \
+    --log_completions true \
+    --report_to tensorboard
+```
+
+## 已知问题
+- 强化学习训练：
+  - 在强化学习训练中，如果使用 vLLM 作为推理引擎，需要 vLLM>=0.11.0。建议使用 ROCm7.0 或者我们提供的镜像以避免出现 sleep mode memory leak 问题。
+  - 在使用 [Ray Megatron](../../source/Instruction/Ray.md) 而非 `torchrun` 的方式进行多 GPU/Node 训练时，不设置 `CUDA_VISIBLE_DEVICES`/`HIP_VISIBLE_DEVICES`等，以避免冲突问题。
+- MoE 模型训练：
+  - MoE 模型建议增加环境变量 `NVTE_USE_GROUPED_GEMM_TRITON=1` 和 `--gradient_accumulation_fusion false` 以避免偶发的GPU卡死问题。
@@ -0,0 +1,211 @@
+# Elastic
+
+
+
+## 安装依赖
+
+集群部署K8S,并在集群中部署DLrover,[DLRover](https://github.com/intelligent-machine-learning/dlrover),
+`pip install dlrover && pip install tornado && pip install kubernetes && pip install ms-swift`
+
+经过反复测试验证的训练镜像中的其它依赖以及版本：
+deepspeed 0.16.5（需参考https://github.com/deepspeedai/DeepSpeed/pull/7585/files 修复universal checkpoint 相关问题）
+pytorch 2.6.0
+
+
+## 如何启动
+
+通过在`--callbacks`中添加`deepspeed_elastic`（可选`graceful_exit`）启用弹性训练，并配置DeepSpeed弹性参数。
+命令组成=dlrover-run +dlrover 命令参数+swift 启动命令 +swift参数,dlrover-run除自定义的参数外，其他参数与torchrun一致；
+dlrover-run 参数如下:
+```
+usage: dlrover-run [-h] [--nnodes NNODES] [--nproc-per-node NPROC_PER_NODE]
+                   [--rdzv-backend RDZV_BACKEND] [--rdzv-endpoint RDZV_ENDPOINT] [--rdzv-id RDZV_ID]
+                   [--rdzv-conf RDZV_CONF] [--standalone] [--max-restarts MAX_RESTARTS]
+                   [--monitor-interval MONITOR_INTERVAL] [--start-method {spawn,fork,forkserver}]
+                   [--role ROLE] [-m] [--no-python] [--run-path] [--log-dir LOG_DIR] [-r REDIRECTS]
+                   [-t TEE] [--local-ranks-filter LOCAL_RANKS_FILTER] [--node-rank NODE_RANK]
+                   [--master-addr MASTER_ADDR] [--master-port MASTER_PORT] [--local-addr LOCAL_ADDR]
+                   [--logs-specs LOGS_SPECS] [--precheck {0,1,2}] [--node_unit NODE_UNIT]
+                   [--auto_config] [--auto_tunning] [--exclude-straggler] [--save_at_breakpoint]
+                   [--accelerator {nvidia.com/gpu,ascend-npu}] [--training_port TRAINING_PORT]
+                   [--switchbox-check] [--box-pairs PAIR [PAIR ...]] [--min-bandwidth MIN_BANDWIDTH]
+                   [--min-channels MIN_CHANNELS] [--numa-affinity] [--network-check]
+                   [--comm-perf-test] [--ucp_device_type UCP_DEVICE_TYPE]
+                   training_script
+
+```
+在弹性训练中我们需要关注的参数为：
+
+--nnodes NNODES       Number of nodes, or the range of nodes in form
+                        <minimum_nodes>:<maximum_nodes>.
+
+--nproc-per-node NPROC_PER_NODE   Number of processes per node.
+示例:
+
+```bash
+model=your model path
+dataset=your dataset
+output= your output dir
+export CUDA_VISIBLE_DEVICES=0 根据实际使用的GPU情况设置
+deepspeed_config_or_type=deepspeed类型或者配置文件的路径，如 zero1 或者/xxx/ms-swift/swift/llm/ds_config/zero1.json
+
+dlrover-run --nnodes 1:$NODE_NUM --nproc_per_node=1  \
+/opt/conda/lib/python3.10/site-packages/swift/cli/sft.py --model $model \
+--model_type qwen3 \
+--tuner_type lora  \
+--torch_dtype bfloat16 \
+--dataset $dataset \
+--num_train_epochs 4 \
+--per_device_train_batch_size 1 \
+--per_device_eval_batch_size 1 \
+--learning_rate 5e-7 \
+--gradient_accumulation_steps 8 \
+--eval_steps 500 \
+--save_steps 10 \
+--save_total_limit 20 \
+--logging_steps 1 \
+--output_dir $output \
+--warmup_ratio 0.01 \
+--dataloader_num_workers 4 \
+--temperature 1.0 \
+--system 'You are a helpful assistant.' \
+--lora_rank 8 \
+--lora_alpha 32 \
+--target_modules all-linear \
+--dataset_num_proc 1 \
+--use_flash_ckpt true \
+--callbacks deepspeed_elastic graceful_exit \
+--deepspeed $deepspeed_config_or_type \
+```
+
+## 配置文件示例
+默认情况下的zero1为以下示例配置,
+
+```json
+{
+    "fp16": {
+        "enabled": "auto",
+        "loss_scale": 0,
+        "loss_scale_window": 1000,
+        "initial_scale_power": 16,
+        "hysteresis": 2,
+        "min_loss_scale": 1
+    },
+
+    "bf16": {
+        "enabled": "auto"
+    },
+
+    "zero_optimization": {
+        "stage": 1,
+        "offload_optimizer": {
+            "device": "none",
+            "pin_memory": true
+        },
+        "allgather_partitions": true,
+        "allgather_bucket_size": 2e8,
+        "overlap_comm": false,
+        "reduce_scatter": true,
+        "reduce_bucket_size": 2e8,
+        "contiguous_gradients": true
+    },
+
+    "gradient_accumulation_steps": "auto",
+    "gradient_clipping": "auto",
+    "steps_per_print": 2000,
+    "train_batch_size": "auto",
+    "train_micro_batch_size_per_gpu": "auto",
+    "wall_clock_breakdown": false,
+    "elasticity": {
+        "ignore_non_elastic_batch_info": true,
+        "enabled": true,
+        "max_train_batch_size": 8,
+        "micro_batch_sizes": [
+          4,
+          2
+        ],
+        "min_gpus": 1,
+        "max_gpus": 4,
+        "min_time": 20,
+        "version": 0.1
+      }
+}
+```
+
+如果用户需要自定义，可以在启动命令中deepspeed_config_or_type指定自定义的zero1.json的存放路径,其中弹性相关的配置为：
+```json
+...
+
+  "elasticity": {
+        "ignore_non_elastic_batch_info": true,
+        "enabled": true,
+        "max_train_batch_size": 8,
+        "micro_batch_sizes": [
+          4,
+          2
+        ],
+        "min_gpus": 1,
+        "max_gpus": 4,
+        "min_time": 20,
+        "version": 0.1
+      }
+```
+
+- ignore_non_elastic_batch_info：代表在elasticity里的配置会忽略外层的batch_size相关的配置，训练过程中会根据实际的训练进程个数实时修改batch_size等相关的参数
+计算原则为：
+ global-training-batch-size = micro-batch-size * gradient-accumulation-steps * world-size
+- max_train_batch_size：最大batch_size数
+- micro_batch_sizes：elasticity下允许的每卡micro-batch size列表，相当于train_micro_batch_size_per_gpu的候选值
+- min_gpus：最小gpu数目
+- max_gpus：最大gpu数目
+更详细的内容见：[Deepspeed](https://www.deepspeed.ai/docs/config-json/#elastic-training-config-v01-and-v02)
+
+
+## 启动训练
+
+```yaml
+---
+apiVersion: elastic.iml.github.io/v1alpha1
+kind: ElasticJob
+metadata:
+  name: deepspeed-elastic-swift
+  namespace: dlrover
+spec:
+  distributionStrategy: AllreduceStrategy
+  optimizeMode: single-job
+  replicaSpecs:
+    worker:
+      replicas: 1 #【这里需要与启动命令中的--nnodes NNODES的最大值一致】
+      template:
+        spec:
+          restartPolicy: Never
+          containers:
+            - name: main
+              image: #【训练镜像，需要安装deepspeed,dlrover 和swift 】
+              imagePullPolicy: IfNotPresent
+              command:
+                - /bin/bash
+                - -c
+                - sh start.sh # 启动脚本
+              resources:
+                limits:
+                  cpu: '8'
+                  memory: 16Gi
+                  nvidia.com/gpu: '1'
+              volumeMounts:
+                - mountPath: /model
+                  name: volume-model
+                - mountPath: /dev/shm
+                  name: volume-shm
+          restartPolicy: Never
+          volumes:
+            - hostPath:
+                path: /model
+                type: Directory
+              name: volume-model
+            - emptyDir:
+                medium: Memory
+                sizeLimit: 200Gi
+              name: volume-shm
+
+```
@@ -0,0 +1,211 @@
+# Embedding训练
+
+SWIFT已经支持Embedding模型的训练，包括纯文本和多模态两个类型。目前已经支持的模型有：
+
+1. modernbert embedding模型
+   - [ModelScope](https://modelscope.cn/models/iic/gte-modernbert-base) [Hugging Face](https://huggingface.co/Alibaba-NLP/gte-modernbert-base)
+2. gte embedding模型
+   - 1.5B: [ModelScope](https://www.modelscope.cn/models/iic/gte_Qwen2-1.5B-instruct) [Hugging Face](https://huggingface.co/Alibaba-NLP/gte-Qwen2-1.5B-instruct)
+   - 7B: [ModelScope](https://www.modelscope.cn/models/iic/gte_Qwen2-7B-instruct) [Hugging Face](https://huggingface.co/Alibaba-NLP/gte-Qwen2-7B-instruct)
+3. gme embedding模型
+   - 2B: [ModelScope](https://www.modelscope.cn/models/iic/gme-Qwen2-VL-2B-Instruct) [Hugging Face](https://huggingface.co/Alibaba-NLP/gme-Qwen2-VL-2B-Instruct)
+   - 7B: [ModelScope](https://www.modelscope.cn/models/iic/gme-Qwen2-VL-7B-Instruct) [Hugging Face](https://huggingface.co/Alibaba-NLP/gme-Qwen2-VL-7B-Instruct)
+4. qwen3-embedding模型
+   - 0.6B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-Embedding-0.6B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-Embedding-0.6B)
+   - 4B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-Embedding-4B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-Embedding-4B)
+   - 8B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-Embedding-8B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-Embedding-8B)
+5. qwen3-vl-embedding模型
+   - 2B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-VL-Embedding-2B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-VL-Embedding-2B)
+   - 8B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-VL-Embedding-8B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-VL-Embedding-8B)
+
+
+开发者可以自行集成自己的模型，模型forward输出值需要满足：
+
+```text
+{"last_hidden_state": some-embedding-tensor}
+```
+
+返回值是一个json，具有`last_hidden_state` key，value是embedding tensor即可，输入部分可以使用我们已经支持的template。用户也可以通过指定
+
+```shell
+   --task_type embedding
+```
+参数来将任意一个其他模型转换为embedding模型进行训练。
+
+需要注意的是，SWIFT目前支持的embedding模型均为符合纯文本或多模态LLM，目前并不支持CLIP类型的模型训练。
+
+此外，SWIFT支持的所有embedding模型在模型forward最后都增加了normalize，如自行增加新模型请注意增加normalize层。
+
+## loss
+
+目前SWIFT支持的Embedding模型可以使用的loss有：
+
+- cosine_similarity: cosine相似度loss，计算两个embedding的相似度，并根据label的值拟合，实际为MSE loss
+- contrastive: 可调margin的对比学习loss，label仅支持0和1两个值
+- online_contrastive: 考虑hard negative和hard positive部分的contrastive loss，label仅支持0和1两个值
+- infonce: 在同一个batch中不同row两两计算cosine相似度，并使row内部相似度最大，不同row相似度最小，不需要label
+
+loss的源代码可以在[这里](https://github.com/modelscope/ms-swift/blob/main/swift/loss/mapping.py)找到。
+
+## 数据集格式
+
+> 注：
+> 1. `<image>`标签可以出现在`messages`/`positive_messages`/`negative_messages`的任意位置；它们各自拥有独立的`images`/`positive_images`/`negative_images`字段用于提供图片路径或URL。
+> 2. 不再需要跨字段的“对应顺序”。对齐规则为：`images`的长度等于`messages`中`<image>`标签的数量；`positive_images`与`negative_images`均为“list of list”，其外层长度分别等于`positive_messages`与`negative_messages`的长度；并且外层每一项的内层列表长度等于该条消息序列中`<image>`标签的数量。
+> 3. `messages`代表anchor样本（anchor sample）；`positive_messages`/`negative_messages`为“list of messages”（因此多一层`[]`）；相应地，`positive_images`/`negative_images`也多一层`[]`并与之逐项对齐。
+> 4. 也支持`<video>`, `<audio>`标签；可按相同规则分别通过`videos`/`positive_videos`/`negative_videos`与`audios`/`positive_audios`/`negative_audios`提供对应模态数据。
+> 5. 当前约束：`positive_messages`的外层长度必须为1（即仅提供一个positive样本）；对应地，`positive_images`的外层长度也必须为1。
+
+### cosine_similarity loss对应的格式
+
+```json lines
+# LLM
+{"messages": [{"role": "user", "content": "sentence1"}], "positive_messages": [[{"role": "user", "content": "sentence2"}]], "label": 0.8}
+# MLLM
+{"messages": [{"role": "user", "content": "<image>"}], "images": ["/some/images1.jpg"],"positive_messages": [[{"role": "user", "content": "<image>sentence"}]], "positive_images": [["/some/images2.jpg"]], "label": 0.7}
+{"messages": [{"role": "user", "content": "sentence1"}], "positive_messages": [[{"role": "user", "content": "<image>sentence2"}]], "positive_images": [["/some/images.jpg"]], "label": 0.7}
+```
+
+
+### contrastive/online_contrastive loss对应的格式
+
+```json lines
+# LLM
+{"messages": [{"role": "user", "content": "sentence1"}], "positive_messages": [[{"role": "user", "content": "sentence2"}]], "label": 1}
+# MLLM
+{"messages": [{"role": "user", "content": "<image>"}], "images": ["/some/images1.jpg"], "positive_messages": [[{"role": "user", "content": "<image>sentence"}]], "positive_images": [["/some/images2.jpg"]], "label": 1}
+{"messages": [{"role": "user", "content": "sentence1"}], "positive_messages": [[{"role": "user", "content": "<image>sentence2"}]], "positive_images": [["/some/images.jpg"]], "label": 0}
+```
+
+评测的指标分别是两个embedding的欧式距离、点积等的pearson系数以及spearman系数，共八个指标。
+
+### infonce 格式
+
+```json lines
+# LLM
+{"messages": [{"role": "user", "content": "sentence1"}], "positive_messages": [[{"role": "user", "content": "sentence2"}]]}
+# MLLM
+{"messages": [{"role": "user", "content": "<image>"}], "images": ["/some/images.jpg"], "positive_messages": [[{"role": "user", "content": "sentence"}]]}
+{"messages": [{"role": "user", "content": "<image>sentence1"}], "images": ["/some/images.jpg"], "positive_messages": [[{"role": "user", "content": "<image>sentence2"}]], "positive_images": [["/some/positive_images.jpg"]], "negative_messages": [[{"role": "user", "content": "<image><image>sentence3"}], [{"role": "user", "content": "<image>sentence4"}]], "negative_images": [["/some/negative_images1.jpg", "/some/negative_images2.jpg"], ["/some/negative_images3.jpg"]]}
+```
+
+infonce loss支持几个环境变量：
+1. `INFONCE_TEMPERATURE`： temperature参数，不设置的话默认值是0.1
+2. `INFONCE_USE_BATCH`： 使用sample内部的`negative_messages`（hard negative样例）还是使用一个batch内其他样本作为in-batch negatives；默认为True，表示使用batch内部的样本作为负例
+3. `INFONCE_HARD_NEGATIVES`： hard negatives的数量；如果不设置会使用数据中提供的所有`negative_messages`。由于长度未必一致，因此会采用for循环计算loss（计算会慢）。若设置为某个数值，则不足会随机采样补齐，超长会选用前`INFONCE_HARD_NEGATIVES`个
+4. `INFONCE_MASK_FAKE_NEGATIVE`： mask掉假negative。默认为False，开启时会判断 `positive_similarity + INFONCE_FAKE_NEG_MARGIN`，比该阈值大的样本相似度会被设置为 `-inf`，以防止正样本泄露问题
+5. `INFONCE_FAKE_NEG_MARGIN`：假负样本屏蔽的边际，默认 `0.1`。
+6. `INFONCE_INCLUDE_QQ`：是否在分母中加入 q–q 分量（query 间相似度）作为负例，默认 `False`。
+7. `INFONCE_INCLUDE_DD`：是否在分母中加入 d–d 分量（正样本文档与 batch 内所有文档的相似度）作为负例，默认 `False`。
+
+> 也可以在数据集中将hard negatives数量设置为数量相等，这样即使不设置也不会使用for循环方式，加快计算速度
+> `negative_messages`也可以不提供。在这种情况下，保持`INFONCE_USE_BATCH=True`，会使用一个batch内部的其他样本作为负例
+
+infonce loss的评测会有下面几个指标：
+- mean_neg 所有hard_negative的平均值
+- mean_pos 所有positive的平均值
+- margin positive-max_hard_negative的平均值
+
+## 训练
+
+SWIFT提供的脚手架训练脚本：
+
+- [Qwen3-Embedding/Qwen3-VL-Embedding模型](https://github.com/modelscope/ms-swift/blob/main/examples/train/embedding/qwen3)
+- [GME模型](https://github.com/modelscope/ms-swift/blob/main/examples/train/embedding/train_gme.sh)
+
+## 推理
+
+SWIFT已经支持GME、GTE、Qwen3-Embedding模型的部署，请查看[这里](https://github.com/modelscope/ms-swift/blob/main/examples/deploy/embedding/client.py)。
+- 推理脚本参考[这里](https://github.com/modelscope/ms-swift/blob/main/examples/infer/demo_embedding.py)。
+
+也可以使用原模型的代码进行推理：
+
+https://www.modelscope.cn/models/iic/gte_Qwen2-7B-instruct
+
+https://www.modelscope.cn/models/iic/gme-Qwen2-VL-7B-Instruct
+
+如果使用了其他模型从0训练embedding（例如，原版`qwen2-vl`模型+`--task_type embedding`），也可以使用gme的推理代码，但请注意：
+
+https://www.modelscope.cn/models/iic/gme-Qwen2-VL-7B-Instruct/file/view/master/gme_inference.py?status=1#L111
+
+这里的模板请修改为模型自身的template，以免最后的embedding对不上。需要额外注意的是，gme模型的template和`qwen2-vl`或`qwen2.5-vl`系列的chatml template并不相同，其推理代码最后的结束字符是`<|endoftext|>`而非`<|im_end|>`.
+
+## 高级功能
+
+- Qwen3-Embedding 自定义 Instruction：
+  - 默认无 Instruction，输入模板为：`{Query}<|endoftext|>`。
+  - 通过在 system message 中添加 Instruction，可将输入改为：`{Instruction} {Query}<|endoftext|>`。
+  - 示例：
+
+```json lines
+{"messages": [
+  {"role": "system", "content": "请用中文回答，并输出简洁要点"},
+  {"role": "user", "content": "介绍一下Qwen3-Embedding"}
+]}
+```
+
+> 说明：Qwen3-Embedding 模板会将 system 内容前置拼接到首条 user 消息中，并使用 `<|endoftext|>` 作为结束标记。
+
+### 转换前后示例
+
+- 不加 Instruction：
+
+  输入数据（messages）：
+
+  ```json lines
+  {"messages": [
+    {"role": "user", "content": "北京明天天气如何？"}
+  ]}
+  ```
+
+  模板转换后（送入模型的实际文本）：
+
+  ```text
+  北京明天天气如何？<|endoftext|>
+  ```
+
+- 加 Instruction：
+
+  输入数据（messages，包含system）：
+
+  ```json lines
+  {"messages": [
+    {"role": "system", "content": "请使用中文、精炼输出要点"},
+    {"role": "user", "content": "北京明天天气如何？"}
+  ]}
+  ```
+
+  模板转换后（送入模型的实际文本）：
+
+  ```text
+  请使用中文、精炼输出要点 北京明天天气如何？<|endoftext|>
+  ```
+
+- positive/negative 同理：
+
+  若在某个 positive/negative 的消息序列中提供 system，则会将该 system 内容前置到该序列首条 user 内容之前；未提供 system 则不前置。
+
+  输入数据（包含一个 positive 带 system，和一个 negative 无 system）：
+
+  ```json lines
+  {
+    "messages": [
+      {"role": "user", "content": "Anchor"}
+    ],
+    "positive_messages": [[
+      {"role": "system", "content": "指令"},
+      {"role": "user", "content": "Positive"}
+    ]],
+    "negative_messages": [[
+      {"role": "user", "content": "Negative"}
+    ]]
+  }
+  ```
+
+  模板转换后（送入模型的实际文本）：
+
+  ```text
+  Anchor<|endoftext|>
+  指令 Positive<|endoftext|>
+  Negative<|endoftext|>
+  ```
@@ -0,0 +1,145 @@
+# GRPO代码训练
+本文档介绍如何使用GRPO对模型进行代码训练
+
+模型：[Qwen/Qwen2.5-7B-Instruct](https://www.modelscope.cn/models/Qwen/Qwen2.5-VL-7B-Instruct)
+
+数据集：[open-r1/verifiable-coding-problems-python-10k](https://www.modelscope.cn/datasets/open-r1/verifiable-coding-problems-python-10k/dataPeview)
+
+数据集样例
+```json
+{
+  "problem": "Solve the following coding problem using the programming language python: Polycarp has $n$ different binary words. A word called binary if it contains only characters '0' and '1'. For example, these words are binary: \"0001\", \"11\", \"0\" and \"0011100\". Polycarp wants to offer his set of $n$ binary words to play a game \"words\". In this game, players name words and each next word (starting from the second) must start with the last character of the previous word. The first word can be any. For example, these sequence of words can be named during the game: \"0101\", \"1\", \"10\", \"00\", \"00001\". Word reversal is the operation of reversing the order of the characters. For example, the word \"0111\" after the reversal becomes \"1110\", the word \"11010\" after the reversal becomes \"01011\". Probably, Polycarp has such a set of words that there is no way to put them in the order correspondent to the game rules. In this situation, he wants to reverse some words from his set so that: the final set of $n$ words still contains different words (i.e. all words are unique); there is a way to put all words of the final set of words in the order so that the final sequence of $n$ words is consistent with the game rules. Polycarp wants to reverse minimal number of words. Please, help him. -----Input----- The first line of the input contains one integer $t$ ($1 \\le t \\le 10^4$) — the number of test cases in the input. Then $t$ test cases follow. The first line of a test case contains one integer $n$ ($1 \\le n \\le 2\\cdot10^5$) — the number of words in the Polycarp's set. Next $n$ lines contain these words. All of $n$ words aren't empty and contains only characters '0' and '1'. The sum of word lengths doesn't exceed $4\\cdot10^6$. All words are different. Guaranteed, that the sum of $n$ for all test cases in the input doesn't exceed $2\\cdot10^5$. Also, guaranteed that the sum of word lengths for all test cases in the input doesn't exceed $4\\cdot10^6$. -----Output----- Print answer for all of $t$ test cases in the order they appear. If there is no answer for the test case, print -1. Otherwise, the first line of the output should contain $k$ ($0 \\le k \\le n$) — the minimal number of words in the set which should be reversed. The second line of the output should contain $k$ distinct integers — the indexes of the words in the set which should be reversed. Words are numerated from $1$ to $n$ in the order they appear. If $k=0$ you can skip this line (or you can print an empty line). If there are many answers you can print any of them. -----Example----- Input 4 4 0001 1000 0011 0111 3 010 101 0 2 00000 00001 4 01 001 0001 00001 Output 1 3 -1 0 2 1 2 The input will be stdin and you should print your solution to stdout Now solve the problem and return the code.",
+  "verification_info": {
+    "language": "python",
+    "test_cases": [
+      {
+        "input": "4\n4\n0001\n1000\n0011\n0111\n3\n010\n101\n0\n2\n00000\n00001\n4\n01\n001\n0001\n00001\n",
+        "output": "1\n3 \n-1\n0\n\n2\n1 2 \n",
+        "type": "stdin_stdout"
+      }
+    ]
+  }
+}
+```
+
+`verification_info` 提供了程序语言以及测试用例，其中包含输入和预期的输出。
+
+
+## 奖励函数
+使用`code_reward`和`code_format`奖励进行训练，实现细节见[代码](https://github.com/modelscope/ms-swift/blob/main/examples/train/grpo/plugin/plugin.py)
+
+- `code_reward`通过[e2b](https://e2b.dev/)或[judge0](https://judge0.com/)执行生成的代码，根据数据集中的测试用例对代码进行验证给出奖励值。
+- `code_format`要求模型输出包含代码块的格式化回答。
+
+注：当前通过e2b执行代码仅支持python语言，如需执行其他语言，可以使用judge0执行（[judge0支持语言列表](https://github.com/judge0/judge0?tab=readme-ov-file#supported-languages)）。
+
+## 训练脚本
+### e2b
+- 在[e2b](https://e2b.dev/dashboard)注册获取E2B_API_KEY，并设置为环境变量。
+- `--reward_funcs`添加`external_code_reward`作为奖励函数。
+- `--external_plugins`设置为plugin.py的路径。
+首先拉起 vLLM server
+```bash
+CUDA_VISIBLE_DEVICES=7 \
+swift rollout \
+  --model Qwen/Qwen2.5-7B-Instruct \
+  --vllm_enable_lora true \
+  --vllm_max_lora_rank 16
+```
+
+```bash
+E2B_API_KEY=xxx \
+WANDB_API_KEY=xxx \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6 \
+NPROC_PER_NODE=7 \
+swift rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen2.5-7B-Instruct \
+    --external_plugins examples/train/grpo/plugin/plugin.py \
+    --reward_funcs external_code_reward external_code_format \
+    --reward_weights 1.0 0.1 \
+    --vllm_mode server \
+    --use_vllm true \
+    --vllm_server_host 127.0.0.1 \
+    --vllm_server_port 8000 \
+    --tuner_type lora \
+    --lora_rank 16 \
+    --lora_alpha 32 \
+    --torch_dtype bfloat16 \
+    --dataset 'open-r1/verifiable-coding-problems-python-10k' \
+    --load_from_cache_file true \
+    --max_completion_length 2048 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 2 \
+    --per_device_eval_batch_size 2 \
+    --learning_rate 1e-6 \
+    --gradient_accumulation_steps 1 \
+    --eval_steps 200 \
+    --save_steps 200 \
+    --save_total_limit 2 \
+    --logging_steps 5 \
+    --max_length 4096 \
+    --output_dir output \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --dataset_num_proc 4 \
+    --num_generations 14 \
+    --temperature 0.9 \
+    --system 'examples/train/grpo/prompt.txt' \
+    --deepspeed zero2 \
+    --log_completions true \
+    --report_to wandb
+```
+
+### judge0
+- 设置环境变量：
+    - （必需）JUDGE0_ENDPOINT: judge0访问地址。
+    - （可选）JUDGE0_X_AUTH_TOKEN: judge0访问Token。
+- `--reward_funcs`添加`external_code_reward_by_judge0`作为奖励函数。
+- `--external_plugins`设置为plugin.py的路径。
+
+```bash
+JUDGE0_ENDPOINT=xxx \
+JUDGE0_X_AUTH_TOKEN=xxx \
+WANDB_API_KEY=xxx \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6 \
+NPROC_PER_NODE=7 \
+swift rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen2.5-7B-Instruct \
+    --external_plugins examples/train/grpo/plugin/plugin.py \
+    --reward_funcs external_code_reward_by_judge0 external_code_format \
+    --reward_weights 1.0 0.1 \
+    --vllm_mode server \
+    --use_vllm true \
+    --vllm_server_host 127.0.0.1 \
+    --vllm_server_port 8000 \
+    --tuner_type lora \
+    --torch_dtype bfloat16 \
+    --dataset 'open-r1/verifiable-coding-problems-python-10k' \
+    --load_from_cache_file true \
+    --max_completion_length 2048 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 2 \
+    --per_device_eval_batch_size 2 \
+    --learning_rate 1e-6 \
+    --gradient_accumulation_steps 1 \
+    --eval_steps 200 \
+    --save_steps 200 \
+    --save_total_limit 2 \
+    --logging_steps 5 \
+    --max_length 4096 \
+    --output_dir output \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --dataset_num_proc 4 \
+    --num_generations 14 \
+    --temperature 0.9 \
+    --system 'examples/train/grpo/prompt.txt' \
+    --deepspeed zero2 \
+    --log_completions true \
+    --report_to wandb
+```
+
+训练奖励曲线图
+![训练奖励曲线图](../../resources/grpo_code.png)
@@ -0,0 +1,314 @@
+# 多模态GRPO完整实验流程
+本文介绍如何使用SWIFT GRPO进行多模态模型和任务的训练。目标是对多个多模态任务进行训练，提升任务精度，任务定义和训练参数等参考了 [R1-V](https://github.com/Deep-Agent/R1-V.git) 和 [open-r1-multimodal](https://github.com/EvolvingLMMs-Lab/open-r1-multimodal.git)
+
+
+
+## ClevrCount 任务
+### 任务与数据集定义
+本任务从clevr_cogen_a_train数据集出发，模型的目标是输出图像中包含的物体数量，因此，我们定义数据集如下：
+
+```python
+class ClevrPreprocessor(ResponsePreprocessor):
+
+    def preprocess(self, row: Dict[str, Any]) -> Dict[str, Any]:
+        query = row.get('query', '')
+        query = f"""{query} Output the thinking process in <think> </think> and
+ final answer (number) in <answer> </answer> tags."""
+        row.update({'query': query})
+        return super().preprocess(row)
+
+
+register_dataset(
+    DatasetMeta(
+        ms_dataset_id='AI-ModelScope/clevr_cogen_a_train',
+        subsets=[
+            SubsetDataset(
+                name='default',
+                subset='default',
+                split=['train'],
+            ),
+        ],
+        preprocess_func=ClevrPreprocessor(),
+        tags=['qa', 'math']))
+
+```
+这里重新定义dataset preprocessor的目的是修改query。数据集示例样本如下，包含messages,images和solution字段，solution会送入后续的奖励函数中，而messages和images则会作为模型输入。
+- 注意：`{'role': 'assistant', 'content': '<answer> 3 </answer>'}`将会在GRPOTrainer中被移除，可以忽略。'solution'字段将会透传入ORM中。在自定义数据集时，'images'字段组织成`["image_path1", "image_path2"]`即可。
+
+```json
+{
+    "images": ["image_path1", "image_path2"],
+    "messages": [
+        {
+            "role": "user",
+            "content": "How many items are there in the image? Output the thinking process in <think> </think> and \n final answer (number) in <answer> </answer> tags."
+        }
+    ],
+    "solution": "<answer> 3 </answer>"
+}
+```
+
+
+## 奖励函数定义：
+本任务使用的奖励函数有两个，一个是 Deepseek-R1 中提到的格式奖励函数，另一是 ClevrCount 的准确性奖励函数。前者已经在swift中内置，通过 `--reward_funcs format` 可以直接使用，而后者需要我们自己定义，在这里我们使用 external_plugin 的方式定义准确性奖励函数，将代码放在`swift/examples/train/grpo/plugin/plugin.py`中。
+
+在这里，奖励函数的输入包括completions和solution两个字段，分别表示模型生成的文本和真值。每个都是list，支持多个completion同时计算。注意，在这里，solution字段是数据集中定义的字段透传而来，如果有任务上的变动，可以分别对数据集和奖励函数做对应的改变即可。
+```python
+
+class MultiModalAccuracyORM(ORM):
+
+    def __call__(self, completions, solution, **kwargs) -> List[float]:
+        """
+        Reward function that checks if the completion is correct.
+        Args:
+            completions (list[str]): Generated outputs
+            solution (list[str]): Ground Truths.
+
+        Returns:
+            list[float]: Reward scores
+        """
+        rewards = []
+        from math_verify import parse, verify
+        for content, sol in zip(completions, solution):
+            reward = 0.0
+            # Try symbolic verification first
+            try:
+                answer = parse(content)
+                if float(verify(answer, parse(sol))) > 0:
+                    reward = 1.0
+            except Exception:
+                pass  # Continue to next verification method if this fails
+
+            # If symbolic verification failed, try string matching
+            if reward == 0.0:
+                try:
+                    # Extract answer from solution if it has think/answer tags
+                    sol_match = re.search(r'<answer>(.*?)</answer>', sol)
+                    ground_truth = sol_match.group(1).strip() if sol_match else sol.strip()
+
+                    # Extract answer from content if it has think/answer tags
+                    content_match = re.search(r'<answer>(.*?)</answer>', content)
+                    student_answer = content_match.group(1).strip() if content_match else content.strip()
+
+                    # Compare the extracted answers
+                    if student_answer == ground_truth:
+                        reward = 1.0
+                except Exception:
+                    pass  # Keep reward as 0.0 if both methods fail
+            rewards.append(reward)
+        return rewards
+orms['external_r1v_acc'] = MultiModalAccuracyORM
+```
+
+### GRPO训练实验记录
+#### 训练参数：
+我们选取 Qwen2.5-VL-3B-Instruct 作为基础模型进行训练，选取 Instruct 而不是基模的主要原因是可以更快地获取 format reward。我们在八卡 GPU 上进行实验。如果遇到vllm部署qwen2.5-vl报错，可以参考[issue](https://github.com/vllm-project/vllm/issues/13285)
+
+由于任务简单，我们设置max_completion_length为1024，奖励函数选择external_r1v_acc和format，学习率和beta分别设置为1e-6和0.001。其他设置如下所示，batch_size和num_generations的设置原则可以参考[GRPO完整流程](./GRPO.md)。
+首先拉起 external vLLM server
+```bash
+CUDA_VISIBLE_DEVICES=6,7 \
+swift rollout \
+    --model Qwen/Qwen2.5-VL-3B-Instruct \
+    --vllm_data_parallel_size 2
+```
+
+```shell
+WANDB_API_KEY=your_wandb_api_key \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5 \
+NPROC_PER_NODE=6 \
+swift rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen2.5-VL-3B-Instruct \
+    --external_plugins examples/train/grpo/plugin/plugin.py \
+    --reward_funcs external_r1v_acc format \
+    --use_vllm true \
+    --vllm_mode server \
+    --vllm_server_host 127.0.0.1 \
+    --vllm_server_port 8000 \
+    --tuner_type full \
+    --torch_dtype bfloat16 \
+    --dataset 'AI-ModelScope/clevr_cogen_a_train' \
+    --load_from_cache_file true \
+    --max_completion_length 1024 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 8 \
+    --per_device_eval_batch_size 8 \
+    --learning_rate 1e-6 \
+    --gradient_accumulation_steps 2 \
+    --save_strategy 'steps' \
+    --eval_strategy 'steps' \
+    --eval_steps 1000 \
+    --save_steps 1000 \
+    --save_total_limit 10 \
+    --logging_steps 1 \
+    --output_dir output/GRPO_CLEVR_COUNTDOWN \
+    --warmup_ratio 0.01 \
+    --dataloader_num_workers 4 \
+    --num_generations 24 \
+    --temperature 1.0 \
+    --system 'examples/train/grpo/prompt.txt' \
+    --deepspeed zero3 \
+    --log_completions true \
+    --report_to wandb \
+    --num_iterations 1 \
+    --async_generate false \
+    --beta 0.001 \
+```
+#### 实验现象
+![image.png](../../resources/grpo_clevr_count.png)
+由于数据集和任务比较简单，模型训练了500个epoch已经基本收敛，有以下观察。
+1. 自定义的ClevrORM在不断增加，证明模型学习到了如何完成这一任务，最终任务成功率从初始的0.4攀升到1左右。
+2. 由于是Instruct模型，Format Reward基本稳定在1，这可能也与数据集所有样本都是一样的query有一定关系。
+3. reward_std 稳定到0.1以下。
+4. completion length最终稳定在60-80，模型学习到的固定输出范式是逐个物体列举数数。
+
+step 1:
+```
+"<think> The image shows 5 distinct items: a cyan metallic cylinder, a red metallic cylinder, a small purple metallic cylinder, a large gray metallic sphere, and a small yellow metallic cube. To count the number of items, I add the counts of each type of object: 1 cyan cylinder, 1 red cylinder, 1 purple cylinder, 1 gray sphere, and 1 yellow cube. Therefore, the total number of items is 5. </think>\n<answer>5</answer>"
+"Let's count the number of items in the image:\n1. A large cyan metallic cylinder.\n2. A small purple metallic cylinder.\n3. A large red metallic cylinder.\n4. A large gray metallic sphere.\n5. A small yellow metallic cube.\n\n<answer>5</answer>"
+"<think> The image shows four distinct objects: a large cyan metallic cylinder, a smaller purple metallic cylinder, a large red metallic cylinder, and a small yellow metallic cube. Counting each of these items individually, there are five items in total. </think>\n<answer>5</answer>"
+```
+step 400:
+```
+"<think> Counting the number of items in the image:\n1. Green matte sphere\n2. Large metallic yellow sphere\n3. Small metallic brown cube\n\nThere are three distinct objects in total.\n</think>\n<answer>3</answer>"
+"<think> Counting the objects in the image:\n1. Large yellow metallic sphere\n2. Small green rubber sphere\n3. Small brown metallic cube\n\nThere are three distinct items in the image.\n</think>\n<answer>3</answer>"
+```
+总体来讲，这一任务比较简单，reward的收敛也比较典型。
+
+## Geometric QA任务
+### 任务与数据集定义
+本任务为Geometric QA任务，任务描述为：给定一个几何图形，回答有关几何图形的数学问题。原始数据来自于[论文](https://arxiv.org/pdf/2312.11370)，[R1-V](https://github.com/Deep-Agent/R1-V.git)对数据进行了预处理，将所有数据全部处理成了problem-solution的格式，而图像则保留在image字段中，因此，我们不需要额外定义数据集，直接使用`--dataset AI-ModelScope/GEOQA_R1V_Train_8K`即可。
+### 奖励函数
+由于也是数学题，同时，答案也处理成了最终结果，因此，我们直接使用以上定义过的`MultiModalAccuracyORM`奖励函数。
+### GRPO训练实验记录
+#### 训练参数：
+选取的模型和大部分超参数与上一个实验相似，主要有两点不同：
+1. SWIFT 已支持`--num_iteration`参数，单次rollout可以进行多次更新，这里设置为2。
+2. 在实验时发现，在数学问题中，训练可能会出现不稳定现象，导致模型训崩，具体表现为所有rewar迅速降低，loss、grad_norm和kl都迅速增大，后续也难以恢复正常状态。因此，这里设置`--max_grad_norm 0.5`，保证稳定训练，当然，这种现象的出现也有一定的随机性。
+
+```shell
+WANDB_API_KEY=your_wandb_api_key \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5 \
+MAX_PIXELS=401408 \
+NPROC_PER_NODE=6 \
+swift rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen2.5-VL-3B-Instruct \
+    --external_plugins examples/train/grpo/plugin/plugin.py \
+    --reward_funcs external_r1v_acc format \
+    --use_vllm true \
+    --vllm_mode server \
+    --vllm_server_host 127.0.0.1 \
+    --vllm_server_port 8000 \
+    --tuner_type full \
+    --torch_dtype bfloat16 \
+    --dataset 'AI-ModelScope/GEOQA_R1V_Train_8K' \
+    --load_from_cache_file true \
+    --max_completion_length 1024 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 8 \
+    --per_device_eval_batch_size 8 \
+    --learning_rate 1e-6 \
+    --gradient_accumulation_steps 2 \
+    --save_strategy 'steps' \
+    --eval_strategy 'steps' \
+    --eval_steps 400 \
+    --save_steps 400 \
+    --save_total_limit 10 \
+    --logging_steps 1 \
+    --output_dir output/GRPO_GEOQA \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --num_generations 8 \
+    --temperature 1.0 \
+    --repetition_penalty 1.1 \
+    --system 'examples/train/grpo/prompt.txt' \
+    --deepspeed zero3 \
+    --log_completions true \
+    --report_to wandb \
+    --num_iterations 2 \
+    --async_generate false \
+    --beta 0.001 \
+    --max_grad_norm 0.5 \
+```
+
+#### 实验现象
+![image.png](../../resources/grpo_geoqa.png)
+训练曲线如上图所示。
+1. 相比于Count任务，Geometric QA任务的难度明显更大，因此，Accuracy Reward收敛明显更慢，同时震荡幅度也明显更大。
+2. completion_length的变化趋势比较明显，最终收敛到250 token左右。
+3. reward基本收敛，标准差在一共1300个step时稳定在0.2左右。
+以下是训练后的模型completition示例：
+```
+User:
+"If AB is the tangent to circle O with the tangent point A, and BO intersects circle O at point C, and point D is located on circle O, what is the measure of angle ADC if the degree of angle ABO is 32.0?"
+Assistant:
+"<think>\nTo find the measure of angle ADC, we first need to understand the properties of the tangent and the circle. Since AB is a tangent to the circle at point A, the line segment OA (which is perpendicular to the tangent AB) is perpendicular to AB. This means that angle OAB is 90 degrees.\n\nGiven that angle ABO is 32 degrees, we can find angle BAO by subtracting angle ABO from 90 degrees:\n∠BAO = 90° - ∠ABO = 90° - 32° = 58°\n\nSince angle BAO is an angle in the minor arc AD, the angle ADC, which is an angle in the minor arc AD, is half the angle BAO. Therefore, angle ADC is:\n∠ADC = 1/2 × ∠BAO = 1/2 × 58° = 29°\n\nSo, the measure of angle ADC is 29 degrees.\n</think>\n<answer>\nThe measure of angle ADC is 29 degrees.\n</answer>"
+```
+## Multimodal Open R1 数据集实验
+### 任务与数据集定义
+本任务为参考[open-r1-multimodal](https://github.com/EvolvingLMMs-Lab/open-r1-multimodal.git)的实验，使用数据集：[lmms-lab/multimodal-open-r1-8k-verified](https://www.modelscope.cn/datasets/lmms-lab/multimodal-open-r1-8k-verified)，该数据集专注于多模态的数学推理任务，数据由GPT4o基于`Math360K`和`Geo170K`数据集生成，包含推理路径和可验证答案。数据集中已包含了image, problem和solution字段，我们也不需要针对prompt进行修改，因此无需额外定义数据集。
+### 奖励函数
+我们直接使用以上定义过的`MultiModalAccuracyORM`奖励函数。
+### GRPO训练实验记录
+#### 训练参数：
+选取的模型和大部分超参数与上一个实验相似，由于训练的时候出现了OOM，我们设置`MAX_PIXELS=262144`以降低显存占用。
+```shell
+WANDB_API_KEY=your_wandb_api_key \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5 \
+MAX_PIXELS=262144 \
+MASTER_PORT=29600 \
+NPROC_PER_NODE=6 \
+swift rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen2.5-VL-3B-Instruct \
+    --external_plugins examples/train/grpo/plugin/plugin.py \
+    --reward_funcs external_r1v_acc format \
+    --use_vllm true \
+    --vllm_mode server \
+    --vllm_server_host 127.0.0.1 \
+    --vllm_server_port 8000 \
+    --tuner_type full \
+    --torch_dtype bfloat16 \
+    --dataset 'lmms-lab/multimodal-open-r1-8k-verified' \
+    --load_from_cache_file true \
+    --max_completion_length 1024 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 8 \
+    --per_device_eval_batch_size 8 \
+    --learning_rate 1e-6 \
+    --gradient_accumulation_steps 2 \
+    --save_strategy 'steps' \
+    --eval_strategy 'steps' \
+    --eval_steps 400 \
+    --save_steps 400 \
+    --save_total_limit 10 \
+    --logging_steps 1 \
+    --output_dir output/GRPO_GEOQA \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --num_generations 8 \
+    --temperature 1.0 \
+    --repetition_penalty 1.1 \
+    --system 'examples/train/grpo/prompt.txt' \
+    --deepspeed zero3 \
+    --log_completions true \
+    --report_to wandb \
+    --num_iterations 2 \
+    --async_generate false \
+    --beta 0.001 \
+    --max_grad_norm 0.5 \
+```
+
+#### 实验现象
+![image.png](../../resources/grpo_openr1_multimodal.png)
+训练曲线如上图所示。
+一共8k数据，训练了1268个step，Accuracy Reward收敛到0.5左右，completion_length基本收敛到200token左右，reward_std最终在0.2左右震荡。
+以下是训练后的模型completition示例：
+```
+User:
+"Based on the map, which state falls into the lowest percentage range of lots, and what is that percentage range?"
+Assistant:
+"<think>\nThe image provided shows a color-coded map of the USA indicating different ranges of lot percentages across various states. According to the legend at the bottom, the lowest percentage range (6.0% - 6.5%) is represented by white. In the image, Alabama (AL) is shaded in white, which corresponds to the 6.0% - 6.5% category. Therefore, based on the map, the state that falls into the lowest percentage range of lots is Alabama, with the percentage range of 6.0% - 6.5%.\nTherefore, the answer is 6.0% - 6.5%.\n</think>\n<answer>Alabama</answer>"
+```
@@ -0,0 +1,195 @@
+# GRPO完整实验流程
+
+本文从较为简单的数学任务 Coundown Game 出发，从数据集定义、奖励函数定义和GRPO训练几个步骤介绍完整的GRPO训练流程。任务定义和训练参数等参考了 [mini-deepseek-r1](https://github.com/philschmid/deep-learning-pytorch-huggingface/blob/main/training/mini-deepseek-r1-aha-grpo.ipynb)。
+
+## 任务与数据集定义
+
+Coundown Game 的任务目标是根据给定的几个数字和加减乘除四种运算，得到目标数字，因此，我们定义数据集如下：
+```python
+class CoundownTaskPreprocessor(ResponsePreprocessor):
+
+    def preprocess(self, row: Dict[str, Any]) -> Dict[str, Any]:
+        numbers = row['nums']
+        target = row.pop('response', None)
+        query = f"""
+        Using the numbers {numbers}, create an equation that equals {target}.
+        You can use basic arithmetic operations (+, -, *, /) and each number can only be used once.
+        Show your work in <think> </think> tags. And return the final equation and answer in <answer> </answer> tags,
+        for example <answer> (1 + 2) / 3 * 4 = 4 </answer>.
+        """
+        row.update({'target': target, 'query': query})
+        return super().preprocess(row)
+
+register_dataset(
+    DatasetMeta(
+        ms_dataset_id='zouxuhong/Countdown-Tasks-3to4',
+        subsets=['default'],
+        preprocess_func=CoundownTaskPreprocessor(),
+        tags=['math']))
+```
+通过 template， 使用 numbers 和 target 完成任务定义，并给到 query 字段供模型采样使用。同时，我们需要保留 nums 和 target 两个字段，用于后续的奖励函数计算。
+
+## 奖励函数定义：
+本任务使用的奖励函数有两个，一个是 Deepseek-R1 中提到的格式奖励函数，另一是 Coundown Game 的准确性奖励函数。前者已经在swift中内置，通过 `--reward_funcs format` 可以直接使用，而后者需要我们自己定义，在这里我们使用 external_plugin 的方式定义准确性奖励函数，将代码放在`swift/examples/train/grpo/plugin/plugin.py`中。
+
+在这里，奖励函数的输入包括 completions、target 和 nums 三个字段，分别表示模型生成的文本、目标答案和可用的数字。每个都是list，支持多个 completion 同时计算。注意，在这里，除了 completions 之外的参数都是数据集中定义的字段透传而来，如果有任务上的变动，可以分别对数据集和奖励函数做对应的改变即可。
+```python
+class CountdownORM(ORM):
+    def __call__(self, completions, target, nums, **kwargs) -> List[float]:
+        """
+        Evaluates completions based on Mathematical correctness of the answer
+        Args:
+            completions (list[str]): Generated outputs
+            target (list[str]): Expected answers
+            nums (list[str]): Available numbers
+        Returns:
+            list[float]: Reward scores
+        """
+        rewards = []
+        for completion, gt, numbers in zip(completions, target, nums):
+            try:
+                # Check if the format is correct
+                match = re.search(r"<answer>(.*?)<\/answer>", completion)
+                if match is None:
+                    rewards.append(0.0)
+                    continue
+                # Extract the "answer" part from the completion
+                equation = match.group(1).strip()
+                if '=' in equation:
+                    equation = equation.split('=')[0]
+                # Extract all numbers from the equation
+                used_numbers = [int(n) for n in re.findall(r'\d+', equation)]
+                # Check if all numbers are used exactly once
+                if sorted(used_numbers) != sorted(numbers):
+                    rewards.append(0.0)
+                    continue
+                # Define a regex pattern that only allows numbers, operators, parentheses, and whitespace
+                allowed_pattern = r'^[\d+\-*/().\s]+$'
+                if not re.match(allowed_pattern, equation):
+                    rewards.append(0.0)
+                    continue
+                # Evaluate the equation with restricted globals and locals
+                result = eval(equation, {'__builtins__': None}, {})
+                # Check if the equation is correct and matches the ground truth
+                if abs(float(result) - float(gt)) < 1e-5:
+                    rewards.append(1.0)
+                else:
+                    rewards.append(0.0)
+            except Exception as e:
+                # If evaluation fails, reward is 0
+                rewards.append(0.0)
+        return rewards
+orms['external_countdown'] = CountdownORM
+```
+
+## GRPO训练实验记录
+首先贴上GRPO的公式：
+
+$$
+{\scriptstyle
+\begin{aligned}
+\mathcal{J}_{G R P O}(\theta) & =\mathbb{E}\left[q \sim P(Q),\left\{o_i\right\}_{i=1}^G \sim \pi_{\theta_{o l d}}(O \mid q)\right] \\
+& \frac{1}{G} \sum_{i=1}^G \frac{1}{\left|o_i\right|} \sum_{t=1}^{\left|o_i\right|}\left\{\min \left[\frac{\pi_\theta\left(o_{i, t} \mid q, o_{i,<t}\right)}{\pi_{\theta_{o l d}}\left(o_{i, t} \mid q, o_{i,<t}\right)} \hat{A}_{i, t}, \operatorname{clip}\left(\frac{\pi_\theta\left(o_{i, t} \mid q, o_{i,<t}\right)}{\pi_{\theta_{o l d}}\left(o_{i, t} \mid q, o_{i,<t}\right)}, 1-\varepsilon, 1+\varepsilon\right) \hat{A}_{i, t}\right]-\beta \mathbb{D}_{K L}\left[\pi_\theta| | \pi_{r e f}\right]\right\}
+\end{aligned}
+}
+$$
+
+### 训练参数：
+我们选取 Qwen2.5-3B-Instruct 作为基础模型进行训练，选取 Instruct 而不是基模的主要原因是可以更快地获取 format reward。我们在三卡 GPU 上进行实验，因此vllm的推理部署在最后一张卡上，而进程数设置为2，在剩下两张卡上进行梯度更新。
+
+由于任务较为简单，我们设置 max_completion_length 和 vllm_max_model_len 为1024，如果有更复杂的任务，可以适当加大模型输出长度，但请注意，**这两个参数越大，模型训练需要的显存越多，训练速度越慢，单个step的训练时间与max_completion_length呈现线性关系**。
+
+在我们的实验中，总batch_size为
+
+```
+num_processes * per_device_train_batch_size * gradient_accumulation_steps = 2 * 8 * 8 = 128
+```
+
+注意，这里单卡batch_size设置也与显存息息相关，请根据显存上限设置一个合适的值。 同时，还有一个公式，即总的steps数量 :$num\_steps = epochs \times len(datasets) \times num\_generations \div batch\_size $，需要根据这个来合理规划训练的学习率和warmup设置。
+
+最后比较重要的设置是学习率和 beta，学习率比较好理解，而beta则是是以上公式的 $\beta$，即KL散度的梯度的权重。这两个参数设置的越大，模型收敛原则上更快，但训练往往会不稳定。经过实验，我们分别设置为 `5e-7` 和 `0.001`。在实际训练中，请根据是否出现不稳定的震荡情况适当调整这两个参数。
+
+对于KL散度，社区有很多的讨论，可以参考[为什么GRPO坚持用KL散度](https://zhuanlan.zhihu.com/p/25862547100)。
+
+其他参数的设置，没有做太多探讨，所以这里不进行详细说明。
+```bash
+CUDA_VISIBLE_DEVICES=2 \
+swift rollout \
+    --model Qwen/Qwen2.5-3B-Instruct
+```
+
+```bash
+CUDA_VISIBLE_DEVICES=0,1 \
+WANDB_API_KEY=your_wandb_key \
+NPROC_PER_NODE=2 \
+swift rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen2.5-3B-Instruct \
+    --external_plugins examples/train/grpo/plugin/plugin.py \
+    --reward_funcs external_countdown format \
+    --use_vllm true \
+    --vllm_mode server \
+    --vllm_server_host 127.0.0.1 \
+    --vllm_server_port 8000 \
+    --tuner_type full \
+    --torch_dtype bfloat16 \
+    --dataset 'zouxuhong/Countdown-Tasks-3to4#50000' \
+    --load_from_cache_file true \
+    --max_length 2048 \
+    --max_completion_length 1024 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 8 \
+    --per_device_eval_batch_size 8 \
+    --learning_rate 5e-7 \
+    --gradient_accumulation_steps 8 \
+    --eval_steps 500 \
+    --save_steps 100 \
+    --save_total_limit 20 \
+    --logging_steps 1 \
+    --output_dir output/GRPO_COUNTDOWN \
+    --warmup_ratio 0.01 \
+    --dataloader_num_workers 4 \
+    --num_generations 8 \
+    --temperature 1.0 \
+    --system 'You are a helpful assistant. You first thinks about the reasoning process in the mind and then provides the user with the answer.' \
+    --deepspeed zero3 \
+    --log_completions true \
+    --report_to wandb \
+    --beta 0.001 \
+    --num_iterations 1
+```
+### 实验现象
+![image.png](../../resources/grpo_countdown.png)
+从训练了2000 step的实验结果来看，有几点观察：
+1. 自定义的CoundownORM在不断增加，证明模型学习到了如何完成这一任务，最终任务成功率在0.5左右。
+2. Format Reward整体处在较高的水平，在0.9-1左右震荡。
+3. reward_std 最终在0.2-0.3左右，仍未完全收敛，模型仍然有继续提升reward的空间。
+4. 观察模型输出可以发现，相当一部分失败案例是由于模型简单加减乘除做不对，因此模型最终的收敛方向也变成了逐步运算上，如果换成更大的模型，可能有不同的收敛方向。
+5. completion length呈现先下降再增加，在200 step左右最低，然后逐渐上升到350左右。证明模型经历了思考方式的转变。
+6. 模型的思考方式在不断变化，最终模型发现做排列组合并逐步运算能更好地完成这一任务，最终的采样输出也大多是这一格式，以下是不同step的completion变化：
+
+step 1:
+```
+"<think>\nWe need to create an equation using the given numbers [70, 5, 42, 30] exactly once and make it equal to 77. \n\nFirst, let's consider the possibility of multiplication or division to get closer to 77. Notice that 77 is close to 70 and 42. If we can use these numbers together, it might work.\n\nMultiplying 70 by 1.1 would give us approximately 77, which is very close. So, let's try to make 1.1 using the remaining numbers 5 and 30. \nIf we take 30/5 = 6, and then 5/6 = 0.8333..., this isn't useful here, so let's look at other possibilities.\n\nNext, let's consider if there's another way to achieve 77 using addition, subtraction, or another combination of our numbers. Given the numbers provided, it seems that multiplication or division will be key. \n\nWe can try subtracting 5 from 30 to get 25. Then, if we divide 42 by 25, we don't get a whole number, but we can round it to the nearest whole number, 1. Now, we need to make the equation fit 77. Let's multiply 25 by 3 and add 7 (since 77 = 25*3 + 7). However, we only have one 7 available and we need to find a way to use the remaining numbers to get 7.\n\nLet's try:  \n70 - 42 = 28  \nThen, 28 + 5 = 33  \nNext, 33 + 30 = 63  \nFinally, 77 - 63 = 14, which doesn't help.\n\nConsidering different combinations, one viable way is:\n(70 - 42) * (30 / 5) = 28 * 6 = 168 / 2 = 84 / 2 = 42 / 2 = 21 / 3 = 7\n\nSo, (70 - 42) * (30 / 5) = 77.\n</think>\n<answer>(70 - 42) * (30 / 5) = 77</answer>"
+```
+step 200:
+```
+"<think>\nWe need to use all the given numbers in a way that the resultant value of the calculation is 99. Given these restrictions, it's clear we should look into how the numbers relate and the mathematical operations that will bring them together to meet our condition.\n\nFirstly, let's evaluate the sums, differences, and multiplication/division among the numbers and their relations to see how this could lead us towards an outcome of 99.\n- Summing the three numbers: 96 + 70 + 73 = 239, which is far from 99. This shows addition isn't practical.\n- Subtracting numbers: For instance, subtracting the lowest two (i.e., 73 - 70 = 3) and combining with the highest one (96) does not work. Also, there is no other combination of subtraction that would result in the number needing to add up to 99.\n- Multiplying or dividing the numbers alone wouldn’t reach to any near solution since none of the products or division results of the numbers themselves is very close to 99. We might think more carefully about the arrangement of them using a combination of the operations provided.\nTherefore, considering the possible arrangement, a combination like taking (73 - 70 + 96) may produce an effective solution as this will sum the values in such a manner that it aligns with the goal of 99.\n\nSo we conclude that the operation: 73 - 70 + 96 gives the right sequence to equal 99.\n</think>\n\n<answer>73 - 70 + 96 = 99</answer>"
+```
+step 500:
+```
+"<think>\nLet's begin by exploring various possible combinations of the given numbers using the arithmetic operators we have access to.\n\n- If I add the numbers, I get: 56 + 73 + 51 = 180 which is not equal to our target number (68)\n- If I subtract one number from another I will still exceed our target value as well since the maximum difference is: |(difference between max-min):| | (73 - 51) or | (73 - 56), etc.|\n- Let's multiply the numbers individually and see if the division operation can bring us closer to the goal:\n    - (73 * 51) - 56 = 3723 - 56 = 3667 which isn't the goal either.\n    - The only operator left is addition and subtraction; I'll try the combination: \n    ((73 - 56) + 51) gives me (17 + 51) = 68.\n    \nThus, our solution fits the provided problem constraints and meets the required outcome.\n</think>\n<answer>(73 - 56) + 51 = 68</answer>"
+```
+
+step 1000:
+```
+"<think>\nWe need to form an expression using the given numbers (50, 86, and 49) such that it equals 85. Let's try different combinations:\n\n(86 - 50) + 49 = 76 + 49 = 125 (too big)\n(86 - 49) + 50 = 37 + 50 = 87 (too big)\n(86 - 50) + 49 = 37 + 49 = 86 (too big)\n(86 + 50) - 49 = 136 - 49 = 87 (too big)\n(86 - 50) + (49 - x)? Not working!\n(50 + 86) - 49: this is 136 which isn't our aim.\n50 + (86 - 49) = 50 + 37 = 87 which wasn't correct.\n50 - 86 + 49 = -16 + 49: This doesn't match up as well.\n86 - (50 + 49) = 86 - 99 which doesn't work too.\n\nWe try one more:\n(86 + 49) - 50 = 135 - 50 = 85!\n\nThat's it!\n</think>\n\n<answer>(86 + 49) - 50 = 85</answer>"
+```
+
+step 2000:
+```
+"<think>\nWe need to form an expression using the numbers 58, 9, 78, and 44 which evaluates to 73. Let's try different combinations:\n(78 - 58) + (9 + 44) = 10 + 53 = 63 (too low)\n(78 - 58) + (9 - 44) = 20 - 35 = -15 (too low)\n(78 - 58) + (44 - 9) = 20 + 35 = 55 (too low)\n(78 + 58) - (9 + 44) = 136 - 53 = 83 (too high)\n(78 + 58) - (9 - 44) = 136 + 35 = 171 (too high)\n(78 + 58) - (44 + 9) = 136 + 53 = 189 (too high)\n(78 + 9) - (58 + 44) = 87 - 102 = -15 (too low)\n(78 + 9) - (58 - 44) = 87 - 14 = 73\n\nSo our solution is: (78 + 9) - (58 - 44) = 73</think>\n\n<answer>(78 + 9) - (58 - 44) = 73</answer>"
+```
+
+附learning_rate和beta分别取值1e-6和0.04的不稳定实验记录，模型在step 200左右出现了震荡，format和CountdownORM瞬间走低：
+![](../../resources/grpo_countdown_1.png)
@@ -0,0 +1,658 @@
+
+# 注册多模态模型最佳实践
+
+本文将介绍如何在ms-swift中注册多模态模型，并成功推理和训练。本文将以Qwen2.5-Omni为例子，注册新的model_type和template `my_qwen2_5_omni`，并支持文本、图片、视频和音频的训练。由于Qwen2.5-Omni已经在ms-swift中注册，我们可以通过显式指定model_type和template来使用我们自定义的部分。
+
+## 环境准备
+```shell
+# 避免未来出现与文档的不兼容情况
+pip install "ms-swift>=4.0"
+
+pip install "transformers==4.57.*" "qwen_omni_utils==0.0.8"
+```
+
+
+## 注册模型
+
+第一步，我们需要注册模型，来获取模型和processor。
+
+```python
+from transformers import AutoConfig, PretrainedConfig, PreTrainedModel
+
+from swift.model import (Model, ModelGroup, ModelMeta, MultiModelKeys, get_model_processor, register_model,
+                         register_model_arch, ModelLoader)
+from swift.model.models.qwen import patch_qwen_vl_utils
+from swift.model.patcher import patch_get_input_embeddings
+from swift.model.utils import use_submodel_func
+from swift.utils import get_env_args, Processor
+
+register_model_arch(
+    MultiModelKeys(
+        'my_qwen2_5_omni',
+        # `freeze_llm`, `freeze_vit`, `freeze_aligner`将根据下面的值来决定其行为。
+        # 例如：全参数训练，若设置`freeze_vit=True`，将冻结以`thinker.audio_tower`和`thinker.visual`为前缀的模型层的参数。
+        # LoRA训练，若设置`freeze_vit=False`，将额外为以`thinker.audio_tower`和`thinker.visual`为前缀的Linear层添加LoRA。
+        language_model=['thinker.model', 'thinker.lm_head'],
+        vision_tower=['thinker.audio_tower', 'thinker.visual'],
+        aligner=['thinker.audio_tower.proj', 'thinker.visual.merger'],
+        # generator的部分将永远不进行训练或处于冻结状态。
+        # 如果你希望`thinker.audio_tower`, `thinker.audio_tower.proj`永远不进行训练，你可以放置到generator中，并将其从vision_tower, aligner中移除。
+        generator=['talker', 'token2wav'],
+    ))
+
+class Qwen2_5OmniLoader(ModelLoader):
+
+
+    def get_config(self, model_dir: str) -> PretrainedConfig:
+        config = AutoConfig.from_pretrained(model_dir, trust_remote_code=True)
+        enable_audio_output = get_env_args('ENABLE_AUDIO_OUTPUT', bool, None)
+        if enable_audio_output is not None:
+            config.enable_audio_output = enable_audio_output
+        return config
+
+    def get_processor(self, model_dir: str, config: PretrainedConfig) -> Processor:
+        from transformers import Qwen2_5OmniProcessor
+        from qwen_omni_utils import vision_process
+        processor = Qwen2_5OmniProcessor.from_pretrained(model_dir, trust_remote_code=True)
+        # Control constants in qwen_omni_utils library via environment variables,
+        # e.g., `MAX_PIXELS`, etc.
+        patch_qwen_vl_utils(vision_process)
+        return processor
+
+    def get_model(self, model_dir: str, config: PretrainedConfig, processor: Processor,
+                  model_kwargs) -> PreTrainedModel:
+        from transformers import Qwen2_5OmniForConditionalGeneration
+        print('Run my_qwen2_5_omni...')
+        self.auto_model_cls = self.auto_model_cls or Qwen2_5OmniForConditionalGeneration
+        model = super().get_model(model_dir, config, processor, model_kwargs)
+        # For multimodal model consistency, we replace the model's forward/generate functions
+        # with those of its language_model.
+        # Handle additional parts separately.
+        use_submodel_func(model, 'thinker')
+        # Avoid inplace operations on leaf_variable during training
+        # (replacing parts of input_embeds with images_embeds)
+        patch_get_input_embeddings(model.thinker.visual, 'patch_embed')
+        # Some custom settings for model/config (usually not needed; configure based on
+        # specific model if errors occur during training/inference)
+        model.config.keys_to_ignore_at_inference += ['hidden_states', 'attention_mask']
+        model.config.talker_config.pad_token_id = None
+        return model
+
+
+register_model(
+    ModelMeta(
+        'my_qwen2_5_omni',
+        [
+            ModelGroup([
+                Model('Qwen/Qwen2.5-Omni-3B', 'Qwen/Qwen2.5-Omni-3B'),
+                Model('Qwen/Qwen2.5-Omni-7B', 'Qwen/Qwen2.5-Omni-7B'),
+            ]),
+        ],
+        # 用来获取model和processor的函数。
+        Qwen2_5OmniLoader,
+        template='my_qwen2_5_omni',
+        is_multimodal=True,  # 是否是多模态模型
+        model_arch='my_qwen2_5_omni',  # 通常只为多模态模型设置
+        # 用于model_type的自动匹配
+        architectures=['Qwen2_5OmniModel', 'Qwen2_5OmniForConditionalGeneration'],
+        # 用来提示用户依赖版本（可删除）
+        requires=['transformers>=4.50', 'soundfile', 'qwen_omni_utils', 'decord'],
+        # 用来提示用户（可删除）
+        tags=['vision', 'video', 'audio'],
+        # 全参数训练/merge-lora需要额外保存的文件
+        additional_saved_files=['spk_dict.pt'],
+    ))
+
+if __name__ == '__main__':
+    # 测试与debug
+    model, processor = get_model_processor('Qwen/Qwen2.5-Omni-7B', model_type='my_qwen2_5_omni')
+```
+
+## 注册模板
+
+第二步，我们需要注册模板，来自定义如何将文本、图片、视频和音频进行预处理（`_encode`和`_data_collator`方法）。这是ms-swift支持多模态模型训练的关键模块。预处理方式请参考transformers推理实现，并进行对齐。
+
+template的功能如下：
+1. 支持正常推理与训练，预处理文本和多模态信息，并支持grounding任务。
+2. 支持padding_free和packing训练。
+3. 支持混合模态数据训练。
+
+
+```python
+from functools import partial
+from typing import Any, Dict, List, Literal, Optional
+
+import torch
+from transformers.integrations import is_deepspeed_zero3_enabled
+from swift import get_model_processor
+from swift.template import StdTemplateInputs, Template, TemplateMeta, get_template, register_template
+from swift.template.utils import Context, findall
+from swift.template.vision_utils import load_audio
+from swift.utils import Processor, get_env_args, get_logger, get_packed_seq_params, is_deepspeed_enabled, to_float_dtype
+
+logger = get_logger()
+
+class Qwen2_5OmniTemplate(Template):
+    use_model = True  # 是否在预处理的过程中需要model参与
+    # 需要注意是：并不是所有的多模态模型都能支持padding_free/packing。`transformers`库内的模型通常可以支持
+    support_padding_free = True  # 是否支持padding_free和packing（多模态模型）
+    norm_bbox = 'none'  # grounding任务使用绝对坐标还是norm1000坐标
+
+    # 这里的tokens将不会被裁剪（例如设置`--truncation_strategy left/right`）
+    # 并会使用简略方式打印（调用`template.safe_decode`）
+    placeholder_tokens = ['<|IMAGE|>', '<|AUDIO|>', '<|VIDEO|>']
+
+    def init_processor(self, processor: Processor) -> None:
+        """在初始化processor时，额外初始化所需的一些常量"""
+        if processor is None:
+            return
+        super().init_processor(processor)
+        from transformers.models.qwen2_5_omni.processing_qwen2_5_omni import Qwen2_5OmniProcessorKwargs
+        default = Qwen2_5OmniProcessorKwargs._defaults
+        self.seconds_per_chunk = default['videos_kwargs']['seconds_per_chunk']
+        self.position_id_per_seconds = default['videos_kwargs']['position_id_per_seconds']
+        self.use_audio_in_video = get_env_args('use_audio_in_video', bool, False)
+        self.sampling_rate = get_env_args('sampling_rate', int, self.processor.feature_extractor.sampling_rate)
+        # `QWENVL_BBOX_FORMAT`的含义参考grounding数据集自定义文档
+        self.bbox_format = get_env_args('QWENVL_BBOX_FORMAT', str, 'legacy')
+
+
+    def replace_tag(self, media_type: Literal['image', 'video', 'audio'], index: int,
+                    inputs: StdTemplateInputs) -> List[Context]:
+        """读取多模态数据，并替换通用多模态tag。
+        例如：图像tag从`<image>` -> `<|vision_bos|><|IMAGE|><|vision_eos|>`"""
+        # 读取多模态数据也可以在`_encode`函数中进行，怎么方便怎么来。
+        from qwen_omni_utils import fetch_image, fetch_video
+        if media_type == 'image':
+            inputs.images[index] = fetch_image({'image': inputs.images[index]})
+            return ['<|vision_bos|><|IMAGE|><|vision_eos|>']
+        elif media_type == 'audio':
+            if self.mode != 'vllm':  # 'vllm'推理场景下不需要处理
+                inputs.audios[index] = load_audio(inputs.audios[index], self.sampling_rate)
+            return ['<|audio_bos|><|AUDIO|><|audio_eos|>']
+        elif media_type == 'video':
+            video = inputs.videos[index]
+            _video = fetch_video({'video': video})
+            if isinstance(_video, torch.Tensor):
+                _video = _video.to(torch.uint8)
+            inputs.videos[index] = _video
+            if self.use_audio_in_video:
+                import librosa
+                if video.startswith('http://') or video.startswith('https://'):
+                    import audioread
+                    video = audioread.ffdec.FFmpegAudioFile(video)
+                video = librosa.load(video, sr=self.sampling_rate)[0]
+                inputs.audios.insert(inputs.audio_idx, (video, 'video'))
+                inputs.audio_idx += 1
+                return ['<|vision_bos|><|audio_bos|><|VIDEO|><|audio_eos|><|vision_eos|>']
+            else:
+                return ['<|vision_bos|><|VIDEO|><|vision_eos|>']
+
+
+    def replace_ref(self, ref: str, index: int, inputs: StdTemplateInputs) -> List[Context]:
+        """替换grounding任务的通用tag: `<ref-object>`"""
+        if self.bbox_format == 'legacy':
+            return [f'<|object_ref_start|>{ref}<|object_ref_end|>']
+        else:
+            return [ref]
+
+    def replace_bbox(self, bbox: List[int], index: int, inputs: StdTemplateInputs) -> List[Context]:
+        """替换grounding任务的通用tag: `<bbox>`"""
+        if self.bbox_format == 'legacy':
+            return [f'<|box_start|>{self._get_bbox_str(bbox)}<|box_end|>']
+        else:
+            return [str(bbox)]
+
+    def packing_row(self, row: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """支持packing & mrope。通常情况不需要继承该函数，这里为了自定义mrope的position_ids。"""
+        position_ids = []
+        for r in row:
+            r = r.copy()
+            r['input_ids'] = torch.tensor(r['input_ids'])[None]
+            position_ids.append(self._get_position_ids(r))
+        packed = super().packing_row(row)
+        packed['position_ids'] = torch.concat(position_ids, dim=-1)
+        return packed
+
+    def _get_new_tokens_use_audio_in_video(self, i, *, video_grid_thw, video_second_per_grid, audio_lengths,
+                                           video_token_id, audio_token_id):
+        """辅助函数，用于支持`use_audio_in_video`为True的情况"""
+        merge_size = self.processor.image_processor.merge_size
+        grid_thw = video_grid_thw[i]
+        height = grid_thw[1] // merge_size
+        width = grid_thw[2] // merge_size
+        audio_token_indices = torch.arange(audio_lengths[i])
+        video_token_indices = torch.arange(grid_thw[0]).reshape(-1, 1, 1)
+
+        video_token_indices = torch.broadcast_to(video_token_indices,
+                                                 (video_token_indices.shape[0], height, width)).reshape(-1)
+        video_token_indices = (video_token_indices * video_second_per_grid[i] * self.position_id_per_seconds)
+        tokens_per_chunk = int(self.position_id_per_seconds * self.seconds_per_chunk)
+        video_chunk_indexes = self.processor.get_chunked_index(video_token_indices, tokens_per_chunk)
+        audio_chunk_indexes = self.processor.get_chunked_index(audio_token_indices, tokens_per_chunk)
+
+        res = []
+        for j in range(max(len(video_chunk_indexes), len(audio_chunk_indexes))):
+            if j < len(video_chunk_indexes):
+                video_seq_length = video_chunk_indexes[j][1] - video_chunk_indexes[j][0]
+                res += video_token_id * video_seq_length
+            if j < len(audio_chunk_indexes):
+                audio_seq_length = audio_chunk_indexes[j][1] - audio_chunk_indexes[j][0]
+                res += audio_token_id * audio_seq_length
+        return res
+
+
+    def _encode(self, inputs: StdTemplateInputs) -> Dict[str, Any]:
+        """这里决定如何将text/images/audios/videos -> input_ids、labels、loss_scale以及pixel_values等多模态内容
+        这里的处理逻辑通常可以从对应模型的预处理代码实现中借鉴。
+        推荐：请先做推理对齐再做训练"""
+        encoded = Template._encode(self, inputs)  # 处理纯文本部分，具体请参考自定义模型文档
+        logger.info_once('Run qwen2_5_omni template')
+        processor = self.processor
+        # 获取多模态内容
+        media_inputs = processor(
+            text='',
+            audio=inputs.audios or None,
+            images=inputs.images or None,
+            videos=inputs.videos or None,
+            do_resize=False,
+            return_tensors='pt')
+        # 我们不使用`processor`产生的input_ids和attention_mask。因为其不产生`labels`。
+        media_inputs.pop('input_ids')
+        media_inputs.pop('attention_mask')
+        media_inputs = to_float_dtype(media_inputs, self.model_info.torch_dtype)
+
+        input_ids = encoded['input_ids']
+        labels = encoded['labels']
+        loss_scale = encoded.get('loss_scale', None)
+        # audio模态
+        audio_token_id = self._tokenize('<|AUDIO|>')
+        idx_list = findall(input_ids, audio_token_id)  # 查找所有的audio_token
+        feature_attention_mask = media_inputs.get('feature_attention_mask')
+        if feature_attention_mask is not None:
+            audio_feature_lengths = torch.sum(feature_attention_mask, dim=1)
+            audio_lengths = ((audio_feature_lengths - 1) // 2 + 1 - 2) // 2 + 1
+        else:
+            audio_lengths = None
+        audio_lengths_origin = audio_lengths
+        # video_audios_mask用于处理`use_audio_in_video`，区分是纯audio(0)还是video中的audio(1)
+        video_audios_mask = []
+        for i, audio in enumerate(inputs.audios):
+            if isinstance(audio, tuple) and audio[1] == 'video':
+                inputs.audios[i] = audio[0]
+                video_audios_mask.append(True)
+            else:
+                video_audios_mask.append(False)
+        video_audios_mask = torch.tensor(video_audios_mask)
+        if idx_list:
+            # 过滤掉video中的audio的内容（将在video部分处理）
+            if self.use_audio_in_video:
+                audio_lengths = audio_lengths[~video_audios_mask]
+
+            def _get_new_audio_tokens(i):
+                return audio_token_id * audio_lengths[i]
+
+            # 对input_ids的多模态tokens进行展开
+            input_ids, labels, loss_scale = self._extend_tokens(input_ids, labels, loss_scale, idx_list,
+                                                                _get_new_audio_tokens)
+
+        # image和video模态
+        for media_type in ['image', 'video']:
+            token = f'<|{media_type.upper()}|>'
+            token_id = self._tokenize(token)
+            idx_list = findall(input_ids, token_id)
+            if idx_list:
+                merge_size = processor.image_processor.merge_size
+                media_grid_thw = media_inputs.get(f'{media_type}_grid_thw')
+                if media_type == 'video' and self.use_audio_in_video:
+                    audio_lengths = audio_lengths_origin[video_audios_mask]
+                    video_second_per_grid = media_inputs['video_second_per_grid']
+                    _get_new_tokens_use_audio_in_video = partial(
+                        self._get_new_tokens_use_audio_in_video,
+                        video_grid_thw=media_grid_thw,
+                        video_second_per_grid=video_second_per_grid,
+                        audio_lengths=audio_lengths,
+                        video_token_id=token_id,
+                        audio_token_id=audio_token_id)
+                    input_ids, labels, loss_scale = self._extend_tokens(input_ids, labels, loss_scale, idx_list,
+                                                                        _get_new_tokens_use_audio_in_video)
+
+                else:
+
+                    def _get_new_tokens(i):
+                        token_len = (media_grid_thw[i].prod() // (merge_size**2))
+                        return token_id * token_len
+
+                    input_ids, labels, loss_scale = self._extend_tokens(input_ids, labels, loss_scale, idx_list,
+                                                                        _get_new_tokens)
+
+        encoded['input_ids'] = input_ids
+        encoded['labels'] = labels
+        encoded['loss_scale'] = loss_scale
+        encoded.update(media_inputs)  # 将多模态内容加入其中
+        return encoded
+
+    def _post_encode(self, model, inputs: Dict[str, Any]) -> Dict[str, Any]:
+        """该函数通常用于解决混合模型训练zero2/zero3卡住的问题，
+        即有的进程为纯文本数据未过vit，有的进程含图片数据过了vit。这里将创建dummy_image来解决。
+
+        该函数将被注册在`model.forward`前的pre_forward_hook中。
+        该函数需返回 含多模态信息的input_embeds。
+        """
+        if not self.is_training:
+            return inputs
+
+        input_ids = inputs['input_ids']
+        input_features = inputs.get('input_features')
+        feature_attention_mask = inputs.get('feature_attention_mask')
+
+        base_model = self.get_base_model(model)
+        inputs_embeds = base_model.thinker.model.embed_tokens(input_ids)
+        thinker_config = model.config.thinker_config
+        # 辅助函数，用于处理text/image/video混合模态数据场景。（内部会创建dummy_image）
+        inputs_embeds = self._get_inputs_embeds_hf(inputs_embeds, inputs, model.thinker.visual, self.processor,
+                                                   thinker_config)
+        # 含audio的混合模态数据场景
+        if input_features is None:
+            if is_deepspeed_enabled() and not is_deepspeed_zero3_enabled():
+                # 注意: 由于transformers实现中，经过audio部分模型层的次数与audio数量相关
+                # 因此zero3在不同进程audios数不同场景下会卡住（需修改transformers代码修复）。此场景请使用zero2。
+                input_features = input_ids.new_zeros([1, 128, 128], dtype=model.thinker.audio_tower.dtype)
+                feature_attention_mask = input_ids.new_ones([1, 128], dtype=torch.bool)
+                audio_res = model.thinker.get_audio_features(input_features, feature_attention_mask)
+                # 兼容transformers 5.0
+                if hasattr(audio_res, 'last_hidden_state'):
+                    audio_embeds = audio_res.last_hidden_state
+                else:
+                    audio_embeds = audio_res
+                inputs_embeds = inputs_embeds + audio_embeds.mean() * 0.
+        else:
+            audio_res = model.thinker.get_audio_features(input_features, feature_attention_mask)
+            # 兼容transformers 5.0
+            if hasattr(audio_res, 'last_hidden_state'):
+                audio_embeds = audio_res.last_hidden_state
+            else:
+                audio_embeds = audio_res
+            audio_mask = (input_ids == thinker_config.audio_token_index).unsqueeze(-1).expand_as(inputs_embeds)
+            audio_embeds = audio_embeds.to(inputs_embeds.device, inputs_embeds.dtype)
+            inputs_embeds = inputs_embeds.masked_scatter(audio_mask, audio_embeds)
+
+        return {'inputs_embeds': inputs_embeds}
+
+    def _get_position_ids(self, inputs: Dict[str, Any]):
+        """辅助函数，用来获取mrope的position_ids"""
+        feature_attention_mask = inputs.get('feature_attention_mask')
+        if feature_attention_mask is not None:
+            audio_feature_lengths = torch.sum(feature_attention_mask, dim=1)
+        else:
+            audio_feature_lengths = None
+        video_second_per_grid = inputs.pop('video_second_per_grid', None)
+        input_ids = inputs['input_ids']
+        attention_mask = inputs.get('attention_mask')
+        if attention_mask is None:
+            attention_mask = torch.ones_like(input_ids)
+        position_ids, _ = self.model.thinker.get_rope_index(
+            input_ids,
+            inputs.get('image_grid_thw'),
+            inputs.get('video_grid_thw'),
+            attention_mask,
+            self.use_audio_in_video,
+            audio_feature_lengths,
+            video_second_per_grid,
+        )
+        return self._concat_text_position_ids(position_ids)  # 第一维为text_position_ids
+
+    def _data_collator(self, batch: List[Dict[str, Any]], *, padding_to: Optional[int] = None) -> Dict[str, Any]:
+        """传入dataloader的`collate_fn`"""
+        res = super()._data_collator(batch, padding_to=padding_to)
+        if not self.padding_free and self.is_training:
+            # 其中padding_free/packing场景将会在packing_row中处理position_ids。
+            res['position_ids'] = self._get_position_ids(res)
+        if 'position_ids' in res:
+            # 创建`packed_seq_params`以支持padding_free/packing & flash-attn
+            position_ids = res['position_ids']
+            res['position_ids'] = position_ids[1:]
+            res['text_position_ids'] = text_position_ids = position_ids[0]
+            # https://github.com/huggingface/transformers/pull/40194
+            res.update(get_packed_seq_params(text_position_ids))
+        return res
+
+    def _data_collator_mm_data(self, batch: List[Dict[str, Any]]) -> Dict[str, Any]:
+        """处理`_data_collator`函数中的多模态部分。（该函数兼容padding_free/packing）"""
+        res = super()._data_collator_mm_data(batch)
+        video_second_per_grid = self.gather_list(batch, 'video_second_per_grid')
+        if video_second_per_grid:
+            res['video_second_per_grid'] = video_second_per_grid
+        input_features = [b['input_features'] for b in batch if b.get('input_features') is not None]
+        feature_attention_mask = [
+            b['feature_attention_mask'] for b in batch if b.get('feature_attention_mask') is not None
+        ]
+        if input_features:
+            res['input_features'] = torch.concat(input_features)
+            res['feature_attention_mask'] = torch.concat(feature_attention_mask)
+        return res
+
+    def generate(self, model, *args, **kwargs):
+        """`TransformersEngine`会调用template.generate方法进行文本生成，这里继承进行自定义。"""
+        if kwargs.get('video_grid_thw') is not None:
+            kwargs['use_audio_in_video'] = self.use_audio_in_video
+        return super().generate(model, *args, **kwargs)
+
+
+register_template(
+    TemplateMeta('my_qwen2_5_omni', prefix=[], prompt=['<|im_start|>user\n{{QUERY}}<|im_end|>\n<|im_start|>assistant\n'],
+                 chat_sep=['<|im_end|>\n'], suffix=['<|im_end|>'],
+                 system_prefix=['<|im_start|>system\n{{SYSTEM}}<|im_end|>\n'],
+                 default_system='You are a helpful assistant.', stop_words=['<|endoftext|>'],
+                 agent_template='hermes',
+                 template_cls=Qwen2_5OmniTemplate))
+
+if __name__ == '__main__':
+    # 测试与debug
+    model, processor = get_model_processor('Qwen/Qwen2.5-Omni-7B', model_type='my_qwen2_5_omni')
+    template = get_template(processor, template_type='my_qwen2_5_omni')
+    data = {
+        'messages': [
+            {'role': 'user', 'content': '描述视频<video>与图片<image>内容。'},
+            {'role': 'assistant', 'content': '一个小孩和一只猫咪。'},
+        ],
+        'videos': ['https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/baby.mp4'],
+        'images': ['https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/cat.png'],
+    }
+    template.set_mode('train')
+    encoded = template.encode(data)
+    print('input_ids: ' + template.safe_decode(encoded['input_ids']))
+    print('labels: ' + template.safe_decode(encoded['labels']))
+    print('keys: ' + str(encoded.keys()))
+```
+
+
+## 推理对齐
+接下来，你需要进行TransformersEngine与transformers的推理对齐。通常你需要对齐`input_ids`以及输出内容。你可以书写以下测试函数：
+
+```python
+import os
+from transformers import Qwen2_5OmniForConditionalGeneration, Qwen2_5OmniProcessor
+from qwen_omni_utils import process_mm_info
+from modelscope import snapshot_download
+from swift.infer_engine import TransformersEngine, InferRequest, RequestConfig
+import requests
+
+def infer_hf():
+    model_dir = snapshot_download('Qwen/Qwen2.5-Omni-7B')
+    model = Qwen2_5OmniForConditionalGeneration.from_pretrained(
+        model_dir, torch_dtype="auto", device_map="auto", attn_implementation='flash_attention_2')
+    processor = Qwen2_5OmniProcessor.from_pretrained(model_dir)
+    # 使用decord读取视频（暂不支持url）
+    resp = requests.get('https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/baby.mp4')
+    with open('_baby.mp4', 'wb') as f:
+        f.write(resp.content)
+
+    conversation = [
+        {
+            "role": "user",
+            "content": [
+                {"type": "video", "video": "_baby.mp4"},
+                {"type": "image", "image": "http://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/cat.png"},
+                {"type": "text", "text": "描述视频和图像。"},
+            ],
+        },
+    ]
+
+    USE_AUDIO_IN_VIDEO = False
+    text = processor.apply_chat_template(conversation, add_generation_prompt=True, tokenize=False)
+    audios, images, videos = process_mm_info(conversation, use_audio_in_video=USE_AUDIO_IN_VIDEO)
+    inputs = processor(text=text, audio=audios, images=images, videos=videos, return_tensors="pt", padding=True,
+                       use_audio_in_video=USE_AUDIO_IN_VIDEO)
+    inputs = inputs.to(model.device).to(model.dtype)
+    text_ids = model.generate(**inputs, use_audio_in_video=USE_AUDIO_IN_VIDEO, thinker_do_sample=False,
+                              return_audio=False)
+    text = processor.batch_decode(text_ids[:, inputs['input_ids'].shape[1]:], skip_special_tokens=True, clean_up_tokenization_spaces=False)
+    return inputs['input_ids'][0].tolist(), text[0]
+
+def test_my_qwen2_5_omni():
+    engine = TransformersEngine('Qwen/Qwen2.5-Omni-7B', model_type='my_qwen2_5_omni', attn_impl='flash_attention_2')
+    infer_request = InferRequest(messages=[{
+        "role": "user",
+        "content": "<video><image>描述视频和图像。",
+    }],
+        videos=["https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/baby.mp4"],
+        images=["http://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/cat.png"],
+    )
+    request_config = RequestConfig(temperature=0, max_tokens=512)
+    input_ids = engine.template.encode(infer_request)['input_ids']
+    resp_list = engine.infer([infer_request], request_config)
+    resp = resp_list[0].choices[0].message.content
+    return input_ids, resp
+
+
+if __name__ == '__main__':
+    # 开启debug模式，会打印`TransformersEngine.infer`的input_ids和generate_ids
+    os.environ['SWIFT_DEBUG'] = '1'
+    input_ids_hf, response_hf = infer_hf()
+    input_ids_swift, response_swift = test_my_qwen2_5_omni()
+    # 测试input_ids和response对齐
+    assert input_ids_hf == input_ids_swift
+    assert response_hf == response_swift
+```
+
+
+## 开始训练
+
+使用python代码训练，这通常更容易debug：
+```python
+from swift import sft_main, SftArguments
+import os
+if __name__ == '__main__':
+    os.environ['MAX_PIXELS'] = '1003520'
+    sft_main(SftArguments(
+        model='Qwen/Qwen2.5-Omni-7B',
+        dataset=['AI-ModelScope/LaTeX_OCR#5000'],
+        model_type='my_qwen2_5_omni',
+        template='my_qwen2_5_omni',
+        load_from_cache_file=True,
+        split_dataset_ratio=0.01,
+        tuner_type='lora',
+        torch_dtype='bfloat16',
+        attn_impl='flash_attn',
+        padding_free=True,
+        num_train_epochs=1,
+        per_device_train_batch_size=16,
+        per_device_eval_batch_size=16,
+        learning_rate=1e-4,
+        lora_rank=8,
+        lora_alpha=32,
+        target_modules=['all-linear'],
+        freeze_vit=True,
+        freeze_aligner=True,
+        gradient_accumulation_steps=1,
+        eval_steps=50,
+        save_steps=50,
+        save_total_limit=2,
+        logging_steps=5,
+        max_length=2048,
+        output_dir='output',
+        warmup_ratio=0.05,
+        dataloader_num_workers=4,
+        dataset_num_proc=1,
+    ))
+```
+
+使用命令行训练：
+```shell
+# 4 * 35GiB
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+NPROC_PER_NODE=4 \
+VIDEO_MAX_PIXELS=50176 \
+FPS_MAX_FRAMES=12 \
+MAX_PIXELS=1003520 \
+swift sft \
+    --model Qwen/Qwen2.5-Omni-7B \
+    --model_type my_qwen2_5_omni \
+    --template my_qwen2_5_omni \
+    --external_plugins 'examples/custom/my_qwen2_5_omni/my_register.py' \
+    --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#2000' \
+              'AI-ModelScope/LaTeX_OCR:human_handwrite#2000' \
+              'speech_asr/speech_asr_aishell1_trainsets:validation#2000' \
+              'swift/VideoChatGPT:all#2000' \
+    --load_from_cache_file true \
+    --split_dataset_ratio 0.01 \
+    --tuner_type lora \
+    --torch_dtype bfloat16 \
+    --attn_impl flash_attn \
+    --padding_free true \
+    --packing true \
+    --num_train_epochs 3 \
+    --per_device_train_batch_size 1 \
+    --per_device_eval_batch_size 1 \
+    --learning_rate 1e-4 \
+    --lora_rank 8 \
+    --lora_alpha 32 \
+    --target_modules all-linear \
+    --freeze_vit true \
+    --freeze_aligner true \
+    --gradient_accumulation_steps 1 \
+    --eval_steps 50 \
+    --save_steps 50 \
+    --save_total_limit 2 \
+    --logging_steps 5 \
+    --max_length 4096 \
+    --output_dir output \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --dataset_num_proc 1 \
+    --deepspeed zero2
+```
+
+训练后对验证集进行推理：（环境变量请与训练时对齐）
+```shell
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+CUDA_VISIBLE_DEVICES=0 \
+VIDEO_MAX_PIXELS=50176 \
+FPS_MAX_FRAMES=12 \
+MAX_PIXELS=1003520 \
+swift infer \
+   --adapters output/vx-xxx/checkpoint-xxx \
+    --stream true \
+    --max_new_tokens 512 \
+    --load_data_args true
+```
+
+使用以下命令将训练权重推送到 Modelscope：
+```shell
+swift export \
+    --adapters output/vx-xxx/checkpoint-xxx \
+    --push_to_hub true \
+    --hub_model_id '<your-model-id>' \
+    --hub_token '<your-sdk-token>'
+```
+
+## 提交PR
+
+如果你想给ms-swift提交PR，你需要额外运行以下命令，对代码进行整理：
+
+```shell
+pip install pre-commit
+pre-commit run --all-files
+```
@@ -0,0 +1,280 @@
+# Metax支持
+
+## 1. 在 Metax 平台上使用 Swift
+你可以选择构建自己的镜像，也可以直接拉取已有的预构建镜像。本文以拉取预构建镜像为例，演示如何在 Metax 上使用 ms-swift。
+### 1.1. 启动 ms-swift 容器
+```bash
+docker pull mx-devops-acr-cn-shanghai.cr.volces.com/opensource/public-ai-release/maca/ms-swift:3.10.3-maca.ai3.3.0.16-torch2.6-py310-ubuntu22.04-amd64
+# 你可以根据需要调整 --privileged 参数，并仅挂载特定的 GPU 卡。
+# 更多信息请参考我们的官方文档：https://developer.metax-tech.com
+# 必须通过 --device 挂载 Metax GPU 设备：--device=/dev/dri --device=/dev/mxcd
+docker run  -it --net=host --uts=host --ipc=host --privileged=true --group-add video  \
+    --shm-size 100gb --ulimit memlock=-1 \
+    --security-opt seccomp=unconfined --security-opt apparmor=unconfined \
+    --device=/dev/dri --device=/dev/mxcd \
+    -v /root/workspace:/external \
+    --name swift_test \
+    mx-devops-acr-cn-shanghai.cr.volces.com/opensource/public-ai-release/maca/ms-swift:3.10.3-maca.ai3.3.0.16-torch2.6-py310-ubuntu22.04-amd64
+```
+## 2. 环境检查
+### 2.1. 检查 Metax GPU 是否可用
+得益于与 CUDA 的兼容性，我们可以像使用 NVIDIA GPU 一样检查 Metax 设备是否可用：
+```python
+import torch
+print(torch.cuda.is_available())
+# True
+```
+### 2.2. 检查 GPU 之间的 P2P 连接拓扑
+```bash
+mx-smi topo -m
+# output
+=================== MetaX System Management Interface Log ===================
+Timestamp                                         : Wed Feb 11 16:37:10 2026
+
+Attached GPUs                                     : 8
+Device link type matrix
+        GPU0    GPU1    GPU2    GPU3    GPU4    GPU5    GPU6    GPU7    Node Affinity  CPU Affinity
+GPU0    X       MX      MX      MX      NODE    NODE    NODE    NODE    0              0-31,64-95
+GPU1    MX      X       MX      MX      NODE    NODE    NODE    NODE    0              0-31,64-95
+GPU2    MX      MX      X       MX      NODE    NODE    NODE    NODE    0              0-31,64-95
+GPU3    MX      MX      MX      X       NODE    NODE    NODE    NODE    0              0-31,64-95
+GPU4    NODE    NODE    NODE    NODE    X       MX      MX      MX      0              0-31,64-95
+GPU5    NODE    NODE    NODE    NODE    MX      X       MX      MX      0              0-31,64-95
+GPU6    NODE    NODE    NODE    NODE    MX      MX      X       MX      0              0-31,64-95
+GPU7    NODE    NODE    NODE    NODE    MX      MX      MX      X       0              0-31,64-95
+
+Legend:
+  X    = Self
+  SYS  = Connection traversing PCIe as well as the SMP interconnect between NUMA nodes (e.g., QPI/UPI)
+  NODE = Connection traversing PCIe as well as the interconnect between PCIe Host Bridges within a NUMA node
+  PHB  = Connection traversing PCIe as well as a PCIe Host Bridge (typically the CPU)
+  PXB  = Connection traversing multiple PCIe bridges (without traversing the PCIe Host Bridge)
+  PIX  = Connection traversing at most a single PCIe bridge
+  MX   = Connection traversing MetaXLink
+  ETH  = Connection traversing Eth
+  NA   = Connection type is unknown
+```
+### 2.3. 查看 GPU 状态
+```bash
+mx-smi
+# output
+    =================== MetaX System Management Interface Log ===================
+Timestamp                                         : Wed Feb 11 09:55:49 2026
+
+Attached GPUs                                     : 8
+---------------------------------------------------------------------------------+
+| MX-SMI 2.2.9                       Kernel Mode Driver Version: 3.4.4            |
+| MACA Version: 3.3.0.15             BIOS Version: 1.30.0.0                       |
+|------------------+-----------------+---------------------+----------------------|
+| Board       Name | GPU   Persist-M | Bus-id              | GPU-Util      sGPU-M |
+| Pwr:Usage/Cap    | Temp       Perf | Memory-Usage        | GPU-State            |
+|==================+=================+=====================+======================|
+| 0     MetaX C500 | 0           Off | 0000:0e:00.0        | 0%          Disabled |
+| 57W / 350W       | 35C          P0 | 826/65536 MiB       | Available            |
+------------------+-----------------+---------------------+----------------------+
+| 1     MetaX C500 | 1           Off | 0000:0f:00.0        | 0%          Disabled |
+| 58W / 350W       | 37C          P0 | 826/65536 MiB       | Available            |
+------------------+-----------------+---------------------+----------------------+
+| 2     MetaX C500 | 2           Off | 0000:10:00.0        | 0%          Disabled |
+| 58W / 350W       | 36C          P0 | 826/65536 MiB       | Available            |
+------------------+-----------------+---------------------+----------------------+
+| 3     MetaX C500 | 3           Off | 0000:12:00.0        | 0%          Disabled |
+| 60W / 350W       | 35C          P0 | 826/65536 MiB       | Available            |
+------------------+-----------------+---------------------+----------------------+
+| 4     MetaX C500 | 4           Off | 0000:35:00.0        | 0%          Disabled |
+| 57W / 350W       | 33C          P0 | 826/65536 MiB       | Available            |
+------------------+-----------------+---------------------+----------------------+
+| 5     MetaX C500 | 5           Off | 0000:36:00.0        | 0%          Disabled |
+| 56W / 350W       | 34C          P0 | 826/65536 MiB       | Available            |
+------------------+-----------------+---------------------+----------------------+
+| 6     MetaX C500 | 6           Off | 0000:37:00.0        | 0%          Disabled |
+| 55W / 350W       | 34C          P0 | 826/65536 MiB       | Available            |
+------------------+-----------------+---------------------+----------------------+
+| 7     MetaX C500 | 7           Off | 0000:38:00.0        | 0%          Disabled |
+| 56W / 350W       | 36C          P0 | 826/65536 MiB       | Available            |
+------------------+-----------------+---------------------+----------------------+
+
+---------------------------------------------------------------------------------+
+| Process:                                                                        |
+|  GPU                    PID         Process Name                 GPU Memory     |
+|                                                                  Usage(MiB)     |
+|=================================================================================|
+|  no process found                                                               |
+---------------------------------------------------------------------------------+
+```
+
+## 3. 运行示例
+我们支持直接使用社区版 Swift，同时在镜像中 /workspace 目录下提供了经过更多优化的版本。强烈建议优先使用该目录下的软件包。
+
+### 3.1. 运行 Swift 示例
+在大多数场景下，可直接运行 Swift 的训练示例：
+```bash
+# We assume that the ms-swift code is under /workspace
+cd /workspace/ms-swift/
+bash examples/train/full/train.sh
+
+```
+运行输出示例（节选）：
+```bash
+# output:
+{'loss': 1.47077751, 'grad_norm': 10.5625, 'learning_rate': 2e-06, 'token_acc': 0.65511727, 'epoch': 0.01, 'global_step/max_steps': '1/94', 'percentage': '1.06%', 'elapsed_time': '2s', 'remaining_time': '4m 28s', 'memory(GiB)': 4.87, 'train_speed(iter/s)': 0.345807}
+{'loss': 1.58882141, 'grad_norm': 10.75, 'learning_rate': 1e-05, 'token_acc': 0.61763144, 'epoch': 0.05, 'global_step/max_steps': '5/94', 'percentage': '5.32%', 'elapsed_time': '10s', 'remaining_time': '3m 12s', 'memory(GiB)': 5.64, 'train_speed(iter/s)': 0.461462}
+{'loss': 1.56617603, 'grad_norm': 12.8125, 'learning_rate': 9.92e-06, 'token_acc': 0.61519274, 'epoch': 0.11, 'global_step/max_steps': '10/94', 'percentage': '10.64%', 'elapsed_time': '20s', 'remaining_time': '2m 52s', 'memory(GiB)': 5.64, 'train_speed(iter/s)': 0.485796}
+{'loss': 1.63347206, 'grad_norm': 13.6875, 'learning_rate': 9.69e-06, 'token_acc': 0.60373975, 'epoch': 0.16, 'global_step/max_steps': '15/94', 'percentage': '15.96%', 'elapsed_time': '30s', 'remaining_time': '2m 39s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.493855}
+{'loss': 1.60613976, 'grad_norm': 11.0, 'learning_rate': 9.32e-06, 'token_acc': 0.59997221, 'epoch': 0.21, 'global_step/max_steps': '20/94', 'percentage': '21.28%', 'elapsed_time': '39s', 'remaining_time': '2m 27s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.500516}
+{'loss': 1.45015478, 'grad_norm': 15.25, 'learning_rate': 8.8e-06, 'token_acc': 0.62373584, 'epoch': 0.27, 'global_step/max_steps': '25/94', 'percentage': '26.60%', 'elapsed_time': '49s', 'remaining_time': '2m 16s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.50548}
+{'loss': 1.39427547, 'grad_norm': 13.9375, 'learning_rate': 8.18e-06, 'token_acc': 0.6357994, 'epoch': 0.32, 'global_step/max_steps': '30/94', 'percentage': '31.91%', 'elapsed_time': '59s', 'remaining_time': '2m 5s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.508409}
+{'loss': 1.53672237, 'grad_norm': 11.125, 'learning_rate': 7.45e-06, 'token_acc': 0.61650612, 'epoch': 0.37, 'global_step/max_steps': '35/94', 'percentage': '37.23%', 'elapsed_time': '1m 8s', 'remaining_time': '1m 55s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.510425}
+{'loss': 1.54039021, 'grad_norm': 13.8125, 'learning_rate': 6.65e-06, 'token_acc': 0.61613974, 'epoch': 0.43, 'global_step/max_steps': '40/94', 'percentage': '42.55%', 'elapsed_time': '1m 18s', 'remaining_time': '1m 45s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.512302}
+{'loss': 1.40159426, 'grad_norm': 9.4375, 'learning_rate': 5.79e-06, 'token_acc': 0.64041773, 'epoch': 0.48, 'global_step/max_steps': '45/94', 'percentage': '47.87%', 'elapsed_time': '1m 27s', 'remaining_time': '1m 35s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.512983}
+{'loss': 1.54977188, 'grad_norm': 11.9375, 'learning_rate': 4.91e-06, 'token_acc': 0.61078816, 'epoch': 0.53, 'global_step/max_steps': '50/94', 'percentage': '53.19%', 'elapsed_time': '1m 37s', 'remaining_time': '1m 25s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.514489}
+{'loss': 1.6754509, 'grad_norm': 13.0625, 'learning_rate': 4.04e-06, 'token_acc': 0.58574393, 'epoch': 0.59, 'global_step/max_steps': '55/94', 'percentage': '58.51%', 'elapsed_time': '1m 46s', 'remaining_time': '1m 15s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.515752}
+{'loss': 1.37204351, 'grad_norm': 9.25, 'learning_rate': 3.19e-06, 'token_acc': 0.6391937, 'epoch': 0.64, 'global_step/max_steps': '60/94', 'percentage': '63.83%', 'elapsed_time': '1m 56s', 'remaining_time': '1m 5s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.516829}
+{'loss': 1.47697926, 'grad_norm': 11.375, 'learning_rate': 2.4e-06, 'token_acc': 0.62817259, 'epoch': 0.69, 'global_step/max_steps': '65/94', 'percentage': '69.15%', 'elapsed_time': '2m 5s', 'remaining_time': '55s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.517947}
+{'loss': 1.4336628, 'grad_norm': 8.125, 'learning_rate': 1.69e-06, 'token_acc': 0.63453862, 'epoch': 0.75, 'global_step/max_steps': '70/94', 'percentage': '74.47%', 'elapsed_time': '2m 14s', 'remaining_time': '46s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.518833}
+{'loss': 1.54315252, 'grad_norm': 9.625, 'learning_rate': 1.08e-06, 'token_acc': 0.60202073, 'epoch': 0.8, 'global_step/max_steps': '75/94', 'percentage': '79.79%', 'elapsed_time': '2m 24s', 'remaining_time': '36s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.519627}
+{'loss': 1.47180223, 'grad_norm': 9.5625, 'learning_rate': 6e-07, 'token_acc': 0.62211501, 'epoch': 0.85, 'global_step/max_steps': '80/94', 'percentage': '85.11%', 'elapsed_time': '2m 33s', 'remaining_time': '26s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.520284}
+{'loss': 1.44068375, 'grad_norm': 10.125, 'learning_rate': 2.5e-07, 'token_acc': 0.62673112, 'epoch': 0.91, 'global_step/max_steps': '85/94', 'percentage': '90.43%', 'elapsed_time': '2m 43s', 'remaining_time': '17s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.520331}
+{'loss': 1.44893646, 'grad_norm': 8.375, 'learning_rate': 5e-08, 'token_acc': 0.63837478, 'epoch': 0.96, 'global_step/max_steps': '90/94', 'percentage': '95.74%', 'elapsed_time': '2m 52s', 'remaining_time': '7s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.520707}
+{'train_runtime': 183.4332, 'train_samples_per_second': 8.177, 'train_steps_per_second': 0.512, 'train_loss': 1.50650934, 'token_acc': 0.6194337, 'epoch': 1.0, 'global_step/max_steps': '94/94', 'percentage': '100.00%', 'elapsed_time': '3m 3s', 'remaining_time': '0s', 'memory(GiB)': 6.5, 'train_speed(iter/s)': 0.512463}
+Train: 100%|█████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████████| 94/94 [03:03<00:00,  1.95s/it]
+[INFO:swift] last_model_checkpoint: /workspace/ms-swift/output/v0-20260211-143035/checkpoint-94
+[INFO:swift] best_model_checkpoint: None
+[INFO:swift] images_dir: /workspace/ms-swift/output/v0-20260211-143035/images
+[INFO:swift] End time of running main: 2026-02-11 14:34:09.521336
+
+```
+### 3.2. 使用 Megatron-LM 作为 Swift 后端
+若希望使用 Megatron-LM 作为 Swift 的后端，需设置 `MEGATRON_LM_PATH` 环境变量：
+
+```bash
+export MEGATRON_LM_PATH=/workspace/Megatron-LM-0.15.0
+cd /workspace/ms-swift
+bash examples/megatron/pretrain.sh
+```
+
+### 3.3. 使用其他版本的 ms-swift
+Metax 平台要求使用与 Maca 兼容的软件包。例如，编译可能依赖 torch2.8，因此需使用 torch2.8+maca3.3.x.x 版本。
+
+默认情况下，安装会覆盖环境中已有的 PyTorch。因此，建议使用 --no-deps 参数进行安装：
+```bash
+
+git clone -b ${SWIFT_VERSION} https://github.com/modelscope/ms-swift.git
+cd ms-swift
+pip install . --no-deps
+
+```
+每次环境变更后，请检查 PyTorch 版本及其可用性：
+```bash
+pip list |grep torch
+# output:
+# torch2.x.x+metax3.x.x.x
+```
+
+```python
+import torch
+torch.cuda.is_available()
+```
+
+### 3.4. Metax 与 NVIDIA CUDA 的差异
+Metax 在大部分接口上与 NVIDIA 对齐，但在某些软件行为和环境变量上存在差异。
+
+#### 3.4.1. MACA_MPS_MODE
+默认情况下，MACA 不允许多个进程共享同一块 GPU。如果 GPU 已被占用，则无法启动新进程。
+
+如需启用类似 MPS（Multi-Process Service）的功能，需设置：`MACA_MPS_MODE=1`
+```bash
+# 运行其他脚本...
+export MACA_MPS_MODE=1
+cd /workspace/ms-swift/
+bash examples/train/full/train.sh
+```
+#### 3.4.2. MCCL_SOCKET_IFNAME GLOO_SOCKET_IFNAME & MCCL_IB_HCA
+在多节点训练时，建议设置以下环境变量以确保节点间通信正常：
+> MCCL_SOCKET_IFNAME：用于 MCCL 通信的网络接口
+> GLOO_SOCKET_IFNAME：用于 GLOO 通信的网络接口
+> MCCL_IB_HCA：指定使用的 InfiniBand 设备
+
+可通过 ifconfig 和 mx-smi 确定所用网卡和 IB 设备：
+```bash
+ifconfig
+# output
+ens20f0np0: xxx
+            inet: your node ip
+            xxx
+...
+```
+```bash
+mx-smi topo -n
+# output
+mx-smi  version: 2.2.9
+
+=================== MetaX System Management Interface Log ===================
+Timestamp                                         : Wed Feb 11 18:53:44 2026
+
+Attached GPUs                                     : 8
+Device link type matrix
+        GPU0    GPU1    GPU2    GPU3    GPU4    GPU5    GPU6    GPU7    NIC0    NIC1    NIC2    NIC3    NIC4    NIC5    Node Affinity  CPU Affinity
+GPU0    X       MX      MX      MX      NODE    NODE    NODE    NODE    PIX     PIX     NODE    NODE    SYS     SYS     0              0-31,64-95
+GPU1    MX      X       MX      MX      NODE    NODE    NODE    NODE    PIX     PIX     NODE    NODE    SYS     SYS     0              0-31,64-95
+GPU2    MX      MX      X       MX      NODE    NODE    NODE    NODE    PIX     PIX     NODE    NODE    SYS     SYS     0              0-31,64-95
+GPU3    MX      MX      MX      X       NODE    NODE    NODE    NODE    PIX     PIX     NODE    NODE    SYS     SYS     0              0-31,64-95
+GPU4    NODE    NODE    NODE    NODE    X       MX      MX      MX      NODE    NODE    PIX     PIX     SYS     SYS     0              0-31,64-95
+GPU5    NODE    NODE    NODE    NODE    MX      X       MX      MX      NODE    NODE    PIX     PIX     SYS     SYS     0              0-31,64-95
+GPU6    NODE    NODE    NODE    NODE    MX      MX      X       MX      NODE    NODE    PIX     PIX     SYS     SYS     0              0-31,64-95
+GPU7    NODE    NODE    NODE    NODE    MX      MX      MX      X       NODE    NODE    PIX     PIX     SYS     SYS     0              0-31,64-95
+NIC0    PIX     PIX     PIX     PIX     NODE    NODE    NODE    NODE    X       PIX     NODE    NODE    SYS     SYS
+NIC1    PIX     PIX     PIX     PIX     NODE    NODE    NODE    NODE    PIX     X       NODE    NODE    SYS     SYS
+NIC2    NODE    NODE    NODE    NODE    PIX     PIX     PIX     PIX     NODE    NODE    X       PIX     SYS     SYS
+NIC3    NODE    NODE    NODE    NODE    PIX     PIX     PIX     PIX     NODE    NODE    PIX     X       SYS     SYS
+NIC4    SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     X       PIX
+NIC5    SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     SYS     PIX     X
+
+Legend:
+  X    = Self
+  SYS  = Connection traversing PCIe as well as the SMP interconnect between NUMA nodes (e.g., QPI/UPI)
+  NODE = Connection traversing PCIe as well as the interconnect between PCIe Host Bridges within a NUMA node
+  PHB  = Connection traversing PCIe as well as a PCIe Host Bridge (typically the CPU)
+  PXB  = Connection traversing multiple PCIe bridges (without traversing the PCIe Host Bridge)
+  PIX  = Connection traversing at most a single PCIe bridge
+  MX   = Connection traversing MetaXLink
+  ETH  = Connection traversing Eth
+  NA   = Connection type is unknown
+
+NIC Legend:
+
+  NIC0: mlx5_0
+  NIC1: mlx5_1
+  NIC2: mlx5_2
+  NIC3: mlx5_3
+  NIC4: mlx5_4
+  NIC5: mlx5_5
+# 根据拓扑信息可知：
+#  1. GPU0–GPU3 与 NIC0/NIC1（即 mlx5_0, mlx5_1）通信
+#  2. GPU4–GPU7 与 NIC2/NIC3（即 mlx5_2, mlx5_3）通信
+
+
+```
+因此，推荐设置如下:
+`MCCL_SOCKET_IFNAME=ens20f0np0`
+`GLOO_SOCKET_IFNAME=ens20f0np0`
+`MCCL_IB_HCA=mlx5_0,mlx5_1,mlx5_2,mlx5_3`
+
+```bash
+# node 1
+export MCCL_SOCKET_IFNAME=ens20f0np0
+export GLOO_SOCKET_IFNAME=ens20f0np0
+export MCCL_IB_HCA=mlx5_0,mlx5_1,mlx5_2,mlx5_3
+cd /workspace/ms-swift/
+bash examples/train/multi-node/torchrun/train_node1.sh
+```
+
+```bash
+# node 2
+# 需修改脚本中的 master_addr 为节点1的IP
+export MCCL_SOCKET_IFNAME=ens20f0np0
+export GLOO_SOCKET_IFNAME=ens20f0np0
+export MCCL_IB_HCA=mlx5_0,mlx5_1,mlx5_2,mlx5_3
+cd /workspace/ms-swift/
+bash examples/train/multi-node/torchrun/train_node2.sh
+```
@@ -0,0 +1,6 @@
+
+# 更多最佳实践
+
+- [Qwen2.5自我认知微调](https://github.com/modelscope/ms-swift/tree/main/examples/notebook/qwen2_5-self-cognition)
+- [Qwen2-VL Latex-OCR微调](https://github.com/modelscope/ms-swift/tree/main/examples/notebook/qwen2vl-ocr)
+- [Qwen2.5-VL Grounding任务微调](https://github.com/modelscope/ms-swift/tree/main/examples/notebook/qwen2_5-vl-grounding)
@@ -0,0 +1,849 @@
+# NPU支持
+
+我们在 ms-swift 上增加了对昇腾 NPU 的支持，用户可以在昇腾 NPU 上进行模型的微调和推理。
+
+本文档介绍如何在昇腾 NPU 上完成环境准备、模型训练、保存合并、推理、部署和常见问题排查。
+
+如果你是第一次在 NPU 上使用 ms-swift，推荐按以下顺序阅读：
+
+1. 先查看“支持范围速览”，确认模型、算法和后端是否已验证。
+2. 根据“选择你的使用路线”决定只装基础环境，还是额外安装 MindSpeed/Megatron-SWIFT。
+3. 根据自己的环境管理习惯选择“本地环境安装”或“镜像/容器环境安装”，然后执行“NPU 可用性检查”。
+4. 使用“快速跑通”完成一次 ModelScope 模型 LoRA 训练、合并、推理和部署。
+5. 需要更大规模训练时，再阅读 DDP、DeepSpeed 和 MindSpeed/Megatron-SWIFT 相关章节。
+
+## 硬件配套和支持的操作系统
+
+**表 1**  产品硬件支持列表
+
+|产品|是否支持|
+|--|:-:|
+|<term>Ascend 950 系列产品</term>|√|
+|<term>Atlas A3 训练系列产品</term>|√|
+|<term>Atlas A3 推理系列产品</term>|x|
+|<term>Atlas A2 训练系列产品</term>|√|
+|<term>Atlas A2 推理系列产品</term>|x|
+|<term>Atlas 200I/500 A2 推理产品</term>|x|
+|<term>Atlas 推理系列产品</term>|x|
+|<term>Atlas 训练系列产品</term>|x|
+
+> [!NOTE]
+>
+> 本节表格中“√”代表支持，“x”代表不支持。
+
+- 各硬件产品对应物理机部署场景支持的操作系统请参考[兼容性查询助手](https://www.hiascend.com/hardware/compatibility)。
+- 各硬件产品对应虚拟机及容器部署场景支持的操作系统请参考《CANN 软件安装》的“[操作系统兼容性说明](https://www.hiascend.com/document/detail/zh/canncommercial/900/softwareinst/instg/instg_0101.html?OS=openEuler&InstallType=netyum)”章节（商用版）或“[操作系统兼容性说明](https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/900/softwareinst/instg/instg_0101.html?OS=openEuler&InstallType=netyum)”章节（社区版）。
+
+## 支持范围速览
+
+推荐基础环境版本：
+
+| software  | version         |
+| --------- | --------------- |
+| Python    | >= 3.10, < 3.12 |
+| CANN      | >= 8.5.1        |
+| torch     | >= 2.7.1        |
+| torch_npu | >= 2.7.1.post4  |
+
+基础环境准备请参照 [Ascend PyTorch 安装文档](https://gitcode.com/Ascend/pytorch)。本文示例实验环境为 8 * 昇腾910B3 64G。
+注：vllm ascend系列官方推荐版本配套已更新至 CANN9.0.0 torch 2.9.0 torch_npu 2.9.0 vllm-ascend 0.18.0(A3) 0.19.1(A5)，详情请参阅 [vLLM Ascend 安装文档](https://docs.vllm.ai/projects/ascend/en/v0.18.0/installation.html)。
+
+| 一级特性 | 特性                | 进展     |
+| -------- | ------------------- | -------- |
+| 训练范式 | CPT                 | 已支持   |
+|          | SFT                 | 已支持   |
+|          | DPO                 | 已支持   |
+|          | RM                  | 已支持   |
+| 分布式   | DDP                 | 已支持   |
+|          | FSDP                | 已支持   |
+|          | FSDP2               | 已支持   |
+|          | DeepSpeed           | 已支持   |
+|          | MindSpeed(Megatron) | 已支持   |
+| 低参微调 | FULL                | 已支持   |
+|          | LoRA                | 已支持   |
+|          | QLoRA               | 暂不支持 |
+| RLHF     | GRPO                | 已支持   |
+|          | PPO                 | 已支持   |
+| 性能优化 | FA 等融合算子        | 已支持    |
+|          | Liger-Kernel        | 暂不支持 |
+| 部署     | PT                  | 已支持   |
+|          | vLLM                | 已支持   |
+|          | SGLang              | 暂不支持 |
+
+### 已验证 SFT 组合
+
+| algorithm | model families              | strategy              | hardware          |
+| --------- | --------------------------- | --------------------- | ----------------- |
+| SFT       | Qwen2.5-0.5B-Instruct       | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen2.5-1.5B-Instruct       | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen2.5-7B-Instruct         | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen2.5-VL-3B-Instruct      | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen2.5-VL-7B-Instruct      | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen2.5-Omni-3B             | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen3-8B                    | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen3-30B-A3B               | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen3-32B                   | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen3-VL-30B-A3B-Instruct   | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen3-Omni-30B-A3B-Instruct | FSDP1/FSDP2/deepspeed/Megatron | Atlas 900 A2 PODc/A3 SuperPoD |
+| SFT       | InternVL3-8B                | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Ovis2.5-2B                  | FSDP1/FSDP2/deepspeed | Atlas 900 A2 PODc |
+| SFT       | Qwen3.5-27B                 | FSDP1/FSDP2/deepspeed/Megatron | Atlas 900 A2 PODc/A3 SuperPoD |
+| SFT       | Qwen3.5-35B-A3B             | FSDP1/FSDP2/deepspeed/Megatron | Atlas 900 A2 PODc/A3 SuperPoD |
+
+### 已验证 RL 组合
+
+| algorithm | model families      | strategy  | rollout engine | hardware          |
+| --------- | ------------------- | --------- | -------------- | ----------------- |
+| **GRPO**  | Qwen2.5-7B-Instruct | deepspeed | vllm-ascend    | Atlas 900 A2 PODc |
+| **GRPO**  | Qwen3-8B            | deepspeed | vllm-ascend    | Atlas 900 A2 PODc |
+| **DPO**   | Qwen2.5-7B-Instruct | deepspeed | vllm-ascend    | Atlas 900 A2 PODc |
+| **DPO**   | Qwen3-8B            | deepspeed | vllm-ascend    | Atlas 900 A2 PODc |
+| **PPO**   | Qwen2.5-7B-Instruct | deepspeed | vllm-ascend    | Atlas 900 A2 PODc |
+| **PPO**   | Qwen3-8B            | deepspeed | vllm-ascend    | Atlas 900 A2 PODc |
+
+### 暂不支持或未完全验证
+
+| item                              |
+| --------------------------------- |
+| Liger-kernel                      |
+| 量化/QLoRA相关                    |
+| 使用sglang作为推理引擎            |
+| 使用megatron时开启ETP进行lora训练 |
+
+### PEFT Transformers 5 MoE fused expert LoRA 限制
+
+在使用 Qwen3.5-MoE、Qwen3-Omni-MoE 等 Transformers 5 MoE 结构模型进行 LoRA 训练时，部分 expert 权重可能不是普通 `nn.Linear` 模块，而是 fused `nn.Parameter`。这类参数需要依赖 PEFT 的 `target_parameters` 路径注入 LoRA。
+
+当前该路径在 `lora_dropout`、ZeRO-3/FSDP、多 adapter 等组合场景下仍未完全稳定。典型触发条件包括：
+
+- 使用 MoE 模型；
+- 使用 LoRA，并希望覆盖 fused expert 参数；
+- 模型配置或命令行 `--model_type` 触发 PEFT 的 Transformers 5 MoE target conversion 路径；
+- 使用默认 `lora_dropout != 0`，或使用 ZeRO-3/FSDP 等参数分片后端。
+
+如果只是进行常规 Qwen3.5 GRPO/SFT LoRA 训练，建议避免额外指定 `--model_type` 去扩大触发范围；若模型配置本身已经触发该路径，则优先使用 full 参数训练或关闭对应 LoRA 组合。若确实需要训练 fused expert 参数，建议等待 PEFT 上游能力稳定，或在 `lora_dropout=0` 且目标模型、训练后端已单独验证的前提下使用。
+
+## 选择你的使用路线
+
+| 场景                         | 推荐路线                                      | 是否需要 MindSpeed |
+| ---------------------------- | --------------------------------------------- | ------------------ |
+| 只做普通 SFT/LoRA/推理       | 本地环境安装或镜像/容器环境安装              | 不需要             |
+| 需要 Megatron-SWIFT 大模型训练 | 先装基础环境，再装 MindSpeed/Megatron/mcore-bridge | 需要               |
+| 需要 GRPO/PPO/DPO 等 RLHF    | 基础训练环境 + vLLM-Ascend rollout/deploy     | 通常不需要         |
+| 只是验证 NPU 是否可用        | 跑 NPU 可用性检查脚本                         | 不需要             |
+
+## 环境准备
+
+### 镜像/容器环境安装
+官方 NPU 镜像已发布在 [quay.io/ascend/ms-swift](https://quay.io/repository/ascend/ms-swift?tab=tags)。推荐优先根据设备代际、Python、CANN 和系统版本选择匹配的镜像标签；如需锁定分支或定制依赖，再使用项目提供的 Dockerfile 自行构建。容器方式的优势是依赖版本更容易固化，也便于在多台昇腾机器之间复现实验环境。
+
+下面以 A2、Python 3.11、CANN 9.0.0、Ubuntu 22.04 标签为例，实际使用时请以 Quay 标签页中适配当前机器和软件栈的最新标签为准：
+
+```shell
+docker pull quay.io/ascend/ms-swift:v4.3.0-A2-py311-CANN9.0.0-ubuntu22.04
+export IMAGE_NAME=quay.io/ascend/ms-swift:v4.3.0-A2-py311-CANN9.0.0-ubuntu22.04
+export WORKSPACE=/path/to/workspace
+```
+
+如果需要自行构建镜像，先 clone modelscope 仓库，然后使用仓库中的 [Dockerfile.ascend](https://github.com/modelscope/modelscope/blob/master/docker/Dockerfile.ascend) 和 [build_image.py](https://github.com/modelscope/modelscope/blob/master/docker/build_image.py)：
+
+```shell
+git clone https://github.com/modelscope/modelscope.git
+cd modelscope
+DOCKER_REGISTRY=ms-swift python docker/build_image.py \
+  --image_type ascend \
+  --python_version 3.11.11 \
+  --soc_version ascend910b1 \
+  --arch arm
+```
+
+当前 `build_image.py` 生成的 Ascend 镜像名格式为 `{DOCKER_REGISTRY}:{swift_branch}-{atlas_hardware}-{python_tag}-{arch}`。以上命令以 ARM 架构的 Atlas 900 A2 PODc 为例，通常会生成 `ms-swift:main-A2-py311-arm`。如果使用自行构建的镜像，请按构建日志中的镜像名替换上面的 `IMAGE_NAME`：
+
+```shell
+export IMAGE_NAME=ms-swift:main-A2-py311-arm
+```
+
+启动容器前建议先确认宿主机暴露的 NPU 设备：
+
+```shell
+ls /dev/davinci*
+```
+
+启动容器时需要把 NPU 设备、驱动、固件、`npu-smi` 和必要日志目录挂载进去。下面示例按常见 8 卡设备 `davinci0` 到 `davinci7` 编写；部分机器会额外暴露到 `davinci15`，这时请按 `ls /dev/davinci*` 的结果把对应设备都加到 `docker run` 中：
+
+```shell
+docker run -it \
+  --name swift-ascend \
+  --network=host --ipc=host --shm-size=128g \
+  --device=/dev/davinci0 --device=/dev/davinci1 \
+  --device=/dev/davinci2 --device=/dev/davinci3 \
+  --device=/dev/davinci4 --device=/dev/davinci5 \
+  --device=/dev/davinci6 --device=/dev/davinci7 \
+  --device=/dev/davinci_manager --device=/dev/devmm_svm --device=/dev/hisi_hdc \
+  -v /usr/local/Ascend/driver:/usr/local/Ascend/driver:ro \
+  -v /usr/local/Ascend/firmware:/usr/local/Ascend/firmware:ro \
+  -v /usr/local/sbin/npu-smi:/usr/local/sbin/npu-smi:ro \
+  -v /etc/ascend_install.info:/etc/ascend_install.info:ro \
+  -v /var/log/npu:/var/log/npu \
+  -v ${WORKSPACE}:/workspace \
+  ${IMAGE_NAME} \
+  /bin/bash
+```
+
+进入容器后，建议先执行 `source /usr/local/Ascend/ascend-toolkit/set_env.sh`，再运行后文的 NPU 可用性检查脚本，确认容器内可以正确访问昇腾设备。如果容器内无法识别 NPU，请优先检查 `/dev/davinci*`、`/dev/davinci_manager`、驱动目录和 `npu-smi` 是否正确挂载。
+
+### 本地环境安装
+```shell
+# 创建新的 conda 虚拟环境（可选）
+conda create -n swift-npu python=3.11 -y
+conda activate swift-npu
+
+# 注意进行后续操作前要先 source 激活 CANN 环境
+source /usr/local/Ascend/ascend-toolkit/set_env.sh
+
+# 设置 pip 全局镜像（可选，加速下载）
+pip config set global.index-url https://mirrors.aliyun.com/pypi/simple/
+pip install ms-swift -U
+
+# 使用源码安装
+git clone https://github.com/modelscope/ms-swift.git
+cd ms-swift
+pip install -e .
+
+# 安装 torch_npu
+pip install torch_npu==2.9.0 decorator
+# 如果你想要使用 deepspeed（控制显存占用，训练速度会有一定下降）
+pip install deepspeed
+
+# 如果需要使用 evaluation 功能，请安装以下包
+pip install evalscope[opencompass]
+
+# 如果需要使用 vllm-ascend 进行推理，请安装以下包（更多版本请参考 [vLLM-Ascend 官网](https://docs.vllm.ai/projects/ascend/en/latest/installation.html)）
+pip install vllm==0.18.0
+pip install vllm-ascend==0.18.0
+```
+
+### NPU 可用性检查
+
+测试环境是否安装正确，NPU能否被正常加载：
+
+```python
+from transformers.utils import is_torch_npu_available
+import torch
+
+print(is_torch_npu_available())  # True
+print(torch.npu.device_count())  # 8
+print(torch.randn(10, device='npu:0'))
+```
+
+### MindSpeed/Megatron-SWIFT 可选安装
+
+如果需要使用 MindSpeed(Megatron-LM)，请按照下面引导安装必要依赖。
+
+```shell
+# 1. 获取并切换 Megatron-LM 至 v0.16.0 版本
+git clone https://github.com/NVIDIA/Megatron-LM.git
+cd Megatron-LM
+git checkout core_v0.16.0
+cd ..
+
+# 2. 获取并安装 MindSpeed
+git clone https://gitcode.com/Ascend/MindSpeed.git
+cd MindSpeed
+git checkout core_r0.16.0
+pip install -e .
+cd ..
+
+# 3. 获取并安装 mcore-bridge
+git clone https://github.com/modelscope/mcore-bridge.git
+cd mcore-bridge
+pip install -e .
+cd ..
+
+# 4. 获取并安装 triton-ascend
+pip install triton-ascend==3.2.1 --extra-index-url=https://triton-ascend.osinfra.cn/pypi/simple
+
+# 5. 设置环境变量
+export PYTHONPATH=$PYTHONPATH:<your_local_megatron_lm_path>
+export MEGATRON_LM_PATH=<your_local_megatron_lm_path>
+
+# 6. 如需回退到 transformers 的 GatedDeltaNet 实现，可关闭 Megatron GDN
+export USE_MCORE_GDN=0
+```
+
+执行如下命令验证 MindSpeed(Megatron-LM) 是否配置成功：
+```shell
+python -c "import mindspeed.megatron_adaptor; from swift.megatron.init import init_megatron_env; init_megatron_env(); print('✓ NPU环境下的Megatron-SWIFT配置验证成功！')"
+```
+
+### Qwen3.5 FLA补丁说明
+
+当前仓库已经内置了面向昇腾 NPU 的 Qwen3.5 linear attention patch，无需用户再额外修改 `transformers` 或 `fla` 源码。该 patch 的目标不是直接替换整个 `flash-linear-attention` 包，而是在 `Qwen3.5` 实际调用的 `chunk_gated_delta_rule` 路径上，将底层 GPU Triton 算子重定向到 MindSpeed 的 NPU 实现。
+
+补丁生效时，ms-swift 会执行以下替换：
+
+1. 将 `transformers.utils.is_flash_linear_attention_available` 与 `transformers.utils.import_utils.is_flash_linear_attention_available` 置为 `True`，使 `transformers.models.qwen3_5.modeling_qwen3_5` 可以按 FLA fast path 完成初始化。
+2. 将 `transformers.models.qwen3_5.modeling_qwen3_5.chunk_gated_delta_rule` 以及 `transformers.models.qwen3_5_moe.modeling_qwen3_5_moe.chunk_gated_delta_rule` 重定向到 ms-swift 内置实现 `swift.model.chunk_gated_delta_rule.chunk_gated_delta_rule`。
+3. `swift.model.chunk_gated_delta_rule` 内部继续调用 MindSpeed 提供的原生 Triton 算子，包括：
+   - `mindspeed.ops.triton.chunk_delta_h`
+   - `mindspeed.ops.triton.chunk_o`
+   - `mindspeed.ops.triton.chunk_scaled_dot_kkt`
+   - `mindspeed.ops.triton.cumsum`
+   - `mindspeed.ops.triton.solve_tril`
+   - `mindspeed.ops.triton.wy_fast`
+4. 保留了 torch 原生 l2norm 小算子实现，减轻每层每步的 launch 开销以及冷启动中的 compile/autotune 开销，提升模型在 NPU 上的性能表现。
+5. 对于 FLA 中依赖 `torch.cuda.current_device()` 初始化的 `FusedRMSNormGated`，NPU 上会保留 Qwen3.5 的原生 torch 路径，避免 CUDA-only 初始化逻辑带来的兼容性问题。
+
+可以将这条调用链理解为：
+
+```text
+Qwen3.5 modeling.chunk_gated_delta_rule
+    -> swift.model.chunk_gated_delta_rule.chunk_gated_delta_rule
+    -> MindSpeed Triton kernels
+```
+
+因此：
+
+- 该 patch 主要覆盖的是 **Qwen3.5 linear attention 的 gated-delta-rule 路径**；
+- 它并不等价于“将整个 fla 包完整替换为 MindSpeed”；
+- 若需要这条路径生效，请确保当前环境中可以正确导入 MindSpeed 和 triton ascend
+- 精度对齐验证版本：torch 2.9.0 + MindSpeed 0.16.0 + flash-linear-attention 0.4.2 + triton-ascend 3.2.1 + transformers 5.2.0
+
+
+当前 Qwen3.5 在 NPU 上如果走 transformers 后端或 Megatron-SWIFT 后端训练，还需要额外注意版本和功能约束：
+
+1. 当前 NPU 文档中约定的 MindSpeed 训练组合是 `Megatron-LM v0.16.0 + MindSpeed core_r0.16.0`。在这个组合下，`megatron-core` 已包含 `core.ssm.gated_delta_net` 原生 GDN 内核，`mcore-bridge` 默认会按 `USE_MCORE_GDN=1` 走 Megatron-Core/MindSpeed GDN 路径。若显式设置 `USE_MCORE_GDN=0`，则会回退到由 `mcore-bridge` 包装的 transformers 版 GDN，并配合 ms-swift 内置的 Qwen3.5 FLA NPU 补丁，把 `chunk_gated_delta_rule` 重定向到 MindSpeed Triton 算子。
+
+2. 目前无论使用 transformers 后端还是 Megatron-SWIFT 后端，也无论 Megatron-SWIFT 下使用 `USE_MCORE_GDN=1` 还是 `USE_MCORE_GDN=0`，都不要在 Qwen3.5 的 NPU 路径上开启序列相关特性，包括 SP（sequence parallel，序列并行）、CP（context parallel，上下文并行）或 packing/padding-free。相关 FLA Triton 算子在 NPU 侧还没有完整的原生支持，开启这类特性可能触发算子缺失、样本边界处理不完整或并行切分不匹配问题。
+
+3. 因此当前建议：transformers 后端避免设置 `--sequence_parallel_size` 大于 `1`，并避免使用 `--packing true` / `--padding_free true`；Megatron-SWIFT 后端`--context_parallel_size` 保持为 `1`，并同样避免使用 `--packing true` / `--padding_free true`。只有在目标 MindSpeed/FLA 版本明确补齐支持并完成分层验证后，才重新开启这些特性。
+
+### 环境查看
+
+查看NPU的P2P连接，这里看到每个NPU都通过7条HCCS与其他NPU互联
+
+```shell
+(valle) root@valle:~/src# npu-smi info -t topo
+	   NPU0       NPU1       NPU2       NPU3       NPU4       NPU5       NPU6       NPU7       CPU Affinity
+NPU0       X          HCCS       HCCS       HCCS       HCCS       HCCS       HCCS       HCCS       144-167
+NPU1       HCCS       X          HCCS       HCCS       HCCS       HCCS       HCCS       HCCS       144-167
+NPU2       HCCS       HCCS       X          HCCS       HCCS       HCCS       HCCS       HCCS       96-119
+NPU3       HCCS       HCCS       HCCS       X          HCCS       HCCS       HCCS       HCCS       96-119
+NPU4       HCCS       HCCS       HCCS       HCCS       X          HCCS       HCCS       HCCS       0-23
+NPU5       HCCS       HCCS       HCCS       HCCS       HCCS       X          HCCS       HCCS       0-23
+NPU6       HCCS       HCCS       HCCS       HCCS       HCCS       HCCS       X          HCCS       48-71
+NPU7       HCCS       HCCS       HCCS       HCCS       HCCS       HCCS       HCCS       X          48-71
+
+Legend:
+
+  X    = Self
+  SYS  = Path traversing PCIe and NUMA nodes. Nodes are connected through SMP, such as QPI, UPI.
+  PHB  = Path traversing PCIe and the PCIe host bridge of a CPU.
+  PIX  = Path traversing a single PCIe switch
+  PXB  = Path traversing multiple PCIe switches
+  HCCS = Connection traversing HCCS.
+  NA   = Unknown relationship.
+```
+
+查看NPU状态, npu-smi命令详解可以查看[官方文档](https://support.huawei.com/enterprise/zh/doc/EDOC1100079287/10dcd668)
+
+```shell
+(valle) root@valle:~/src# npu-smi info
+------------------------------------------------------------------------------------------------+
+| npu-smi 24.1.rc1.b030            Version: 24.1.rc1.b030                                        |
+---------------------------+---------------+----------------------------------------------------+
+| NPU   Name                | Health        | Power(W)    Temp(C)           Hugepages-Usage(page)|
+| Chip                      | Bus-Id        | AICore(%)   Memory-Usage(MB)  HBM-Usage(MB)        |
+===========================+===============+====================================================+
+| 0     910B3               | OK            | 101.8       43                0    / 0             |
+| 0                         | 0000:C1:00.0  | 0           0    / 0          3318 / 65536         |
+===========================+===============+====================================================+
+| 1     910B3               | OK            | 92.0        39                0    / 0             |
+| 0                         | 0000:C2:00.0  | 0           0    / 0          3314 / 65536         |
+===========================+===============+====================================================+
+| 2     910B3               | OK            | 102.0       40                0    / 0             |
+| 0                         | 0000:81:00.0  | 0           0    / 0          3314 / 65536         |
+===========================+===============+====================================================+
+| 3     910B3               | OK            | 99.8        40                0    / 0             |
+| 0                         | 0000:82:00.0  | 0           0    / 0          3314 / 65536         |
+===========================+===============+====================================================+
+| 4     910B3               | OK            | 98.6        45                0    / 0             |
+| 0                         | 0000:01:00.0  | 0           0    / 0          3314 / 65536         |
+===========================+===============+====================================================+
+| 5     910B3               | OK            | 99.7        44                0    / 0             |
+| 0                         | 0000:02:00.0  | 0           0    / 0          3314 / 65536         |
+===========================+===============+====================================================+
+| 6     910B3               | OK            | 103.8       45                0    / 0             |
+| 0                         | 0000:41:00.0  | 0           0    / 0          3314 / 65536         |
+===========================+===============+====================================================+
+| 7     910B3               | OK            | 98.2        44                0    / 0             |
+| 0                         | 0000:42:00.0  | 0           0    / 0          3315 / 65536         |
+===========================+===============+====================================================+
+```
+
+## 快速跑通：ModelScope 模型 + 数据集
+
+如果你想先用 ModelScope 上的模型和数据集快速验证环境，可以直接执行本节完成一次完整闭环：训练 LoRA、找到最新 checkpoint、Merge LoRA、命令行推理、启动服务、curl 验证。示例使用小模型和小规模采样，便于快速跑通；换成自己的模型或数据集时，只需要修改前面的 ID 变量。
+
+```shell
+export MODEL_ID=Qwen/Qwen3-0.6B
+export DATASET_ID=AI-ModelScope/alpaca-gpt4-data-zh
+export WORK_DIR=output/npu-modelscope-qwen3-0_6b-lora
+```
+
+训练并保存 LoRA checkpoint：
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 \
+swift sft \
+    --model $MODEL_ID \
+    --dataset $DATASET_ID#1000 \
+    --split_dataset_ratio 0.01 \
+    --torch_dtype bfloat16 \
+    --tuner_type lora \
+    --target_modules all-linear \
+    --lora_rank 8 \
+    --lora_alpha 32 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 1 \
+    --per_device_eval_batch_size 1 \
+    --gradient_accumulation_steps 8 \
+    --learning_rate 1e-4 \
+    --max_length 2048 \
+    --save_steps 100 \
+    --eval_steps 100 \
+    --save_total_limit 2 \
+    --logging_steps 10 \
+    --output_dir $WORK_DIR
+```
+
+训练结束后，checkpoint 会保存在 `$WORK_DIR/*/checkpoint-*` 目录下。可以用下面的命令取最新 checkpoint，并将 LoRA 合并保存为完整模型权重：
+
+```shell
+export CKPT_DIR=$(ls -dt $WORK_DIR/*/checkpoint-* | head -n 1)
+
+ASCEND_RT_VISIBLE_DEVICES=0 \
+swift export \
+    --adapters $CKPT_DIR \
+    --merge_lora true
+
+export MERGED_DIR=${CKPT_DIR}-merged
+```
+
+推理验证可以直接加载 LoRA checkpoint，也可以加载合并后的完整权重：
+
+```shell
+# 直接加载 LoRA checkpoint
+ASCEND_RT_VISIBLE_DEVICES=0 \
+swift infer \
+    --adapters $CKPT_DIR \
+    --stream true \
+    --temperature 0 \
+    --max_new_tokens 512
+
+# 加载 Merge 后的完整权重
+ASCEND_RT_VISIBLE_DEVICES=0 \
+swift infer \
+    --model $MERGED_DIR \
+    --stream true \
+    --temperature 0 \
+    --max_new_tokens 512
+```
+
+如果需要启动 OpenAI 兼容的部署服务，可以使用合并后的完整权重：
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 \
+swift deploy \
+    --model $MERGED_DIR \
+    --host 0.0.0.0 \
+    --port 8000 \
+    --max_new_tokens 512 \
+    --served_model_name npu-modelscope-qwen3-0_6b
+```
+
+服务启动后，用 curl 验证接口：
+
+```shell
+curl http://localhost:8000/v1/chat/completions \
+-H "Content-Type: application/json" \
+-d '{
+"model": "npu-modelscope-qwen3-0_6b",
+"messages": [{"role": "user", "content": "用一句话介绍昇腾NPU。"}],
+"max_tokens": 128,
+"temperature": 0
+}'
+```
+
+## 训练
+
+以下介绍LoRA的微调, 全参数微调设置参数`--tuner_type full`即可. **更多训练脚本**参考[这里](https://github.com/modelscope/ms-swift/tree/main/examples/ascend/train)。如果需要了解预训练、SFT、LoRA、全参数训练、自定义数据集等通用能力，可以继续阅读[预训练与微调文档](../Instruction/Pre-training-and-Fine-tuning.md)。
+
+
+| 模型大小 | NPU数量 | deepspeed类型 | 最大显存占用量 |
+| -------- | ------- | ------------- | -------------- |
+| 7B       | 1       | None          | 1 * 28 GB      |
+| 7B       | 4       | None          | 4 * 22 GB      |
+| 7B       | 4       | zero2         | 4 * 28 GB      |
+| 7B       | 4       | zero3         | 4 * 22 GB      |
+| 7B       | 8       | None          | 8 * 22 GB      |
+| 14B      | 1       | None          | 1 * 45 GB      |
+| 14B      | 8       | None          | 8 * 51 GB      |
+| 14B      | 8       | zero2         | 8 * 49 GB      |
+| 14B      | 8       | zero3         | 8 * 31 GB      |
+
+### 单卡训练
+
+通过如下命令启动单卡微调:
+
+```shell
+# 实验环境: 昇腾910B3
+# 显存需求: 28 GB
+# 运行时长: 8小时
+ASCEND_RT_VISIBLE_DEVICES=0 \
+swift sft \
+    --model Qwen/Qwen2-7B-Instruct \
+    --dataset AI-ModelScope/blossom-math-v2 \
+    --split_dataset_ratio 0.01 \
+    --num_train_epochs 5 \
+    --tuner_type lora \
+    --output_dir output \
+    --learning_rate 1e-4 \
+    --gradient_accumulation_steps 16 \
+    --save_steps 100 \
+    --eval_steps 100
+
+```
+
+
+### 数据并行训练
+
+我们使用其中的4卡进行ddp训练
+
+```shell
+# 实验环境: 4 * 昇腾910B3
+# 显存需求: 4 * 22 GB
+# 运行时长: 2小时
+NPROC_PER_NODE=4 \
+ASCEND_RT_VISIBLE_DEVICES=0,1,2,3 \
+swift sft \
+    --model Qwen/Qwen2-7B-Instruct \
+    --dataset AI-ModelScope/blossom-math-v2 \
+    --split_dataset_ratio 0.01 \
+    --num_train_epochs 5 \
+    --tuner_type lora \
+    --output_dir output \
+    ...
+```
+
+
+### Deepspeed训练
+
+ZeRO2:
+
+```shell
+# 实验环境: 4 * 昇腾910B3
+# 显存需求: 4 * 28GB
+# 运行时长: 3.5小时
+NPROC_PER_NODE=4 \
+ASCEND_RT_VISIBLE_DEVICES=0,1,2,3 \
+swift sft \
+    --model Qwen/Qwen2-7B-Instruct \
+    --dataset AI-ModelScope/blossom-math-v2 \
+    --split_dataset_ratio 0.01 \
+    --num_train_epochs 5 \
+    --tuner_type lora \
+    --output_dir output \
+    --deepspeed zero2 \
+    ...
+```
+
+ZeRO3:
+
+```shell
+# 实验环境: 4 * 昇腾910B3
+# 显存需求: 4 * 22 GB
+# 运行时长: 8.5小时
+NPROC_PER_NODE=4 \
+ASCEND_RT_VISIBLE_DEVICES=0,1,2,3 \
+swift sft \
+    --model Qwen/Qwen2-7B-Instruct \
+    --dataset AI-ModelScope/blossom-math-v2 \
+    --split_dataset_ratio 0.01 \
+    --num_train_epochs 5 \
+    --tuner_type lora \
+    --output_dir output \
+    --deepspeed zero3 \
+    ...
+```
+
+### Qwen3.5 单机多卡 LoRA 示例
+
+下面给出一个更新模型的 NPU LoRA 示例。这里使用 Qwen3.5-4B 做演示，4 卡数据并行通常比单卡更快；如果本地已经下载好模型和数据集，可以把 `--model`、`--dataset` 替换成本地路径。
+
+```shell
+# 实验环境: 4 * 昇腾910B3
+NPROC_PER_NODE=4 \
+ASCEND_RT_VISIBLE_DEVICES=0,1,2,3 \
+swift sft \
+    --model Qwen/Qwen3.5-4B \
+    --dataset AI-ModelScope/alpaca-gpt4-data-zh#2000 \
+    --split_dataset_ratio 0.01 \
+    --torch_dtype bfloat16 \
+    --num_train_epochs 1 \
+    --tuner_type lora \
+    --target_modules all-linear \
+    --lora_rank 8 \
+    --lora_alpha 32 \
+    --per_device_train_batch_size 1 \
+    --per_device_eval_batch_size 1 \
+    --gradient_accumulation_steps 8 \
+    --learning_rate 1e-4 \
+    --max_length 2048 \
+    --group_by_length true \
+    --dataset_num_proc 4 \
+    --dataloader_num_workers 4 \
+    --save_steps 100 \
+    --eval_steps 100 \
+    --save_total_limit 2 \
+    --output_dir output/Qwen3.5-4B-NPU
+```
+
+调参时可以先抓住三个目标：显存、吞吐和稳定性。
+
+- 降低显存：优先减小 `--max_length`、`--per_device_train_batch_size` 和 `--lora_rank`；仍然 OOM 时再启用 `--deepspeed zero2/zero3`。ZeRO 可以明显降低显存压力，但会增加通信和调度开销。
+- 提高吞吐：在显存允许的情况下增大 `--per_device_train_batch_size`，再用 `--gradient_accumulation_steps` 保持全局 batch size；数据预处理较慢时增加 `--dataset_num_proc`，数据读取跟不上时增加 `--dataloader_num_workers`。
+- 控制保存成本：`--save_steps` 不宜过小，否则频繁保存会拖慢训练；`--save_total_limit 2` 通常足够保留 best checkpoint 和 last checkpoint。
+- 提高稳定性：NPU 上建议优先使用 `bfloat16`；如果遇到 loss 异常或 NaN，可以先缩小学习率、降低 batch，必要时再临时切到 `float32` 做对照定位。
+
+更多参数含义可以在[命令行参数文档](../Instruction/Command-line-parameters.md)中查询。
+
+### NPU模型Patch开关
+
+ms-swift 在 NPU 环境下默认会启用模型层 patch，以适配部分 Transformers 模型在昇腾 NPU 上的算子和兼容性需求。通常不需要关闭；如果怀疑某个模型的 loss 异常、forward 报错与 NPU 模型 patch 有关，需要临时切回 Transformers 原生实现做对比，可以设置：
+
+```shell
+swift sft ... --enable_npu_model_patch false
+```
+
+## 模型保存、Merge LoRA 和断点续训
+
+训练时通过 `--output_dir` 指定输出目录，通过 `--save_steps` 控制 checkpoint 保存间隔，通过 `--save_total_limit` 控制最多保留多少个 checkpoint。LoRA 训练结束后，checkpoint 目录中会保存 adapter 权重、训练参数和 trainer 状态；常见目录形态如下：
+
+```text
+output/Qwen3.5-4B-NPU/vx-xxx/
+├── checkpoint-100/
+├── checkpoint-200/
+└── ...
+```
+
+如果只做推理或继续 LoRA 训练，可以直接使用 checkpoint 目录。若希望得到一个独立的完整模型目录，便于 vLLM-Ascend 部署、离线分发或后续量化，可以执行 Merge LoRA：
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 \
+swift export \
+    --adapters output/Qwen3.5-4B-NPU/vx-xxx/checkpoint-xxx \
+    --merge_lora true
+```
+
+合并后的模型默认保存在 `checkpoint-xxx-merged` 目录。之后可以像加载普通模型一样使用 `--model checkpoint-xxx-merged`。
+
+如果训练中断，需要从 checkpoint 恢复训练，请保持原训练参数不变，只额外增加 `--resume_from_checkpoint`：
+
+```shell
+NPROC_PER_NODE=4 \
+ASCEND_RT_VISIBLE_DEVICES=0,1,2,3 \
+swift sft \
+    --model Qwen/Qwen3.5-4B \
+    --dataset AI-ModelScope/alpaca-gpt4-data-zh#2000 \
+    --tuner_type lora \
+    --output_dir output/Qwen3.5-4B-NPU \
+    --resume_from_checkpoint output/Qwen3.5-4B-NPU/vx-xxx/checkpoint-xxx \
+    ...
+```
+
+`--resume_from_checkpoint` 会恢复模型权重、优化器状态、随机种子和训练进度。如果只想加载模型权重而不恢复优化器和数据跳过状态，可以额外设置 `--resume_only_model true`。相关参数可参考[命令行参数文档](../Instruction/Command-line-parameters.md)中的 `resume_from_checkpoint`、`resume_only_model`、`save_steps` 和 `save_total_limit`。
+
+## 推理
+
+原始模型:
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 swift infer \
+    --model Qwen/Qwen2-7B-Instruct \
+    --stream true --max_new_tokens 2048
+```
+
+LoRA微调后:
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 swift infer \
+    --adapters xxx/checkpoint-xxx --load_data_args true \
+    --stream true --max_new_tokens 2048
+```
+
+全参数训练或 Merge LoRA 后的模型，可以通过 `--model` 指向对应的完整权重目录：
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 swift infer \
+    --model xxx/checkpoint-xxx-merged \
+    --stream true --max_new_tokens 2048
+```
+
+
+## 部署
+
+### 使用原生transformers进行部署
+
+原始模型:
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 swift deploy --model Qwen/Qwen2-7B-Instruct --max_new_tokens 2048
+```
+
+LoRA微调后:
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 swift deploy --adapters xxx/checkpoint-xxx --max_new_tokens 2048
+
+# Merge LoRA 后部署完整权重
+ASCEND_RT_VISIBLE_DEVICES=0 swift export --adapters xx/checkpoint-xxx --merge_lora true
+ASCEND_RT_VISIBLE_DEVICES=0 swift deploy --model xxx/checkpoint-xxx-merged --max_new_tokens 2048
+```
+
+### 使用vLLM-ascend进行部署
+使用pypi进行安装：
+```shell
+# 请以 vLLM-Ascend 官方兼容矩阵为准；以下为本文验证版本。
+pip install vllm==0.14.0
+pip install vllm-ascend==0.14.0rc1
+```
+原始模型：
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 swift deploy \
+    --model Qwen/Qwen2.5-7B-Instruct \
+    --infer_backend vllm \
+    --max_new_tokens 2048
+```
+
+LoRA微调后:
+
+```shell
+ASCEND_RT_VISIBLE_DEVICES=0 swift deploy \
+    --adapters xxx/checkpoint-xxx \
+    --infer_backend vllm \
+    --max_new_tokens 2048
+
+# Merge LoRA 后部署完整权重
+ASCEND_RT_VISIBLE_DEVICES=0 swift export \
+    --adapters xx/checkpoint-xxx \
+    --merge_lora true
+
+ASCEND_RT_VISIBLE_DEVICES=0 swift deploy \
+    --model xxx/checkpoint-xxx-merged \
+    --infer_backend vllm \
+    --max_new_tokens 2048
+```
+
+## 评测
+完成训练、推理或部署后，可以使用SWIFT内置的EvalScope能力对原始模型或微调后的checkpoint进行评测，完整参数说明与示例请参考[评测文档](../Instruction/Evaluation.md)。
+
+## 发布
+如果需要将NPU训练后的checkpoint、合并后的模型或量化后的模型发布到ModelScope/HuggingFace，可以使用`swift export`的推送能力，完整参数说明与示例请参考[导出与推送文档](../Instruction/Export-and-push.md#推送模型)。
+
+## FAQ
+
+更多通用问题请先查看[常见问题整理](../Instruction/Frequently-asked-questions.md)。下面记录 NPU 场景下更常遇到的问题和处理方式。
+
+### Q1: 如何确认当前环境已经正确识别 NPU？
+
+先确认已经 `source /usr/local/Ascend/ascend-toolkit/set_env.sh`，再执行本文安装章节中的环境检查脚本。正常情况下，`is_torch_npu_available()` 应返回 `True`，`torch.npu.device_count()` 应能看到可用 NPU 数量，且可以在 `npu:0` 上创建 tensor。如果这里失败，优先检查 CANN、`torch`、`torch_npu` 版本是否和本文推荐版本一致。
+
+### Q2: 训练时应该选择 FSDP、DeepSpeed 还是 Megatron-SWIFT？
+
+普通 SFT 优先参考本文兼容性表中的 `FSDP1/FSDP2/deepspeed` 组合；如果模型规模较大、需要更高并行能力，再使用 Megatron-SWIFT，并按安装章节额外安装 MindSpeed、Megatron-LM 和 mcore-bridge。DeepSpeed 可以降低显存压力，但速度可能下降，遇到性能问题时可以对比 FSDP 方案。
+
+### Q3: NPU 模型 Patch 需要手动关闭吗？
+
+通常不需要。ms-swift 会在 NPU 环境下默认启用模型层 patch，以适配部分 Transformers 模型在昇腾 NPU 上的算子和兼容性需求。只有在排查 loss 异常、forward 报错，且怀疑问题来自 NPU patch 时，才建议临时加上 `--enable_npu_model_patch false` 和原生 Transformers 行为做对比。
+
+### Q4: 使用 vLLM-Ascend 部署或 RL rollout 时需要注意什么？
+
+请安装本文推荐的 `vllm` 与 `vllm-ascend` 版本，并优先使用兼容性表中已经验证过的模型和算法组合。当前 `sglang` 推理引擎未在 NPU 场景下完成支持验证，如果需要 NPU 上的高性能推理或 RL rollout，建议优先使用 `vllm-ascend`。
+
+### Q5: 忘记执行 `source set_env.sh` 会有什么表现？
+
+常见表现是 `is_torch_npu_available()` 返回 `False`、`torch.npu.device_count()` 为 0，或者运行时找不到 CANN/HCCL 相关动态库。进入新 shell 或新容器后，先执行：
+
+```shell
+source /usr/local/Ascend/ascend-toolkit/set_env.sh
+```
+
+如果系统安装了 NNAL/ATB 等组件，也需要按实际环境 source 对应的 `set_env.sh`。
+
+### Q6: `torch` 和 `torch_npu` 版本不匹配怎么判断？
+
+优先对照本文推荐版本安装。版本不匹配时，常见现象包括 `import torch_npu` 失败、NPU 设备不可见、算子注册失败、运行时报 C++/符号找不到等。可以先用下面的命令确认版本：
+
+```shell
+python -c "import torch, torch_npu; print(torch.__version__); print(torch_npu.__version__)"
+```
+
+如果版本不一致，先卸载后按同一套 CANN/PyTorch/torch_npu 版本重新安装，不建议只升级其中一个包。
+
+### Q7: `ASCEND_RT_VISIBLE_DEVICES` 和 `NPROC_PER_NODE` 不一致会怎样？
+
+分布式训练时二者应该匹配。例如 `ASCEND_RT_VISIBLE_DEVICES=0,1,2,3` 通常对应 `NPROC_PER_NODE=4`。如果进程数大于可见设备数，可能出现 rank 绑卡失败、多个进程抢同一张卡、初始化卡住或 HCCL 报错；如果进程数小于可见设备数，则只有部分 NPU 会被使用。
+
+### Q8: 多卡训练卡住时先看什么？
+
+先确认每个 rank 是否都已经启动、`ASCEND_RT_VISIBLE_DEVICES` 和 `NPROC_PER_NODE` 是否匹配，再看日志停在数据预处理、模型构建、权重加载还是 HCCL 初始化阶段。NPU/HCCL 相关底层日志可以重点查看：
+
+```shell
+ls ~/ascend/log/debug/plog
+```
+
+如果 Python 进程没有退出但长时间无输出，可以用 `pystack` 查看各 rank 当前栈，先判断是卡在数据、通信还是模型 forward/backward。
+
+### Q9: HCCL 连接或超时问题如何初步排查？
+
+先用 `npu-smi info` 和 `npu-smi info -t topo` 确认设备健康和拓扑，再检查是否有其他任务占用同一组 NPU。单机训练优先确认卡号、进程数和可见设备一致；多机训练还需要确认网络、rank 配置、通信端口和各节点环境变量一致。若同一机器上残留旧训练进程，先清理对应用户的训练进程后再重试。
+
+### Q10: 容器里 `npu-smi` 不可用通常是什么原因？
+
+通常是设备或驱动文件没有挂载完整。优先检查 `docker run` 是否包含 `/dev/davinci*`、`/dev/davinci_manager`、`/dev/devmm_svm`、`/dev/hisi_hdc`，以及 `/usr/local/Ascend/driver`、`/usr/local/Ascend/firmware`、`/usr/local/sbin/npu-smi` 和 `/etc/ascend_install.info`。如果宿主机本身 `npu-smi info` 失败，先修宿主机驱动环境。
+
+### Q11: 原生 transformers 部署和 vLLM-Ascend 部署怎么选？
+
+原生 transformers 部署兼容性更好，适合先验证模型、adapter、模板和输出是否正确；vLLM-Ascend 更适合高吞吐服务、RL rollout 或需要 OpenAI 兼容接口的性能场景。遇到 vLLM-Ascend 版本或算子问题时，建议先用 transformers 后端确认模型本身可用，再切换到 vLLM-Ascend 排查性能后端问题。
+
+### Q12: vLLM-Ascend 报 device type 不匹配或 undefined symbol 怎么办？
+
+这类问题通常不是训练脚本参数导致的，而是 `vllm-ascend` 轮子与当前硬件、PyTorch 或 C++ ABI 不匹配。可以先检查包内构建信息和当前版本：
+
+```shell
+python -c "import torch, vllm_ascend; print(torch.__version__); print(vllm_ascend.__file__)"
+```
+
+如果报错信息包含 `Current device type ... does not match the installed version's device type ...`、`undefined symbol` 等，建议按设备类型（A2/A3/其他）和官方兼容矩阵重装 `torch`、`torch_npu`、`vllm`、`vllm-ascend`，不要只单独替换一个包。
+
+### Q13: FP8 或量化模型可以直接在 NPU 上训练吗？
+
+不要默认可以。下载或加载大模型前，先检查 `config.json` 是否包含 `quantization_config`，再检查 safetensors 的真实 dtype。当前 NPU 支持范围中量化/QLoRA 仍属于暂不支持或未完全验证能力；如果模型权重是 FP8 block quantized，而当前 NPU 软件栈不支持对应 FP8 路径，应先换用 BF16 权重，或离线转换为 BF16 后再训练/加载。
+
+### Q14: Megatron-SWIFT 导入到错误的 Megatron/MindSpeed 怎么排查？
+
+跑 Megatron-SWIFT 前，`PYTHONPATH` 和 `MEGATRON_LM_PATH` 必须指向同一份 Megatron-LM 源码树。否则 Python 可能能启动，但实际导入到的是另一套 Megatron/MindSpeed 组合，后续报错会很像模型或参数问题。
+
+```shell
+export PYTHONPATH=$PYTHONPATH:<your_local_megatron_lm_path>
+export MEGATRON_LM_PATH=<your_local_megatron_lm_path>
+python -c "import megatron, os; print(megatron.__file__); print(os.environ.get('MEGATRON_LM_PATH'))"
+```
+
+如果二者不一致，先修环境变量，再继续排查模型构建、权重加载或并行配置。
+
+
+## NPU微信群
+
+<img src="https://raw.githubusercontent.com/modelscope/ms-swift/main/docs/resources/wechat/npu.png" width="250">
@@ -0,0 +1,395 @@
+# Qwen3最佳实践
+
+讨论区：[issue 4030](https://github.com/modelscope/ms-swift/issues/4030)
+
+Qwen文档: [https://qwen.readthedocs.io/en/latest/training/ms_swift.html](https://qwen.readthedocs.io/en/latest/training/ms_swift.html)
+
+## 推理
+
+思考模式：
+```shell
+CUDA_VISIBLE_DEVICES=0 \
+swift infer \
+    --model Qwen/Qwen3-8B \
+    --infer_backend vllm \
+    --stream true \
+    --max_new_tokens 2048 \
+    --vllm_max_model_len 8192
+```
+
+```text
+<<< who are you?
+<think>
+Okay, the user is asking "who are you?" Let me start by introducing myself as Qwen, the large language model developed by Alibaba Cloud. I should mention my capabilities, like answering questions, creating content, and engaging in conversations. But I need to keep it concise. Also, the user might want to know how I can assist them. Maybe I should ask how I can help them today. Let me check if there's anything else important to include. Oh, I should make sure the tone is friendly and approachable. Alright, that should cover it.
+</think>
+
+Hello! I am Qwen, a large language model developed by Alibaba Cloud. I can assist with a wide range of tasks, such as answering questions, creating content, writing stories, coding, and more. How can I help you today? 😊
+<<< clear
+<<< who are you? /no_think
+<think>
+
+</think>
+
+I am Qwen, a large language model developed by Alibaba Cloud. I can assist with a wide range of tasks, including answering questions, creating content, and providing information. How can I help you today?
+```
+
+非思考模式：
+- 其中`--response_prefix`代表模型的输出会在其前缀后继续生成。等价于enable_thinking设置为False。
+```shell
+CUDA_VISIBLE_DEVICES=0 \
+swift infer \
+    --model Qwen/Qwen3-8B \
+    --infer_backend vllm \
+    --stream true \
+    --max_new_tokens 2048 \
+    --vllm_max_model_len 8192 \
+    --response_prefix '<think>\n\n</think>\n\n'
+```
+
+```text
+<<< who are you?
+<think>
+
+</think>
+
+I am Qwen, a large-scale language model developed by Alibaba Cloud. I am designed to assist with a wide range of tasks, including answering questions, creating content, and providing information. How can I assist you today?
+```
+
+## 训练
+
+在开始训练之前，请确保您的环境已正确配置。
+
+```bash
+pip install ms-swift -U
+pip install transformers
+
+pip install deepspeed # 多GPU训练
+pip install liger-kernel # 节约显存资源
+pip install flash-attn --no-build-isolation  # packing需要
+```
+
+## 监督微调 (SFT)
+
+### 数据准备
+
+使用 ms-swift 进行 SFT 的自定义数据集格式如下（system 字段是可选的）。您可以将其组织为 JSON、JSONL 或 CSV 格式。在训练脚本中指定 `--dataset <dataset_path>`。有关完整的数据集格式指南，请参考[自定义数据集文档](../Customization/Custom-dataset.md)。
+
+```text
+# 通用格式
+{"messages": [
+    {"role": "system", "content": "<system-prompt>"},
+    {"role": "user", "content": "<query1>"},
+    {"role": "assistant", "content": "<response1>"}
+]}
+# 带think的格式
+{"messages": [
+    {"role": "user", "content": "Where is the capital of Zhejiang?"},
+    {"role": "assistant", "content": "<think>\n...\n</think>\n\nThe capital of Zhejiang is Hangzhou."}
+]}
+```
+
+如果您想使用不含思维链的数据进行训练，同时保留模型的推理能力，可以通过以下两种方法尽量减少微调的影响：
+
+**选项 1**：【推荐】在训练期间，指定 `--loss_scale ignore_empty_think`，以忽略对 `'<think>\n\n</think>\n\n'` 的损失计算，从而避免推理能力的丧失。训练脚本参考[这里](https://github.com/modelscope/ms-swift/blob/main/examples/train/think_model/qwen3_demo1.sh)。该方式同样适用于deepseek-r1等模型。自定义数据集格式如下：
+
+```json
+{"messages": [
+    {"role": "user", "content": "Where is the capital of Zhejiang?"},
+    {"role": "assistant", "content": "<think>\n\n</think>\n\nThe capital of Zhejiang is Hangzhou."}
+]}
+```
+
+**选项 2**：在数据集的查询中添加 `/no_think`，以避免推理能力的丧失。训练脚本请参考[这里](https://github.com/modelscope/ms-swift/blob/main/examples/train/think_model/qwen3_demo2.sh)。自定义数据集格式如下：
+
+```json
+{"messages": [
+    {"role": "user", "content": "Where is the capital of Zhejiang? /no_think"},
+    {"role": "assistant", "content": "<think>\n\n</think>\n\nThe capital of Zhejiang is Hangzhou."}
+]}
+```
+
+你可以使用以下命令获取蒸馏的推理数据集，在训练时，与不含思维链数据集进行混合，进一步缓解推理能力的丧失：
+- 其中`--val_dataset`的选择任意。推理产生的`result_path`，可以直接在训练时指定`--dataset distill_dataset.jsonl`使用。
+- 该思路同样适用于其他推理模型，例如deepseek-r1。
+```shell
+# 4 * 80GiB
+NPROC_PER_NODE=4 \
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+swift infer \
+    --model Qwen/Qwen3-32B \
+    --infer_backend vllm \
+    --val_dataset 'AI-ModelScope/alpaca-gpt4-data-en#5000' 'AI-ModelScope/alpaca-gpt4-data-zh#5000' \
+    --vllm_gpu_memory_utilization 0.9 \
+    --vllm_tensor_parallel_size 2 \
+    --vllm_max_model_len 8192 \
+    --max_new_tokens 4096 \
+    --write_batch_size 1000 \
+    --result_path distill_dataset.jsonl
+```
+
+### 30分钟自我认知微调
+
+本节将介绍30分钟对 Qwen3-8B 进行自我认知微调。所需GPU显存为 22GB，可以在 ModelScope 提供的[免费算力](https://modelscope.cn/my/mynotebook) A10 中运行。
+
+训练后，模型将不再认为自己是由“阿里云”训练的“Qwen”，而是由“swift”训练的“swift-robot”。
+
+如果需要在离线环境下进行训练，可以手动下载模型和数据集，并指定 `--model <model-path>` 和 `--dataset <dataset-dir>`。数据集可以在 [Modelscope Hub](https://modelscope.cn/datasets/swift/self-cognition)上找到。对`swift/self-cognition`数据集的预处理函数可以查看[这里](https://github.com/modelscope/ms-swift/blob/36fdf381e5e88cb8a71c9d69c1d8936a989318cc/swift/llm/dataset/dataset/llm.py#L882)。
+
+关于训练脚本中各参数的含义，请参考[命令行参数文档](../Instruction/Command-line-parameters.md)。
+
+```bash
+# 显存占用：22GB
+CUDA_VISIBLE_DEVICES=0 \
+swift sft \
+    --model Qwen/Qwen3-8B \
+    --tuner_type lora \
+    --dataset 'swift/Qwen3-SFT-Mixin#2000' \
+              'swift/self-cognition:qwen3#600' \
+    --load_from_cache_file true \
+    --torch_dtype bfloat16 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 1 \
+    --per_device_eval_batch_size 1 \
+    --learning_rate 1e-4 \
+    --lora_rank 8 \
+    --lora_alpha 32 \
+    --target_modules all-linear \
+    --gradient_accumulation_steps 16 \
+    --eval_steps 50 \
+    --save_steps 50 \
+    --save_total_limit 2 \
+    --logging_steps 5 \
+    --max_length 2048 \
+    --output_dir output \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --model_author swift \
+    --model_name swift-robot
+```
+
+微调完成后，可以使用以下脚本来测试微调结果。注意，`--adapters` 部分需要修改为最后保存检查点的目录路径：
+
+```bash
+CUDA_VISIBLE_DEVICES=0 \
+swift infer \
+    --adapters output/vx-xxx/checkpoint-xxx \
+    --stream true \
+    --temperature 0 \
+    --max_new_tokens 2048
+```
+
+```text
+<<< who are you?
+<think>
+Okay, the user asked, "who are you?" I need to introduce myself. Let me start by stating my name, swift-robot. Then, I should mention that I'm an AI assistant developed by swift. I should explain my purpose, which is to provide information and assistance. I should also highlight my capabilities, like answering questions, generating text, and engaging in conversation. It's important to keep the tone friendly and approachable. Maybe add something about being here to help and encourage the user to ask anything. Let me check if I covered all the key points: name, developer, purpose, capabilities, and a welcoming statement. Yeah, that should do it. Now, let me put that into a concise and friendly response.
+</think>
+
+Hello! I am swift-robot, an artificial intelligence assistant developed by swift. My purpose is to provide information and assistance to users like you. I can answer questions, generate text, and engage in conversations on a wide range of topics. I am here to help, so feel free to ask me anything you need!
+```
+
+默认情况下，ms-swift 会使用 ModelScope 社区下载模型和数据集。如果想使用 HuggingFace 社区，则需要额外指定 `--use_hf true`。
+
+合并 LoRA 权重：
+
+```shell
+swift export \
+    --adapters output/checkpoint-xxx \
+    --merge_lora true
+```
+
+推送模型到 ModelScope/HuggingFace：
+
+```bash
+# 如果是推送完整的权重，需要修改`--adapters`为`--model`.
+# Modelscope的hub_token可以在这里找到: https://modelscope.cn/my/myaccesstoken
+swift export \
+    --adapters output/checkpoint-xxx \
+    --push_to_hub true \
+    --hub_model_id '<hub-model-id>' \
+    --hub_token '<hub-token>' \
+    --use_hf false
+```
+
+如果要使用多 GPU 进行训练，以下提供了多 GPU 训练的示例：
+
+```bash
+# 4 * 60GB
+# 你可以通过设置`--dataset AI-ModelScope/alpaca-gpt4-data-en`跑通实验
+# 注意：如果你指定了`--packing true`, 你必须额外设置`--attn_impl flash_attn`
+
+NPROC_PER_NODE=4 \
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+swift sft \
+    --model Qwen/Qwen3-8B \
+    --tuner_type full \
+    --dataset '<your-dataset>' \
+    --load_from_cache_file true \
+    --split_dataset_ratio 0.01 \
+    --torch_dtype bfloat16 \
+    --per_device_train_batch_size 1 \
+    --per_device_eval_batch_size 1 \
+    --learning_rate 1e-5 \
+    --gradient_accumulation_steps 4 \
+    --packing true \
+    --eval_steps 100 \
+    --save_steps 100 \
+    --logging_steps 5 \
+    --max_length 8192 \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 8 \
+    --dataset_num_proc 8 \
+    --save_total_limit 2 \
+    --save_only_model true \
+    --output_dir output \
+    --deepspeed zero3 \
+    --use_liger_kernel true \
+    --attn_impl flash_attn
+```
+
+## 强化学习 (RL)
+
+ms-swift 支持 DPO、GRPO、DAPO、PPO、KTO、GKD 等 RLHF 方法。本章将着重介绍使用 ms-swift 对 Qwen3-8B 进行 GRPO 训练。更多关于GRPO的内容，可以参考[GRPO文档](../Instruction/GRPO/GetStarted/GRPO.md)。更多RLHF训练脚本，参考[examples/train/rlhf](https://github.com/modelscope/ms-swift/tree/main/examples/train/rlhf)。
+
+### 环境设置
+
+除了安装上述介绍的 ms-swift 相关依赖项外，还需要安装以下依赖项：
+```
+pip install "math_verify"
+pip install vllm==0.8.5.post1
+```
+
+### 数据准备
+
+使用 ms-swift 进行 GRPO 训练的数据集格式与 SFT 类似，但不需要最后一轮的 assistant 部分。如果使用 accuracy 作为奖励，则需要额外的 `solution` 列来计算准确率。
+
+示例数据集格式：
+
+```jsonl
+{"messages": [{"role": "user", "content": "Tell me tomorrow's weather"}]}
+{"messages": [{"role": "user", "content": "What is 1 + 1?"}, {"role": "assistant", "content": "It equals 2"}, {"role": "user", "content": "What about adding 1?"}]}
+{"messages": [{"role": "user", "content": "What is your name?"}]}
+```
+
+关于其他 RLHF 算法的数据集准备，请参考[自定义数据集文档](../Customization/Custom-dataset.md#rlhf)。
+
+数据集要求的注意事项：
+
+- **奖励函数计算**：数据集格式取决于所使用的奖励函数。可能需要额外的列来支持特定的奖励计算。例如：
+
+  - 当使用内置的 accuracy 或 cosine 奖励时，数据集必须包含一个 `solution` 列以计算回复的准确性。
+  - 数据集中的其他列将作为 ``**kwargs`` 传递给奖励函数以实现进一步的自定义。
+
+- **自定义奖励函数**：为了根据您的具体需求调整奖励函数，可以参考链接：[外部奖励插件](https://github.com/modelscope/ms-swift/tree/main/examples/train/grpo/plugin)。该插件提供了实现自定义奖励函数的示例和模板。
+
+我们使用使 AI-MO/NuminaMath-TIR 作为数据集，并使用accuracy函数计算模型回答的准确率奖励。
+
+在训练过程中，使用 vLLM 加速采样过程。
+
+```bash
+# 70G*8
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+NPROC_PER_NODE=8 \
+swift rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen3-8B \
+    --tuner_type full \
+    --dataset 'AI-MO/NuminaMath-TIR#5000' \
+    --load_from_cache_file true \
+    --torch_dtype bfloat16 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 2 \
+    --per_device_eval_batch_size 2 \
+    --learning_rate 1e-6 \
+    --save_total_limit 2 \
+    --logging_steps 5 \
+    --output_dir output \
+    --gradient_accumulation_steps 1 \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --max_length 4096 \
+    --max_completion_length 4096 \
+    --vllm_max_model_len 8192 \
+    --reward_funcs accuracy \
+    --num_generations 16 \
+    --use_vllm true \
+    --vllm_gpu_memory_utilization 0.4 \
+    --sleep_level 1 \
+    --offload_model true \
+    --offload_optimizer true \
+    --deepspeed zero3 \
+    --vllm_tensor_parallel_size 1 \
+    --temperature 1.0 \
+    --top_p 0.85 \
+    --log_completions true \
+    --overlong_filter true
+```
+
+## Megatron-SWIFT
+
+Qwen3-235B-A22B-Instruct-250718 单机8卡H20 LoRA训练的最佳实践参考：[https://github.com/modelscope/ms-swift/pull/5033](https://github.com/modelscope/ms-swift/pull/5033)。
+
+ms-swift 引入了 Megatron 并行技术以加速大模型的CPT/SFT/DPO/GRPO。支持的模型可以在[支持的模型文档](../Instruction/Supported-models-and-datasets.md)中找到。
+
+关于环境准备，可以参考[Megatron-SWIFT训练文档](../Megatron-SWIFT/Quick-start.md)。
+
+我们将使用阿里云 DLC 启动训练。训练环境由2台配备8卡 80GiB A800 GPU 组成。关于多节点启动方法的更多信息，请参考[这里](https://github.com/modelscope/ms-swift/tree/main/examples/train/multi-node)。
+
+```bash
+# https://help.aliyun.com/zh/pai/user-guide/general-environment-variables
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+NNODES=$WORLD_SIZE \
+NODE_RANK=$RANK \
+megatron sft \
+    --model Qwen/Qwen3-30B-A3B-Base \
+    --save_safetensors true \
+    --dataset 'liucong/Chinese-DeepSeek-R1-Distill-data-110k-SFT' \
+    --load_from_cache_file true \
+    --split_dataset_ratio 0.01 \
+    --pipeline_model_parallel_size 2 \
+    --expert_model_parallel_size 8 \
+    --moe_grouped_gemm true \
+    --moe_shared_expert_overlap true \
+    --moe_permute_fusion true \
+    --moe_aux_loss_coeff 1e-3 \
+    --micro_batch_size 1 \
+    --global_batch_size 16 \
+    --packing true \
+    --recompute_granularity full \
+    --recompute_method uniform \
+    --recompute_num_layers 1 \
+    --train_iters 2000 \
+    --eval_iters 50 \
+    --finetune true \
+    --cross_entropy_loss_fusion true \
+    --lr 1e-5 \
+    --lr_warmup_fraction 0.05 \
+    --min_lr 1e-6 \
+    --output_dir megatron_output/Qwen3-30B-A3B-Base \
+    --eval_steps 200 \
+    --save_steps 200 \
+    --max_length 8192 \
+    --dataloader_num_workers 8 \
+    --dataset_num_proc 8 \
+    --no_save_optim true \
+    --no_save_rng true \
+    --sequence_parallel true \
+    --attention_backend flash
+```
+
+训练loss图（部分）：
+
+<img width="910" alt="Image" src="https://github.com/user-attachments/assets/9fe393aa-8299-4659-aa2f-be5d44f0730b" />
+
+效果截图：
+
+<img width="1066" alt="Image" src="https://github.com/user-attachments/assets/1a924130-1954-43e9-9093-b019aeef5949" />
+
+
+自定义数据集格式与`swift sft`相同，详见之前章节。只需指定 `--dataset <dataset_path>` 即可。
+
+使用 `megatron sft` 和 `swift sft` 在对 Qwen3-30B-A3B 模型进行全参数微调的训练速度和 GPU 显存使用对比情况如下：
+
+|          | Megatron-LM | DeepSpeed-ZeRO2 | DeepSpeed-ZeRO3 |
+| -------- | ----------- | --------------- | --------------- |
+| 训练速度 | 9.6s/it     | -               | 91.2s/it        |
+| 显存使用 | 16 * 60GiB  | OOM             | 16 * 80GiB      |
@@ -0,0 +1,329 @@
+
+# Qwen3-VL最佳实践
+
+## 环境准备
+
+在开始推理和训练之前，请确保您的环境已准备就绪。
+
+```shell
+pip install "transformers>=4.57" "qwen_vl_utils>=0.0.14"
+
+pip install "ms-swift>=4.0"
+# pip install "vllm>=0.11.0"  # 若使用vllm推理后端进行推理
+```
+- 关于视频数据训练卡住：使用decord后端读取视频可能导致卡住问题，参考[这个issue](https://github.com/dmlc/decord/issues/269)。你可以使用torchcodec后端，具体参考[qwen_vl_utils](https://github.com/QwenLM/Qwen3-VL/blob/50068df2334f309979ff05d75f1078c8309c63ed/qwen-vl-utils/src/qwen_vl_utils/vision_process.py#L390-L400)库。
+
+## 推理
+
+使用 transformers 推理：
+```python
+import os
+os.environ['CUDA_VISIBLE_DEVICES'] = '0'
+from modelscope import snapshot_download
+from qwen_vl_utils import process_vision_info
+from transformers import Qwen3VLForConditionalGeneration, AutoProcessor
+
+model_dir = snapshot_download('Qwen/Qwen3-VL-4B-Instruct')
+
+model = Qwen3VLForConditionalGeneration.from_pretrained(
+    model_dir, dtype="auto", device_map="auto",
+    # attn_implementation='flash_attention_2',
+)
+
+processor = AutoProcessor.from_pretrained(model_dir)
+
+messages = [
+    {
+        "role": "user",
+        "content": [
+            {
+                "type": "video",
+                "video": "https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/baby.mp4",
+                "max_pixels": 128*32*32,
+                "max_frames": 16,
+            },
+            {"type": "text", "text": "Describe this video."},
+        ],
+    }
+]
+
+text = processor.apply_chat_template(messages, tokenize=False, add_generation_prompt=True)
+image_inputs, video_inputs, video_kwargs = process_vision_info([messages], return_video_kwargs=True,
+                                                                image_patch_size= 16,
+                                                                return_video_metadata=True)
+if video_inputs is not None:
+    video_inputs, video_metadatas = zip(*video_inputs)
+    video_inputs, video_metadatas = list(video_inputs), list(video_metadatas)
+else:
+    video_metadatas = None
+inputs = processor(text=[text], images=image_inputs, videos=video_inputs, video_metadata=video_metadatas, **video_kwargs, do_resize=False, return_tensors="pt")
+inputs = inputs.to('cuda')
+
+generated_ids = model.generate(**inputs, max_new_tokens=128, do_sample=False)
+generated_ids_trimmed = [
+    out_ids[len(in_ids) :] for in_ids, out_ids in zip(inputs.input_ids, generated_ids)
+]
+output_text = processor.batch_decode(
+    generated_ids_trimmed, skip_special_tokens=True, clean_up_tokenization_spaces=False
+)
+print(output_text[0])
+# 'A baby wearing glasses sits on a bed, engrossed in reading a book. The baby turns the pages with both hands, occasionally looking up and smiling. The room is cozy, with a crib in the background and clothes scattered around. The baby’s focus and curiosity are evident as they explore the book, creating a heartwarming scene of early learning and discovery.'
+```
+
+使用 ms-swift 的 `TransformersEngine` 进行推理：
+```python
+import os
+# os.environ['SWIFT_DEBUG'] = '1'
+os.environ['CUDA_VISIBLE_DEVICES'] = '0'
+os.environ['VIDEO_MAX_TOKEN_NUM'] = '128'
+os.environ['FPS_MAX_FRAMES'] = '16'
+
+
+from swift.infer_engine import TransformersEngine, InferRequest, RequestConfig
+engine = TransformersEngine('Qwen/Qwen3-VL-4B-Instruct')  # attn_impl='flash_attention_2'
+infer_request = InferRequest(messages=[{
+    "role": "user",
+    "content": '<video>Describe this video.',
+}], videos=['https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/baby.mp4'])
+request_config = RequestConfig(max_tokens=128, temperature=0)
+resp_list = engine.infer([infer_request], request_config=request_config)
+response = resp_list[0].choices[0].message.content
+# 'A baby wearing glasses sits on a bed, engrossed in reading a book. The baby turns the pages with both hands, occasionally looking up and smiling. The room is cozy, with a crib in the background and clothes scattered around. The baby’s focus and curiosity are evident as they explore the book, creating a heartwarming scene of early learning and discovery.'
+
+# use stream
+request_config = RequestConfig(max_tokens=128, temperature=0, stream=True)
+gen_list = engine.infer([infer_request], request_config=request_config)
+for chunk in gen_list[0]:
+    if chunk is None:
+        continue
+    print(chunk.choices[0].delta.content, end='', flush=True)
+print()
+```
+
+使用命令行推理：
+```shell
+CUDA_VISIBLE_DEVICES=0 \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=16 \
+swift infer \
+    --model Qwen/Qwen3-VL-4B-Instruct \
+    --stream true
+```
+
+```
+<<< who are you?
+Hello! I'm Qwen, a large-scale language model independently developed by the Tongyi Lab under Alibaba Group. My main functions include answering questions, creating text such as stories, official documents, emails, scripts, and more, as well as performing logical reasoning, programming, and other tasks. If you have any questions or need assistance, feel free to let me know anytime, and I'll do my best to help!
+--------------------------------------------------
+<<< <image>describe the image.
+Input an image path or URL <<< http://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/cat.png
+This is a beautifully detailed, close-up portrait of an adorable tabby kitten, rendered with a soft, painterly effect that gives it a gentle, dreamy quality.
+
+Here’s a breakdown of the image:
+
+- **The Kitten:** The subject is a young, fluffy kitten with a classic tabby pattern. Its fur is a mix of white and soft grayish-brown stripes, with a prominent dark stripe running down the center of its forehead and over its nose. The kitten’s face is predominantly white, with delicate markings around its eyes and cheeks.
+
+- **The Eyes:** Its most captivating feature is its large, round, and expressive eyes. They are a striking shade of bright blue-gray, with dark pupils that give it an intense, curious, and slightly innocent gaze. The eyes are wide open, suggesting the kitten is alert and attentive.
+
+- **The Expression:** The kitten’s expression is sweet and innocent. Its small pink nose and slightly parted mouth give it a gentle, almost pleading look. Its whiskers are long and white, standing out against its fur.
+
+- **The Style:** The image has a soft-focus, artistic quality, reminiscent of impressionist painting. The edges of the kitten’s fur are slightly blurred, creating a halo effect that draws attention to its face. The background is softly blurred with muted tones of green and gray, which helps the kitten stand out as the clear focal point.
+
+- **Overall Impression:** The image evokes feelings of warmth, cuteness, and tenderness. The kitten appears to be looking directly at the viewer, creating a sense of connection and affection.
+
+This is a lovely and charming depiction of a young kitten, capturing its innocence and charm in a visually appealing and emotionally engaging way.
+--------------------------------------------------
+<<< <video>describe the video.
+Input a video path or URL <<< https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/baby.mp4
+This video captures a charming and adorable moment of a young child, likely a toddler, sitting on a bed and pretending to read a book. The child is wearing glasses, which adds a humorous and endearing touch to the scene — as if they’re a little scholar or librarian.
+
+Here’s a breakdown of what unfolds:
+
+- The child is seated cross-legged on a bed with a patterned quilt. Behind them, a crib and some household items are visible, suggesting a cozy bedroom setting.
+
+- The child holds an open book and appears to be turning the pages with focused attention, mimicking the behavior of a real reader.
+
+- At one point, the child looks up, smiles, or seems to react with delight — perhaps amused by something in the book or just enjoying the activity.
+
+- The child’s movements are gentle and deliberate, showing a sense of concentration and curiosity. They turn pages, sometimes with one hand, and occasionally lift the book slightly as if to examine it more closely.
+
+- The video has a warm, candid feel — it’s not staged, and the child’s natural behavior makes it feel authentic and heartwarming.
+
+Overall, this is a sweet, lighthearted video that showcases the innocence and imagination of early childhood. The child’s engagement with the book, combined with their glasses and playful demeanor, creates a delightful and memorable scene.
+```
+
+- 其中特定模型参数，例如 `VIDEO_MAX_TOKEN_NUM` 等环境变量的含义参考[命令行参数文档](../Instruction/Command-line-parameters.md#qwen3_vl-qwen3_5)。
+
+
+## 训练
+
+本文档将介绍如何使用 ms-swift 与 Megatron-SWIFT 训练 Qwen3-VL。推荐 Dense 模型使用 ms-swift（即 transformers 后端，更加方便简单），而 Moe 模型使用 Megatron-SWIFT（即 megatron 后端，更快的训练速度，benchmark查看[这里](../Megatron-SWIFT/Quick-start.md#benchmark)）。
+
+如果您需要自定义数据集微调模型，你可以将数据准备成以下格式，并在命令行中设置`--dataset train.jsonl --val_dataset val.jsonl`，其中验证集为可选。更多介绍请参考[多模态数据集文档](../Customization/Custom-dataset.md#多模态)。
+```jsonl
+{"messages": [{"role": "user", "content": "浙江的省会在哪？"}, {"role": "assistant", "content": "浙江的省会在杭州。"}]}
+{"messages": [{"role": "user", "content": "<image><image>两张图片有什么区别"}, {"role": "assistant", "content": "前一张是小猫，后一张是小狗"}], "images": ["/xxx/x.jpg", "/xxx/x.png"]}
+{"messages": [{"role": "system", "content": "你是个有用无害的助手"}, {"role": "user", "content": "<image>图片中是什么，<video>视频中是什么"}, {"role": "assistant", "content": "图片中是一个大象，视频中是一只小狗在草地上奔跑"}], "images": ["/xxx/x.jpg"], "videos": ["/xxx/x.mp4"]}
+```
+
+Qwen3-VL的bbox输出采用归一化1000的相对坐标。你可以使用 ms-swift 提供的 grounding 数据集格式，其中"bbox"中的坐标为绝对坐标，ms-swift 会自动将绝对坐标转为归一化1000的相对坐标。更多信息请参考[grounding数据集格式文档](../Customization/Custom-dataset.md#grounding)。
+```jsonl
+{"messages": [{"role": "user", "content": "<image>找到图像中的<ref-object>"}, {"role": "assistant", "content": "[\n\t{\"bbox_2d\": <bbox>, \"label\": \"<ref-object>\"},\n\t{\"bbox_2d\": <bbox>, \"label\": \"<ref-object>\"}\n]"}], "images": ["cat.png"], "objects": {"ref": ["羊", "羊", "羊"], "bbox": [[90.9, 160.8, 135, 212.8], [360.9, 480.8, 495, 532.8]]}}
+```
+
+### Dense模型
+
+以下提供对`Qwen3-VL-4B-Instruct`模型的微调脚本，我们使用混合模态数据作为Demo数据集，该示例脚本仅作为演示用途。训练显存为2 * 21GiB，训练时间为12分钟。
+- 若觉得预处理时间太长，你可以将`--packing`去除，或者使用[cached dataset](https://github.com/modelscope/ms-swift/tree/main/examples/train/cached_dataset)。
+
+```shell
+# 2 * 21GiB
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=16 \
+NPROC_PER_NODE=2 \
+CUDA_VISIBLE_DEVICES=0,1 \
+swift sft \
+    --model Qwen/Qwen3-VL-4B-Instruct \
+    --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#10000' \
+              'AI-ModelScope/LaTeX_OCR:human_handwrite#5000' \
+              'swift/VideoChatGPT:Generic#2000' \
+    --load_from_cache_file true \
+    --split_dataset_ratio 0.01 \
+    --tuner_type lora \
+    --torch_dtype bfloat16 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 1 \
+    --per_device_eval_batch_size 1 \
+    --attn_impl flash_attn \
+    --padding_free true \
+    --learning_rate 1e-4 \
+    --lora_rank 8 \
+    --lora_alpha 32 \
+    --target_modules all-linear \
+    --freeze_vit true \
+    --freeze_aligner true \
+    --packing true \
+    --gradient_checkpointing true \
+    --vit_gradient_checkpointing false \
+    --gradient_accumulation_steps 2 \
+    --eval_steps 100 \
+    --save_steps 100 \
+    --save_total_limit 2 \
+    --logging_steps 5 \
+    --max_length 4096 \
+    --output_dir output \
+    --warmup_ratio 0.05 \
+    --deepspeed zero2 \
+    --dataset_num_proc 4 \
+    --dataloader_num_workers 4
+```
+
+训练结束后，我们使用以下脚本对验证集进行推理：
+```shell
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+CUDA_VISIBLE_DEVICES=0 \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=16 \
+swift infer \
+    --adapters output/vx-xxx/checkpoint-xxx \
+    --stream true \
+    --max_new_tokens 2048 \
+    --load_data_args true
+```
+
+```
+--------------------------------------------------
+[QUERY] Using LaTeX to perform OCR on the image.
+[LABELS] 1 + \frac { 1 } { 1 ! } + \frac { 1 } { 2 ! } + \frac { 1 } { 3 ! } + \frac { 1 } { 4 ! }
+[RESPONSE] 1 + \frac { 1 } { 1 ! } + \frac { 1 } { 2 ! } + \frac { 1 } { 3 ! } + \frac { 1 } { 4 ! }
+--------------------------------------------------
+[QUERY] What color suit is the man wearing while playing the saxophone on stage?
+[LABELS] The man is wearing a black suit and white shirt while playing the saxophone on the red-floored stage.
+[RESPONSE] The man is wearing a black suit while playing the saxophone on stage.
+--------------------------------------------------
+...
+```
+
+### Moe模型
+
+
+以下提供对`Qwen3-VL-30B-A3B-Instruct`模型的微调脚本，我们使用 Megatron-SWIFT 进行单机全参数训练。我们同样采用混合数据进行训练，该示例脚本仅作为演示用途。训练所需显存资源为8 * 80GiB，训练时间为20分钟。
+
+关于 Megatron-SWIFT 的环境安装，请参考[Megatron-SWIFT文档](../Megatron-SWIFT/Quick-start.md)。Megatron-SWIFT 与 ms-swift 共用 template 和 dataset 模块，因此前面介绍的自定义数据集格式和模型特有环境变量依旧生效。
+
+
+微调脚本如下，训练技巧与并行技术的调整参考[Megatron-SWIFT文档](../Megatron-SWIFT/Quick-start.md#训练技巧)。
+```shell
+# 8 * 80GiB
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+OMP_NUM_THREADS=14 \
+NPROC_PER_NODE=8 \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=16 \
+megatron sft \
+    --model Qwen/Qwen3-VL-30B-A3B-Instruct \
+    --save_safetensors true \
+    --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#10000' \
+              'AI-ModelScope/LaTeX_OCR:human_handwrite#5000' \
+              'swift/VideoChatGPT:Generic#2000' \
+    --load_from_cache_file true \
+    --split_dataset_ratio 0.01 \
+    --moe_permute_fusion true \
+    --tensor_model_parallel_size 4 \
+    --expert_model_parallel_size 8 \
+    --moe_grouped_gemm true \
+    --moe_shared_expert_overlap true \
+    --moe_aux_loss_coeff 1e-6 \
+    --micro_batch_size 1 \
+    --global_batch_size 4 \
+    --recompute_granularity full \
+    --recompute_method uniform \
+    --recompute_num_layers 1 \
+    --num_train_epochs 1 \
+    --finetune true \
+    --cross_entropy_loss_fusion true \
+    --lr 1e-5 \
+    --lr_warmup_fraction 0.05 \
+    --min_lr 1e-6 \
+    --output_dir megatron_output/Qwen3-VL-30B-A3B-Instruct \
+    --eval_steps 500 \
+    --save_steps 500 \
+    --max_length 4096 \
+    --packing true \
+    --dataloader_num_workers 8 \
+    --dataset_num_proc 8 \
+    --no_save_optim true \
+    --no_save_rng true \
+    --sequence_parallel true \
+    --moe_expert_capacity_factor 2 \
+    --attention_backend flash
+```
+
+训练结束后，我们使用以下脚本对验证集进行推理：
+```shell
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+CUDA_VISIBLE_DEVICES=0 \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=16 \
+swift infer \
+    --model megatron_output/Qwen3-VL-30B-A3B-Instruct/vx-xxx/checkpoint-xxx \
+    --stream true \
+    --max_new_tokens 2048 \
+    --load_data_args true
+```
+
+
+使用以下命令将训练权重推送到 Modelscope：
+```shell
+swift export \
+    --model output/vx-xxx/checkpoint-xxx \
+    --push_to_hub true \
+    --hub_model_id '<your-model-id>' \
+    --hub_token '<your-sdk-token>'
+```
@@ -0,0 +1,564 @@
+# Qwen3.5 最佳实践
+
+ms-swift 支持使用transformers/Megatron后端对[Qwen3.5](https://github.com/QwenLM/Qwen3.5) Dense/Moe模型进行训练。Qwen3.5 属于混合思考的多模态模型，结合了linear attention和full attention。本文将介绍如何对Qwen3.5 Dense/Moe模型进行推理、指令微调以及强化学习。
+
+
+## 环境设置
+```shell
+pip install -U ms-swift
+pip install -U "transformers>=5.9" "qwen_vl_utils>=0.0.14" peft liger-kernel
+
+# flash-linear-attention
+# 若出现训练缓慢的问题请参考：https://github.com/fla-org/flash-linear-attention/issues/758
+# 请使用python3.12: https://github.com/fla-org/flash-linear-attention/issues/121
+pip install -U "flash-linear-attention>=0.4.2" --no-build-isolation
+
+# causal_conv1d
+pip install -U git+https://github.com/Dao-AILab/causal-conv1d --no-build-isolation
+
+# flash-attention
+pip install "flash-attn==2.8.3" --no-build-isolation
+
+# deepspeed训练
+pip install deepspeed
+
+# vllm (torch2.10) for inference/deployment/RL
+pip install -U "vllm>=0.17.0"
+```
+
+- Qwen3.5 视频数据训练卡住：使用decord后端读取视频可能导致卡住问题，参考[这个issue](https://github.com/dmlc/decord/issues/269)。你可以使用torchcodec后端，具体参考[qwen_vl_utils](https://github.com/QwenLM/Qwen3-VL/blob/50068df2334f309979ff05d75f1078c8309c63ed/qwen-vl-utils/src/qwen_vl_utils/vision_process.py#L390-L400)库。
+- 如果你在昇腾 NPU 上使用 Qwen3.5，并且需要了解 FLA / MindSpeed 的替换关系、补丁生效路径以及版本验证信息，请参考 [NPU支持文档中的 Qwen3.5 FLA补丁说明](./NPU-support.md#qwen35-fla补丁说明)。
+
+
+## 推理
+
+使用 ms-swift 的 `TransformersEngine` 进行推理：
+
+- 其中特定模型参数，例如 `VIDEO_MAX_TOKEN_NUM` 等环境变量的含义与Qwen3-VL相同，参考[命令行参数文档](../Instruction/Command-line-parameters.md#qwen3_vl,qwen3_5)。
+
+```python
+import os
+# os.environ['SWIFT_DEBUG'] = '1'
+os.environ['CUDA_VISIBLE_DEVICES'] = '0'
+os.environ['IMAGE_MAX_TOKEN_NUM'] = '1024'
+os.environ['VIDEO_MAX_TOKEN_NUM'] = '128'
+os.environ['FPS_MAX_FRAMES'] = '16'
+
+from swift import get_model_processor, get_template
+from swift.infer_engine import TransformersEngine, InferRequest, RequestConfig
+
+model, processor = get_model_processor('Qwen/Qwen3.5-4B')  # attn_impl='flash_attention_2'
+template = get_template(processor, enable_thinking=False)
+engine = TransformersEngine(model, template=template)
+infer_request = InferRequest(messages=[{
+    "role": "user",
+    "content": '<video>Describe this video.',
+}], videos=['https://modelscope-open.oss-cn-hangzhou.aliyuncs.com/images/baby.mp4'])
+request_config = RequestConfig(max_tokens=128, temperature=0)
+resp_list = engine.infer([infer_request], request_config=request_config)
+response = resp_list[0].choices[0].message.content
+print(response)
+
+# use stream
+request_config = RequestConfig(max_tokens=128, temperature=0, stream=True)
+gen_list = engine.infer([infer_request], request_config=request_config)
+for chunk in gen_list[0]:
+    if chunk is None:
+        continue
+    print(chunk.choices[0].delta.content, end='', flush=True)
+print()
+```
+
+使用命令行进行推理：
+
+```shell
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=16 \
+CUDA_VISIBLE_DEVICES=0 \
+swift infer \
+    --model Qwen/Qwen3.5-4B \
+    --enable_thinking false \
+    --stream true
+```
+
+
+## 微调
+
+本章将介绍如何使用 ms-swift 与 Megatron-SWIFT 训练 Qwen3.5。推荐 Dense 模型使用 ms-swift（即 transformers 后端，更加方便简单），而 Moe 模型使用 Megatron-SWIFT（即 megatron 后端，更快的训练速度）
+
+如果您需要自定义数据集微调模型，你可以将数据准备成以下格式，并在命令行中设置`--dataset train.jsonl --val_dataset val.jsonl`，其中验证集为可选。更多介绍请参考[多模态数据集文档](../Customization/Custom-dataset.md#多模态)。
+
+```jsonl
+{"messages": [{"role": "user", "content": "浙江的省会在哪？"}, {"role": "assistant", "content": "浙江的省会在杭州。"}]}
+{"messages": [{"role": "user", "content": "<image><image>两张图片有什么区别"}, {"role": "assistant", "content": "前一张是小猫，后一张是小狗"}], "images": ["/xxx/x.jpg", "/xxx/x.png"]}
+{"messages": [{"role": "system", "content": "你是个有用无害的助手"}, {"role": "user", "content": "<image>图片中是什么，<video>视频中是什么"}, {"role": "assistant", "content": "图片中是一个大象，视频中是一只小狗在草地上奔跑"}], "images": ["/xxx/x.jpg"], "videos": ["/xxx/x.mp4"]}
+```
+
+Qwen3.5的bbox输出采用归一化1000的相对坐标。你可以使用 ms-swift 提供的 grounding 数据集格式，其中"bbox"中的坐标为绝对坐标，ms-swift 会自动将绝对坐标转为归一化1000的相对坐标。更多信息请参考[grounding数据集格式文档](../Customization/Custom-dataset.md#grounding)。
+
+```jsonl
+{"messages": [{"role": "user", "content": "<image>找到图像中的<ref-object>"}, {"role": "assistant", "content": "[\n\t{\"bbox_2d\": <bbox>, \"label\": \"<ref-object>\"},\n\t{\"bbox_2d\": <bbox>, \"label\": \"<ref-object>\"}\n]"}], "images": ["cat.png"], "objects": {"ref": ["羊", "羊", "羊"], "bbox": [[90.9, 160.8, 135, 212.8], [360.9, 480.8, 495, 532.8]]}}
+```
+
+
+### Dense模型
+
+以下提供对Qwen3.5-4B模型的微调脚本，该示例脚本仅作为演示用途。训练显存为 4 * 20GiB，训练时间为12分钟。Qwen3.5已支持在transformers中使用packing/padding_free（需"ms-swift>=4.3.1"，megatron无此版本限制）。下面我们使用group_by_length参数来加速训练，保证DP的负载均衡并减少micro batch中的零填充，但这会导致loss曲线跳动（因数据随机不充分），你也可以去掉此参数并使用`--packing true`代替。
+- 关于数据预处理：若使用packing/group_by_length参数，则需要对所有数据做提前预处理，获取数据input_ids长度，这需要消耗一定时间。若你希望在训练时处理数据，你可以去除这个两个参数。
+- 降低显存消耗：可以通过`--deepspeed zero2/zero3`, 开启序列并行`--sequence_parallel_size`，或者使用`--use_liger_kernel true`。
+- 训练加速：可以开启`--attn_impl flash_attention_2`，MoE模型建议开启`--experts_impl grouped_mm`。
+
+```shell
+# 4 * 20GiB
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+NPROC_PER_NODE=4 \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=12 \
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+swift sft \
+    --model Qwen/Qwen3.5-4B \
+    --tuner_type lora \
+    --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \
+              'AI-ModelScope/alpaca-gpt4-data-en#500' \
+              'swift/self-cognition#500' \
+              'AI-ModelScope/LaTeX_OCR:human_handwrite#2000' \
+    --load_from_cache_file true \
+    --add_non_thinking_prefix true \
+    --loss_scale ignore_empty_think \
+    --split_dataset_ratio 0.01 \
+    --torch_dtype bfloat16 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 4 \
+    --per_device_eval_batch_size 4 \
+    --learning_rate 1e-4 \
+    --lora_rank 8 \
+    --lora_alpha 32 \
+    --target_modules all-linear \
+    --gradient_accumulation_steps 1 \
+    --group_by_length true \
+    --output_dir output/Qwen3.5-4B \
+    --eval_steps 50 \
+    --save_steps 50 \
+    --save_total_limit 2 \
+    --logging_steps 5 \
+    --max_length 2048 \
+    --warmup_ratio 0.05 \
+    --dataset_num_proc 4 \
+    --dataloader_num_workers 4 \
+    --deepspeed zero2 \
+    --model_author swift \
+    --model_name swift-robot
+```
+
+训练结束后，使用以下脚本对验证集进行推理：
+
+```shell
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+CUDA_VISIBLE_DEVICES=0 \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=12 \
+swift infer \
+    --adapters output/Qwen3.5-4B/vx-xxx/checkpoint-xxx \
+    --stream true \
+    --enable_thinking false \
+    --max_new_tokens 512 \
+    --load_data_args true
+```
+
+
+```text
+[QUERY] 你好，你是谁？
+[RESPONSE] <think>
+
+</think>
+
+你好，我是由swift开发的人工智能语言模型，我的名字叫swift-robot。很高兴能与你交流。
+--------------------------------------------------
+[QUERY] Using LaTeX to perform OCR on the image.
+[LABELS] e = \sum _ { k = 0 } ^ { \infty } \frac { 1 } { k ! }
+[RESPONSE] <think>
+
+</think>
+
+e = \sum _ { k = 0 } ^ { \infty } \frac { 1 } { k ! }
+```
+
+使用python进行推理：
+```python
+import os
+# os.environ['SWIFT_DEBUG'] = '1'
+os.environ['CUDA_VISIBLE_DEVICES'] = '0'
+os.environ['IMAGE_MAX_TOKEN_NUM'] = '1024'
+os.environ['VIDEO_MAX_TOKEN_NUM'] = '128'
+os.environ['FPS_MAX_FRAMES'] = '16'
+
+from peft import PeftModel
+from swift import get_model_processor, get_template
+from swift.infer_engine import TransformersEngine, InferRequest, RequestConfig
+
+adapter_dir = 'output/Qwen3.5-4B/vx-xxx/checkpoint-xxx'
+enable_thinking = False
+
+model, processor = get_model_processor('Qwen/Qwen3.5-4B')  # attn_impl='flash_attention_2'
+model = PeftModel.from_pretrained(model, adapter_dir)
+template = get_template(processor, enable_thinking=enable_thinking)
+engine = TransformersEngine(model, template=template)
+infer_request = InferRequest(messages=[{
+    "role": "user",
+    "content": 'who are you?',
+}])
+request_config = RequestConfig(max_tokens=128, temperature=0)
+resp_list = engine.infer([infer_request], request_config=request_config)
+response = resp_list[0].choices[0].message.content
+print(response)
+
+# use stream
+request_config = RequestConfig(max_tokens=128, temperature=0, stream=True)
+gen_list = engine.infer([infer_request], request_config=request_config)
+for chunk in gen_list[0]:
+    if chunk is None:
+        continue
+    print(chunk.choices[0].delta.content, end='', flush=True)
+print()
+# I am an artificial intelligence assistant named swift-robot, trained by swift. I am designed to understand and generate natural language text in order to provide information, answer questions, and engage in conversation with humans. How can I assist you?
+```
+
+
+使用transformers后端训练MoE的例子参考：https://github.com/modelscope/ms-swift/blob/main/examples/models/qwen3_5/transformers.sh
+
+### Moe模型
+Qwen3.5-35B-A3B Megatron训练，环境的准备请参考[Megatron-SWIFT快速开始文档](../Megatron-SWIFT/Quick-start.md)。你可以在15分钟内跑完以下案例：
+
+```shell
+# 4 * 40GiB
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+NPROC_PER_NODE=4 \
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=12 \
+megatron sft \
+    --model Qwen/Qwen3.5-35B-A3B \
+    --save_safetensors true \
+    --merge_lora true \
+    --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#500' \
+              'AI-ModelScope/alpaca-gpt4-data-en#500' \
+              'swift/self-cognition#500' \
+              'AI-ModelScope/LaTeX_OCR:human_handwrite#2000' \
+    --load_from_cache_file true \
+    --add_non_thinking_prefix true \
+    --loss_scale ignore_empty_think \
+    --split_dataset_ratio 0.01 \
+    --tuner_type lora \
+    --lora_rank 8 \
+    --lora_alpha 32 \
+    --target_modules all-linear \
+    --expert_model_parallel_size 4 \
+    --moe_permute_fusion true \
+    --moe_grouped_gemm true \
+    --moe_shared_expert_overlap true \
+    --moe_aux_loss_coeff 1e-6 \
+    --micro_batch_size 4 \
+    --global_batch_size 16 \
+    --recompute_granularity full \
+    --recompute_method uniform \
+    --recompute_num_layers 1 \
+    --num_train_epochs 1 \
+    --group_by_length true \
+    --finetune true \
+    --freeze_llm false \
+    --freeze_vit true \
+    --freeze_aligner true \
+    --cross_entropy_loss_fusion true \
+    --lr 1e-4 \
+    --lr_warmup_fraction 0.05 \
+    --min_lr 1e-5 \
+    --output_dir megatron_output/Qwen3.5-35B-A3B \
+    --eval_steps 200 \
+    --save_steps 200 \
+    --max_length 2048 \
+    --dataloader_num_workers 8 \
+    --dataset_num_proc 8 \
+    --no_save_optim true \
+    --no_save_rng true \
+    --sequence_parallel true \
+    --attention_backend flash \
+    --padding_free false \
+    --model_author swift \
+    --model_name swift-robot
+```
+训练结束后，使用以下脚本对验证集进行推理：
+
+```shell
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+IMAGE_MAX_TOKEN_NUM=1024 \
+VIDEO_MAX_TOKEN_NUM=128 \
+FPS_MAX_FRAMES=12 \
+swift infer \
+    --model megatron_output/Qwen3.5-35B-A3B/vx-xxx/checkpoint-xxx-merged \
+    --stream true \
+    --enable_thinking false \
+    --max_new_tokens 512 \
+    --load_data_args true
+```
+
+Megatron-SWIFT训练Qwen3.5的提示：
+- 全参数训练：参考[这个例子](https://github.com/modelscope/ms-swift/blob/main/examples/models/qwen3_5/packing.sh)。
+- TP 限制解除：使用 "megatron-core>=0.16" 可解除 TP 受到的 `num_query_groups` 限制。
+- 关于MTP训练："mcore-bridge>=1.1.0"支持了多模态MTP的训练。请安装对应版本。
+- CP支持："mcore-bridge>=1.1.0"支持了GDN的CP训练，需安装megatron-core [main分支](https://github.com/NVIDIA/Megatron-LM)。
+- 默认 `GatedDeltaNet` 使用 Megatron 实现，需使用 "megatron-core>=0.16"（ms-swift>=4.1.0，之前版本默认使用transformers实现）。设置环境变量 `USE_MCORE_GDN=0`可切换至 transformers 实现，**transformers实现不支持packing和GDN的TP/CP**。
+- padding_free/packing的支持：packing可以提升训练速度。参考[这个例子](https://github.com/modelscope/ms-swift/tree/main/examples/models/qwen3_5/packing.sh)。
+  - Qwen3-Next的Megatron GatedDeltaNet支持参考[这个PR](https://github.com/modelscope/mcore-bridge/pull/76)，需要"mcore-bridge>=1.4.0"。
+- apply_wd_to_qk_layernorm: 对 qk layernorm 应用权重衰减。默认为False。
+- 关于FP8训练：参考[这个例子](https://github.com/modelscope/ms-swift/blob/main/examples/models/qwen3_5/fp8.sh)。你需要安装"mcore-bridge>=1.2.0"，并设置参数`--linear_decoupled_in_proj true`，将`in_proj`解耦为`in_proj_qkvz`, `in_proj_ba`，其中`in_proj_ba`仍使用原始精度训练。
+
+
+## 强化学习（RL）
+
+以 Qwen3.5-2B 模型为例，下面展示基于 [GSM8K](https://www.modelscope.cn/datasets/modelscope/gsm8k) 数据集进行 GRPO 和 GKD 训练，并以 GSM8K 评测集为标准验证训练效果。为避免模型输出过长的思维链，以下统一设置 `enable_thinking false`。
+
+### GRPO
+
+#### Dense 模型
+使用 GRPO 进行全参数训练，以 `gsm8k_accuracy` 和 `gsm8k_format` 作为奖励函数。奖励函数的实现参考 [gsm8k_plugin.py](https://github.com/modelscope/ms-swift/blob/main/examples/train/grpo/plugin/gsm8k/gsm8k_plugin.py)。
+
+```shell
+SYSTEM_PROMPT="""You are a helpful math assistant. Solve the problem step by step and put your final answer within \\boxed{}."""
+
+CUDA_VISIBLE_DEVICES=0,1,2,3 \
+NPROC_PER_NODE=4 \
+swift rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen3.5-2B \
+    --external_plugins examples/train/grpo/plugin/gsm8k/gsm8k_plugin.py \
+    --reward_funcs gsm8k_accuracy gsm8k_format \
+    --columns '{"answer": "solution"}' \
+    --enable_thinking false \
+    --use_vllm true \
+    --vllm_mode colocate \
+    --vllm_gpu_memory_utilization 0.4 \
+    --vllm_tensor_parallel_size 1 \
+    --vllm_max_model_len 10240 \
+    --sleep_level 1 \
+    --tuner_type full \
+    --torch_dtype bfloat16 \
+    --dataset 'modelscope/gsm8k' \
+    --load_from_cache_file true \
+    --max_length 2048 \
+    --max_completion_length 8192 \
+    --num_train_epochs 1 \
+    --per_device_train_batch_size 4 \
+    --gradient_accumulation_steps 4 \
+    --learning_rate 1e-6 \
+    --lr_scheduler_type cosine \
+    --save_steps 10 \
+    --save_total_limit 100 \
+    --logging_steps 1 \
+    --warmup_ratio 0.0 \
+    --dataloader_num_workers 4 \
+    --num_generations 8 \
+    --temperature 1.0 \
+    --system "$SYSTEM_PROMPT" \
+    --deepspeed zero2 \
+    --log_completions true \
+    --report_to tensorboard swanlab \
+    --max_grad_norm 1.0 \
+    --epsilon 0.2 \
+    --epsilon_high 0.28 \
+    --scale_rewards none
+```
+
+使用以下指令进行评测：
+
+```shell
+CUDA_VISIBLE_DEVICES=0 swift eval \
+    --model output/Qwen3.5-2B/vxx-xxx-xxx/checkpoint-xx \
+    --enable_thinking false \
+    --eval_dataset gsm8k \
+    --eval_backend Native --infer_backend vllm \
+    --eval_generation_config '{"max_tokens":8192,"temperature":0.0,"do_sample":false}'
+```
+
+以 10 步为间隔，前 50 步的 GSM8K 评测结果如下：
+
+| 模型 / Steps | GSM8K Accuracy | 提升 |
+|---|---|---|
+| Qwen3.5-2B (baseline) | 0.7597 | - |
+| GRPO 10 steps | 0.7650 | +0.53 |
+| GRPO 20 steps | 0.7748 | +1.51 |
+| GRPO 30 steps | 0.7779 | +1.82 |
+| GRPO 40 steps | 0.7817 | +2.20 |
+| GRPO 50 steps | 0.7885 | +2.88 |
+
+#### MoE 模型
+
+使用 Megatron 后端对 Qwen3.5-35B-A3B MoE 模型进行 GRPO LoRA 训练，在 [DAPO-Math-17k](https://www.modelscope.cn/datasets/open-r1/DAPO-Math-17k-Processed) 数据集上训练，使用 `accuracy` 作为奖励函数。
+
+```shell
+SYSTEM_PROMPT="""You are a helpful math assistant. Solve the problem step by step and put your final answer within \\boxed{}."""
+
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+NPROC_PER_NODE=8 \
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+megatron rlhf \
+    --rlhf_type grpo \
+    --model Qwen/Qwen3.5-35B-A3B \
+    --save_safetensors true \
+    --enable_thinking false \
+    --merge_lora true \
+    --context_parallel_size 1 \
+    --tensor_model_parallel_size 1 \
+    --expert_model_parallel_size 8 \
+    --pipeline_model_parallel_size 1 \
+    --moe_permute_fusion true \
+    --dataset open-r1/DAPO-Math-17k-Processed \
+    --system "$SYSTEM_PROMPT" \
+    --num_train_epochs 1 \
+    --global_batch_size 64 \
+    --micro_batch_size 1 \
+    --steps_per_generation 2 \
+    --num_generations 8 \
+    --reward_funcs accuracy \
+    --use_vllm true \
+    --vllm_mode colocate \
+    --vllm_gpu_memory_utilization 0.5 \
+    --vllm_tensor_parallel_size 2 \
+    --vllm_max_model_len 9192 \
+    --max_length 1000 \
+    --max_completion_length 8192 \
+    --tuner_type lora \
+    --target_modules all-linear \
+    --lr 5e-5 \
+    --bf16 true \
+    --beta 0.00 \
+    --epsilon 0.2 \
+    --epsilon_high 0.28 \
+    --dynamic_sample false \
+    --overlong_filter true \
+    --loss_type grpo \
+    --sleep_level 1 \
+    --offload_model true \
+    --offload_bridge false \
+    --offload_optimizer true \
+    --logging_steps 1 \
+    --recompute_granularity full \
+    --recompute_method uniform \
+    --recompute_num_layers 1 \
+    --finetune \
+    --dataloader_num_workers 8 \
+    --dataset_num_proc 8 \
+    --no_save_optim \
+    --no_save_rng \
+    --save_steps 20 \
+    --attention_backend flash \
+    --moe_expert_capacity_factor 2 \
+    --temperature 1.0 \
+    --padding_free false \
+    --sequence_parallel true \
+    --log_completions true \
+    --report_to tensorboard swanlab
+```
+
+使用以下指令在 AIME-2025 和 MATH-500 上评测：
+
+```shell
+CUDA_VISIBLE_DEVICES=0,1 swift eval \
+    --model <checkpoint-merged-path> \
+    --enable_thinking false \
+    --eval_dataset aime25 math_500 \
+    --eval_backend Native --infer_backend vllm \
+    --vllm_tensor_parallel_size 2 \
+    --vllm_gpu_memory_utilization 0.9 \
+    --vllm_max_model_len 10000 \
+    --eval_generation_config '{"max_tokens":8192,"temperature":0.0,"do_sample":false}' \
+    --eval_num_proc 8
+```
+
+在 AIME-2025 和 MATH-500 上的评测结果如下：
+
+| 模型 / Steps | AIME-2025 | MATH-500 |
+|---|---|---|
+| Qwen3.5-35B-A3B (baseline) | 43.33 | 92.40 |
+| Megatron GRPO 20 steps | 53.33 (+10.00) | 95.80 (+3.40) |
+| Megatron GRPO 40 steps | 53.33 (+10.00) | 96.60 (+4.20) |
+
+### GKD
+
+使用 GKD 进行 LoRA 训练，以 Qwen3.5-9B 作为 teacher 模型。首先使用 swift deploy 拉起 teacher server（也可以通过 `--teacher_model` 参数直接加载模型）：
+
+```shell
+CUDA_VISIBLE_DEVICES=0 \
+swift deploy \
+    --model Qwen/Qwen3.5-9B \
+    --infer_backend vllm \
+    --port 8000 \
+    --vllm_tensor_parallel_size 1 \
+    --vllm_max_model_len 10240 \
+    --gpu-memory-utilization 0.8 \
+    --max_logprobs 64
+```
+
+然后在其余 GPU 上启动 GKD 训练：
+
+```shell
+NPROC_PER_NODE=3 \
+CUDA_VISIBLE_DEVICES=1,2,3 \
+swift rlhf \
+    --rlhf_type gkd \
+    --model Qwen/Qwen3.5-2B \
+    --teacher_model_server http://localhost:8000 \
+    --gkd_logits_topk 64 \
+    --enable_thinking false \
+    --tuner_type lora \
+    --use_vllm true \
+    --vllm_mode colocate \
+    --vllm_gpu_memory_utilization 0.5 \
+    --vllm_tensor_parallel_size 1 \
+    --vllm_max_model_len 10240 \
+    --sleep_level 0 \
+    --dataset 'modelscope/gsm8k' \
+    --lmbda 1 \
+    --beta 0.5 \
+    --torch_dtype bfloat16 \
+    --per_device_train_batch_size 2 \
+    --gradient_accumulation_steps 16 \
+    --learning_rate 5e-5 \
+    --logging_steps 1 \
+    --save_steps 100 \
+    --save_total_limit 10 \
+    --max_length 2048 \
+    --max_completion_length 8192 \
+    --warmup_ratio 0.1 \
+    --save_only_model true \
+    --dataloader_num_workers 4 \
+    --dataset_num_proc 4 \
+    --attn_impl flash_attn \
+    --report_to tensorboard swanlab
+```
+
+使用以下指令进行评测：
+
+```shell
+CUDA_VISIBLE_DEVICES=0 swift eval \
+    --model Qwen/Qwen3.5-2B \
+    --adapters output/Qwen3.5-2B/vxx-xxx-xxx/checkpoint-xx \
+    --merge_lora true \
+    --enable_thinking false \
+    --eval_dataset gsm8k \
+    --eval_backend Native --infer_backend vllm \
+    --eval_generation_config '{"max_tokens":8192,"temperature":0.0,"do_sample":false}'
+```
+
+以 100 步为间隔，前 300 步的 GSM8K 评测结果如下：
+
+| 模型 / Steps | GSM8K Accuracy | 提升 |
+|---|---|---|
+| Qwen3.5-2B (baseline) | 0.7597 | - |
+| GKD 100 steps | 0.7968 | +3.71 |
+| GKD 200 steps | 0.8188 | +5.91 |
+| GKD 300 steps | 0.8332 | +7.35 |
@@ -0,0 +1,234 @@
+# 快速训练VL模型
+
+本文档提供从零开始快速训练视觉语言(Vision-Language, VL)模型的最佳实践。
+
+涉及的模型链接：
+- [Qwen2.5-VL-7B-Instruct](https://www.modelscope.cn/models/Qwen/Qwen2.5-VL-7B-Instruct)
+- [Qwen3-8B](https://www.modelscope.cn/models/Qwen/Qwen3-8B)
+
+训练的模型链接：
+- [Simple-VL-8B](https://www.modelscope.cn/models/swift/Simple-VL-8B/summary)
+
+
+本训练流程基于 Qwen2.5-VL-7B-Instruct 模型架构，将其内部的语言模型（LLM）部分替换为 Qwen3-8B 的权重，训练模型的视觉理解能力。具体步骤如下：
+
+1. 修改原始模型的配置文件 config.json，使其适配 Qwen3-8B 的模型结构。
+2. 初始化并加载新的模型权重，保存为新模型。
+3. 对新模型进行两阶段微调：
+    1. 第一阶段：仅训练视觉到语言的对齐模块（aligner），冻结 ViT 和 LLM 部分。
+    2. 第二阶段：解冻所有模块，联合训练提升整体性能。
+
+
+## 模型修改
+
+### 修改配置文件 config.json
+因为 Qwen2.5-VL-7B-Instruct 模型的底模 Qwen2.5-7B-Instruct 与 Qwen3-8B 在模型结构上存在部分差异（比如层数，hidden_state_dims），我们首先需要基于Qwen2.5-VL-7B-Instruct的config.json文件，创建一个新的config.json文件，并修改以下参数对齐Qwen3-8B
+
+```
+修改
+1. hidden_size 3584->4096
+2. intermediate_size: 18944->12288
+3. num_attention_heads: 28->32
+4. num_key_value_heads: 4->8
+5. num_hidden_layers: 28->36
+6. vocab_size:152064->151936
+7. max_window_layers:28->36
+8. out_hidden_size: 3584->4096
+
+新增
+1. head_dim： 128
+```
+
+### 模型权重初始化与替换
+使用以下 Python 脚本完成模型权重的初始化、替换与保存：
+
+```python
+import torch
+from modelscope import Qwen2_5_VLForConditionalGeneration, AutoModelForCausalLM, AutoConfig
+from transformers.models.qwen2_5_vl.modeling_qwen2_5_vl import Qwen2_5_VLPatchMerger, Qwen2_5_VLModel
+from accelerate import Accelerator
+
+# 加载原始 VL 模型和 Qwen3-8B 模型
+qwen2_5_vl_7b_model = Qwen2_5_VLForConditionalGeneration.from_pretrained(
+    "Qwen/Qwen2.5-VL-7B-Instruct",
+    device_map="cuda",
+    torch_dtype=torch.bfloat16
+)
+device = qwen2_5_vl_7b_model.device
+qwen3_8b_model = AutoModelForCausalLM.from_pretrained(
+    "Qwen/Qwen3-8B",
+    device_map=device,
+    torch_dtype=torch.bfloat16
+)
+
+# 加载配置
+old_config = AutoConfig.from_pretrained("Qwen/Qwen2.5-VL-7B-Instruct")
+new_config = AutoConfig.from_pretrained("/path/to/new_config_dir") # 新 config 的文件夹路径
+new_visual_config = new_config.vision_config
+
+# 1. 替换 ViT 到 LLM 的 merger(aligner) 层
+new_merger = Qwen2_5_VLPatchMerger(
+            dim=new_visual_config.out_hidden_size,
+            context_dim=new_visual_config.hidden_size,
+            spatial_merge_size=new_visual_config.spatial_merge_size,
+        ).to(device).to(torch.bfloat16)
+qwen2_5_vl_7b_model.visual.merger = new_merger
+
+# 2. 替换 VL 模型的 LLM 部分
+new_llm_model = Qwen2_5_VLModel(new_config).to(device).to(torch.bfloat16)
+
+for name, param in qwen3_8b_model.model.named_parameters():
+    if name in new_llm_model.state_dict():
+        new_llm_model.state_dict()[name].copy_(param)
+
+qwen2_5_vl_7b_model.model = new_llm_model
+qwen2_5_vl_7b_model.lm_head = qwen3_8b_model.lm_head
+
+# 3. 保存修改后的模型
+accelerator = Accelerator()
+accelerator.save_model(
+    model=qwen2_5_vl_7b_model,
+    save_directory="/path/to/save/Qwen3-VL-Model",
+    max_shard_size="4GB",
+    safe_serialization=True
+)
+```
+
+保存完权重后，将原 Qwen2.5-VL-7B-Instruct 模型文件夹中除模型权重的文件(包括`model.safetensors.index.json`) 复制到新的模型权重文件夹中，并替换 config.json 为新修改的 config.json文件。
+
+## 训练
+
+为简化流程，我们跳过预训练（pretrain），直接进入监督微调（SFT）。训练分为两个阶段：
+
+### stage1 训练 Aligner 层
+仅训练视觉到语言的对齐层（Aligner），冻结 ViT 和 LLM 部分：
+
+```bash
+NNODES=$WORLD_SIZE \
+NODE_RANK=$RANK \
+NPROC_PER_NODE=8 \
+MAX_PIXELS=1003520 \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+swift sft \
+    --model /path/to/new_vl_model \
+    --model_type qwen2_5_vl \
+    --tuner_type full \
+    --dataset xxx  \
+    --load_from_cache_file true \
+    --split_dataset_ratio 0.01 \
+    --torch_dtype bfloat16 \
+    --attn_impl flash_attn \
+    --freeze_vit true \
+    --freeze_llm true \
+    --freeze_aligner false \
+    --num_train_epochs 3 \
+    --per_device_train_batch_size 2 \
+    --learning_rate 5e-6 \
+    --gradient_accumulation_steps 8 \
+    --eval_steps -1 \
+    --save_steps 1000 \
+    --save_total_limit 10 \
+    --logging_steps 5 \
+    --max_length 8192 \
+    --output_dir output \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --dataset_num_proc 8 \
+    --deepspeed zero2
+```
+
+### stage2 训练整个模型
+解冻所有模块，联合训练以增强模型的整体视觉理解能力：
+
+```bash
+NNODES=$WORLD_SIZE \
+NODE_RANK=$RANK \
+NPROC_PER_NODE=8 \
+MAX_PIXELS=1003520 \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+swift sft \
+    --model /path/to/stage1_checkpoint \
+    --model_type qwen2_5_vl \
+    --tuner_type full \
+    --dataset xxx \
+    --load_from_cache_file true \
+    --split_dataset_ratio 0.01 \
+    --torch_dtype bfloat16 \
+    --attn_impl flash_attn \
+    --freeze_vit false \
+    --freeze_llm false \
+    --freeze_aligner false \
+    --num_train_epochs 3 \
+    --per_device_train_batch_size 2 \
+    --learning_rate 5e-6 \
+    --gradient_accumulation_steps 8 \
+    --eval_steps -1 \
+    --save_steps 1000 \
+    --save_total_limit 10 \
+    --logging_steps 5 \
+    --max_length 8192 \
+    --output_dir output \
+    --warmup_ratio 0.05 \
+    --dataloader_num_workers 4 \
+    --dataset_num_proc 8 \
+    --deepspeed zero2
+```
+
+## 推理/部署/评测
+
+### 推理
+通过`swift infer`来推理训练得到的模型
+```bash
+swift infer \
+    --model /path/to/stage2_checkpoint
+
+```
+
+### 部署
+使用 vLLM 加速模型服务部署：
+
+```
+CUDA_VISIBLE_DEVICES=0 \
+MAX_PIXELS=1003520 \
+VIDEO_MAX_PIXELS=50176 \
+FPS_MAX_FRAMES=12 \
+swift deploy \
+    --model /path/to/stage2_checkpoint \
+    --infer_backend vllm \
+    --vllm_gpu_memory_utilization 0.9 \
+    --vllm_max_model_len 8192 \
+    --max_new_tokens 2048 \
+    --vllm_limit_mm_per_prompt '{"image": 5, "video": 2}' \
+    --served_model_name Qwen3-VL
+```
+
+### 评测
+通过 [EvalScope](https://github.com/modelscope/evalscope/) 对训练得到的 VL 模型进行评测
+
+以下是以 MMMU benchmark 为例的评测代码：
+```python
+from evalscope import TaskConfig, run_task
+
+task_cfg_dict = TaskConfig(
+    work_dir='outputs',
+    eval_backend='VLMEvalKit',
+    eval_config={
+        'data': ['MMMU_DEV_VAL'],
+        'mode': 'all',
+        'model': [
+            {'api_base': 'http://localhost:8000/v1/chat/completions',
+            'key': 'EMPTY',
+            'name': 'CustomAPIModel',
+            'temperature': 0.6,
+            'type': 'Qwen3-VL',
+            'img_size': -1,
+            'video_llm': False,
+            'max_tokens': 512,}
+            ],
+        'reuse': False,
+        'nproc': 64,
+        'judge': 'exact_matching'},
+)
+
+run_task(task_cfg=task_cfg_dict)
+```
@@ -0,0 +1,128 @@
+# Reranker训练
+
+SWIFT已经支持Reranker模型的训练，目前已经支持的模型有：
+
+1. modernbert reranker模型
+   - [ModelScope](https://www.modelscope.cn/models/iic/gte-reranker-modernbert-base) [Hugging Face](https://huggingface.co/Alibaba-NLP/gte-reranker-modernbert-base)
+2. qwen3-reranker模型
+   - 0.6B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-Reranker-0.6B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-Reranker-0.6B)
+   - 4B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-Reranker-4B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-Reranker-4B)
+   - 8B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-Reranker-8B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-Reranker-8B)
+3. qwen3-vl-reranker模型
+   - 2B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-VL-Reranker-2B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-VL-Reranker-2B)
+   - 8B: [ModelScope](https://www.modelscope.cn/models/Qwen/Qwen3-VL-Reranker-8B) [Hugging Face](https://huggingface.co/Qwen/Qwen3-VL-Reranker-8B)
+
+## 实现方式
+
+目前SWIFT支持两种Reranker模型的实现方式，二者在架构和损失函数计算上有显著差异：
+
+### 1. 分类式Reranker
+
+**适用模型：** modernbert reranker模型（如gte-reranker-modernbert-base）
+
+**核心原理：**
+- 基于序列分类架构，在预训练模型基础上添加分类头
+- 输入：query-document对，输出：单个相关性分数
+
+
+### 2. 生成式Reranker
+
+**适用模型：** qwen3-reranker模型（0.6B/4B/8B）
+
+**核心原理：**
+- 基于生成式语言模型架构（CausalLM）
+- 输入：query-document对，输出：特定token的概率（如"yes"/"no"）
+- 通过对比最后位置特定token的logits进行分类
+
+## 损失函数类型
+
+SWIFT支持多种损失函数来训练Reranker模型：
+
+### Pointwise损失函数
+Pointwise方法将排序问题转化为二分类问题，独立处理每个query-document对：
+
+- **核心思想：** 对每个query-document对进行二分类，判断文档是否与查询相关
+- **损失函数：** 二分类交叉熵
+- **适用场景：** 简单高效，适合大规模数据训练
+
+环境变量配置：
+- `GENERATIVE_RERANKER_POSITIVE_TOKEN`：正例token（默认："yes"）
+- `GENERATIVE_RERANKER_NEGATIVE_TOKEN`：负例token（默认："no"）
+
+### Listwise损失函数
+Listwise方法将排序问题转化为多分类问题，从多个候选文档中选择正例：
+
+- **核心思想：** 对每个query的候选文档组（1个正例 + n个负例）进行多分类，识别正例文档
+- **损失函数：** 多分类交叉熵
+- **适用场景：** 学习文档间的相对排序关系，更符合信息检索的实际需求
+
+环境变量配置：
+- `LISTWISE_RERANKER_TEMPERATURE`：softmax温度参数（默认：1.0）
+- `LISTWISE_RERANKER_MIN_GROUP_SIZE`：最小组大小，如果组内文档数量小于该值，则不计算损失（默认：2）
+
+**Listwise vs Pointwise：**
+- **Pointwise：** 独立判断相关性，训练简单，但忽略了文档间的相对关系
+- **Listwise：** 学习相对排序，性能更优，更适合排序任务的本质需求
+
+loss的源代码可以在[这里](https://github.com/modelscope/ms-swift/blob/main/swift/loss/mapping.py)找到。
+
+## 数据集格式
+
+```json lines
+# LLM
+{"messages": [{"role": "user", "content": "query"}], "positive_messages": [[{"role": "assistant", "content": "relevant_doc1"}],[{"role": "assistant", "content": "relevant_doc2"}]], "negative_messages": [[{"role": "assistant", "content": "irrelevant_doc1"}],[{"role": "assistant", "content": "irrelevant_doc2"}], ...]}
+# MLLM
+{"messages": [{"role": "user", "content": "<image>query"}], "images": ["/some/images.jpg"], "positive_messages": [[{"role": "assistant", "content": "<image>relevant_doc1"}]], "positive_images": [["/some/positive_images.jpg"]], "negative_messages": [[{"role": "assistant", "content": "<image><image>irrelevant_doc1"}], [{"role": "assistant", "content": "<image>irrelevant_doc2"}]], "negative_images": [["/some/negative_images1.jpg", "/some/negative_images2.jpg"], ["/some/negative_images3.jpg"]]}
+```
+
+**字段说明：**
+- `messages`：查询文本
+- `positive_messages`：与查询相关的正例文档列表，支持多个正例
+- `negative_messages`：与查询不相关的负例文档列表，支持多个负例
+
+**环境变量配置：**
+- `MAX_POSITIVE_SAMPLES`：每个query的最大正例数量（默认：1）
+- `MAX_NEGATIVE_SAMPLES`：每个query的最大负例数量（默认：7）
+
+> 默认会从每条数据中取出`MAX_POSITIVE_SAMPLES`条正样本和`MAX_NEGATIVE_SAMPLES`条负样本，每条正样本会和`MAX_NEGATIVE_SAMPLES`条负样本组成一个group，因此每条数据会扩展成`MAX_POSITIVE_SAMPLES`x`(1 + MAX_NEGATIVE_SAMPLES)`条数据。
+> 如果数据中正例/负例数量不足，会取全部正例/负例，如果数据中正例和负例数量超过`MAX_POSITIVE_SAMPLES`和`MAX_NEGATIVE_SAMPLES`，会进行随机采样。
+> **IMPORTANT**：展开后的数据会放在同一个batch中，因此每个设备上的实际批处理大小（effective batch size）将是 `per_device_train_batch_size` × `MAX_POSITIVE_SAMPLES` × (1 + `MAX_NEGATIVE_SAMPLES`)。请注意调整 `per_device_train_batch_size` 以避免显存不足。
+
+## 脚手架
+
+SWIFT提供的脚手架训练脚本：
+
+- [Qwen3-Reranker/Qwen3-VL-Reranker](https://github.com/modelscope/ms-swift/blob/main/examples/train/reranker/qwen3)
+- [Pointwise分类式Reranker](https://github.com/modelscope/ms-swift/blob/main/examples/train/reranker/train_reranker.sh)
+- [Pointwise生成式Reranker](https://github.com/modelscope/ms-swift/blob/main/examples/train/reranker/train_generative_reranker.sh)
+- [Listwise分类式Reranker](https://github.com/modelscope/ms-swift/blob/main/examples/train/reranker/train_reranker_listwise.sh)
+- [Listwise生成式Reranker](https://github.com/modelscope/ms-swift/blob/main/examples/train/reranker/train_generative_reranker_listwise.sh)
+
+推理脚本参考[这里](https://github.com/modelscope/ms-swift/blob/main/examples/infer/demo_reranker.py)。
+
+## 高级功能
+
+- Qwen3-Reranker 自定义 Instruction：
+  - 默认模板如下：
+
+```text
+<|im_start|>system
+Judge whether the Document meets the requirements based on the Query and the Instruct provided. Note that the answer can only be "yes" or "no".<|im_end|>
+<|im_start|>user
+<Instruct>: {Instruction}
+<Query>: {Query}
+<Document>: {Document}<|im_end|>
+<|im_start|>assistant
+<think>
+
+</think>
+
+
+```
+
+- 默认 Instruction：
+  - `Given a web search query, retrieve relevant passages that answer the query`
+
+- Instruction 优先级（就近覆盖）：
+  - `positive_messages`/`negative_messages` 内提供的 `system` > 主 `messages` 的 `system` > 默认 Instruction。
+  - 即：若某个 positive/negative 的消息序列内包含 `system`，则优先使用该条；否则若主 `messages` 含 `system` 则使用之；两者都未提供时，使用默认 Instruction。
@@ -0,0 +1,259 @@
+# DeepSeek-V4 训练支持
+
+
+目前Megatron-SWIFT支持了DeepSeek-V4的微调与RL支持，包括MTP、FP8等特性。（FP4 blockwise训练暂时不支持，会在加载权重时自动转成FP8/BF16）
+
+你需要使用Megatron-Core dev分支以及mcore-bridge、ms-swift main分支。
+
+```shell
+pip install git+https://github.com/NVIDIA/Megatron-LM.git@dev
+pip install git+https://github.com/modelscope/mcore-bridge.git
+pip install git+https://github.com/modelscope/ms-swift.git
+
+# Megatron-LM在以下commit hash下进行测试
+# pip install git+https://github.com/NVIDIA/Megatron-LM.git@c6449f0b23be397449f21c0967c5fc90785e55ea
+```
+
+## 精度对齐
+
+- 为了支持精度对齐测试（FP32），你需注释掉[这几行](https://github.com/NVIDIA/Megatron-LM/blob/bd381ac364b5139840f0cba6389db54f2c092e90/megatron/core/transformer/experimental_attention_variant/dsa.py#L41-L43)。
+
+修改完代码后，测试以下代码，确认无精度对齐问题（测试transformers/megatron forward对齐情况）：
+
+创建mini版本的模型，我们将创建4层：
+
+```python
+import os
+import torch
+from modelscope.hub.file_download import model_file_download
+from safetensors.torch import safe_open
+from swift import safe_snapshot_download
+
+from mcore_bridge.utils import Fp8Dequantizer, SafetensorLazyLoader, StreamingSafetensorSaver
+
+model_id = 'deepseek-ai/DeepSeek-V4-Flash-Base'
+# Some models have the first few layers as dense and the rest as MoE; set this value accordingly
+model_dir = safe_snapshot_download(model_id, download_model=False)
+
+loader = SafetensorLazyLoader(model_dir)
+state_dict = loader.get_state_dict()
+saver = StreamingSafetensorSaver(save_dir=model_dir)
+fp8_dequantizer = Fp8Dequantizer()  # Used to convert fp8 weights to bf16
+
+
+def _open_file(self, filename: str):
+    if filename not in self._file_handles:
+        file_path = os.path.join(self.hf_model_dir, filename)
+        tmp_dir = os.path.join(self.hf_model_dir, 'tmp')
+        if not os.path.exists(file_path):
+            file_path = os.path.join(tmp_dir, filename)
+        if not os.path.exists(file_path):
+            file_path = model_file_download(
+                model_id=model_id,
+                file_path=filename,
+                local_dir=tmp_dir,
+            )
+        self._file_handles[filename] = safe_open(file_path, framework='pt')
+    return self._file_handles[filename]
+
+
+SafetensorLazyLoader._open_file = _open_file  # monkey patch (lazy downloading)
+new_state_dict = {}
+for k, v in state_dict.items():
+    if k.startswith('layers.'):
+        idx = int(k[len('layers.'):].split('.', 1)[0])
+        if idx >= 4:
+            continue
+    if k.endswith('.scale'):
+        continue
+    elif k.endswith('.weight'):
+        weight_scale_inv = k.replace('.weight', '.scale')
+        if weight_scale_inv in state_dict:
+            v = fp8_dequantizer.convert(v.load(), state_dict[weight_scale_inv].load()).to(torch.bfloat16)
+    new_state_dict[k] = v if isinstance(v, torch.Tensor) else v.load()
+
+for k, v in new_state_dict.items():
+    saver.add_tensor(k, v)
+saver.finalize()
+```
+然后修改`config.json`：
+- num_hidden_layers修改为`4`。
+- compress_ratios修改为`[0, 0, 4, 128, 0]`。
+- 删除`quantization_config`。
+
+
+然后创建`test.py`，使用以下命令运行：`CUDA_VISIBLE_DEVICES=0,1,2,3 torchrun --nproc_per_node=4 test.py`。更多参考[自定义Megatron模型文档](https://swift.readthedocs.io/zh-cn/latest/Megatron-SWIFT/Custom-Model.html)。
+
+```python
+import os
+
+os.environ['SWIFT_TEST_CONVERT_PRECISION'] = '1'
+
+from swift.megatron import MegatronExportArguments, megatron_export_main
+from swift import safe_snapshot_download
+model_id = 'deepseek-ai/DeepSeek-V4-Flash-Base'
+
+model_dir = safe_snapshot_download(model_id, download_model=False)
+
+if __name__ == '__main__':
+    megatron_export_main(
+        MegatronExportArguments(
+            model=model_dir,
+            to_mcore=True,
+            attention_backend='flash',
+            tensor_model_parallel_size=1,
+            pipeline_model_parallel_layout='Et*3|t*1mL',
+            pipeline_model_parallel_size=2,
+            expert_model_parallel_size=2,
+            mtp_num_layers=1,
+            test_convert_precision=True,
+        ))
+```
+
+当出现以下结果时，则表示对齐没有问题，可以进行训练了。
+![精度对齐](../../resources/deepseek_v4/precision.png)
+
+
+## LoRA训练
+
+BF16精度LoRA训练脚本如下，最后会保存LoRA增量权重和Merge-LoRA后的BF16完整权重。
+
+```shell
+PYTORCH_CUDA_ALLOC_CONF='expandable_segments:True' \
+NPROC_PER_NODE=8 \
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+megatron sft \
+    --model deepseek-ai/DeepSeek-V4-Flash \
+    --save_safetensors true \
+    --dataset 'AI-ModelScope/alpaca-gpt4-data-zh#1000' \
+              'AI-ModelScope/alpaca-gpt4-data-en#1000' \
+              'swift/self-cognition#1000' \
+    --model_author swift \
+    --model_name swift-robot \
+    --merge_lora true \
+    --load_from_cache_file true \
+    --add_non_thinking_prefix true \
+    --loss_scale ignore_empty_think \
+    --split_dataset_ratio 0.01 \
+    --tuner_type lora \
+    --lora_rank 16 \
+    --lora_alpha 32 \
+    --tensor_model_parallel_size 1 \
+    --expert_model_parallel_size 8 \
+    --micro_batch_size 4 \
+    --global_batch_size 32 \
+    --padding_free false \
+    --group_by_length true \
+    --recompute_granularity full \
+    --recompute_method uniform \
+    --recompute_num_layers 1 \
+    --moe_permute_fusion true \
+    --moe_grouped_gemm true \
+    --moe_shared_expert_overlap true \
+    --moe_aux_loss_coeff 1e-3 \
+    --num_train_epochs 1 \
+    --finetune true \
+    --cross_entropy_loss_fusion true \
+    --lr 1e-4 \
+    --lr_warmup_fraction 0.05 \
+    --min_lr 1e-5 \
+    --output_dir megatron_output/DeepSeek-V4-Flash \
+    --eval_steps 200 \
+    --save_steps 200 \
+    --max_length 4096 \
+    --dataloader_num_workers 8 \
+    --dataset_num_proc 8 \
+    --no_save_optim true \
+    --no_save_rng true \
+    --sequence_parallel true \
+    --mtp_num_layers 1 \
+    --attention_backend flash
+```
+
+显存占用：
+![显存占用](../../resources/deepseek_v4/memory.png)
+
+
+训练日志与损失：
+![loss](../../resources/deepseek_v4/loss.png)
+
+提示：
+- 如果你要设置pp并行，你需要额外设置`pipeline_model_parallel_layout`。例如：
+```
+--pipeline_model_parallel_size 2 \
+--pipeline_model_parallel_layout 'Et*22|t*21mL' \
+```
+- 全参数训练也是支持的，你需要降低learning_rate，并提高并行数。参考64卡训练例子：
+```
+--lr 1e-5 \
+--min_lr 1e-6 \
+--tensor_model_parallel_size 1 \
+--expert_model_parallel_size 8 \
+--pipeline_model_parallel_size 8 \
+--pipeline_model_parallel_layout Et*5|t*5|t*6|t*6|t*6|t*5|t*5|t*5mL \
+```
+- Packing/CP的支持：需安装mcore-bridge/ms-swift main分支。参考这两个PR：[ms-swift#9705](https://github.com/modelscope/ms-swift/pull/9705)、[mcore-bridge#140](https://github.com/modelscope/mcore-bridge/pull/140)。若要使用CP，你需要额外设置（需结合packing一起使用`--packing true`，并注意这个PR的合并[megatron-core#5706](https://github.com/NVIDIA/Megatron-LM/pull/5706)）：
+```
+--sequence_packing_scheduler dp_balanced \
+--cp_partition_mode contiguous \
+```
+- 暂时不支持TP，待Megatron-Core支持。
+- FP8训练：你可以设置以下参数开启FP8训练，并最终将权重保存成FP8权重。推荐使用全参数训练。如果要使用LoRA + FP8，你需要只保存LoRA权重（设置`--merge_lora false`），并使用BF16权重进行Merge-LoRA（FP8 精度有限，LoRA delta 会被舍入为 0）。参考[这个例子](https://github.com/modelscope/ms-swift/blob/main/examples/megatron/fp8/lora.sh)。
+```
+--fp8_recipe blockwise \
+--fp8_format e4m3 \
+--fp8_param_gather true \
+```
+
+推理训练后的模型：
+
+```shell
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+swift infer \
+    --model megatron_output/DeepSeek-V4-Flash/vx-xxx/checkpoint-xxx-merged \
+    --infer_backend transformers \
+    --enable_thinking false \
+    --max_new_tokens 2048
+```
+
+推理结果：
+
+![result](../../resources/deepseek_v4/infer_result.png)
+
+跑通vLLM推理：
+
+- 如果要使用vllm推理，你可以参考[这里的文档](https://recipes.vllm.ai/deepseek-ai/DeepSeek-V4-Flash)。你需要FP4/FP8精度的权重。
+- 此外你需要copy原始的'config.json'文件，并修改'expert_dtype'（与训练后的config.json一致）。因为，使用transformers的`config.save_pretrained`保存的文件与原始文件不同，vllm不兼容保存后的文件。
+- 如果遇到tilelang问题，可以查看[这个issue](https://github.com/modelscope/ms-swift/issues/9494)。
+- mcore-bridge DeepSeek-V4 Fp8修复：[PR](https://github.com/modelscope/mcore-bridge/pull/133)。
+
+这里先做量化（这里的量化会导致LoRA增量信息丢失，这里只作为例子，建议使用FP8全参数训练并导出FP8权重）：
+
+```shell
+CUDA_VISIBLE_DEVICES=0,1,2,3,4,5,6,7 \
+NPROC_PER_NODE=8 \
+megatron export \
+    --model megatron_output/DeepSeek-V4-Flash/vx-xxx/checkpoint-xxx-merged \
+    --output_dir megatron_output/DeepSeek-V4-Flash/vx-xxx/checkpoint-xxx-merged-FP8 \
+    --to_hf true \
+    --fp8_recipe blockwise \
+    --fp8_format e4m3 \
+    --fp8_param_gather true \
+    --mtp_num_layers 1 \
+    --expert_model_parallel_size 8
+```
+
+vLLM启动命令：
+```shell
+vllm serve megatron_output/DeepSeek-V4-Flash/vx-xxx/checkpoint-xxx-merged-FP8 \
+    --trust-remote-code \
+    --kv-cache-dtype fp8 \
+    --block-size 256 \
+    --enable-expert-parallel \
+    --tensor-parallel-size 8 \
+    --max-model-len 8192 \
+    --tokenizer-mode deepseek_v4 \
+    --tool-call-parser deepseek_v4 \
+    --enable-auto-tool-choice \
+    --reasoning-parser deepseek_v4
+```