LLaMA-Factory双系统部署全指南：CUDA安装、避坑排错与WebUI启动
LLaMA-Factory作为轻量化大模型训练与部署工具，环境配置环节（CUDA安装、依赖适配等）易踩坑。本文覆盖Linux/Windows双系统CUDA安装、LLaMA-Factory部署与校验、高级配置，以及克隆失败、CUDA不可用等核心报错的解决方案，提供一站式本地部署参考。
最近在本地部署LLaMA-Factory时，踩了一连串环境配置的坑——从GitHub克隆失败、CUDA不可用到虚拟环境依赖缺失，最终成功启动WebUI。这篇文章就把完整的排错过程和解决方案整理出来，希望能帮到遇到类似问题的同学。
一、前置安装指南：CUDA与LLaMA-Factory基础部署
1.1 CUDA安装（Linux+Windows双系统）
CUDA是NVIDIA推出的并行计算平台，是LLaMA-Factory利用GPU加速的基础。需根据自身操作系统选择对应安装流程，安装前务必确认硬件与系统兼容性。
1.1.1 Linux系统CUDA安装
CUDA让开发者可借助NVIDIA GPU实现高性能并行计算，安装前需完成三步兼容性检查：
GPU兼容性校验：访问 https://developer.nvidia.com/cuda-gpus，查询本地GPU是否支持CUDA；
系统版本校验：命令行输入uname -m && cat /etc/*release，确认系统为x86_64架构且版本兼容（示例输出如下）：x86_64
DISTRIB_ID=Ubuntu
DISTRIB_RELEASE=22.04
gcc环境校验：命令行输入gcc --version，需确保gcc已安装（示例输出如下）：
gcc (Ubuntu 11.4.0-1ubuntu1~22.04) 11.4.0
兼容性确认后，按以下步骤安装（推荐CUDA 12.2版本）：
卸载旧版本（若有）：若此前安装过其他CUDA版本（如12.1），先执行卸载命令：
sudo /usr/local/cuda-12.1/bin/cuda-uninstaller# 若卸载命令失效，直接删除文件夹
sudo rm -r /usr/local/cuda-12.1/
sudo apt clean && sudo apt autoclean
下载并安装CUDA 12.2：执行以下命令，按提示完成安装（注意：若已安装NVIDIA驱动，建议取消Driver选项勾选，避免版本冲突）：wget https://developer.download.nvidia.com/compute/cuda/12.2.0/local_installers/cuda_12.2.0_535.54.03_linux.run
sudo sh cuda_12.2.0_535.54.03_linux.run
安装校验：命令行输入nvcc -V，若显示对应CUDA版本号，则安装成功。
1.1.2 Windows系统CUDA安装
Windows系统需先确认系统版本兼容性，再执行安装：
系统版本校验：打开「设置」-「关于」，查看「Windows规格」，需为以下支持版本之一：Microsoft Windows 11 21H2/22H2-SV2/23H2
Microsoft Windows 10 21H2/22H2
Microsoft Windows Server 2022
下载与安装：访问NVIDIA官网下载对应版本的CUDA安装包，按向导提示完成安装（建议使用默认路径，便于后续环境变量配置）。
安装校验与环境变量检查：打开CMD输入
nvcc -V，若显示版本信息则安装成功；若失败，需检查系统环境变量，确保CUDA相关路径已正确添加。
1.2 LLaMA-Factory安装与校验
完成CUDA安装后，即可部署LLaMA-Factory，需先确保已安装Python、Git等基础依赖。
1.2.1 基础安装步骤
# 1. 克隆仓库（若此前克隆失败，可参考后续排错方案） git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git # 2. 进入项目目录 cd LLaMA-Factory # 3. 安装核心依赖（torch与评估指标） pip install -e ".[torch,metrics]" # 4. 解决环境冲突（若安装时出现冲突） # pip install --no-deps -e .1.2.2 安装校验
安装完成后，执行以下命令快速验证：
llamafactory-cli version若能正常显示版本信息界面，则说明LLaMA-Factory安装成功。
1.3 LLaMA-Factory高级选项配置（Windows）
针对Windows用户的进阶需求（如量化训练、高速注意力机制），补充以下配置方案：
1.3.1 启用量化LoRA（QLoRA）
安装适配Windows的bitsandbytes包（用于大模型量化）：
pip install https://github.com/jllllll/bitsandbytes-windows-webui/releases/download/wheels/bitsandbytes-0.41.2.post2-py3-none-win_amd64.whl1.3.2 启用FlashAttention-2
根据本地CUDA版本，安装对应版本的flash-attention包（提升模型推理与训练速度），具体版本可参考FlashAttention官方文档。
1.3.3 额外依赖说明
若有分布式训练、模型量化、推理加速等需求，可安装对应依赖，具体说明如下：
依赖名称 | 描述 |
|---|---|
torch | 开源深度学习框架，广泛用于机器学习研究 |
torch-npu | PyTorch的昇腾设备兼容包 |
metrics | 模型性能评估与监控工具 |
deepspeed | 提供分布式训练零冗余优化器 |
bitsandbytes | 大型语言模型量化工具 |
hqq/eetq | 大模型量化工具，适配不同量化需求 |
gptq/awq/aqlm | 用于加载对应量化格式的模型 |
vllm | 提供高速并发模型推理服务 |
galore/badam | 高效全参微调算法实现 |
qwen | 加载Qwen v1模型所需依赖 |
modelscope | 魔搭社区依赖，提供模型与数据集下载 |
swanlab | 开源训练跟踪工具，可视化训练过程 |
dev | LLaMA-Factory开发维护所需依赖 |
二、核心报错排错指南
完成基础安装后，启动LLaMA-Factory过程中可能遇到仓库克隆失败、CUDA不可用、依赖缺失等问题，以下是针对性解决方案。
2.1 坑1：仓库克隆失败——网络限制与镜像选择
报错现象
从GitHub克隆时提示连接重置，从某Gitee镜像克隆时提示403权限拒绝：
(base) PS E:\pc-project> git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git Cloning into 'LLaMA-Factory'... fatal: unable to access 'https://github.com/hiyouga/LLaMA-Factory.git/': Recv failure: Connection was reset (base) PS E:\pc-project> git clone https://gitee.com/qzl9999/LLaMA-Factory.git Cloning into 'LLaMA-Factory'... remote: [session-6b44feb3] Access denied fatal: unable to access 'https://gitee.com/qzl9999/LLaMA-Factory.git/': The requested URL returned error: 403原因分析
GitHub克隆失败是国内网络访问限制导致；Gitee 403是因为选择的镜像仓库权限设置问题（非公开可克隆）。
解决方案
优先选择GitHub国内镜像站，配合Git网络配置优化；备选方案使用官方维护的Gitee镜像：
# 1. 配置Git超时与网络参数（避免连接超时） git config --global http.lowSpeedLimit 0 git config --global http.lowSpeedTime 999999 git config --global http.timeout 300 # 2. 使用GitHub镜像站克隆（推荐） git clone --depth 1 https://github.91chi.fun/https://github.com/hiyouga/LLaMA-Factory.git # 3. 备选：使用Gitee官方维护镜像 rm -rf LLaMA-Factory # 删除之前失败的文件夹 git clone https://gitee.com/mirrors_LLaMA-Factory/LLaMA-Factory.git如果Git命令仍失败，可直接手动下载源码压缩包：访问https://github.com/hiyouga/LLaMA-Factory/archive/refs/heads/main.zip，解压后重命名为“LLaMA-Factory”即可。
2.2 坑2：CUDA不可用——PyTorch版本错配
报错现象
进入Python交互环境，调用torch.cuda相关函数时报错：
>>> import torch >>> torch.cuda.current_device() Traceback (most recent call last): File "<stdin>", line 1, in <module> File "...\torch\cuda\__init__.py", line 403, in _lazy_init raise AssertionError("Torch not compiled with CUDA enabled") AssertionError: Torch not compiled with CUDA enabled查看PyTorch编译配置，发现USE_CUDA=0（纯CPU版本）：
PyTorch编译配置： PyTorch built with: ... - Build settings: ... USE_CUDA=0, ...原因分析
默认安装的是纯CPU版本的PyTorch，而本地有NVIDIA MX230显卡（支持CUDA 12.5），需要安装带CUDA支持的PyTorch版本。
解决方案
步骤1：先确认本地显卡与CUDA支持情况
# 在PowerShell中执行，查看显卡信息 nvidia-smi输出显示显卡为NVIDIA GeForce MX230，驱动版本556.12，支持CUDA 12.5，确认硬件支持GPU加速。
步骤2：卸载纯CPU版本PyTorch，安装适配CUDA 12.5的版本
# 1. 激活llama_factory虚拟环境 conda activate llama_factory # 2. 卸载CPU版PyTorch pip uninstall torch -y pip cache purge # 清理缓存，避免安装冲突 # 3. 安装适配CUDA 12.5的PyTorch（cu124版本兼容CUDA 12.5） pip install torch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 --index-url https://download.pytorch.org/whl/cu124>>> import torch >>> print("CUDA是否可用：", torch.cuda.is_available()) # 输出True即成功 >>> print("GPU名称：", torch.cuda.get_device_name(0)) # 输出NVIDIA GeForce MX230 >>> print("PyTorch版本：", torch.__version__) # 输出2.4.0+cu1242.3 坑3：依赖缺失——虚拟环境未激活
报错现象
直接用base环境的Python运行webui.py，提示缺少torch模块：
(base) PS E:\pc-project\LLaMA-Factory> & D:/python/miniconda3/python.exe e:/pc-project/LLaMA-Factory/src/webui.py Traceback (most recent call last): File "e:\pc-project\LLaMA-Factory\src\webui.py", line 7, in <module> from llamafactory.extras.misc import fix_proxy, is_env_enabled File "e:\pc-project\LLaMA-Factory\src\llamafactory\extras\misc.py", line 23, in <module> import torch ModuleNotFoundError: No module named 'torch'原因分析
Anaconda的base环境与llama_factory虚拟环境相互隔离，torch等依赖只安装在llama_factory环境中，base环境中没有这些依赖，导致报错。
解决方案
核心是“先激活虚拟环境，再运行脚本”，提供两种可行方式：
方式1：激活环境后运行（推荐）
# 1. 激活llama_factory虚拟环境 conda activate llama_factory # 2. 切换到LLaMA-Factory根目录 cd E:\pc-project\LLaMA-Factory # 3. 运行webui.py（适配2GB显存，添加优化参数） python src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing方式2：直接调用虚拟环境的Python（无需手动激活）
# 直接指定llama_factory环境的Python路径 & D:/python/miniconda3/envs/llama_factory/python.exe e:/pc-project/LLaMA-Factory/src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing参数说明：
--device cuda:0：指定使用第0号GPU（本地MX230）；--load_in_4bit：4比特量化加载模型，大幅降低显存占用；--use_gradient_checkpointing：梯度检查点，进一步节省显存。
2.4 坑4：WebUI启动无响应——低显存适配
问题现象
执行启动命令后，终端无响应或长时间无输出。
原因分析
MX230显卡仅2GB显存，默认启动方式显存占用过高，导致静默崩溃；或首次启动需加载依赖，过程较慢。
解决方案
添加日志输出参数查看进度，同时进一步优化显存占用：
python src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing --offload_folder ./offload --verbose参数说明：
--offload_folder ./offload：将部分模型数据卸载到硬盘，牺牲少量速度换显存；--verbose：打印启动日志，清晰看到加载进度（如“Loading tokenizer...”“Initializing model...”）。
启动成功后，终端会显示访问地址（如http://127.0.0.1:7860），打开浏览器即可进入WebUI。
仓库克隆失败（GitHub连接重置、Gitee 403权限拒绝）；
PyTorch CUDA支持缺失（报“Torch not compiled with CUDA enabled”）；
虚拟环境依赖缺失（直接运行WebUI报“ModuleNotFoundError: No module named 'torch'”）。
二、核心报错解析与分步解决方案
坑1：仓库克隆失败——网络限制与镜像选择
报错现象
从GitHub克隆时提示连接重置，从某Gitee镜像克隆时提示403权限拒绝：
(base) PS E:\pc-project> git clone --depth 1 https://github.com/hiyouga/LLaMA-Factory.git Cloning into 'LLaMA-Factory'... fatal: unable to access 'https://github.com/hiyouga/LLaMA-Factory.git/': Recv failure: Connection was reset (base) PS E:\pc-project> git clone https://gitee.com/qzl9999/LLaMA-Factory.git Cloning into 'LLaMA-Factory'... remote: [session-6b44feb3] Access denied fatal: unable to access 'https://gitee.com/qzl9999/LLaMA-Factory.git/': The requested URL returned error: 403原因分析
GitHub克隆失败是国内网络访问限制导致；Gitee 403是因为选择的镜像仓库权限设置问题（非公开可克隆）。
解决方案
优先选择GitHub国内镜像站，配合Git网络配置优化；备选方案使用官方维护的Gitee镜像：
# 1. 配置Git超时与网络参数（避免连接超时） git config --global http.lowSpeedLimit 0 git config --global http.lowSpeedTime 999999 git config --global http.timeout 300 # 2. 使用GitHub镜像站克隆（推荐） git clone --depth 1 https://github.91chi.fun/https://github.com/hiyouga/LLaMA-Factory.git # 3. 备选：使用Gitee官方维护镜像 rm -rf LLaMA-Factory # 删除之前失败的文件夹 git clone https://gitee.com/mirrors_LLaMA-Factory/LLaMA-Factory.git如果Git命令仍失败，可直接手动下载源码压缩包：访问https://github.com/hiyouga/LLaMA-Factory/archive/refs/heads/main.zip，解压后重命名为“LLaMA-Factory”即可。
坑2：CUDA不可用——PyTorch版本错配
报错现象
进入Python交互环境，调用torch.cuda相关函数时报错：
>>> import torch >>> torch.cuda.current_device() Traceback (most recent call last): File "<stdin>", line 1, in <module> File "...\torch\cuda\__init__.py", line 403, in _lazy_init raise AssertionError("Torch not compiled with CUDA enabled") AssertionError: Torch not compiled with CUDA enabled查看PyTorch编译配置，发现USE_CUDA=0（纯CPU版本）：
PyTorch编译配置： PyTorch built with: ... - Build settings: ... USE_CUDA=0, ...原因分析
默认安装的是纯CPU版本的PyTorch，而本地有NVIDIA MX230显卡（支持CUDA 12.5），需要安装带CUDA支持的PyTorch版本。
解决方案
步骤1：先确认本地显卡与CUDA支持情况
# 在PowerShell中执行，查看显卡信息 nvidia-smi输出显示显卡为NVIDIA GeForce MX230，驱动版本556.12，支持CUDA 12.5，确认硬件支持GPU加速。
步骤2：卸载纯CPU版本PyTorch，安装适配CUDA 12.5的版本
# 1. 激活llama_factory虚拟环境 conda activate llama_factory # 2. 卸载CPU版PyTorch pip uninstall torch -y pip cache purge # 清理缓存，避免安装冲突 # 3. 安装适配CUDA 12.5的PyTorch（cu124版本兼容CUDA 12.5） pip install torch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 --index-url https://download.pytorch.org/whl/cu124步骤3：验证CUDA是否可用
>>> import torch >>> print("CUDA是否可用：", torch.cuda.is_available()) # 输出True即成功 >>> print("GPU名称：", torch.cuda.get_device_name(0)) # 输出NVIDIA GeForce MX230 >>> print("PyTorch版本：", torch.__version__) # 输出2.4.0+cu124坑3：依赖缺失——虚拟环境未激活
报错现象
直接用base环境的Python运行webui.py，提示缺少torch模块：
(base) PS E:\pc-project\LLaMA-Factory> & D:/python/miniconda3/python.exe e:/pc-project/LLaMA-Factory/src/webui.py Traceback (most recent call last): File "e:\pc-project\LLaMA-Factory\src\webui.py", line 7, in <module> from llamafactory.extras.misc import fix_proxy, is_env_enabled File "e:\pc-project\LLaMA-Factory\src\llamafactory\extras\misc.py", line 23, in <module> import torch ModuleNotFoundError: No module named 'torch'原因分析
Anaconda的base环境与llama_factory虚拟环境相互隔离，torch等依赖只安装在llama_factory环境中，base环境中没有这些依赖，导致报错。
解决方案
核心是“先激活虚拟环境，再运行脚本”，提供两种可行方式：
方式1：激活环境后运行（推荐）
# 1. 激活llama_factory虚拟环境 conda activate llama_factory # 2. 切换到LLaMA-Factory根目录 cd E:\pc-project\LLaMA-Factory # 3. 运行webui.py（适配2GB显存，添加优化参数） python src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing方式2：直接调用虚拟环境的Python（无需手动激活）
# 直接指定llama_factory环境的Python路径 & D:/python/miniconda3/envs/llama_factory/python.exe e:/pc-project/LLaMA-Factory/src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing参数说明：
--device cuda:0：指定使用第0号GPU（本地MX230）；--load_in_4bit：4比特量化加载模型，大幅降低显存占用；--use_gradient_checkpointing：梯度检查点，进一步节省显存。
坑4：WebUI启动无响应——低显存适配
问题现象
执行启动命令后，终端无响应或长时间无输出。
原因分析
MX230显卡仅2GB显存，默认启动方式显存占用过高，导致静默崩溃；或首次启动需加载依赖，过程较慢。
解决方案
添加日志输出参数查看进度，同时进一步优化显存占用：
python src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing --offload_folder ./offload --verbose参数说明：
--offload_folder ./offload：将部分模型数据卸载到硬盘，牺牲少量速度换显存；--verbose：打印启动日志，清晰看到加载进度（如“Loading tokenizer...”“Initializing model...”）。
启动成功后，终端会显示访问地址（如http://127.0.0.1:7860），打开浏览器即可进入WebUI。
三、避坑总结与关键提醒
环境隔离是核心：Anaconda虚拟环境必须激活后使用，所有依赖安装和脚本运行都要在目标环境中进行，避免混用base环境；
CUDA版本要匹配：安装PyTorch前先通过
nvidia-smi确认显卡支持的CUDA版本，选择兼容的PyTorch-CUDA版本（如CUDA 12.5适配cu124版本）；低显存显卡需优化：2GB显存仅能运行小模型（如LLaMA-3-8B 4bit、Qwen-1.8B），必须添加
--load_in_4bit等量化参数，否则会显存不足；日志是排错关键：遇到无响应或报错时，添加
--verbose参数查看详细日志，快速定位问题所在；依赖安装按需选择：基础使用仅需安装
torch和metrics，进阶需求（量化、分布式训练）再安装对应依赖，避免环境冗余。环境隔离是核心：Anaconda虚拟环境必须激活后使用，所有依赖安装和脚本运行都要在目标环境中进行，避免混用base环境；
CUDA版本要匹配：安装PyTorch前先通过
nvidia-smi确认显卡支持的CUDA版本，选择兼容的PyTorch-CUDA版本（如CUDA 12.5适配cu124版本）；低显存显卡需优化：2GB显存仅能运行小模型（如LLaMA-3-8B 4bit、Qwen-1.8B），必须添加
--load_in_4bit等量化参数，否则会显存不足；日志是排错关键：遇到无响应或报错时，添加
--verbose参数查看详细日志，快速定位问题所在。
四、最终成功启动流程（一键复制）
# 1. 激活虚拟环境 conda activate llama_factory # 2. 切换到项目根目录 cd E:\pc-project\LLaMA-Factory # 3. 优化参数启动WebUI python src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing --offload_folder ./offload --verbose按照以上步骤，就能顺利完成CUDA安装、LLaMA-Factory部署及WebUI启动。若遇到其他报错，建议优先查看终端日志，重点关注“网络连接”“显存占用”“依赖版本”“环境激活”这四个核心点，大部分问题都能迎刃而解。
# 1. 激活虚拟环境 conda activate llama_factory # 2. 切换到项目根目录 cd E:\pc-project\LLaMA-Factory # 3. 优化参数启动WebUI python src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing --offload_folder ./offload --verbose按照以上步骤，就能顺利解决LLaMA-Factory部署过程中的克隆、CUDA适配、依赖缺失等问题，成功启动WebUI。如果遇到其他报错，建议优先查看终端日志，重点关注“网络连接”“显存占用”“依赖版本”这三个核心点，大部分问题都能迎刃而解。
