环境搭建与工具链

阅读顺序：第 3 篇 — 动手搭环境之前建议先读训练环境要求与说明，确认你的机器能跑。

🤖 本文以 WSL2 + Ubuntu 24.04 为准，原生 Linux 完全适用，macOS/Windows 原生请参考末尾的适配说明。

1. 完整工具链概览

训练一条 AI 模型，需要从硬件到软件层层搭建：

text

硬件 (NVIDIA GPU)
  → NVIDIA 驱动（Windows 端安装，WSL/原生 Linux 共用）
    → CUDA Toolkit（GPU 编程平台）
      → cuDNN（深度神经网络加速库）
        → Python + Miniconda（环境管理）
          → PyTorch（深度学习框架）
            → Transformers / PEFT / Accelerate（训练工具库）
              → TensorBoard / WandB（监控可视化）

每一层依赖下一层。下面的安装步骤按这个顺序走。

2. 操作系统基础环境

2.1 确认操作系统

bash

# 确认你当前的环境
cat /etc/os-release | grep PRETTY_NAME
# WSL 用户应输出：PRETTY_NAME="Ubuntu 24.04.4 LTS"
 
uname -m
# 应输出：x86_64（ARM 用户注意：本文仅适用 x86_64）

2.2 更新系统 & 装基础工具

bash

sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git curl wget unzip vim tmux

2.3 WSL 环境优化（仅 WSL 用户）

🔥 关键优化 1：配置 .wslconfig

在 Windows 的 %USERPROFILE%\.wslconfig 中设置资源上限：

ini

[wsl2]
memory=32GB           # 根据你的物理内存调整，留 4~8GB 给 Windows
processors=8          # 根据你的 CPU 核心数调整
swap=8GB              # 启用 swap，防 OOM 崩溃
localhostForwarding=true

修改后重启 WSL：

powershell

# 在 Windows PowerShell 或 CMD 中执行
wsl --shutdown
wsl

⚠️ 默认 WSL 只使用物理内存的 50%，不配置的话大模型直接 OOM 被杀。

🔥 关键优化 2：数据一定要放 WSL 内部

绝对不要把训练数据放在 /mnt/d/（Windows NTFS 挂载点）下！

bash

# ❌ 错误：数据在 Windows 分区，I/O 慢 10~50 倍
dataset_path="/mnt/d/datasets/coco"    # 训练时极端慢！
 
# ✅ 正确：数据在 WSL 内部 ext4 文件系统
cp -r /mnt/d/datasets/coco ~/datasets/
mkdir -p ~/datasets ~/models ~/training

你当前的 wiki 文章在 /mnt/d/ 下面是因为文本对 I/O 不敏感。但模型文件和大数据集千万放 WSL 内部。

🔥 关键优化 3：WSL 磁盘空间膨胀问题

bash

# 查看 WSL 磁盘使用
df -h /
 
# 如果发现 WSL 虚拟硬盘只增不减，在 Windows PowerShell 中压缩：
wsl --shutdown
diskpart
# select vdisk file="C:\Users\你的用户名\AppData\Local\Packages\...\ext4.vhdx"
# compact vdisk

3. 安装 Miniconda（Python 环境管理）

为什么用 conda 而不是直接 pip？ conda 可以：

隔离不同项目的 Python 版本和依赖

一个环境坏了删了重建，不影响其他

比 venv 更好地管理 CUDA 相关包

3.1 安装 Mambaforge（推荐，比 Miniconda 更快）

bash

# 下载 Mambaforge（自带 mamba，安装包速度比 conda 快很多）
wget https://github.com/conda-forge/miniforge/releases/latest/download/Miniforge3-Linux-x86_64.sh
bash Miniforge3-Linux-x86_64.sh
 
# 安装过程中输入 yes 同意 license
# 问是否初始化 conda，输入 yes
# 安装完成后重新打开终端

3.2 创建训练专用环境

bash

# 建议每个大项目创建独立环境，避免冲突
conda create -n ml_env python=3.10 -y
 
# 激活环境（每次训练前都要先运行这行）
conda activate ml_env
 
# 配置国内镜像源（加速下载）
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/main/
conda config --add channels https://mirrors.tuna.tsinghua.edu.cn/anaconda/pkgs/free/
conda config --set show_channel_urls yes

常用 conda 命令	作用
`conda activate ml_env`	激活环境
`conda deactivate`	退出环境
`conda env list`	查看所有环境
`conda env remove -n ml_env`	删除环境（坏了就删了重建）

4. 安装 NVIDIA GPU 环境（WSL 特别版）

WSL 的 GPU 配置和原生 Linux 有两个关键区别：

