网站导航
> 技术文档 > 在 Windows 环境下使用 LLaMA Factory 微调 `gemma-3n` 多模态模型_llama factory windows环境

在 Windows 环境下使用 LLaMA Factory 微调 `gemma-3n` 多模态模型_llama factory windows环境

网友: 技术文档 2025-09-03 23:08:16

操作手册：

前言

这篇博客是在Windows环境中微调Gemma3n模型的一些踩坑记录，在此先感谢google/gemini-2.5-pro的帮助。

第一部分：构建与配置 WSL2 开发环境

在 Windows 上进行严肃的深度学习开发，最佳实践是利用 Windows Subsystem for Linux 2 (WSL2)。这为我们提供了一个与生产环境一致的、高性能的 Linux 环境，能从根本上避免 Windows 原生环境下的依赖缺失和兼容性问题。

1.1 在非系统盘安装 WSL2

为避免占用宝贵的系统盘空间，我们需将 WSL2 发行版安装到其他磁盘（如 D:\\）。

  1. 初始安装: 以管理员身份打开 PowerShell，执行标准安装命令。这将临时在 C 盘创建发行版。

    wsl --install -d Ubuntu

    完成初次进入时的用户名和密码设置。

  2. 导出与迁移:
    a. 在目标磁盘创建安装目录，例如 D:\\WSL\\Ubuntu。
    b. 将已安装的 Ubuntu 发行版导出为 TAR 文件：
    powershell wsl --export Ubuntu D:\\WSL\\ubuntu_export.tar
    c. 从系统中注销原有的 C 盘安装，以释放空间：
    powershell wsl --unregister Ubuntu
    d. 将导出的 TAR 文件重新导入到指定的新位置：
    powershell wsl --import Ubuntu D:\\WSL\\Ubuntu D:\\WSL\\ubuntu_export.tar --version 2
    e. 清理临时的 TAR 文件。

1.2 用户与权限标准化

导入的 WSL 实例默认使用 root 用户，这存在安全风险。必须创建一个日常使用的非 root 管理员账户。

  1. 进入 WSL: wsl
  2. 创建新用户: 
    adduser <your_username>

    根据提示设置密码。

  3. 授予 sudo 权限: 
    usermod -aG sudo <your_username>
  4. 设置默认用户: 退出 WSL，回到 PowerShell 中执行： 
    wsl -u  -d Ubuntu

    (可使用 wsl --set-default-user 设置)

1.3 Huggingface代理或Modelscope

国区会遇到Huggingface无法访问的问题，可以通过huggingface.co修改为hf-mirror.com进行代理解决，具体可参考官方示例:
hf-mirror.com

  • 症状: ping hf-mirror.com 不通，或在下载模型时出现 Network is unreachable / ConnectionError。
  • 标准解决方案: 在 PowerShell 中执行 wsl --shutdown。此命令会强制关闭并重置 WSL2 虚拟机，在下次启动时重新获取网络配置，能解决绝大多数网络问题。

当配置hf-mirror.com代理后依然无法正常连接，可以考虑替换为阿里modescope替换进行下载

  • 症状:www.modelscope.ai中的模型与www.modelscope.cn中模型未同步，例如gemma-3n模型
  • 一种可行的解决方案:找到当前环境中的modelscope包源代码，例如你的conda环境是llamafactory，在~\\conda\\envs\\llamafactory\\lib\\python3.1x\\site-packages\\modelscope\\hub\\constants.py中找到
DEFAULT_MODELSCOPE_INTL_DOMAIN = \'www.modelscope.ai\'

将其修改为

DEFAULT_MODELSCOPE_INTL_DOMAIN = \'www.modelscope.com\'
1.4 增加 WSL2 可用内存

大型模型的训练和数据处理需要大量系统内存（RAM）。默认的 WSL2 内存限制可能过低，导致进程被 OOM Killer 意外终止。

  1. 关闭 WSL: wsl --shutdown
  2. 创建配置文件: 在您的 Windows 用户根目录 (C:\\Users\\) 下，创建一个名为 .wslconfig 的文件。
  3. 编辑配置: 添加以下内容，根据您的物理内存大小进行调整（建议为总内存的 50%-75%）。 
    [wsl2]memory=24GB # 示例：为 WSL2 分配 24GB 内存processors=8 # 示例：分配 8 个 CPU 核心
  4. 重启 WSL 以使配置生效。

