LLaMA-Factory 本地部署：环境配置、CUDA 适配与 WebUI 启动

>>> 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。

三、避坑总结与关键提醒

1. 环境隔离是核心：Anaconda 虚拟环境必须激活后使用，所有依赖安装和脚本运行都要在目标环境中进行，避免混用 base 环境；
2. CUDA 版本要匹配：安装 PyTorch 前先通过 nvidia-smi 确认显卡支持的 CUDA 版本，选择兼容的 PyTorch-CUDA 版本（如 CUDA 12.5 适配 cu124 版本）；
3. 低显存显卡需优化：2GB 显存仅能运行小模型（如 LLaMA-3-8B 4bit、Qwen-1.8B），必须添加 --load_in_4bit 等量化参数，否则会显存不足；
4. 日志是排错关键：遇到无响应或报错时，添加 --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

按照以上步骤，就能顺利解决 LLaMA-Factory 部署过程中的克隆、CUDA 适配、依赖缺失等问题，成功启动 WebUI。如果遇到其他报错，建议优先查看终端日志，重点关注'网络连接''显存占用''依赖版本'这三个核心点，大部分问题都能迎刃而解。