最近在本地部署LLaMA-Factory时，踩了一连串环境配置的坑——从GitHub克隆失败、CUDA不可用到虚拟环境依赖缺失，最终成功启动WebUI。这篇文章就把完整的排错过程和解决方案整理出来，希望能帮到遇到类似问题的同学。 一、问题背景：本地部署LLaMA-Factory的核心诉求 目标是在Windows 10环境下，基于Anaconda创建虚拟环境，部署LLaMA-Factory并启动We…
最近在本地部署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 (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'即可。
进入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
直接用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：梯度检查点，进一步节省显存。执行启动命令后，终端无响应或长时间无输出。
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
解析常见 curl 参数并生成 fetch、axios、PHP curl 或 Python requests 示例代码。 在线工具，curl 转代码在线工具，online
将字符串编码和解码为其 Base64 格式表示形式即可。 在线工具，Base64 字符串编码/解码在线工具，online
将字符串、文件或图像转换为其 Base64 表示形式。 在线工具，Base64 文件转换器在线工具，online
将 Markdown（GFM）转为 HTML 片段，浏览器内 marked 解析；与 HTML转Markdown 互为补充。 在线工具，Markdown转HTML在线工具，online
将 HTML 片段转为 GitHub Flavored Markdown，支持标题、列表、链接、代码块与表格等；浏览器内处理，可链接预填。 在线工具，HTML转Markdown在线工具，online
通过删除不必要的空白来缩小和压缩JSON。 在线工具，JSON 压缩在线工具，online