尧图网站建设 
用 Axolotl 微调 Google Gemma 4QLoRA 实战、混合注意力与 MoE 专家量化指南【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotlGemma 4 是 Google 发布的多模态模型家族覆盖 26B-A4B MoE、31B Dense 与 E2B 等形态。本文以仓库中 examples/gemma4/README.md 为骨架完整讲解如何在 Axolotl 上对 Gemma 4 各成员做 LoRA/QLoRA 微调从环境准备、三条可直接运行的示例命令到gemma4_hybrid_attn_impl混合注意力与 MoE 专家量化/专家 LoRA 的底层原理并结合源码给出可复制的完整配置。读完你将掌握 Gemma 4 在单卡 80GB 显存下的微调方案、注意力后端选型依据以及针对多模态模型的 LoRA 目标定位技巧。Gemma 4 家族与仓库中的示例矩阵Gemma 4 是 Google 的多模态模型家族包含不同架构形态的成员。Axolotl 仓库在 examples/gemma4/ 目录下为每个成员准备了可直接运行的微调配置示例配置模型架构单卡显存参考适配器26b-a4b-moe-qlora.yamlgoogle/gemma-4-26B-A4B26B 总参、4B 激活的 MoE1×80GBQLoRA MoE 专家量化31b-qlora.yamlgoogle/gemma-4-31B31B Dense1×80GB约 25.2 GiBQLoRAe2b-vision-lora.yamlgoogle/gemma-4-E2B-itE2B 多模态视觉1×80GB约 10.4 GiBLoRA26b-a4b-moe-nvfp4-lora.yamlnvidia/Gemma-4-26B-A4B-NVFP4MoE NVFP4 预量化检查点单卡sm120LoRA此外examples/gemma4-unified/ 目录还覆盖了 Gemma 4 Unified12B 无编码器多模态成员的文本与视觉 LoRA 配置其注意力与 LoRA 定位的注意事项与主目录完全一致可一并参考。这些模型共享两个关键架构特征也是后续配置中所有特殊处理的根源混合滑动/全局注意力解码器层交替使用 sliding-window attention 与 globalfullattention其中全局层的global_head_dim512多模态结构文本骨干之外还有视觉/音频编码器且部分模型存在 KV-sharing 层。快速开始三步跑通 Gemma 4 微调第一步安装 Axolotl按仓库 docs/installation.qmd 中的指引安装 Axolotl当前仓库为源码形态亦可通过 pip 安装axolotl包。第二步安装 Cut Cross EntropyCut Cross EntropyCCE是降低训练显存占用的关键依赖官方将其作为自定义集成的推荐项详见 docs/custom_integrations.qmd 中关于 Cut Cross Entropy 的说明。它的原理是在计算交叉熵损失时避免物化完整的 logits 张量对sequence_len2048、sample_packing: true这类大 batch 场景的显存收益非常明显。仓库内还提供了便捷安装脚本 scripts/cutcrossentropy_install.py。第三步运行微调示例# 26B MoE QLoRA1×80GB axolotl train examples/gemma4/26b-a4b-moe-qlora.yaml # 31B Dense QLoRA1×80GB约 25.2 GiB axolotl train examples/gemma4/31b-qlora.yaml # E2B 视觉 LoRA1×80GB约 10.4 GiB axolotl train examples/gemma4/e2b-vision-lora.yamlaxolotl train config是 CLI 的统一入口配置文件中所有参数均可被命令行覆盖如--micro_batch_size具体 CLI 用法可参考 docs/cli.qmd。配置逐项拆解以 26B-A4B MoE QLoRA 为例26b-a4b-moe-qlora.yaml 是仓库中信息量最大的 Gemma 4 配置几乎涵盖本节所有主题逐块解读如下。插件与内核栈plugins: - axolotl.integrations.cut_cross_entropy.CutCrossEntropyPlugin - axolotl.integrations.kernels.KernelsPlugin - axolotl.integrations.liger.LigerPlugin use_kernels: true use_scattermoe: true experts_implementation: scattermoe torch_compile: true liger_layer_norm: true liger_rope: true liger_rms_norm: true liger_glu_activation: true liger_rms_norm_gated: true strict: falseCutCrossEntropyPlugin损失计算层使用 CCE降低显存KernelsPlugin use_kernels: true启用 Axolotl 内核库FA2 hub 内核、融合 LoRA 内核等LigerPlugin 系列liger_*开关将 LayerNorm/RMSNorm/RoPE/GLU 激活等算子替换为 Liger Kernel 的融合实现同时降低显存与提升吞吐use_scattermoe: trueexperts_implementation: scattermoeMoE 专家层走 ScatterMoE 内核。从 src/axolotl/integrations/kernels/args.py 的校验逻辑check_experts_implementation可以看到experts_implementation: scattermoe必须搭配use_scattermoe: true否则会被静默回退为eager同理sonicmoe需要use_sonicmoe: true二者不能同时开启。数据与聊天模板chat_template: gemma4 eot_tokens: - turn| datasets: - path: mlabonne/FineTome-100k type: chat_template split: train[:10%] field_messages: conversations message_property_mappings: role: from content: value val_set_size: 0.05 output_dir: ./outputs/gemma4-26b-a4b-qlora sequence_len: 2048 sample_packing: truechat_template: gemma4是仓库内置的 Gemma 4 对话模板E2B 与 Unified 配置分别使用gemma4/gemma4_unifiedeot_tokens补充序列结束 tokenturn|数据集使用 OpenAI Messages 格式type: chat_template通过field_messages与message_property_mappings将数据集字段映射到 role/content。完整字段映射说明见 docs/dataset-formats/conversation.qmdsample_packing: true将多轮对话按sequence_len打包填充是吞吐的关键但它要求注意力实现支持 packing 感知的 block-diagonal mask见下文混合注意力一节。LoRA 目标用正则锁定文本骨干多模态模型的 LoRA 定位是最容易踩坑的点示例配置给出了标准答案load_in_4bit: true quantize_moe_experts: true adapter: qlora lora_r: 16 lora_alpha: 32 lora_dropout: 0 lora_target_modules: model.language_model.layers.[\d].(_checkpoint_wrapped_module.)?(mlp|self_attn).(up|down|gate|q|k|v|o)_projadapter: qloraload_in_4bit: true4-bit NF4 量化 LoRAlora_target_modules使用正则model.language_model.layers.[\d].(_checkpoint_wrapped_module.)?(mlp|self_attn).(up|down|gate|q|k|v|o)_proj只匹配文本解码器的注意力与 MLP 投影层从而跳过视觉/音频编码器同时兼容 FSDP 检查点包装前缀_checkpoint_wrapped_module.。这是 README 明确强调的做法lora_target_linear对多模态模型不兼容必须改用lora_target_modules正则。MoE 专家 LoRA3D 参数张量lora_target_parameters: - experts.gate_up_proj - experts.down_proj与经典 MoE 不同Gemma 4 的专家权重在 transformers v5 中是融合的 3Dnn.Parameter张量而非nn.Linear。lora_target_parameters通过名称后缀匹配直接在 3D 专家张量上挂载 LoRAexperts.gate_up_proj与experts.down_proj。融合 LoRA 内核lora_mlp_kernel: true lora_qkv_kernel: true lora_o_kernel: true fused_attn_kernel: true这三类开关把非专家路径的 LoRA 计算融合进内核lora_mlp_kernel融合文本骨干的共享 MLPGemma4TextMLPlora_qkv_kernel/lora_o_kernel融合注意力 q/k/v/o 投影fused_attn_kernel让 qkv/o 能挂载到 unified 变体上。被路由的专家层由 ScatterMoE 处理这些内核负责其余逐层 LoRA 的加速。注意 README 的 Limitations 明确指出LoRA kernels 不适用于含 KV-sharing 层的模型。训练超参与显存优化gradient_accumulation_steps: 4 micro_batch_size: 1 num_epochs: 1 optimizer: adamw_torch_8bit lr_scheduler: cosine learning_rate: 0.0002 bf16: auto tf32: true gradient_checkpointing: true activation_offloading: true logging_steps: 1 warmup_ratio: 0.1 evals_per_epoch: 4 saves_per_epoch: 1 weight_decay: 0.0optimizer: adamw_torch_8bit、gradient_checkpointingactivation_offloading激活换出到 CPU共同把单卡显存压到 80GB 以内bf16: autotf32: true使用混合精度warmup_ratio: 0.1、evals_per_epoch: 4、saves_per_epoch: 1控制预热、评估与保存节奏。多卡DDP注意事项ddp_find_unused_parameters: true配置注释解释得很清楚LoRA 只作用于文本骨干冻结的视觉/音频编码器与 Gemma 4 的 KV-sharing 层会导致部分适配器参数没有梯度DDP 下会报 parameters that were not used in producing loss。ddp_find_unused_parameters: true正是为此而设单卡运行无影响。混合注意力gemma4_hybrid_attn_impl的原理与源码这是 Gemma 4 微调中最关键的显存/吞吐开关README 给出的 TIPS 是在 31B 上开启gemma4_hybrid_attn_impl: true比flex_attention快约 2 倍约 25.2 GiB 显存、开启 packing同时规避 flex 的head_dim512内核在 Blackwell 上耗尽共享内存sm120 OOM的问题。为什么需要混合注意力Flash Attention 对 head_dim 有硬上限FA2 最高 256、FA4 最高 128都无法直接服务 Gemma 4 全局层的global_head_dim512。因此 README 给出两条可选路线flex_attention对 packing 场景可行但head_dim512的 flex 内核在 Blackwellsm120上可能 OOM且吞吐较低gemma4_hybrid_attn_impl: true滑动窗口层用 FA2、全局层用 packing 感知的 SDPA——这是示例配置实际采用并验证过的路线。配置校验与自动补全在 src/axolotl/utils/schemas/config.py 中该参数被描述为对 Gemma 4 使用混合注意力滑动窗口层用 flash_attention_2全局full_attention层用 sdpa全局层 head_dim512 超出 Flash Attention 支持范围。配置加载时的校验逻辑同文件 config.py非常严格若用户只开了gemma4_hybrid_attn_impl而未指定attn_implementation会自动补全为flash_attention_2若用户显式指定了非flash_attention_2的注意力后端会直接抛ValueError因为滑动窗口层必须在 FA2 下运行。所以示例配置中的这两行是配套的attn_implementation: flash_attention_2 gemma4_hybrid_attn_impl: true且要求本机存在适配当前 GPU 架构的 flash-attn 构建README 明确提到requires a flash-attn build for your GPU arch。源码实现按 layer_types 逐层打补丁混合注意力在模型加载后由 src/axolotl/loaders/patch_manager.py 中的_apply_gemma_hybrid_attention实现通过patch_gemma4_hybrid_mask()安装全局层 packing 感知的 SDPAGLOBAL_PACKED_SDPA并设置 large-head 策略为默认sdpa在模型结构中定位layers多模态封装走model.language_model.layers纯文本的Gemma4ForCausalLM走model.layers读取模型配置的layer_types若缺失则跳过并告警该特性要求模型确为滑动/全局混合注意力结构逐层遍历对非sliding_attention的全局层将其self_attn.config._attn_implementation改写为GLOBAL_PACKED_SDPA并计数。日志会打印 patched %d global layers to use packing-aware SDPA (remaining %d sliding layers use flash_attention_2)。源码注释还解释了一个关键细节如果不打这个补丁仅靠逐层 SDPA 配置覆盖是不够的——Gemma4TextModel.forward仍会在模型层面构造 2D FA2 格式的 mask长上下文下 SDPA 层会因 mask 形状不匹配而崩溃RuntimeError: The expanded size of the tensor ... must match。打包感知的 SDPA 会基于position_ids重建 block-diagonal mask确保在sample_packing: true时各文档不会跨包互相 attend。纯文本 31B 与 NVFP4 变体31b-qlora.yaml 与 26b-a4b-moe-nvfp4-lora.yaml 同样使用attn_implementation: flash_attention_2gemma4_hybrid_attn_impl: true组合NVFP4 变体在注释中再次强调 flex_attention 在 sm120 上 OOM故采用 FA2滑动 SDPA全局的混合方案。NVFP4 检查点的专家权重本身就是 4-bit 打包存储dsv4_fp4_grouped_mode: nvfp4因此该配置不需要quantize_moe_experts改用普通adapter: lora。仓库 docs/nvfp4_lora.qmd 对该路线有完整说明。MoE 专家量化与专家 LoRA26B-A4B26B-A4B 配置在加载时通过 ScatterMoE 内核经 transformers 的ExpertsInterface对专家权重做量化。该机制的前因后果记录在仓库文档 docs/expert_quantization.qmd 中要点如下。为什么需要quantize_moe_expertstransformers v5 将 MoE 专家层从nn.Linear改为融合的 3Dnn.Parameter张量导致 bitsandbytes 无法在模型加载阶段直接量化它们——如果不加处理所有专家权重都会以完整 bf16 精度驻留显存QLoRA 的显存优势荡然无存。quantize_moe_experts: true在加载时拦截权重装载过程对每个专家张量即时量化并立即释放原始 bf16 张量从而大幅压低峰值显存该文档以 GLM-4.7-Flash 为例说明 QLoRA 显存从约 127GiB 降到约 23GiBGemma 4 同样受益于此机制。源码实现量化由 src/axolotl/monkeypatch/moe_quant.py 中的patch_moe_quantization_on_load完成它 patch transformers 的权重加载当检测到名称含 expert 的 3D CUDA 张量时4-bit 模式QLoRA使用 bitsandbytes NF4 参数化可用bnb_4bit_quant_type调整量化类型8-bit 模式LoRA使用自定义的按行 int8 参数化replace_parameter_8bitint8_vectorwise_dequant并在前向时缓存反量化值。同时该模块还 patch 了 PEFT 的_inject_parameterspatch_peft_target_parameters_matching使lora_target_parameters能对已参数化的量化专家张量做名称后缀匹配并挂载 LoRA同时避免将量化专家参数误包装进 LoRA。配套显存调优开关对于 4-bit 量化的 MoE 专家没有现成的融合 4-bit 读取内核默认走 1-launch 的parallel_linear路径把专家反量化为 bf16 参与计算反量化结果在反向时重算、不保存因此保持低显存。针对大专家 MoE 或小显存 GPU配置中预留了两个可调项默认注释关闭# moe_bnb_fast: false # moe_dequant_chunk_size: 32moe_bnb_fast: false回退到分块chunked路径moe_dequant_chunk_size限制单次反量化的临时显存。这两项在 src/axolotl/integrations/kernels/libs/scattermoe_lora/runtime.py 与 chunked_bnb.py 中被读取并写入运行时配置RUNTIME.dequant_chunk_size、fast标志。使用前提与限制依据 docs/expert_quantization.qmd必须满足adapter: qloraload_in_4bit: true或adapter: loraload_in_8bit: true仅限 CUDA GPU未在 ROCm 等后端测试FSDP2 分布式训练兼容lora_dropout在使用lora_target_parameters时必须为 0示例配置正是lora_dropout: 0lora_target_linear与quantize_moe_experts不兼容需改用专家 LoRA 目标定位即lora_target_parameters。E2B 视觉 LoRA多模态微调要点e2b-vision-lora.yaml 展示了多模态视觉微调的完整姿势processor_type: AutoProcessor freeze_mm_modules: true skip_prepare_dataset: true remove_unused_columns: false sample_packing: falseprocessor_type: AutoProcessor加载多模态处理器freeze_mm_modules: true冻结视觉编码器等多模态模块只训练文本骨干的 LoRAskip_prepare_dataset: trueremove_unused_columns: false多模态训练必需跳过常规数据集准备流程视觉数据需保留像素值等非文本列sample_packing: false多模态训练关闭序列打包打包与多模态数据的对齐不兼容注意力后端用attn_implementation: sdpaE2B 示例为简化配置未开启混合注意力LoRA 目标与前面完全一致的正则model.language_model.layers...锁定文本骨干。多模态数据集格式OpenAI multi-content Messages与文本格式的差异见 docs/multimodal.qmd。Gemma 4 Unified 的 12b-vision-lora.yaml 采用完全相同的模式。限制清单与规避方案综合 examples/gemma4/README.md 与 examples/gemma4-unified/README.mdGemma 4 微调有三个公认限制Flash Attention 无法独立服务全局层FA2head_dim≤256与 FA4head_dim≤128均无法承载global_head_dim512。方案二选一flex_attention或gemma4_hybrid_attn_impl: true滑动层走 FA2、全局层走 SDPA需attn_implementation: flash_attention_2与对应 GPU 架构的 flash-attn 构建。在sample_packing: true时必须使用 packing 安全的实现混合注意力的GLOBAL_PACKED_SDPA或 flex_attention否则跨文档 attend 会污染训练信号LoRA 内核不支持 KV-sharing 层含 KV-sharing 的模型不能启用融合 LoRA 内核需评估保留默认路径的显存/吞吐代价lora_target_linear对多模态模型不兼容必须使用lora_target_modules正则将 LoRA 限制在文本骨干。进阶提示从 QLoRA 到全参微调与更多优化全参微调FFT从配置中移除adapter: qlora、load_in_4bit: true与quantize_moe_experts: true即可。README 特别提醒全参训练显存与算力开销巨大该路径未经测试请自行评估硬件条件自备数据集将datasets段替换为你的数据即可字段映射与多模态格式分别参考 docs/dataset_loading.qmd 与 docs/dataset-formats/conversation.qmd进一步优化混合注意力、梯度检查点/激活卸载、8-bit 优化器、Liger 内核只是起点。更多显存与吞吐优化手段见 docs/optimizations.qmd分布式训练方案见 docs/multi-gpu.qmd 与 docs/fsdp_qlora.qmd仓库级佐证混合注意力的逐层补丁逻辑在 src/axolotl/loaders/patch_manager.py参数校验在 src/axolotl/utils/schemas/config.py 与同文件 config.py专家量化实现见 src/axolotl/monkeypatch/moe_quant.py对应测试可在 tests/monkeypatch/test_gemma4_hybrid_mask.py、tests/monkeypatch/test_gemma4_unified_fused_attn.py 与 tests/integrations/test_scattermoe_lora.py 中找到可作为理解与复现上述行为的起点。【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 用 Axolotl 微调 Google Gemma 4：QLoRA 实战、混合注意力与 MoE 专家量化指南
用 Axolotl 微调 Google Gemma 4QLoRA 实战、混合注意力与 MoE 专家量化指南【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotlGemma 4 是 Google 发布的多模态模型家族覆盖 26B-A4B MoE、31B Dense 与 E2B 等形态。本文以仓库中 examples/gemma4/README.md 为骨架完整讲解如何在 Axolotl 上对 Gemma 4 各成员做 LoRA/QLoRA 微调从环境准备、三条可直接运行的示例命令到gemma4_hybrid_attn_impl混合注意力与 MoE 专家量化/专家 LoRA 的底层原理并结合源码给出可复制的完整配置。读完你将掌握 Gemma 4 在单卡 80GB 显存下的微调方案、注意力后端选型依据以及针对多模态模型的 LoRA 目标定位技巧。Gemma 4 家族与仓库中的示例矩阵Gemma 4 是 Google 的多模态模型家族包含不同架构形态的成员。Axolotl 仓库在 examples/gemma4/ 目录下为每个成员准备了可直接运行的微调配置示例配置模型架构单卡显存参考适配器26b-a4b-moe-qlora.yamlgoogle/gemma-4-26B-A4B26B 总参、4B 激活的 MoE1×80GBQLoRA MoE 专家量化31b-qlora.yamlgoogle/gemma-4-31B31B Dense1×80GB约 25.2 GiBQLoRAe2b-vision-lora.yamlgoogle/gemma-4-E2B-itE2B 多模态视觉1×80GB约 10.4 GiBLoRA26b-a4b-moe-nvfp4-lora.yamlnvidia/Gemma-4-26B-A4B-NVFP4MoE NVFP4 预量化检查点单卡sm120LoRA此外examples/gemma4-unified/ 目录还覆盖了 Gemma 4 Unified12B 无编码器多模态成员的文本与视觉 LoRA 配置其注意力与 LoRA 定位的注意事项与主目录完全一致可一并参考。这些模型共享两个关键架构特征也是后续配置中所有特殊处理的根源混合滑动/全局注意力解码器层交替使用 sliding-window attention 与 globalfullattention其中全局层的global_head_dim512多模态结构文本骨干之外还有视觉/音频编码器且部分模型存在 KV-sharing 层。快速开始三步跑通 Gemma 4 微调第一步安装 Axolotl按仓库 docs/installation.qmd 中的指引安装 Axolotl当前仓库为源码形态亦可通过 pip 安装axolotl包。第二步安装 Cut Cross EntropyCut Cross EntropyCCE是降低训练显存占用的关键依赖官方将其作为自定义集成的推荐项详见 docs/custom_integrations.qmd 中关于 Cut Cross Entropy 的说明。它的原理是在计算交叉熵损失时避免物化完整的 logits 张量对sequence_len2048、sample_packing: true这类大 batch 场景的显存收益非常明显。仓库内还提供了便捷安装脚本 scripts/cutcrossentropy_install.py。第三步运行微调示例# 26B MoE QLoRA1×80GB axolotl train examples/gemma4/26b-a4b-moe-qlora.yaml # 31B Dense QLoRA1×80GB约 25.2 GiB axolotl train examples/gemma4/31b-qlora.yaml # E2B 视觉 LoRA1×80GB约 10.4 GiB axolotl train examples/gemma4/e2b-vision-lora.yamlaxolotl train config是 CLI 的统一入口配置文件中所有参数均可被命令行覆盖如--micro_batch_size具体 CLI 用法可参考 docs/cli.qmd。配置逐项拆解以 26B-A4B MoE QLoRA 为例26b-a4b-moe-qlora.yaml 是仓库中信息量最大的 Gemma 4 配置几乎涵盖本节所有主题逐块解读如下。插件与内核栈plugins: - axolotl.integrations.cut_cross_entropy.CutCrossEntropyPlugin - axolotl.integrations.kernels.KernelsPlugin - axolotl.integrations.liger.LigerPlugin use_kernels: true use_scattermoe: true experts_implementation: scattermoe torch_compile: true liger_layer_norm: true liger_rope: true liger_rms_norm: true liger_glu_activation: true liger_rms_norm_gated: true strict: falseCutCrossEntropyPlugin损失计算层使用 CCE降低显存KernelsPlugin use_kernels: true启用 Axolotl 内核库FA2 hub 内核、融合 LoRA 内核等LigerPlugin 系列liger_*开关将 LayerNorm/RMSNorm/RoPE/GLU 激活等算子替换为 Liger Kernel 的融合实现同时降低显存与提升吞吐use_scattermoe: trueexperts_implementation: scattermoeMoE 专家层走 ScatterMoE 内核。从 src/axolotl/integrations/kernels/args.py 的校验逻辑check_experts_implementation可以看到experts_implementation: scattermoe必须搭配use_scattermoe: true否则会被静默回退为eager同理sonicmoe需要use_sonicmoe: true二者不能同时开启。数据与聊天模板chat_template: gemma4 eot_tokens: - turn| datasets: - path: mlabonne/FineTome-100k type: chat_template split: train[:10%] field_messages: conversations message_property_mappings: role: from content: value val_set_size: 0.05 output_dir: ./outputs/gemma4-26b-a4b-qlora sequence_len: 2048 sample_packing: truechat_template: gemma4是仓库内置的 Gemma 4 对话模板E2B 与 Unified 配置分别使用gemma4/gemma4_unifiedeot_tokens补充序列结束 tokenturn|数据集使用 OpenAI Messages 格式type: chat_template通过field_messages与message_property_mappings将数据集字段映射到 role/content。完整字段映射说明见 docs/dataset-formats/conversation.qmdsample_packing: true将多轮对话按sequence_len打包填充是吞吐的关键但它要求注意力实现支持 packing 感知的 block-diagonal mask见下文混合注意力一节。LoRA 目标用正则锁定文本骨干多模态模型的 LoRA 定位是最容易踩坑的点示例配置给出了标准答案load_in_4bit: true quantize_moe_experts: true adapter: qlora lora_r: 16 lora_alpha: 32 lora_dropout: 0 lora_target_modules: model.language_model.layers.[\d].(_checkpoint_wrapped_module.)?(mlp|self_attn).(up|down|gate|q|k|v|o)_projadapter: qloraload_in_4bit: true4-bit NF4 量化 LoRAlora_target_modules使用正则model.language_model.layers.[\d].(_checkpoint_wrapped_module.)?(mlp|self_attn).(up|down|gate|q|k|v|o)_proj只匹配文本解码器的注意力与 MLP 投影层从而跳过视觉/音频编码器同时兼容 FSDP 检查点包装前缀_checkpoint_wrapped_module.。这是 README 明确强调的做法lora_target_linear对多模态模型不兼容必须改用lora_target_modules正则。MoE 专家 LoRA3D 参数张量lora_target_parameters: - experts.gate_up_proj - experts.down_proj与经典 MoE 不同Gemma 4 的专家权重在 transformers v5 中是融合的 3Dnn.Parameter张量而非nn.Linear。lora_target_parameters通过名称后缀匹配直接在 3D 专家张量上挂载 LoRAexperts.gate_up_proj与experts.down_proj。融合 LoRA 内核lora_mlp_kernel: true lora_qkv_kernel: true lora_o_kernel: true fused_attn_kernel: true这三类开关把非专家路径的 LoRA 计算融合进内核lora_mlp_kernel融合文本骨干的共享 MLPGemma4TextMLPlora_qkv_kernel/lora_o_kernel融合注意力 q/k/v/o 投影fused_attn_kernel让 qkv/o 能挂载到 unified 变体上。被路由的专家层由 ScatterMoE 处理这些内核负责其余逐层 LoRA 的加速。注意 README 的 Limitations 明确指出LoRA kernels 不适用于含 KV-sharing 层的模型。训练超参与显存优化gradient_accumulation_steps: 4 micro_batch_size: 1 num_epochs: 1 optimizer: adamw_torch_8bit lr_scheduler: cosine learning_rate: 0.0002 bf16: auto tf32: true gradient_checkpointing: true activation_offloading: true logging_steps: 1 warmup_ratio: 0.1 evals_per_epoch: 4 saves_per_epoch: 1 weight_decay: 0.0optimizer: adamw_torch_8bit、gradient_checkpointingactivation_offloading激活换出到 CPU共同把单卡显存压到 80GB 以内bf16: autotf32: true使用混合精度warmup_ratio: 0.1、evals_per_epoch: 4、saves_per_epoch: 1控制预热、评估与保存节奏。多卡DDP注意事项ddp_find_unused_parameters: true配置注释解释得很清楚LoRA 只作用于文本骨干冻结的视觉/音频编码器与 Gemma 4 的 KV-sharing 层会导致部分适配器参数没有梯度DDP 下会报 parameters that were not used in producing loss。ddp_find_unused_parameters: true正是为此而设单卡运行无影响。混合注意力gemma4_hybrid_attn_impl的原理与源码这是 Gemma 4 微调中最关键的显存/吞吐开关README 给出的 TIPS 是在 31B 上开启gemma4_hybrid_attn_impl: true比flex_attention快约 2 倍约 25.2 GiB 显存、开启 packing同时规避 flex 的head_dim512内核在 Blackwell 上耗尽共享内存sm120 OOM的问题。为什么需要混合注意力Flash Attention 对 head_dim 有硬上限FA2 最高 256、FA4 最高 128都无法直接服务 Gemma 4 全局层的global_head_dim512。因此 README 给出两条可选路线flex_attention对 packing 场景可行但head_dim512的 flex 内核在 Blackwellsm120上可能 OOM且吞吐较低gemma4_hybrid_attn_impl: true滑动窗口层用 FA2、全局层用 packing 感知的 SDPA——这是示例配置实际采用并验证过的路线。配置校验与自动补全在 src/axolotl/utils/schemas/config.py 中该参数被描述为对 Gemma 4 使用混合注意力滑动窗口层用 flash_attention_2全局full_attention层用 sdpa全局层 head_dim512 超出 Flash Attention 支持范围。配置加载时的校验逻辑同文件 config.py非常严格若用户只开了gemma4_hybrid_attn_impl而未指定attn_implementation会自动补全为flash_attention_2若用户显式指定了非flash_attention_2的注意力后端会直接抛ValueError因为滑动窗口层必须在 FA2 下运行。所以示例配置中的这两行是配套的attn_implementation: flash_attention_2 gemma4_hybrid_attn_impl: true且要求本机存在适配当前 GPU 架构的 flash-attn 构建README 明确提到requires a flash-attn build for your GPU arch。源码实现按 layer_types 逐层打补丁混合注意力在模型加载后由 src/axolotl/loaders/patch_manager.py 中的_apply_gemma_hybrid_attention实现通过patch_gemma4_hybrid_mask()安装全局层 packing 感知的 SDPAGLOBAL_PACKED_SDPA并设置 large-head 策略为默认sdpa在模型结构中定位layers多模态封装走model.language_model.layers纯文本的Gemma4ForCausalLM走model.layers读取模型配置的layer_types若缺失则跳过并告警该特性要求模型确为滑动/全局混合注意力结构逐层遍历对非sliding_attention的全局层将其self_attn.config._attn_implementation改写为GLOBAL_PACKED_SDPA并计数。日志会打印 patched %d global layers to use packing-aware SDPA (remaining %d sliding layers use flash_attention_2)。源码注释还解释了一个关键细节如果不打这个补丁仅靠逐层 SDPA 配置覆盖是不够的——Gemma4TextModel.forward仍会在模型层面构造 2D FA2 格式的 mask长上下文下 SDPA 层会因 mask 形状不匹配而崩溃RuntimeError: The expanded size of the tensor ... must match。打包感知的 SDPA 会基于position_ids重建 block-diagonal mask确保在sample_packing: true时各文档不会跨包互相 attend。纯文本 31B 与 NVFP4 变体31b-qlora.yaml 与 26b-a4b-moe-nvfp4-lora.yaml 同样使用attn_implementation: flash_attention_2gemma4_hybrid_attn_impl: true组合NVFP4 变体在注释中再次强调 flex_attention 在 sm120 上 OOM故采用 FA2滑动 SDPA全局的混合方案。NVFP4 检查点的专家权重本身就是 4-bit 打包存储dsv4_fp4_grouped_mode: nvfp4因此该配置不需要quantize_moe_experts改用普通adapter: lora。仓库 docs/nvfp4_lora.qmd 对该路线有完整说明。MoE 专家量化与专家 LoRA26B-A4B26B-A4B 配置在加载时通过 ScatterMoE 内核经 transformers 的ExpertsInterface对专家权重做量化。该机制的前因后果记录在仓库文档 docs/expert_quantization.qmd 中要点如下。为什么需要quantize_moe_expertstransformers v5 将 MoE 专家层从nn.Linear改为融合的 3Dnn.Parameter张量导致 bitsandbytes 无法在模型加载阶段直接量化它们——如果不加处理所有专家权重都会以完整 bf16 精度驻留显存QLoRA 的显存优势荡然无存。quantize_moe_experts: true在加载时拦截权重装载过程对每个专家张量即时量化并立即释放原始 bf16 张量从而大幅压低峰值显存该文档以 GLM-4.7-Flash 为例说明 QLoRA 显存从约 127GiB 降到约 23GiBGemma 4 同样受益于此机制。源码实现量化由 src/axolotl/monkeypatch/moe_quant.py 中的patch_moe_quantization_on_load完成它 patch transformers 的权重加载当检测到名称含 expert 的 3D CUDA 张量时4-bit 模式QLoRA使用 bitsandbytes NF4 参数化可用bnb_4bit_quant_type调整量化类型8-bit 模式LoRA使用自定义的按行 int8 参数化replace_parameter_8bitint8_vectorwise_dequant并在前向时缓存反量化值。同时该模块还 patch 了 PEFT 的_inject_parameterspatch_peft_target_parameters_matching使lora_target_parameters能对已参数化的量化专家张量做名称后缀匹配并挂载 LoRA同时避免将量化专家参数误包装进 LoRA。配套显存调优开关对于 4-bit 量化的 MoE 专家没有现成的融合 4-bit 读取内核默认走 1-launch 的parallel_linear路径把专家反量化为 bf16 参与计算反量化结果在反向时重算、不保存因此保持低显存。针对大专家 MoE 或小显存 GPU配置中预留了两个可调项默认注释关闭# moe_bnb_fast: false # moe_dequant_chunk_size: 32moe_bnb_fast: false回退到分块chunked路径moe_dequant_chunk_size限制单次反量化的临时显存。这两项在 src/axolotl/integrations/kernels/libs/scattermoe_lora/runtime.py 与 chunked_bnb.py 中被读取并写入运行时配置RUNTIME.dequant_chunk_size、fast标志。使用前提与限制依据 docs/expert_quantization.qmd必须满足adapter: qloraload_in_4bit: true或adapter: loraload_in_8bit: true仅限 CUDA GPU未在 ROCm 等后端测试FSDP2 分布式训练兼容lora_dropout在使用lora_target_parameters时必须为 0示例配置正是lora_dropout: 0lora_target_linear与quantize_moe_experts不兼容需改用专家 LoRA 目标定位即lora_target_parameters。E2B 视觉 LoRA多模态微调要点e2b-vision-lora.yaml 展示了多模态视觉微调的完整姿势processor_type: AutoProcessor freeze_mm_modules: true skip_prepare_dataset: true remove_unused_columns: false sample_packing: falseprocessor_type: AutoProcessor加载多模态处理器freeze_mm_modules: true冻结视觉编码器等多模态模块只训练文本骨干的 LoRAskip_prepare_dataset: trueremove_unused_columns: false多模态训练必需跳过常规数据集准备流程视觉数据需保留像素值等非文本列sample_packing: false多模态训练关闭序列打包打包与多模态数据的对齐不兼容注意力后端用attn_implementation: sdpaE2B 示例为简化配置未开启混合注意力LoRA 目标与前面完全一致的正则model.language_model.layers...锁定文本骨干。多模态数据集格式OpenAI multi-content Messages与文本格式的差异见 docs/multimodal.qmd。Gemma 4 Unified 的 12b-vision-lora.yaml 采用完全相同的模式。限制清单与规避方案综合 examples/gemma4/README.md 与 examples/gemma4-unified/README.mdGemma 4 微调有三个公认限制Flash Attention 无法独立服务全局层FA2head_dim≤256与 FA4head_dim≤128均无法承载global_head_dim512。方案二选一flex_attention或gemma4_hybrid_attn_impl: true滑动层走 FA2、全局层走 SDPA需attn_implementation: flash_attention_2与对应 GPU 架构的 flash-attn 构建。在sample_packing: true时必须使用 packing 安全的实现混合注意力的GLOBAL_PACKED_SDPA或 flex_attention否则跨文档 attend 会污染训练信号LoRA 内核不支持 KV-sharing 层含 KV-sharing 的模型不能启用融合 LoRA 内核需评估保留默认路径的显存/吞吐代价lora_target_linear对多模态模型不兼容必须使用lora_target_modules正则将 LoRA 限制在文本骨干。进阶提示从 QLoRA 到全参微调与更多优化全参微调FFT从配置中移除adapter: qlora、load_in_4bit: true与quantize_moe_experts: true即可。README 特别提醒全参训练显存与算力开销巨大该路径未经测试请自行评估硬件条件自备数据集将datasets段替换为你的数据即可字段映射与多模态格式分别参考 docs/dataset_loading.qmd 与 docs/dataset-formats/conversation.qmd进一步优化混合注意力、梯度检查点/激活卸载、8-bit 优化器、Liger 内核只是起点。更多显存与吞吐优化手段见 docs/optimizations.qmd分布式训练方案见 docs/multi-gpu.qmd 与 docs/fsdp_qlora.qmd仓库级佐证混合注意力的逐层补丁逻辑在 src/axolotl/loaders/patch_manager.py参数校验在 src/axolotl/utils/schemas/config.py 与同文件 config.py专家量化实现见 src/axolotl/monkeypatch/moe_quant.py对应测试可在 tests/monkeypatch/test_gemma4_hybrid_mask.py、tests/monkeypatch/test_gemma4_unified_fused_attn.py 与 tests/integrations/test_scattermoe_lora.py 中找到可作为理解与复现上述行为的起点。【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考