记录了在 Windows 10 环境下使用 Anaconda 部署 LLaMA-Factory 并启动 WebUI 的完整过程。主要解决了 GitHub 克隆失败、PyTorch CUDA 版本不匹配导致 GPU 不可用、虚拟环境依赖缺失以及低显存显卡 MX230 启动无响应等问题。通过配置 Git 镜像、安装 cu124 版 PyTorch、激活虚拟环境运行脚本及添加量化参数，实现了本地 GPU 加速部署。
最近在本地部署 LLaMA-Factory 时，遇到了一系列环境配置问题——从 GitHub 克隆失败、CUDA 不可用到虚拟环境依赖缺失，最终成功启动 WebUI。本文整理完整的排错过程和解决方案。
目标是在 Windows 10 环境下，基于 Anaconda 创建虚拟环境，部署 LLaMA-Factory 并启动 WebUI，利用本地 NVIDIA MX230 显卡（2GB 显存）实现 GPU 加速。主要涉及三类问题：
从 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
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'即可。
进入 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 版本）。
默认安装的是纯 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
直接用 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
...
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（无需手动激活）
& 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：梯度检查点，进一步节省显存。执行启动命令后，终端无响应或长时间无输出。
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。
nvidia-smi 确认显卡支持的 CUDA 版本，选择兼容的 PyTorch-CUDA 版本（如 CUDA 12.5 适配 cu124 版本）；--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
按照以上步骤，就能顺利解决 LLaMA-Factory 部署过程中的克隆、CUDA 适配、依赖缺失等问题，成功启动 WebUI。如果遇到其他报错，建议优先查看终端日志，重点关注'网络连接''显存占用''依赖版本'这三个核心点，大部分问题都能迎刃而解。
微信公众号「极客日志」，在微信中扫描左侧二维码关注。展示文案：极客日志 zeeklog
使用加密算法（如AES、TripleDES、Rabbit或RC4）加密和解密文本明文。 在线工具，加密/解密文本在线工具，online
生成新的随机RSA私钥和公钥pem证书。 在线工具，RSA密钥对生成器在线工具，online
基于 Mermaid.js 实时预览流程图、时序图等图表，支持源码编辑与即时渲染。 在线工具，Mermaid 预览与可视化编辑在线工具，online
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online