跳到主要内容 LLaMA-Factory 环境配置与 WebUI 启动指南:CUDA 适配与依赖解决 | 极客日志
Python AI 算法
LLaMA-Factory 环境配置与 WebUI 启动指南:CUDA 适配与依赖解决 记录了在 Windows 10 环境下基于 Anaconda 部署 LLaMA-Factory 并启动 WebUI 的全过程。主要解决了仓库克隆失败、PyTorch CUDA 支持缺失及虚拟环境依赖未激活三大问题。通过配置 Git 镜像、安装适配 CUDA 12.5 的 PyTorch 版本、正确激活 Conda 环境并添加低显存优化参数,最终成功实现 GPU 加速运行。适用于本地显卡资源受限场景下的模型部署参考。
星云 发布于 2026/4/5 更新于 2026/4/13 1 浏览一、问题背景:本地部署 LLaMA-Factory 的核心诉求
目标是在 Windows 10 环境下,基于 Anaconda 创建虚拟环境,部署 LLaMA-Factory 并启动 WebUI,利用本地 NVIDIA MX230 显卡(2GB 显存)实现 GPU 加速。但从克隆仓库开始,就遇到了一系列报错,主要涉及三类问题:
仓库克隆失败(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 镜像:
git config --global http.lowSpeedLimit 0
git config --global http.lowSpeedTime 999999
git config --global http.timeout 300
git clone --depth 1 https://github.91chi.fun/https://github.com/hiyouga/LLaMA-Factory.git
rm -rf LLaMA-Factory
git clone https://gitee.com/mirrors_LLaMA-Factory/LLaMA-Factory.git
坑 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 版本。
解决方案 # 在 PowerShell 中执行,查看显卡信息
nvidia-smi
输出显示显卡为 NVIDIA GeForce MX230,驱动版本 556.12,支持 CUDA 12.5,确认硬件支持 GPU 加速。
步骤 2:卸载纯 CPU 版本 PyTorch,安装适配 CUDA 12.5 的版本
conda activate llama_factory
pip uninstall torch -y
pip cache purge
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())
>>> print ("GPU 名称:" , torch.cuda.get_device_name(0 ))
>>> print ("PyTorch 版本:" , torch.__version__)
坑 3:依赖缺失——虚拟环境未激活
报错现象 直接用 base 环境的 Python 运行 webui.py,提示缺少 torch 模块:
(base) PS E :\pc-project\LLaMA -Factory > & D :/python/mi niconda3/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 环境中没有这些依赖,导致报错。
解决方案 核心是'先激活虚拟环境,再运行脚本',提供两种可行方式:
conda activate llama_factory
cd E:\pc-project\LLaMA-Factory
python src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing
方式 2:直接调用虚拟环境的 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 参数查看详细日志,快速定位问题所在。
四、最终成功启动流程(一键复制)
conda activate llama_factory
cd E:\pc-project\LLaMA-Factory
python src/webui.py --device cuda:0 --load_in_4bit --use_gradient_checkpointing --offload_folder ./offload --verbose
按照以上步骤,就能顺利解决 LLaMA-Factory 部署过程中的克隆、CUDA 适配、依赖缺失等问题,成功启动 WebUI。如果遇到其他报错,建议优先查看终端日志,重点关注'网络连接''显存占用''依赖版本'这三个核心点,大部分问题都能迎刃而解。
微信扫一扫,关注极客日志 微信公众号「极客日志」,在微信中扫描左侧二维码关注。展示文案:极客日志 zeeklog
相关免费在线工具 加密/解密文本 使用加密算法(如AES、TripleDES、Rabbit或RC4)加密和解密文本明文。 在线工具,加密/解密文本在线工具,online
RSA密钥对生成器 生成新的随机RSA私钥和公钥pem证书。 在线工具,RSA密钥对生成器在线工具,online
Mermaid 预览与可视化编辑 基于 Mermaid.js 实时预览流程图、时序图等图表,支持源码编辑与即时渲染。 在线工具,Mermaid 预览与可视化编辑在线工具,online
curl 转代码 解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具,curl 转代码在线工具,online
Base64 字符串编码/解码 将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具,Base64 字符串编码/解码在线工具,online
Base64 文件转换器 将字符串、文件或图像转换为其 Base64 表示形式。 在线工具,Base64 文件转换器在线工具,online