驱动装在 Windows 端，WSL 内不需要装驱动

CUDA Toolkit 装在 WSL 内，和原生 Linux 一样

4.1 确认 GPU 可访问

bash

# 在 WSL 终端中运行
nvidia-smi

如果正常输出 GPU 信息 → 驱动透传正常，跳过 4.2。

如果提示 command not found → 不是没驱动，只是没装 nvidia-utils，直接确认设备：

bash

ls /dev/nvidia*
# 期望输出：/dev/nvidia0  /dev/nvidiactl  /dev/nvidia-modeset  /dev/nvidia-uvm
# 如果有这些设备，说明 GPU 透传正常，可以装 CUDA Toolkit

如果 /dev/nvidia* 不存在 → 检查 Windows 端是否装了 NVIDIA 驱动。

4.2 安装 CUDA Toolkit 12.4

bash

# 添加 CUDA 源（WSL 专用源）
wget https://developer.download.nvidia.com/compute/cuda/repos/wsl-ubuntu/x86_64/cuda-keyring_1.1-1_all.deb
sudo dpkg -i cuda-keyring_1.1-1_all.deb
sudo apt-get update
 
# 安装 CUDA Toolkit
sudo apt-get install -y cuda-toolkit-12-4
 
# 配置环境变量
echo 'export PATH=/usr/local/cuda/bin:$PATH' >> ~/.bashrc
echo 'export LD_LIBRARY_PATH=/usr/local/cuda/lib64:$LD_LIBRARY_PATH' >> ~/.bashrc
source ~/.bashrc
 
# 验证
nvcc --version

4.3 安装 cuDNN（可选，PyTorch 自带 cuDNN）

bash

# 从 NVIDIA 开发者网站下载 cuDNN for CUDA 12.x（需要注册账号）
# 下载后：
sudo dpkg -i cudnn-local-repo-ubuntu2404-9.3.0_1.0-1_amd64.deb
sudo cp /var/cudnn-local-repo-ubuntu2404-9.3.0/cudnn-*-keyring.gpg /usr/share/keyrings/
sudo apt-get update
sudo apt-get install -y cudnn

💡 绝大多数场景不需要单独装 cuDNN，PyTorch 的 pip 包已经自带了编译好的 cuDNN。

5. 安装 PyTorch 与训练工具库

5.1 安装 PyTorch（核心中的核心）

bash

# 先确认你的 CUDA 版本
nvcc --version
 
# 假设 CUDA 12.4，安装对应版本 PyTorch
conda activate ml_env
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124

验证 GPU 是否被 PyTorch 识别：

bash

python -c "
import torch
print(f'PyTorch: {torch.__version__}')
print(f'CUDA可用: {torch.cuda.is_available()}')
if torch.cuda.is_available():
    print(f'GPU: {torch.cuda.get_device_name(0)}')
    print(f'显存: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB')
"
 
# 期望输出示例：
# PyTorch: 2.4.0
# CUDA可用: True
# GPU: NVIDIA GeForce RTX 3090
# 显存: 24.0 GB

如果 CUDA可用: False，重点排查：

PyTorch 版本是否和 CUDA 版本匹配
是否装了 CPU-only 版本的 PyTorch（用 pip list | grep torch 检查）

5.2 安装训练工具库

bash

# ⭐ 大模型训练全家桶
pip install \
  transformers \          # 加载和微调模型
  datasets \              # 数据处理
  accelerate \            # 分布式训练加速
  peft \                  # LoRA/QLoRA 微调
  bitsandbytes \          # 4bit/8bit 量化
  trl \                   # RLHF/DPO 训练
 
# 📊 监控与可视化
pip install tensorboard wandb
 
# 🛠️ 辅助工具
pip install scikit-learn tqdm jupyter

5.3 框架选择：PyTorch vs TensorFlow

维度	PyTorch 🔥	TensorFlow
上手难度	更 Pythonic，容易上手	较复杂
调试体验	动态图，`print` 直接看	静态图为主，调试麻烦
LLM 生态	HuggingFace 全系支持	支持但少
研究界	绝对主流	使用减少
工业部署	逐步追赶（TorchServe）	TF Serving 成熟

✅ 新人无脑选 PyTorch。当前学术界 + 工业界 LLM 生态全部以 PyTorch 为主。

6. 开发工具配置

6.1 tmux：训练会话保活神器

训练跑一半关掉终端 = 训练中断。用 tmux 可以让你关掉终端窗口，训练继续跑。

bash

# ~/.tmux.conf
cat > ~/.tmux.conf << 'EOF'
set -g mouse on
set -g prefix C-a
unbind C-b
bind C-a send-prefix
bind | split-window -h
bind - split-window -v
bind r source-file ~/.tmux.conf
EOF

