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

【GitHub项目推荐--Toonflow AI短剧工厂：一站式AI短剧创作平台】

简介 Toonflow AI短剧工厂是一个革命性的AI驱动短剧创作平台，由HBAI-Ltd团队开发。该项目致力于将小说文本智能转化为完整的短剧视频，实现从文字到影像的全流程自动化。通过集成先进的大语言模型、图像生成和视频合成技术，Toonflow让用户只需动动手指，就能将小说秒变剧集，创作效率提升10倍以上。 核心价值： * 全流程AI化：从文本到角色，从分镜到视频，0门槛完成短剧创作 * 效率革命：创作效率提升10倍+，大幅缩短制作周期 * 智能转换：自动将小说转化为结构化剧本和视觉内容 * 开源免费：基于AGPL-3.0许可证，完全开源且免费使用 技术定位：Toonflow填补了文学创作与影视制作之间的技术鸿沟。通过标准化的AI工作流，它为内容创作者提供了从创意到成品的完整解决方案，降低了视频制作的专业门槛。 主要功能 1. 智能角色生成 系统自动分析原始小说文本，智能识别并生成角色设定。生成内容包括角色的外貌特征、性格特点、身份背景等详细信息。为后续剧本创作和画面设计提供可靠的角色基础。支持批量角色生成，快速构建完整的角色库。 2. 自动化剧本生成 基
AI 的智能体专栏：手把手教你用豆包打造专属 Python 智能管家，轻松解决编程难题

AI 的智能体专栏：手把手教你用豆包打造专属 Python 智能管家，轻松解决编程难题

AI 的智能体专栏：手把手教你用豆包打造专属 Python 智能管家，轻松解决编程难题 AI 的智能体专栏：手把手教你用豆包打造专属 Python 智能管家，轻松解决编程难题，本文介绍了如何利用豆包平台打造专属Python智能管家。首先简述豆包平台的核心优势，接着说明创建前的准备工作，包括注册账号、明确定位和收集训练资料。随后详细讲解创建流程，从新建智能体、基础设置、能力配置到测试优化，还提及集成代码执行环境等高级功能扩展，以及使用技巧与实际应用案例。该智能官能解决多种Python编程问题，可提升学习效率和问题解决速度，是实用的个性化编程助手。 前言     人工智能学习合集专栏是 AI 学习者的实用工具。它像一个全面的 AI 知识库，把提示词设计、AI 创作、智能绘图等多个细分领域的知识整合起来。无论你是刚接触 AI 的新手，还是有一定基础想提升的人，都能在这里找到合适的内容。从最基础的工具操作方法，到背后深层的技术原理，专栏都有讲解，还搭配了实例教程和实战案例。这些内容能帮助学习者一步步搭建完整的 AI 知识体系，让大家快速从入门进步到精通，
10月实测：2025年最好用的12款ai写小说工具（含优劣对比）

10月实测：2025年最好用的12款ai写小说工具（含优劣对比）

最近，ai写小说的风刮得特别大，各种写小说软件层出不穷，很多人问我这些工具到底能不能用。 我花了不少时间，把市面上主流的12款工具都试用了一遍。今天就跟大家掏心窝子聊聊，这些工具哪些是真能帮上忙的“助手”，哪些又是纯粹浪费时间的“玩具”。 我会按照我自己的测评标准，从定位（适合谁）、核心功能（能干嘛）、使用场景（我怎么用），以及最重要的踩坑/建议（避坑指南）这几个方面来说，保证大家看完就能懂，不踩坑。 01、笔灵（一键生成整部小说的创作神器） 传送门：https://ibiling.cn/novel-editor?from=ZEEKLOGeditorgx711（建议复制链接到电脑浏览器打开体验更佳！） 定位： 面向小说作者的综合创作平台，偏重把设定变成实盘稿件并能保存续写。 核心功能： 它的 AI写全篇小说 能按模板一键拉出章节，支持站内保存和一键续写，另外有编辑大纲和素材板块。 使用场景： 我常在凌晨卡文时先让笔灵把整章拉出来当样稿，然后二次改；也会用它保存断更的稿子，续写挺稳。 踩坑/
Flutter 三方库 tiktoken 鸿蒙端侧 AI 重载计算环境适配指南：极尽压榨设备级 BPE 分词器吞吐量边界，打造工业级精控的大模型高昂运算成本阀门-适配鸿蒙 HarmonyOS ohos

Flutter 三方库 tiktoken 鸿蒙端侧 AI 重载计算环境适配指南：极尽压榨设备级 BPE 分词器吞吐量边界，打造工业级精控的大模型高昂运算成本阀门-适配鸿蒙 HarmonyOS ohos

欢迎加入开源鸿蒙跨平台社区：https://openharmonycrossplatform.ZEEKLOG.net Flutter 三方库 tiktoken 鸿蒙端侧 AI 重载计算环境适配指南：极尽压榨设备级 BPE 分词器吞吐量边界，打造工业级精控的大模型高昂运算成本阀门防线 在开发鸿蒙平台的生成式 AI 应用（如大模型助手、智能写作或 Rerank 逻辑）时，如何精确预估 Prompt 的消耗？如何实现窗口精度的截断？tiktoken 提供了一套完整的 OpenAI BPE（字节对编码）分词算法实现。本文将详解该库在 OpenHarmony 上的适配要点。 前言 什么是 tiktoken？它是 OpenAI 为其 GPT 系列模型推出的高性能 BPE 分词器。不同于常规的字符计数，Token 是模型处理文本的最小单位。在鸿蒙操作系统强调的“