本指南旨在帮助用户在 Windows 系统下避开版本冲突、C++ 编译报错等常见坑位，快速搭建基于 RTX 30/40 系列显卡的训练环境。

1. 核心前置依赖

在开始之前，请确保你的硬件和驱动满足以下条件：

• CUDA安装： 建议更新至CUDA 12.x（cuda向下兼容，高一点问题不大）。

• Conda 环境： 安装 Anaconda 或 Miniconda以便分离环境。

2. 步骤详解

第一步：创建 Conda 虚拟环境

LLaMA-Factory 目前兼容最好的版本是Python 3.11

# 创建环境

conda create -n llama_factory python=3.11 -y# 激活环境 conda activate llama_factory

第二步：安装 PyTorch GPU 版本

避坑指南： 不要直接通过 pip install llamafactory[torch] 安装，这往往会装上 CPU 版本。必须根据显卡 CUDA 版本手动安装。

针对 RTX 3090/4090 等显卡（CUDA 12.x 环境，注意根据自己的cuda版本选择torch版本）：

<=12.1

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121

>=12.2

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

第三步：下载并安装 LLaMA-Factory

克隆仓库或下载repo zip在源码目录下安装

git clone https://github.com/hiyouga/LLaMA-Factory.git cd LLaMA-Factory

安装核心依赖（跳过 torch 扩展项，避免覆盖）：

pip install -e ".[torch,metrics]"

第四步：解决 Windows 下的 Bitsandbytes 问题

bitsandbytes 是量化训练（4/8-bit）的核心库，但其官方版对 Windows 支持不佳。

解决方案： 安装第三方维护的 Windows 专用版。

pip install https://github.com/jllllll/bitsandbytes-windows-webui/releases/download/wheels/bitsandbytes-0.41.2.post2-py3-none-win_amd64.whl

第五步：解决 Windows 下的 FlashAttention-2 问题

cuda<=12.1

https://github.com/kingbri1/flash-attention/releases/download/v2.4.1/flash_attn-2.4.1+cu121torch2.1cxx11abiFALSE-cp311-cp311-win_amd64.whl

cuda>=12.2

https://github.com/kingbri1/flash-attention/releases/download/v2.8.3/flash_attn-2.8.3+cu124torch2.6.0cxx11abiFALSE-cp311-cp311-win_amd64.whl

3. 环境验证

运行以下代码，确保显卡被正确识别：

python -c "import torch; print('CUDA 可用:', torch.cuda.is_available()); print('显卡:', torch.cuda.get_device_name(0))"

预期结果： CUDA 可用: True 且输出显卡版本。

4. 关键注意事项与排错（避坑指南）

(1). 环境变量与指令识别

• 问题： 普通 PowerShell 无法识别 conda。

• 对策： 在 Anaconda Prompt 中运行 conda init powershell，并以管理员身份在 PowerShell 执行 Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser。

(2). Python 版本

• 版本过新会导致 numpy 等库找不到 Wheel 文件，从而触发 Compiler cl cannot compile programs 错误（提示需要安装 Visual Studio C++ 编译工具）。

• 固定使用 3.11： LLaMA-Factory 最新的 pyproject.toml 已经不再支持 Python 3.10。

(3). Conda 服务条款报错

• 错误： CondaToSNonInteractiveError。

• 对策： 运行 conda tos accept --channel <url> 手动接受3条条款即可

5. 启动 WebUI

一切就绪后，在 LLaMA-Factory 目录下运行：

llamafactory-cli webui