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

OpenPose Editor实战：AI绘画中的人物姿态精准控制技巧

OpenPose Editor实战：AI绘画中的人物姿态精准控制技巧 【免费下载链接】openpose-editoropenpose-editor - 一个用于编辑和管理Openpose生成的姿势的应用程序，支持多种图像处理功能。 项目地址: https://gitcode.com/gh_mirrors/op/openpose-editor 还在为AI绘画中的人物姿态不自然而烦恼吗？作为深度使用OpenPose Editor的创作者，我发现这款工具彻底改变了我的工作流程。今天分享一些实用的经验技巧，帮助你在AI绘画中实现精准的人物姿态控制。 从零开始的姿态编辑之旅 刚开始接触OpenPose Editor时，我也曾被那些复杂的骨骼点吓到。但经过多次实践，我总结出了一套简单有效的工作流程： 第一步：环境快速搭建 cd extensions git clone https://gitcode.com/gh_mirrors/op/openpose-editor 这个过程只需要几分钟，就能获得一个功能完整的姿态编辑工具。 第二步：界面熟悉与基础设置 OpenPose Edi
An efficient hardware architecture of integer motion estimation based on early termination and data

An efficient hardware architecture of integer motion estimation based on early termination and data

Zhang, Jun, Yu Zhang, and Hao Zhang. “An efficient hardware architecture of integer motion estimation based on early termination and data reuse for versatile video coding.” Expert Systems with Applications 242 (2024): 122706. 一、现存问题分析 1、由于降低搜索复杂度而降低搜索精度 目前已有的一些整数运动估计算法（如三步和四步搜索算法）通过简化搜索模板来降低运动估计的复杂度。然而，减少搜索点的数量和使用更小的搜索窗口会导致搜索算法陷入局部最优而不是全局最优，从而降低运动搜索的准确性。 2、由于增强搜索精度而导致高计算复杂度和资源消耗 另一种类型的整数运动估计算法(例如菱形搜索算法)采用复杂的搜索模板并增加搜索窗口内的搜索点的数量以提高搜索精度。复杂的运动搜索过程和额外的计算数据导致在视频编码期间显著的计算和存储资源消耗，这是以高成本来实现的。
【机器人】复现 StreamVLN 具身导航 | 流式VLN | 连续导航

【机器人】复现 StreamVLN 具身导航 | 流式VLN | 连续导航

StreamVLN 通过在线、多轮对话的方式，输入连续视频，输出动作序列。 通过结合语言指令、视觉观测和空间位姿信息，驱动模型生成导航动作（前进、左转、右转、停止）。 论文地址：StreamVLN: Streaming Vision-and-Language Navigation via SlowFast Context Modeling 代码地址：https://github.com/OpenRobotLab/StreamVLN 本文分享StreamVLN 复现和模型推理的过程～ 下面是示例效果： 1、创建Conda环境 首先创建一个Conda环境，名字为streamvln，python版本为3.9； 然后进入streamvln环境，执行下面命令： conda create -n streamvln python=3.9 conda activate streamvln 2、 安装habitat仿真环境
目标检测数据集——无人机视觉VisDrone数据集

目标检测数据集——无人机视觉VisDrone数据集

随着无人机技术的飞速发展，无人机在航拍、监控、农业、物流等领域的应用日益广泛。与此同时，无人机视角下的视觉任务，如目标检测、目标跟踪和场景理解，也成为了计算机视觉研究的热点。然而，相比传统的地面视角数据集，无人机视角下的图像具有高度变化、小目标密集、复杂背景等独特挑战，这对现有算法提出了更高的要求。 为了应对这些挑战并推动无人机视觉技术的发展，天津大学机器学习与数据挖掘实验室推出了 VisDrone数据集。作为一个大规模、标注精细的无人机视觉数据集，VisDrone 不仅涵盖了丰富的场景和多样化的目标类别，还为研究人员提供了一个极具挑战性的测试平台。无论是小目标检测的精度提升，还是密集场景下的鲁棒性优化，VisDrone 都成为了学术界和工业界不可或缺的资源。该数据集采集自中国14个不同城市，覆盖复杂城市场景、交通枢纽、密集人群等多种环境。 VisDrone官方Github下载渠道可点击访问： https://github.com/VisDrone/VisDrone-Dataset?tab=readme-ov-file 下载的数据集为VisDrone2019-DET-train