4、环境搭建：Python环境、CUDA/GPU配置、安装LLaMA-Factory、依赖包管理与常见安装问题

大模型微调的第一步，也是最容易劝退初学者的一步，就是环境搭建。很多学员在跑通第一个微调实验之前，往往耗费数天时间在CUDA版本冲突、Python解释器错乱、依赖包互相覆盖等问题上。本章将围绕“Python虚拟环境→GPU驱动与CUDA→LLaMA-Factory安装→依赖冲突排查”这条主线，帮助你建立一套可复现、可排障、可迁移的环境搭建方法论。我们不仅讲“怎么装”，更讲“为什么这样装”以及“装坏了怎么救”。

LLaMA-Factory 环境搭建工程链路 GPU 硬件与驱动 NVIDIA Driver ≥ 525 nvidia-smi 验证 CUDA 运行时 CUDA 11.8 / 12.1 nvcc -V 验证 Python 3.10/3.11 conda create -n llm python -V 验证 PyTorch torch.cuda.is_available() = True LLaMA-Factory 安装 git clone + pip install -e . 或 pip install llama-factory 依赖包管理 requirements.txt / pipdeptree 验证与排障闭环 llamafactory-cli version → 跑通 LLaMA-3-8B 单卡 LoRA 最小实验 常见安装问题 CUDA 版本不匹配 bitsandbytes 编译失败 transformers 版本冲突 显存不足 OOM 图：LLaMA-Factory 环境搭建的依赖链路与排障入口

上图展示了环境搭建的完整工程链路：从GPU硬件驱动出发，逐层向上构建CUDA运行时、Python虚拟环境、PyTorch深度学习框架，最终安装LLaMA-Factory并完成依赖管理。任何一个底层环节出现版本错位，都会在上层暴露为难以理解的报错。因此，我们建议严格按照“自底向上”的顺序进行搭建与验证。

4.1 Python虚拟环境：隔离是避免冲突的第一道防线

核心原理：Python的包管理机制（pip）默认将第三方库安装到全局site-packages目录。不同项目对同一库的版本要求往往不同——例如项目A需要transformers 4.40，项目B需要4.45，若共用全局环境，必然产生冲突。虚拟环境（virtualenv/conda env）通过创建独立的Python解释器副本和包安装目录，实现项目间依赖的完全隔离。对于大模型微调，我们强烈推荐使用Conda，因为它不仅能管理Python包，还能精确控制Python版本（如3.10或3.11），并天然支持CUDA相关工具的安装。

操作流程：

  1. 安装Miniconda（推荐）或Anaconda，下载对应Linux x86_64安装包后执行 bash Miniconda3-latest-Linux-x86_64.sh。
  2. 创建专用虚拟环境并指定Python版本：
    conda create -n llm-factory python=3.10 -y
conda activate llm-factory
  3. 验证环境有效性：which python 应指向conda环境路径，python -V 显示3.10.x。
  4. 为pip配置国内镜像源（如清华源）以加速下载：
    pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

实战场景：某学员在服务器上已有TensorFlow 2.10环境（依赖Python 3.9），现在需要微调LLaMA-3-8B。若直接在全局环境安装PyTorch 2.1，极大概率破坏TensorFlow的依赖。通过创建独立的 llm-factory 环境，两个框架互不干扰，且可以随时切换。

常见误区：不要使用 sudo pip install 安装任何包。sudo会绕过虚拟环境，将包安装到系统Python中，不仅污染系统环境，还可能因权限问题导致部分包编译失败。始终确保在激活的conda环境中执行pip命令。

4.2 CUDA/GPU配置：驱动、运行时与PyTorch的三层匹配

核心原理：GPU计算环境分为三层：NVIDIA驱动（与操作系统直接交互）、CUDA Toolkit（提供编译器和运行时库）、PyTorch的CUDA绑定（调用CUDA API）。驱动版本决定支持的最高CUDA版本，而PyTorch在安装时已绑定特定CUDA版本（如cu118、cu121）。关键原则是：驱动版本 ≥ 所需CUDA版本，但PyTorch的CUDA版本不必与系统CUDA Toolkit完全一致，因为PyTorch自带CUDA运行时库。

判断方法：

