LLaMa-Factory 部署实战：从依赖安装到 llamafactory-cli webui 启动成功的分步验证

在大模型微调与部署领域，LLaMa-Factory 凭借灵活的适配性和轻量化特性，成为开发者快速搭建大模型交互环境的优选工具。但实际部署中，常因依赖版本不兼容、配置参数错误或服务启动链路断裂，导致 llamafactory-cli webui 无法正常打开。本文将以 “分步验证” 为核心，从环境准备到 UI 启动全流程拆解，确保每个环节可验证、问题可定位，帮助开发者零踩坑完成部署。

一、环境准备：搭建基础运行框架

环境是部署的前提，此阶段需重点解决 “系统兼容性” 和 “依赖隔离” 问题，避免后续因环境冲突导致启动失败。

1. 系统与硬件要求验证

首先确认运行环境满足基础条件，避免硬件或系统版本不支持导致的隐性问题：

• 操作系统：推荐 Linux（Ubuntu 20.04+/CentOS 8+）、Windows 10+（需开启 WSL2 或管理员权限）、MacOS 12+（M1/M2 芯片需适配 ARM 架构依赖）；
• 硬件配置：CPU 需 8 核以上（推荐 16 核），内存 ≥ 16GB（若加载 7B 模型需 ≥ 32GB），GPU 可选 NVIDIA GTX 1080Ti 及以上（需支持 CUDA 11.3+，无 GPU 可使用 CPU 模式但启动速度较慢）；
• 网络环境：需联网下载依赖包与模型文件（离线环境需提前准备离线依赖包）。

2. Python 环境与虚拟环境搭建

为避免与系统原有 Python 环境冲突，必须通过虚拟环境隔离依赖，步骤如下：

1. 安装 Python 3.8~3.11（不建议 3.12+，部分依赖暂不支持），验证版本：

   bash

   python --version  # 输出应为 Python 3.8.x ~ 3.11.x
   

2. 选择虚拟环境工具（conda 或 venv），此处以 conda 为例：

   bash

   # 创建名为 llama-factory 的虚拟环境
   conda create -n llama-factory python=3.10 -y
   # 激活虚拟环境（Linux/MacOS）
   conda activate llama-factory
   # Windows 激活命令
   # activate llama-factory
   

3. 验证虚拟环境激活成功：命令行前缀应显示 (llama-factory)，表示当前操作在隔离环境中进行。

二、核心依赖安装：解决版本兼容问题

LLaMa-Factory 依赖较多，且部分库（如 PyTorch、transformers）存在严格版本匹配要求，需按 “基础依赖→GPU 加速依赖→项目依赖” 顺序安装，每步完成后验证完整性。

1. 基础依赖安装与验证

先安装通用基础库，确保 Python 环境具备基本运行能力：

bash

pip install --upgrade pip setuptools wheel

验证：执行 pip list | grep pip，确认 pip 版本 ≥ 22.0，避免因旧版 pip 导致依赖安装失败。

2. GPU/CPU 依赖安装（关键步骤）

根据硬件选择对应依赖，此步骤直接影响后续模型加载与 UI 启动效率：

• GPU 环境（推荐）：需先安装 CUDA 11.3/11.6/12.1（需与 PyTorch 版本匹配），再安装 PyTorch：

  bash

  # CUDA 11.8 为例（需根据本地 CUDA 版本调整）
  pip3 install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cu118
  

• CPU 环境：安装纯 CPU 版本 PyTorch：

  bash

  pip3 install torch==2.0.1 torchvision==0.15.2 torchaudio==2.0.2 --index-url https://download.pytorch.org/whl/cpu
  

验证：执行以下命令，无报错则说明 PyTorch 安装成功（GPU 环境会显示 CUDA 版本）：

bash

python -c "import torch; print(torch.__version__); print(torch.cuda.is_available())"
# GPU 环境输出应为 True，CPU 环境输出为 False