前言

随着大模型的普及，越来越多开发者希望在本地 GPU 上进行推理和微调。AMD 在 Windows 上推出了 ROCm 支持，让 Ryzen AI 和 Radeon GPU 用户也能运行 PyTorch。然而，在实际部署过程中，尤其是使用 LlamaFactory 0.9.4 时，会遇到不少兼容性问题。本文记录了我在 Windows11 + AMD AI Max 395 + ROCm 环境下部署 LlamaFactory 的完整排错过程。

问题背景

目标：在本地环境运行 LlamaFactory WebUI，并支持 Qwen3-VL 微调。
环境：

  • Windows11
  • AMD AI Max 395
  • Python 3.12
  • PyTorch (AMD ROCm for Windows 官方构建)

运行命令：

python -m llamafactory.cli webui

报错信息：

ImportError: cannot import name 'GatherOptions' from 'torch._C._distributed_c10d'

原因分析

  • Windows ROCm PyTorch 构建不支持分布式训练，很多底层符号缺失。
  • Hugging Face transformers 在加载 Bloom/Qwen 模型时会强制 import 分布式相关类，例如 GatherOptions、ReduceOp。
  • LlamaFactory 0.9.4 引入了更多依赖（flex_attention、fsdp 等），导致补丁不足以绕过。

解决思路演进

1. 旧版本的补丁方案（0.9.3）

在 LlamaFactory 0.9.3 中，分布式依赖较少。通过伪造 torch.distributed 模块即可绕过：

import sys, types
try:
    import torch.distributed as dist
except ImportError:
    dist = types.ModuleType("torch.distributed")
    sys.modules["torch.distributed"] = dist

并补充一些常用方法 (init_process_group, get_rank, barrier 等)，成功启动 WebUI。

2. 升级到 0.9.4 后的新问题

0.9.4 引入了更多分布式符号，报错集中在：

  • torch._C._distributed_c10d.GatherOptions
  • torch.distributed.fsdp.FlatParameter
  • torch.distributed._shard.sharded_tensor

3. 扩展补丁

为了解决这些问题，我们扩展了补丁，伪造更多模块和类：

if "torch._C._distributed_c10d" not in sys.modules:
    fake_c10d = types.ModuleType("torch._C._distributed_c10d")
    class GatherOptions: pass
    class ReduceOp: pass
    class GroupMember: pass
    class Work: pass
    fake_c10d.GatherOptions = GatherOptions
    fake_c10d.ReduceOp = ReduceOp
    fake_c10d.GroupMember = GroupMember
    fake_c10d.Work = Work
    sys.modules["torch._C._distributed_c10d"] = fake_c10d

同时伪造 fsdp、sharded_tensor 等模块，避免 import 报错。

4. 封装启动脚本

为了避免每次手动打补丁，我们写了一个启动脚本 start_llamafactory.py：

# 打补丁
patch_torch_distributed()

# 启动 LlamaFactory WebUI
if __name__ == "__main__":
    from llamafactory.cli import main
    main()

再配合一个批处理文件 start_llamafactory.bat：

@echo off
set USE_TORCH_DISTRIBUTED=0
set USE_DISTRIBUTED=0
set TORCH_COMPILE_DISABLE=1
python start_llamafactory.py webui
pause

这样只需双击 .bat 文件即可启动。

总结

  • 问题根源：Windows ROCm PyTorch 构建缺失分布式符号。
  • 解决方案：通过 sys.modules 注入伪造模块，绕过 import 检查。
  • 适用范围：单机模式下可以正常运行 WebUI，但分布式和 FSDP 功能不可用。
  • 最佳实践：如果需要完整支持（尤其是 Qwen3-VL 微调），推荐迁移到 Linux + ROCm 环境。

经验启示

  1. 版本升级要谨慎：新版本可能引入更多依赖，导致旧补丁失效。
  2. 补丁是一种权宜之计：只能保证能跑起来，功能不完整。
  3. 环境选择很关键：Windows ROCm 仍在早期阶段，Linux 才是更稳定的选择。