使用 Axolotl 微调 Google Gemma-3n 多模态模型文本、视觉与音频的 QLoRA 完整实战指南【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotl导读Gemma-3n 是 Google 推出的多模态模型家族可同时处理文本、图像与音频输入。本文基于 Axolotl 仓库中 examples/gemma3n 目录下的官方示例完整讲解如何用 Axolotl 对 Gemma-3nE2B 变体进行 QLoRA 微调覆盖环境安装、依赖配置、三套示例配置纯文本 / 文本视觉 / 文本视觉音频的逐项解析、标签掩码与损失计算原理以及全参数微调、多卡扩展等进阶方向。读完本文你将能直接复现仓库给出的训练命令并能按自己的数据集改造出可运行的 Gemma-3n 微调配置。背景Gemma-3n 与 Axolotl 的适配现状Gemma-3n 是多模态模型家族同一基座既能处理文本也能融合图像与音频输入。在 Axolotl 中Gemma-3n 已获得一等支持chat_template: gemma3n是注册在 src/axolotl/utils/schemas/enums.py 中的合法取值对应的处理策略类Gemma3nProcessingStrategy定义在 src/axolotl/processing_strategies.py。从源码看Gemma-3n 的处理策略复用 Gemma3 的对话轮次边界识别逻辑并额外做了两件事通过_mask_non_assistant_keep只保留 assistant 回合用于计算损失在标签掩码中额外剔除image_token_id、audio_token_id、boi_token_id、eoi_token_id等视觉 / 音频边界 token避免模型在微调时被要求去“预测”图片与音频占位符。这一实现方式与 HuggingFace gemma-recipes 仓库中的fine_tune_gemma3n_on_t4notebook 保持一致processing_strategies.py。也就是说Axolotl 对 Gemma-3n 的适配不仅停留在“能跑通”还包括了符合官方训练惯例的损失掩码逻辑多模态微调时不会因视觉 / 音频 token 而污染语言建模目标。环境准备安装 Axolotl 与 Gemma-3n 附加依赖官方 README 给出的安装流程分为三步依次完成即可开始微调。1. 安装 Axolotl前提是环境中已有 PyTorch最低 2.9.1。使用 uv 从 pip 安装uv pip install --no-build-isolation axolotl0.16.1--no-build-isolation让构建过程复用当前环境中的依赖避免在隔离环境中重复编译是 Axolotl 官方推荐的安装方式。若尚未安装 uv可先参考仓库根目录的 README.md 与docs/installation.qmd获取完整的安装指引安装指南。2. 安装 Gemma-3n 的附加依赖在 Axolotl 基础依赖之上Gemma-3n 额外需要两样东西uv pip install timm1.0.17 # 用于加载音频数据 uv pip install librosa0.11.0timm1.0.17视觉骨干Vision Tower依赖的 PyTorch 图像模型库版本被锁定以匹配模型仓库期望的接口librosa0.11.0仅当你要训练包含音频的样本时才需要用于音频解码与特征提取。需要说明的是如果只做纯文本微调librosa 可以不装但 timm 是加载视觉编码器的必要条件。3. 下载示例数据集文件官方 README 提供了一个文本 视觉 音频的 2k 测试数据集供快速验证训练链路。音频与图像样本需要预先下载到本地训练脚本本身不负责下载媒体文件# 文本 视觉 音频 示例数据 wget https://huggingface.co/datasets/Nanobit/text-vision-audio-2k-test/resolve/main/African_elephant.jpg wget https://huggingface.co/datasets/Nanobit/text-vision-audio-2k-test/resolve/main/En-us-African_elephant.oga下载后的African_elephant.jpg与En-us-African_elephant.oga应放置在运行训练命令时的工作目录中因为对应的数据集 Nanobit/text-vision-audio-2k-test 的样本会引用这两个本地文件。三套示例配置从纯文本到多模态仓库 examples/gemma3n 目录下提供了三份 QLoRA 示例配置覆盖递增的模态复杂度配置文件训练模态数据集gemma-3n-e2b-qlora.yml纯文本cgato/SlimOrcaDedupCleanedgemma-3n-e2b-vision-qlora.yml文本 视觉HuggingFaceH4/llava-instruct-mix-vsftgemma-3n-e2b-vision-audio-qlora.yml文本 视觉 音频Nanobit/text-vision-audio-2k-test三份配置都基于base_model: google/gemma-3n-E2B-it即 Google 官方在 HuggingFace 发布的 E2B 指令微调版本。运行方式# 纯文本 axolotl train examples/gemma3n/gemma-3n-e2b-qlora.yml # 文本 视觉 axolotl train examples/gemma3n/gemma-3n-e2b-vision-qlora.yml # 文本 视觉 音频 axolotl train examples/gemma3n/gemma-3n-e2b-vision-audio-qlora.ymlaxolotl train是 Axolotl 的 CLI 入口负责加载 YAML 配置、构建数据集、装配模型与训练器并启动训练循环。三份配置的output_dir均为./outputs/out训练产物适配器、日志、checkpoint会写入该目录。纯文本 QLoRA 配置逐项解析以 gemma-3n-e2b-qlora.yml 为例逐段说明关键配置项的作用。基座模型与量化base_model: google/gemma-3n-E2B-it load_in_8bit: false load_in_4bit: true adapter: qloraload_in_4bit: true以 4-bit 量化加载基座权重配合adapter: qlora使用 QLoRA 方案是单卡微调多模态模型的关键省显存手段load_in_8bit: false明确关闭 8-bit 量化避免与 4-bit 冲突。损失优化插件plugins: - axolotl.integrations.cut_cross_entropy.CutCrossEntropyPlugin cut_cross_entropy: trueCut Cross EntropyCCE通过对交叉熵损失计算阶段进行优化来降低显存占用。该插件在 src/axolotl/integrations/cut_cross_entropy/README.md 中有完整说明其支持的模型列表中明确包含gemma3n与gemma3n_textREADME.md。也就是说这份纯文本配置之所以能开启 CCE正是因为它得到了官方插件的显式支持而多模态配置则因为需要处理图像 / 音频 token 而无法使用该优化。对话模板与 EOT tokenchat_template: gemma3n eot_tokens: - end_of_turnchat_template: gemma3n指定使用 Gemma-3n 的对话模板该取值注册于 enums.pyeot_tokens对话结束标记Gemma-3n 使用end_of_turn。数据集datasets: - path: cgato/SlimOrcaDedupCleaned type: chat_template split: train[:1%] field_messages: conversations message_property_mappings: role: from content: valuetype: chat_template使用聊天模板格式处理数据即按 OpenAI Messages 格式组织多轮对话split: train[:1%]只取训练集前 1% 作为快速验证样本完整训练时可去掉该切片field_messages: conversations指明对话字段名message_property_mappings将数据集字段映射到消息的role与contentSlimOrca 数据中分别是from与value字段。val_set_size: 0.0表示不划分验证集。LoRA 目标模块lora_r: 32 lora_alpha: 16 lora_dropout: 0.05 lora_target_modules: model.language_model.layers.[\d].(mlp|self_attn).(up|down|gate|q|k|v|o)_proj这是 Gemma-3n 微调中最重要的细节之一配置中有一行被注释的lora_target_linear:并注明# Does not work with gemma3n currently——即目前不能用“自动定位所有线性层”的方式必须显式指定正则表达式正则表达式model.language_model.layers.[\d].(mlp|self_attn).(up|down|gate|q|k|v|o)_proj只匹配语言模型子模块model.language_model下的 MLP 与自注意力投影层从而把 LoRA 适配器限制在语言骨干上视觉塔与音频编码器保持冻结。序列长度与打包sequence_len: 2048 sample_packing: true eval_sample_packing: true pad_to_sequence_len: truesequence_len: 2048训练序列最大长度sample_packing将多条短样本打包进同一序列提升训练吞吐eval_sample_packing评估阶段同样启用打包pad_to_sequence_len补齐到固定序列长度。训练超参数gradient_accumulation_steps: 1 micro_batch_size: 1 num_epochs: 4 optimizer: adamw_bnb_8bit lr_scheduler: cosine learning_rate: 0.0002 bf16: auto tf32: true gradient_checkpointing: true gradient_checkpointing_kwargs: use_reentrant: false warmup_ratio: 0.1 saves_per_epoch: 1 weight_decay: 0.0optimizer: adamw_bnb_8bit使用 bitsandbytes 的 8-bit AdamW进一步降低优化器状态显存bf16: auto按硬件自动决定是否使用 bfloat16 混合精度tf32: true在支持的 GPU 上启用 TF32 以加速矩阵运算gradient_checkpointing配合use_reentrant: false以计算换显存是 4-bit QLoRA 单卡训练多模态模型的标配warmup_ratio: 0.1、cosine 调度器、weight_decay: 0.0均为常见 SFT 设置。另外配置中还有一段被注释的unfrozen_parameters示例用于全参数微调FFT时只解冻语言模型层# unfrozen_parameters: # - model.language_model.* # - lm_head # - embed_tokens这与 README 中“删除adapter: qlora与load_in_4bit: true即可做全参数微调”的建议互补若只想微调语言骨干而冻结视觉塔可按上面注释解除注释。多模态配置视觉与音频的关键差异两份多模态配置gemma-3n-e2b-vision-qlora.yml 与 gemma-3n-e2b-vision-audio-qlora.yml在纯文本配置基础上多了几个决定性设置指定 AutoProcessorprocessor_type: AutoProcessor多模态训练必须显式指定processor_type: AutoProcessor由 HF AutoProcessor 负责把图像、音频与文本统一编码为模型输入。数据集准备与打包的调整skip_prepare_dataset: true remove_unused_columns: false sample_packing: false配置注释明确说明“这三行目前是处理带图像的视觉聊天模板所必需的”these 3 lines are needed for now to handle vision chat templates w imagesskip_prepare_dataset: true跳过 Axolotl 的预打包数据集准备流程因为视觉样本需要按样本逐条处理remove_unused_columns: false保留图像 / 音频等非文本列避免在预处理阶段被删除sample_packing: false多模态场景下关闭样本打包因为不同样本的媒体 token 数量差异很大无法安全地拼接到同一序列。DDP 兼容性# gemma3 doesnt seem to play nice with ddp ddp_find_unused_parameters: trueGemma-3n 与 Gemma3 一样在分布式数据并行DDP下存在未使用参数的问题因此显式开启ddp_find_unused_parameters: true。该注释是配置作者基于实际训练经验的记录单卡运行时它无副作用多卡扩展时则避免 DDP 报错。两个数据集的差异视觉配置使用 LLaVA 指令混合数据集datasets: - path: HuggingFaceH4/llava-instruct-mix-vsft type: chat_template split: train[:1%]音频 视觉配置则使用多模态测试数据集且要求媒体文件预先下载即前文 wget 的两个文件datasets: - path: Nanobit/text-vision-audio-2k-test type: chat_template其余超参数两份多模态配置都采用micro_batch_size: 2、gradient_accumulation_steps: 4、num_epochs: 1、val_set_size: 0.01划分 1% 做验证集、pad_to_sequence_len: false并同样使用lora_r: 32 / lora_alpha: 16 / lora_dropout: 0.05与相同的lora_target_modules正则。由于视觉与音频 token 会显著拉长序列多模态配置未启用pad_to_sequence_len避免把稀疏的媒体 token 填充成固定长度浪费算力。注意多模态配置中不再出现cut_cross_entropy因为 CCE 当前只支持纯文本形态的gemma3ngemma3n_text这也是文档中将 CCE 视为文本专用优化的原因。训练中的注意事项与已知问题官方 README 明确给出了一条重要警告WARNING: The loss and grad norm will be much higher than normal. We suspect this to be inherent to the model as of the moment.即训练过程中的 loss 与梯度范数会比常见模型明显偏高作者认为这大概率是 Gemma-3n 模型本身的固有特性而非配置错误。如果你观察到异常高的 loss 与 grad norm属正常现象不必惊慌。仓库作者也表示欢迎社区提交修复方案。对应地多模态配置中的chat_template: gemma3n标签掩码逻辑processing_strategies.py保证了图像与音频 token 不会计入 loss——即便 loss 整体偏高也主要来自语言建模目标本身。进阶方向全参数微调FFT按 README 的 TIPS将配置中的以下两项删除或置空即可切换为全参数微调adapter: qlora load_in_4bit: true若只想微调语言模型部分而冻结视觉塔可同时启用注释中的unfrozen_parametersunfrozen_parameters: - model.language_model.* - lm_head - embed_tokens使用自己的数据集纯文本对话数据遵循 OpenAI Messages 格式具体字段组织方式见 docs/dataset-formats/conversation.qmdchat_template一节多模态数据遵循 OpenAI 多内容multi-contentMessages 格式即一条消息可以同时包含文本、图像、音频等内容项格式细节见 docs/multimodal.qmd 的 Dataset Format 一节。替换配置中的datasets.path并在message_property_mappings中映射好你数据集的字段名即可。多卡与多节点扩展多卡训练参考 docs/multi-gpu.qmd含 FSDP、DeepSpeed 等策略并记得保留多模态配置中的ddp_find_unused_parameters: true多节点训练参考 docs/multi-node.qmdLoRA 优化参考 docs/lora_optims.qmd如 LoRA、rsLoRA 等变体。上传模型到 HF配置中预留了自动上传到 HuggingFace 的入口取消注释并填写即可在训练结束后自动推送 checkpoint 与最终模型# hub_model_id: username/custom_model_name小结Axolotl 为 Gemma-3n 提供了从纯文本到文本 视觉 音频的完整微调链路官方示例配置位于 examples/gemma3n源码层面则有 Gemma3nProcessingStrategy 负责多模态损失掩码、CutCrossEntropyPlugin 负责文本训练的显存优化。按本文步骤安装依赖、下载媒体文件、运行axolotl train即可复现训练理解标签掩码、LoRA 目标正则与多模态下的打包限制则能帮你把这三份示例改造为适合自己业务数据的生产配置。Happy finetuning【免费下载链接】axolotlGo ahead and axolotl questions项目地址: https://gitcode.com/GitHub_Trending/ax/axolotl创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考