检查项命令预期结果
GPU型号与驱动nvidia-smi显示GPU型号、驱动版本（≥525）、显存容量
CUDA Toolkit版本nvcc -V显示CUDA版本（如11.8或12.1）
PyTorch CUDA可用性python -c "import torch; print(torch.cuda.is_available())"输出 True

操作流程：

  1. 运行 nvidia-smi 确认驱动版本。若驱动过旧，需从NVIDIA官网下载对应驱动更新。
  2. 根据驱动版本选择CUDA Toolkit。例如驱动版本为535，可安装CUDA 12.1；若驱动为525，建议CUDA 11.8。
  3. 安装PyTorch时，通过官方命令选择匹配的CUDA版本：
    pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
  4. 验证GPU可用性：
    python -c "import torch; print(torch.cuda.get_device_name(0))"
案例拆解：某学员在RTX 4090上安装PyTorch 2.0（默认CUDA 11.7），运行微调时报错 CUDA error: no kernel image is available for execution on the device。原因是RTX 4090（Ada Lovelace架构）需要CUDA 11.8+才能支持。解决过程：① 检查驱动版本为530，满足要求；② 卸载旧版PyTorch；③ 安装cu121版本PyTorch；④ 重新验证 torch.cuda.is_available() 为True。此案例说明，GPU架构比驱动版本更关键，新卡必须搭配新CUDA。

4.3 安装LLaMA-Factory：源码安装与pip安装的选择

核心原理：LLaMA-Factory提供两种安装方式：pip安装（pip install llama-factory）适合快速体验，但可能不是最新代码；源码安装（git clone + pip install -e .）适合开发调试，能实时获取更新。对于课程学习和生产实践，我们推荐源码安装，因为微调过程中经常需要修改源码或查看内部实现。

操作流程（源码安装）：

git clone https://github.com/hiyouga/LLaMA-Factory.git
cd LLaMA-Factory
pip install -e .

安装完成后，验证安装：llamafactory-cli version 应输出版本号。若需使用LoRA微调，还需安装额外依赖：pip install peft bitsandbytes。

依赖包管理要点：

  • 使用 pip list 查看已安装包版本，重点检查 transformers、datasets、accelerate、peft 的版本兼容性。
  • 遇到依赖冲突时，使用 pipdeptree 分析依赖树：pip install pipdeptree && pipdeptree。
  • 若安装bitsandbytes失败（常见于Windows或旧版CUDA），可尝试源码编译或使用CPU版本降级方案。
常见安装问题与对策：
问题现象可能原因解决方案
pip install 时出现 ERROR: Could not find a version that satisfies the requirementPython版本过低或包名错误确认Python≥3.9，检查包名拼写
import torch 报错 ModuleNotFoundError: No module named 'torch'未激活虚拟环境或PyTorch未安装执行 conda activate llm-factory 后重新安装
bitsandbytes 安装后无法导入CUDA版本与bitsandbytes预编译版本不匹配安装匹配的版本：pip install bitsandbytes==0.43.0
显存不足（OOM）模型过大或batch_size过大使用LoRA/QLoRA，降低batch_size，开启梯度累积

案例拆解（完整排障闭环）：某学员在Ubuntu 20.04上安装LLaMA-Factory时，执行 pip install -e . 后出现 ERROR: Cannot uninstall 'certifi'。分析：系统Python 3.8的certifi被系统包管理器锁定。处理步骤：① 创建新的conda环境（Python 3.10）；② 重新执行源码安装；③ 安装成功后运行 llamafactory-cli version 验证。整个过程耗时15分钟，核心教训是不要与系统Python纠缠，直接使用全新虚拟环境。

总结复盘：环境搭建的本质是版本管理。建议每位学员在开始微调前，先记录一份环境清单（Python版本、CUDA版本、PyTorch版本、LLaMA-Factory版本），并保存为 environment.yml 或 requirements.txt，以便后续复现。遇到问题时，按照“驱动→CUDA→PyTorch→LLaMA-Factory”的层次逐层排查，避免盲目重装。最后，务必跑通一个最小实验（如使用 llamafactory-cli train 微调一个极小模型），确认全链路畅通后再进行正式训练。

← 上一章 📖 返回目录 下一章 →