第二部分：LLaMA Factory 的安装与配置

LLaMA Factory 是一个功能强大的微调框架。我们将围绕它进行配置。

2.1 框架安装

在配置好的 WSL2 环境中执行以下命令：

# 1. 克隆项目git clone https://github.com/hiyouga/LLaMA-Factory.gitcd LLaMA-Factory# 2. 安装核心依赖及多模态组件pip install -e .[torch,multimodal]# 3. 安装编译工具 (解决 Triton 等库的编译依赖)sudo apt update && sudo apt install build-essential -y
2.2 数据集适配与格式化

LLaMA Factory 的多模态训练需要特定格式的数据。如果您的原始数据集（无论是本地还是来自 Hugging Face Hub）不符合要求，必须进行预处理，具体需仔细阅读llamafactory的readme文件。

  • 关键: 用户的提问中必须包含 占位符。
  • 操作: 编写一个一次性的 Python 脚本，使用 datasets.load_dataset 加载您的原始数据，然后迭代、转换格式，并将图片文件和新的 jsonl 文件保存到 LLaMA-Factory/data/ 目录下的一个新文件夹中。
  • 注册数据集: 在 LLaMA-Factory/data/dataset_info.json 文件中，为这个新生成的本地数据集添加一个条目，正确指定 file_name 和 columns 映射。
2.3 核心微调配置 (YAML)

使用 YAML 文件进行配置是最清晰、最可复现的方式。以下是针对 gemma-3n-e4b-it 进行 QLoRA 微调的关键配置项。

# top: 顶级配置top: model_name: google/gemma-3n-e4b-it finetuning_type: lora quantization_bit: 4 # 关键：启用 4-bit 量化 (QLoRA) 以节省显存 template: gemma3n  # 关键：为 gemma-3n 选择正确的对话模板# train: 训练参数train: dataset: - your_dataset_name_in_json_info # 您的数据集名称 # --- 解决 LoRA 目标模块错误的核心配置 --- lora_target: [q_proj, k_proj, v_proj, o_proj] # 关键：手动指定经过社区验证的目标模块 # --- 解决多模态组件加载错误的核心配置 --- # 这个配置需要通过命令行参数 --visual_inputs 添加，或在UI中勾选 # --- 其他重要参数示例 --- compute_type: bf16  # 在支持的硬件上使用 bf16 batch_size: 2# 根据显存调整 gradient_accumulation_steps: 8 # 调整以达到期望的有效批次大小 learning_rate: 2e-4 lr_scheduler_type: cosine num_train_epochs: 3.0 # ... 其他参数 ...

第三部分：执行训练与问题排查

3.1 启动训练命令

为确保训练在 GPU 上运行并使用镜像站，启动命令必须包含必要的环境变量。

# 在 LLaMA-Factory 根目录下执行HF_ENDPOINT=\"https://hf-mirror.com\" \\CUDA_VISIBLE_DEVICES=0 \\llamafactory-cli train --config_file your_config.yaml
3.2 常见 ValueError / AttributeError 排查

在微调 gemma-3n 这种新模型时，遇到的错误通常源于框架的通用逻辑与模型特定实现的不匹配。

  1. 错误: Processor was not found

    • 原因: 框架未能正确初始化多模态组件。
    • 解决方案: 在启动命令中添加 --visual_inputs 标志，强制框架加载视觉模块。

  2. 错误: ... has no attribute \'multi_modal_projector\'

    • 原因: 框架尝试访问一个名为 multi_modal_projector 的通用属性，但 gemma-3n 的实现中并无此同名属性。
    • 解决方案: 对框架源码进行微创“猴子补丁”。在模型加载器（如 src/llama_factory/model/loader.py）的 load_model 函数返回前，为 gemma-3n 模型对象动态添加一个别名：model.multi_modal_projector = model.text_decoder.embed_tokens。同时，在配置中将对应的 freeze_multi_modal_projector 设为 true。

  3. 错误: Target module ... is not supported 或 Target modules set() not found

    • 原因: lora_target 配置不正确。all 自动检测会失败；空格分隔的字符串未被解析为列表；或者列表中的模块名与 gemma-3n 的实际结构（如 ModuleList）不兼容。
    • 解决方案: 严格遵循 2.3 节中的 YAML 配置，使用标准的列表语法，并仅指定经过验证的、针对注意力层的核心投影模块 [q_proj, k_proj, v_proj, o_proj]。
网络标签：

相关问题