bash

# 常用操作
tmux new -s training      # 新建会话
# 训练开始后按 Ctrl+a 然后 d 分离（关闭终端训练继续）
tmux attach -t training    # 重新连回
tmux ls                   # 列出所有会话
tmux kill-session -t training  # 杀掉会话

6.2 VS Code + WSL 远程开发

bash

# 在 WSL 终端中，cd 到项目目录，然后：
code .

第一次运行会自动安装 VS Code Server（在 WSL 中），之后就能像本地一样编辑 WSL 内的文件。

推荐安装的 VS Code 插件（安装在 WSL 端）：

插件	用途
Python	Python 语言支持
Jupyter	交互式 Notebook
GitLens	Git 增强
Remote - WSL	WSL 远程连接（必须）

6.3 Git 配置

bash

git config --global user.name "Your Name"
git config --global user.email "your@email.com"
 
# 如果走代理（WSL 访问 Windows 端的代理需要特殊处理）
# 先获取 Windows 在 WSL 中的 IP
win_ip=$(cat /etc/resolv.conf | grep nameserver | awk '{print $2}')
export http_proxy=http://$win_ip:7890
export https_proxy=http://$win_ip:7890

7. HuggingFace 生态配置

HuggingFace 是训练大模型绕不开的模型/数据集仓库。

7.1 配置国内镜像（解决下载慢）

bash

# 推荐写入 ~/.bashrc，一劳永逸
echo 'export HF_ENDPOINT=https://hf-mirror.com' >> ~/.bashrc
source ~/.bashrc
 
# pip 镜像（只影响 Python 包，不影响模型下载）
pip config set global.index-url https://pypi.tuna.tsinghua.edu.cn/simple

7.2 登录（可选）

bash

# 注册 huggingface.co 后
huggingface-cli login
# 或使用 token
huggingface-cli login --token hf_***

7.3 验证镜像生效

bash

# 下载一个几十 MB 的小模型测试速度
huggingface-cli download gpt2 --local-dir ./gpt2-test
# 如果达到 MB/s 级 → 镜像生效
# 如果只有几 KB/s → 检查 HF_ENDPOINT 配置

8. 一键验证脚本

跑完上述所有步骤后，用这个脚本确认环境是否就绪：

bash

python << 'EOF'
import sys
 
print("=" * 50)
print("训练环境验证脚本")
print("=" * 50)
 
# 1. Python 版本
print(f"\n✅ Python: {sys.version.split()[0]}")
 
# 2. GPU
try:
    import torch
    print(f"✅ PyTorch: {torch.__version__}")
    print(f"✅ CUDA可用: {torch.cuda.is_available()}")
    if torch.cuda.is_available():
        print(f"✅ GPU: {torch.cuda.get_device_name(0)}")
        print(f"✅ 显存: {torch.cuda.get_device_properties(0).total_memory / 1024**3:.1f} GB")
except Exception as e:
    print(f"❌ PyTorch: {e}")
 
# 3. 主要库
libs = [
    ("transformers", "transformers"),
    ("datasets", "datasets"),
    ("accelerate", "accelerate"),
    ("peft", "peft"),
]
for name, lib in libs:
    try:
        __import__(lib)
        print(f"✅ {name}")
    except ImportError:
        print(f"❌ {name} (未安装)")
 
print("\n" + "=" * 50)
EOF

9. 常见问题排查

9.1 GPU / CUDA 问题

现象	原因	解决
`nvidia-smi: command not found`	没装 nvidia-utils	WSL：Windows 端装驱动即可；Linux：`sudo apt install nvidia-utils-535`
`nvidia-smi` 正常但 `torch.cuda.is_available()` 为 False	PyTorch 和 CUDA 版本不匹配	卸载 PyTorch，重装对应 CUDA 版本
`CUDA error: no kernel image`	PyTorch 过旧	升级 PyTorch 到 2.x
`libcusparse.so.12` 找不到	CUDA Toolkit 没装全	`sudo apt install cuda-toolkit-12-4`

9.2 WSL 特有坑

现象	原因	解决
训练极慢	数据在 `/mnt/d/` 下	移到 `~/datasets/`
进程被 kill（无报错退出）	OOM	配置 `.wslconfig` 增加 memory；加 swap
中文显示方块	缺字体	`sudo apt install fonts-noto-cjk`
WSL 时钟错误	时间漂移	`sudo hwclock -s` 或重启 WSL

9.3 显存不足 (OOM) 怎么办

bash

# 策略 1：减小 batch size
TrainingArguments(per_device_train_batch_size=1)  # 从 4 → 2 → 1
 
