1. 环境准备

  • 操作系统：Windows 11
  • Python：确保已安装 Python 3.12（默认路径：C:\Program Files\Python312\python.exe）
  • pip：使用系统自带的 pip，不需要虚拟环境

检查 Python 和 pip

在 PowerShell 中运行：

python --version
python -m pip --version

如果能正常显示版本号，说明环境可用。

2. 安装依赖

升级 pip

python -m pip install --upgrade pip

安装 Llama-Factory

直接在系统环境安装：

python -m pip install llamafactory

安装 PyTorch + TorchVision

Windows 上参考官方文档：

[PyTorch via PIP installation — Use ROCm on Radeon and Ryzen]

pip install --no-cache-dir `
    https://repo.radeon.com/rocm/windows/rocm-rel-7.2/rocm_sdk_core-7.2.0.dev0-py3-none-win_amd64.whl `
    https://repo.radeon.com/rocm/windows/rocm-rel-7.2/rocm_sdk_devel-7.2.0.dev0-py3-none-win_amd64.whl `
    https://repo.radeon.com/rocm/windows/rocm-rel-7.2/rocm_sdk_libraries_custom-7.2.0.dev0-py3-none-win_amd64.whl `
    https://repo.radeon.com/rocm/windows/rocm-rel-7.2/rocm-7.2.0.dev0.tar.gz

pip install --no-cache-dir `
    https://repo.radeon.com/rocm/windows/rocm-rel-7.2/torch-2.9.1%2Brocmsdk20260116-cp312-cp312-win_amd64.whl `
    https://repo.radeon.com/rocm/windows/rocm-rel-7.2/torchaudio-2.9.1%2Brocmsdk20260116-cp312-cp312-win_amd64.whl `
    https://repo.radeon.com/rocm/windows/rocm-rel-7.2/torchvision-0.24.1%2Brocmsdk20260116-cp312-cp312-win_amd64.whl

3. 修复分布式报错（Windows 特有问题）

Windows 上 PyTorch 的分布式接口不完整，Llama-Factory 默认会尝试加载分布式模块，导致报错。解决方法是添加一个 补丁脚本。

在目录：

C:\Program Files\Python312\Lib\site-packages\

新建文件 sitecustomize.py，内容如下：

import sys, types

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

    class Store: pass
    class ProcessGroup: pass
    class FileStore(Store): pass
    class TCPStore(Store): pass
    class Backend:
        @staticmethod
        def register_backend(name, func, *args, **kwargs):
            return None

    dist.Store = Store
    dist.ProcessGroup = ProcessGroup
    dist.FileStore = FileStore
    dist.TCPStore = TCPStore
    dist.Backend = Backend

    dist.is_available = lambda: False
    dist.init_process_group = lambda *args, **kwargs: None
    dist.destroy_process_group = lambda *args, **kwargs: None
    dist.get_rank = lambda: 0
    dist.get_world_size = lambda: 1
    dist.barrier = lambda *args, **kwargs: None
    dist.all_reduce = lambda *args, **kwargs: None
    dist.broadcast = lambda *args, **kwargs: None

    print("[Patch] torch.distributed 已被替换为完整 stub（单机模式）")

patch_torch_distributed()

这样每次启动 Python 时都会自动屏蔽分布式接口，避免报错。

4. 启动 Llama-Factory WebUI

在 PowerShell 中运行：

python -m llamafactory.cli webui

如果看到类似：

[Patch] torch.distributed 已被替换为完整 stub（单机模式）
Running on http://localhost:7860

说明 WebUI 已经成功启动。你可以在浏览器打开 http://localhost:7860 使用。

5. 注意事项

  • 不要直接运行 llamafactory-cli.exe，因为 Windows 的启动器容易损坏。推荐用 python -m llamafactory.cli。
  • 单机模式：由于 Windows 不支持分布式训练，补丁会屏蔽所有分布式接口，只能单机训练。
  • GPU 支持：如果你有 NVIDIA GPU，可以安装 CUDA 版 PyTorch；如果是 AMD GPU，目前在 Windows 下支持有限，建议用 CPU 或 WSL2/Linux。

🎯 总结

在 Windows 11 上部署 Llama-Factory 的关键点是：

  1. 用系统 Python 安装，不需要虚拟环境。
  2. 用 python -m pip 安装依赖，避免损坏的 .exe 启动器。
  3. 添加 sitecustomize.py 补丁，屏蔽分布式接口。
  4. 用 python -m llamafactory.cli webui 启动 WebUI。

这样就能在 Windows 11 上顺利运行 Llama-Factory WebUI，并进行单机训练。