环境配置概述
目标：在 Linux 上创建独立的 Python 3.10/3.11 开发环境，安装并验证以下 GPU 加速依赖（CUDA 12.1）：
- torch==2.4.0+cu121, torchvision==0.19.0+cu121, torchaudio==2.4.0+cu121
- lightning~=2.4, transformers~=4.45, accelerate~=0.34, datasets~=3.0, bitsandbytes~=0.43, tqdm~=4.66
主要步骤：
- 准备 Python 3.10/3.11 与虚拟环境（venv 或 Conda）
- 配置 PyTorch CUDA 12.1 的专用索引源
- 分两步安装：先装三件套（torch/vision/audio）再装其余包
- 运行验证脚本（GPU 可用性、关键库导入、简单训练/推理）
- 提供常见问题排查与可替代方案
前置条件检查
- 硬件与驱动
- NVIDIA GPU（Compute Capability >= 6.0 推荐）
- NVIDIA 驱动版本：建议 ≥ 530（CUDA 12.1 需要该级别或更高）
- 无需单独安装 CUDA Toolkit；PyTorch cu121 轮子自带运行时
[Linux Bash]
nvidia-smi
# 确认能看到 GPU，Driver Version >= 530，并且无错误
- 操作系统
- 现代 64 位 Linux 发行版（如 Ubuntu 20.04/22.04、RHEL8/9、Debian 11/12 等）
- Python 版本
- Python 3.10 或 3.11（不支持 3.12）
- 可用的包管理工具：pip（必需），可选：conda/mamba
[Linux Bash]
python3 --version
# 若显示 3.10.x 或 3.11.x，可使用系统 python 创建 venv
分步配置指南
以下提供两种虚拟环境方案，任选其一。推荐优先使用 venv（系统已有 Python 3.10/3.11 时），若系统无合适 Python 或遇到二进制兼容问题，可使用 Conda 方案。
方案A：使用 venv（系统已有 Python 3.10/3.11）
- 创建项目目录并进入
[Linux Bash]
mkdir -p ~/proj-pt-cu121 && cd ~/proj-pt-cu121
- 创建并激活虚拟环境
- 使用 Python 3.11（如无 3.11，可改为 3.10）
[Linux Bash]
python3.11 -m venv .venv
source .venv/bin/activate
python -V
pip -V
- 升级基础工具，设置 PyTorch CUDA 12.1 索引变量
[Linux Bash]
python -m pip install --upgrade pip setuptools wheel
export TORCH_INDEX_URL="https://download.pytorch.org/whl/cu121"
- 安装 PyTorch 三件套（固定 cu121 构建）
[Linux Bash]
pip install --index-url "$TORCH_INDEX_URL" \
torch==2.4.0+cu121 torchvision==0.19.0+cu121 torchaudio==2.4.0+cu121
- 写入其余依赖约束文件并安装
[Linux Bash]
cat > requirements.txt <<'EOF'
lightning~=2.4
transformers~=4.45
accelerate~=0.34
datasets~=3.0
bitsandbytes~=0.43
tqdm~=4.66
EOF
pip install -r requirements.txt
- 记录最终环境快照（便于复现实验）
[Linux Bash]
pip freeze --exclude-editable > requirements-lock.txt
- 可选：为加速/分布式预配置 Accelerate（默认配置）
[Linux Bash]
accelerate config default
# 可使用默认答案生成 ~/.cache/huggingface/accelerate/default_config.yaml
方案B：使用 Conda（Miniforge/Mambaforge/Anaconda 已安装）
- 使用 conda 创建 Python 3.11 环境并激活
[Linux Bash]
conda create -n pt-cu121 python=3.11 -y
conda activate pt-cu121
python -V
- 安装 PyTorch CUDA 12.1（官方推荐方式）
[Linux Bash]
# 安装 PyTorch 2.4.0 + CUDA 12.1（conda 构建）
conda install -y pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.1 -c pytorch -c nvidia
- 安装其余依赖
[Linux Bash]
pip install "lightning~=2.4" "transformers~=4.45" "accelerate~=0.34" \
"datasets~=3.0" "bitsandbytes~=0.43" "tqdm~=4.66"
pip freeze --exclude-editable > requirements-lock.txt
环境验证方法
- 基础检查（Python、pip、CUDA）
[Linux Bash]
python - <<'PY'
import sys, torch
print("Python:", sys.version)
print("Torch:", torch.__version__)
print("Torch CUDA:", torch.version.cuda)
print("CUDA available:", torch.cuda.is_available())
if torch.cuda.is_available():
print("CUDA device count:", torch.cuda.device_count())
print("Current device:", torch.cuda.current_device())
print("Device name:", torch.cuda.get_device_name(0))
# 简单 GPU 张量运算
a = torch.randn((1024, 1024), device="cuda")
b = torch.randn((1024, 1024), device="cuda")
c = a @ b
print("Matmul OK, c.shape =", tuple(c.shape))
PY
期望：
- Torch 版本为 2.4.0
- Torch CUDA 为 12.1
- CUDA available: True（GPU 场景）
- Matmul OK 输出
- 关键库导入与版本回显
[Linux Bash]
python - <<'PY'
import torchvision, torchaudio, transformers, accelerate, datasets, bitsandbytes, lightning
print("torchvision:", torchvision.__version__)
print("torchaudio:", torchaudio.__version__)
print("transformers:", transformers.__version__)
print("accelerate:", accelerate.__version__)
print("datasets:", datasets.__version__)
print("bitsandbytes:", bitsandbytes.__version__)
print("lightning:", lightning.__version__)
PY
- bitsandbytes CUDA 检测（诊断信息）
[Linux Bash]
python - <<'PY'
from bitsandbytes.cuda_setup import main_check
main_check() # 打印 bnb 与 CUDA/驱动的检查结果
PY
- Transformers/HF 快速推理（使用极小模型，避免大文件下载）
[Linux Bash]
python - <<'PY'
import torch
from transformers import AutoTokenizer, AutoModelForCausalLM, pipeline
model_id = "sshleifer/tiny-gpt2" # 体积极小的测试模型
tok = AutoTokenizer.from_pretrained(model_id)
model = AutoModelForCausalLM.from_pretrained(model_id, torch_dtype=torch.float16 if torch.cuda.is_available() else torch.float32)
pipe = pipeline("text-generation", model=model, tokenizer=tok, device=0 if torch.cuda.is_available() else -1)
out = pipe("Hello, PyTorch", max_new_tokens=5)
print(out[0]["generated_text"])
PY
- Datasets 简单校验（离线构建小数据集）
[Linux Bash]
python - <<'PY'
from datasets import Dataset
ds = Dataset.from_dict({"text": ["hello", "world", "datasets"], "label": [0,1,0]})
print(ds)
print(ds[:2])
PY
- Lightning 快速训练自检（fast_dev_run）
[Linux Bash]
python - <<'PY'
import torch
from torch.utils.data import DataLoader, TensorDataset
import lightning as L
class TinyModule(L.LightningModule):
def __init__(self):
super().__init__()
self.net = torch.nn.Sequential(
torch.nn.Linear(10, 32),
torch.nn.ReLU(),
torch.nn.Linear(32, 2)
)
self.loss = torch.nn.CrossEntropyLoss()
def forward(self, x):
return self.net(x)
def training_step(self, batch, batch_idx):
x, y = batch
logits = self(x)
loss = self.loss(logits, y)
self.log("train_loss", loss)
return loss
def configure_optimizers(self):
return torch.optim.AdamW(self.parameters(), lr=1e-3)
X = torch.randn(128, 10)
y = torch.randint(0, 2, (128,))
dl = DataLoader(TensorDataset(X, y), batch_size=32, shuffle=True)
trainer = L.Trainer(
accelerator="gpu" if torch.cuda.is_available() else "cpu",
devices=1, max_epochs=1, fast_dev_run=True, enable_model_summary=False, logger=False
)
trainer.fit(TinyModule(), dl)
print("Lightning fast_dev_run OK")
PY
- Accelerate 环境信息
[Linux Bash]
accelerate env
故障排除
- CUDA 不可用（torch.cuda.is_available() == False）
- 检查驱动：nvidia-smi 是否正常显示 GPU 与驱动版本（≥ 530）
- 是否错误安装了 CPU 版 PyTorch：确认 torch.version 带有 +cu121 且 torch.version.cuda == "12.1"
- 如非 cu121，请先卸载后重装：
[Linux Bash]
pip uninstall -y torch torchvision torchaudio
pip cache purge
pip install --index-url "https://download.pytorch.org/whl/cu121" \
torch==2.4.0+cu121 torchvision==0.19.0+cu121 torchaudio==2.4.0+cu121
- bitsandbytes 导入失败或提示 GLIBCXX/GLIBC 版本不匹配
- 现象：ImportError/undefined symbol 与 libstdc++.so 相关
- 解决：
- 优先尝试 Conda 环境（Conda 提供更完整的 C++ 运行时依赖）：
[Linux Bash]
# 进入 Conda 方案（见上文方案B），并在同一环境中安装其余依赖
conda create -n pt-cu121 python=3.11 -y
conda activate pt-cu121
conda install -y pytorch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0 pytorch-cuda=12.1 -c pytorch -c nvidia
pip install "bitsandbytes~=0.43" "transformers~=4.45" "accelerate~=0.34" "datasets~=3.0" "lightning~=2.4" "tqdm~=4.66"
- 或升级系统 libstdc++（需管理员权限，因发行版差异较大，此处不提供统一命令，建议遵循系统官方文档）
- 报错 “Illegal instruction” 或 “AVX 指令不支持”
- 部分老旧 CPU 不支持所需向量指令集。建议迁移到支持 AVX/AVX2 的机器或使用 Docker/Conda 的兼容构建（仍可能受限于硬件）
- Transformers/Accelerate 下载超时或网络问题
- 可预下载模型到本地或配置 HTTP(S) 代理
- 确保已激活虚拟环境：which python / which pip / which accelerate 应指向当前环境
- 版本冲突检查
[Linux Bash]
pip check
# 若有冲突，按报错提示的版本范围进行微调（优先固定较新的兼容小版本）
- 使用 CPU 作为应急回退
- 若 GPU 侧依赖临时不可用，可先以 CPU 验证上层逻辑（替换为 CPU 构建的 torch==2.4.0，无 +cu121；此为回退手段，不建议与目标要求长期并存）
[Linux Bash]
pip uninstall -y torch torchvision torchaudio
pip install torch==2.4.0 torchvision==0.19.0 torchaudio==2.4.0
备注与最佳实践
- 固定核心依赖版本，避免无意升级导致不兼容；通过 requirements-lock.txt 复现环境
- 不混用系统级 pip 与虚拟环境 pip；始终确认
which pip 指向 .venv/bin/pip 或 conda env
- 无需单独安装 CUDA Toolkit；仅需合适的 NVIDIA 驱动与对应的 cu121 轮子
- 将大模型/数据缓存目录设置到有足够空间的磁盘（可选）
[Linux Bash]
mkdir -p ~/hf-cache
export HF_HOME=~/hf-cache
按照以上步骤，您将获得一个可复现、与 CUDA 12.1 匹配的 PyTorch/Lightning/Hugging Face 开发环境，并通过了 GPU 运算、库导入、推理与训练的最小验证。