# 策略 2：梯度累积（等效大 batch，不增加显存）
TrainingArguments(gradient_accumulation_steps=8)
 
# 策略 3：混合精度训练（省显存 + 加速）
TrainingArguments(fp16=True)       # 推荐
TrainingArguments(bf16=True)       # 如果 GPU 支持，效果更好
 
# 策略 4：梯度检查点（用计算换显存）
model.config.use_cache = False
model.gradient_checkpointing_enable()

9.4 环境坏了怎么办

bash

# 查看当前环境装了哪些包
pip list
 
# 导出环境备份
pip freeze > requirements.txt
 
# 最干脆的方法：删了重建
conda deactivate
conda env remove -n ml_env
conda create -n ml_env python=3.10 -y
conda activate ml_env
# 然后重新 pip install ...

10. Docker 环境（进阶玩法）

如果你不想污染本机环境，可以用 Docker：

dockerfile

FROM pytorch/pytorch:2.4.0-cuda12.1-cudnn8-runtime
 
RUN pip install transformers datasets accelerate peft bitsandbytes trl
RUN pip install tensorboard wandb scikit-learn tqdm jupyter
 
WORKDIR /workspace
CMD ["jupyter", "notebook", "--ip=0.0.0.0", "--port=8888", "--no-browser", "--allow-root"]

但有 GPU 透传需求时 Docker 配置比 WSL 复杂，新手阶段不建议用 Docker。

11. macOS (Apple Silicon) 适配说明

如果你用的是 M1/M2/M3/M4 Mac：

bash

# 安装 PyTorch 时指定 MPS 后端
pip install torch torchvision torchaudio
 
# 验证 MPS
python -c "import torch; print(torch.backends.mps.is_available())"

限制：

MPS 只支持 FP32 和 FP16，不支持 BF16
训练速度远不如同价位 NVIDIA GPU
7B+ 模型微调基本不可行（显存 = 系统内存，且带宽不够）
适用场景：学习代码逻辑、推理测试、极小模型实验

12. 环境搭建速查表

python

# WSL 用户：先配 .wslconfig
%USERPROFILE%\.wslconfig  →  memory=32GB, swap=8GB
 
# 然后一行一行执行（不要一次性全贴）
sudo apt update && sudo apt upgrade -y
sudo apt install -y build-essential git curl wget unzip vim tmux
 
# 装 Miniconda
bash Miniforge3-Linux-x86_64.sh
 
# 创建环境
conda create -n ml_env python=3.10 -y
conda activate ml_env
 
# 装 CUDA Toolkit（WSL）
sudo apt install -y cuda-toolkit-12-4
 
# 装 PyTorch
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu124
 
# 装训练库
pip install transformers datasets accelerate peft bitsandbytes trl
pip install tensorboard wandb scikit-learn tqdm
 
# 验证
python -c "import torch; print(torch.cuda.is_available())"

下一篇文章：数据准备与预处理

如果还不确定配置是否够用：训练环境要求与说明

小M-Quartz

探索

环境搭建与工具链

环境搭建与工具链

1. 完整工具链概览

2. 操作系统基础环境

2.1 确认操作系统

2.2 更新系统 & 装基础工具

2.3 WSL 环境优化（仅 WSL 用户）

🔥 关键优化 1：配置 .wslconfig

🔥 关键优化 2：数据一定要放 WSL 内部

🔥 关键优化 3：WSL 磁盘空间膨胀问题

3. 安装 Miniconda（Python 环境管理）

3.1 安装 Mambaforge（推荐，比 Miniconda 更快）

3.2 创建训练专用环境

4. 安装 NVIDIA GPU 环境（WSL 特别版）

4.1 确认 GPU 可访问

4.2 安装 CUDA Toolkit 12.4

4.3 安装 cuDNN（可选，PyTorch 自带 cuDNN）

5. 安装 PyTorch 与训练工具库

5.1 安装 PyTorch（核心中的核心）

5.2 安装训练工具库

5.3 框架选择：PyTorch vs TensorFlow

6. 开发工具配置

6.1 tmux：训练会话保活神器

6.2 VS Code + WSL 远程开发

6.3 Git 配置

7. HuggingFace 生态配置

7.1 配置国内镜像（解决下载慢）

7.2 登录（可选）

7.3 验证镜像生效

8. 一键验证脚本

9. 常见问题排查

9.1 GPU / CUDA 问题

9.2 WSL 特有坑

9.3 显存不足 (OOM) 怎么办

9.4 环境坏了怎么办

10. Docker 环境（进阶玩法）

11. macOS (Apple Silicon) 适配说明

12. 环境搭建速查表

关系图谱

目录

反向链接