LLaMA-Factory环境配置与WebUI启动全攻略：从CUDA适配到依赖踩坑

优质文章学习记录

— 7 min read

最近在本地部署LLaMA-Factory时，踩了一连串环境配置的坑——从GitHub克隆失败、CUDA不可用到虚拟环境依赖缺失，最终成功启动WebUI。这篇文章就把完整的排错过程和解决方案整理出来，希望能帮到遇到类似问题的同学。

一、问题背景：本地部署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镜像：

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

三、避坑总结与关键提醒

  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。如果遇到其他报错，建议优先查看终端日志，重点关注“网络连接”“显存占用”“依赖版本”这三个核心点，大部分问题都能迎刃而解。

Read more

DeepSeek-R1+Stable Diffusion：云端双模型，创意加倍

DeepSeek-R1+Stable Diffusion：云端双模型，创意加倍 你是不是也遇到过这样的情况：写文案时灵感来了，想立刻生成一张配图，结果本地电脑跑不动 Stable Diffusion；或者刚部署好 DeepSeek 做文本创作，再想加个图像生成，显卡直接“罢工”？别急，这并不是你的设备不行，而是大模型对硬件的要求确实不低。 尤其是像 DeepSeek-R1 这样的大语言模型，加上 Stable Diffusion 这类图像生成模型，两者同时运行，对显存和算力的需求是叠加的。根据公开信息，仅 DeepSeek-R1 的满血版（671B 参数）就需要高达 1300GB 显存才能运行，即便是量化后的 7B 版本，也需要至少 8GB 显存起步。而 Stable Diffusion 虽然相对轻量，但高质量出图建议使用 12GB
20260121荣品RD-RK3588开发板在荣品Android13下解决打包不上无人机的QGC应用APK的问题

20260121荣品RD-RK3588开发板在荣品Android13下解决打包不上无人机的QGC应用APK的问题

20260121荣品RD-RK3588开发板在荣品Android13下解决打包不上无人机的QGC应用APK的问题 2026/1/21 16:04 需要打包的APK： 1、HelloWorld 2、QGroundControl.apk 3、VStation-2024_12_18-release.apk 4、微信 5、QQ 6、高德 1、QQ可以直接登录 2、微信反复出错。修复之后 还是 不行。 3、高德地图 需要下载新的APK。 不能打开的应该是有APK里的资源文件漏加了 我司 【客户】必须要使用 QGC这个APK BING搜索：qgroundcontrol官网 https://docs.qgroundcontrol.com/Stable_V5.0/en/qgc-user-guide/getting_
【neo4j】安装使用教程

【neo4j】安装使用教程

一、安装 1.0 前置条件 安装配置好jdk17及以上 注意我使用的是neo4j 5.26.10版本，匹配java17刚好 Java Archive Downloads - Java SE 17.0.12 and earlier 无脑安装即可 配置以下环境变量 1.1 安装程序 Neo4j Deployment Center - Graph Database & Analytics 下载解压即可，Windows是绿色版本 1.2 配置环境 添加neo4j的地址 二、基本使用 2.1 开启、关闭和查看运行状态 进入安装目录的bin文件夹，cmd窗口输入 ./neo4j.

西电通院微控指南MCU部分

目录 前言 代码框架 任务1：传感器读取数据 Cubemx配置 编辑 TCS3472颜色传感器 Vl6180距离传感器 语音传感器 传感器初始化 任务2：接收上位机数据，根据上位机指令实现功能。 Cubemx配置 代码部分 串口重定向 前言 在微控讨论贡献度时，做FPGA和MCU的同学贡献度通常会高的离谱，但是事实上这两方面工作难度是有，但是如果认真学习这方面知识，微控的MCU与FPGA难度并不高。 我认为微控作为一个小组作业，有分工合作，每个人都要完成自己分内的东西，秘书，公关，产品经理所作文书工作虽然简单，但是要做好也不容易，也并不应该因为选择了做这个，最终微控得到了很低的得分。FPGA，MCU部分的有一定门槛，但是在我看来绝大多数做该部分的同学，并没有真正去学习这方面的知识，而是使用着从各处找的工程，或者在别人的博文上抄的代码，不知其原理，每天坐在大厅里改来改去，改到凌晨三四点，看似辛苦，做的大部分都是无用功罢了。 所以写本文章的目的把我这次微控所写的工程进行讲解，搭建一个可以直接使用的微控系统设计的代码框架，帮助学弟学妹们在面对微控可以轻