CUDA = Compute Unified Device Architecture（统一计算架构）。专门用于 GPU 通用计算 的平台 + 编程接口。CUDA可以使你的程序（比如矩阵、神经网络）由 GPU 执行，这比CPU能快几十甚至上百倍。
PyTorch 是一个深度学习框架，可以用 Python 来：构建神经网络、加载模型和数据、启动训练和推理、支持 CPU 和 GPU，但Pytorch本身默认使用的CPU，想要Pytorch使用GPU，得安装好 CUDA 运行库（pytorch-cuda），即匹配CUDA兼容的pytorcha版本，这样PyTorch 才能找得到 GPU。
| 比喻角色 | 对应概念 |
|---|---|
| PyTorch 是“程序员” | 写神经网络代码、安排计算 |
| CUDA 是“翻译官” | 把这些代码翻译成显卡能理解的操作指令 |
| GPU 是“工人” | 真正去跑那些深度学习计算任务（卷积、矩阵乘等） |
当前开发环境描述：Windows 11专业版，Python版本 3.10.11，已安装Anaconda（版本 25.5.1）
CUDA的版本可以用命令行来查看（这里的CUDA 是 12.6）：
(ollama_baseline_env) D:\PythonWorkspace\ollama_baseline>nvidia-smi
Sun Jul 27 21:35:04 2025
+-----------------------------------------------------------------------------------------+
| NVIDIA-SMI 560.94 Driver Version: 560.94 CUDA Version: 12.6 |
|-----------------------------------------+------------------------+----------------------+
| GPU Name Driver-Model | Bus-Id Disp.A | Volatile Uncorr. ECC |
| Fan Temp Perf Pwr:Usage/Cap | Memory-Usage | GPU-Util Compute M. |
| | | MIG M. |
|=========================================+========================+======================|
| 0 NVIDIA GeForce RTX 4060 Ti WDDM | 00000000:01:00.0 On | N/A |
| 0% 37C P8 7W / 165W | 934MiB / 16380MiB | 10% Default |
| | | N/A |
+-----------------------------------------+------------------------+----------------------+
注：若 nvidia-smi 命令未能正确显示显卡信息，则可能是未安装显卡驱动、驱动版本老旧、驱动未正确加载等情况。
由于第一次按照教程操作的时候不知道PyTorch默认用的CPU，因此进行了一次再安装的过程，以下是再安装的步骤描述（也可用于初次安装Pytorch的对照）
重新检查并强制安装 GPU 版 PyTorch
请严格按以下命令重新走一遍：
✅ 1. 激活你的虚拟环境
（假设环境名是 agent_gpu）
conda activate agent_gpu✅ 2. 显式卸载可能错误的版本
conda remove pytorch torchvision torchaudio pytorch-cuda -y✅ 3. 再安装 GPU 版 PyTorch + CUDA 11.8
conda install pytorch torchvision torchaudio pytorch-cuda=11.8 -c pytorch -c nvidia这里装的CUDA版本是 11.8，比本机的12.6的版本低，但可以被12.6向下兼容。
安装成功的话，命令行的最后会显示如下信息：
Preparing transaction: done
Verifying transaction: done
Executing transaction: done如果出现如下信息，那就是安装中断了（网络不好，镜像源的负载过大等），可再次执行安装命令（conda安装命令会自动略过已安装的工具包，从中断的位置继续安装），当然，也可以从第二步开始。
('Connection broken: IncompleteRead(73906517 bytes read, 76228566 more expected)', IncompleteRead(73906517 bytes read, )✅ 4. 再次运行验证代码
import torch
print("PyTorch:", torch.__version__)
print("CUDA version in PyTorch:", torch.version.cuda)
print("Is CUDA available?", torch.cuda.is_available())
if torch.cuda.is_available():
print("GPU:", torch.cuda.get_device_name(0))✅ 预期输出应是：
PyTorch: 2.3.0
CUDA version in PyTorch: 11.8
Is CUDA available? True
GPU: NVIDIA GeForce RTX 4060其他工具包的版本选择
开发、部署 AI 项目或 Agent 系统时，工具包的版本选择确实是一个影响系统稳定性的核心因素。
影响 安装工具包版本（如 transformers、peft、torch、accelerate） 的主要因素如下：
| 序号 | 因素类型 | 说明 |
|---|---|---|
| 1️⃣ | Python 版本 | 是最根本的兼容限制，决定能否安装某些工具包 |
| 2️⃣ | CUDA 版本（+ 显卡驱动） | 决定 PyTorch、bitsandbytes 是否能 GPU 加速 |
| 3️⃣ | 操作系统（Windows / Linux / macOS） | 某些工具包仅支持特定系统（如 bitsandbytes） |
| 4️⃣ | PyTorch 版本 | 是大模型训练的核心底座，很多包（如 transformers）要配合使用 |
| 5️⃣ | 目标模型支持要求 | 你想用的模型是否支持当前版本的 transformers / peft |
| 6️⃣ | 项目代码的依赖版本 | 某些开源项目中 requirements.txt 指定了必须版本 |
| 7️⃣ | 虚拟环境内已有包的版本冲突 | pip 会尝试“兼容”已安装的包，可能导致回退或不装新版 |
| 8️⃣ | 你执行的安装命令是否指定版本 | 比如：pip install transformers==4.33 会锁定特定版本 |
| 9️⃣ | PyPI 上可用版本与发布时间 | 某些版本已经从 PyPI 下架，或有 bug 的版本被替换 |
| 🔟 | 代理环境（如清华镜像）或公司镜像 | 某些版本在镜像站同步延迟或不可用 |
如何选择正确的版本组合？下面是推荐的选择顺序：
| 顺序 | 决定方式 | 示例 |
|---|---|---|
| 1️⃣ | 先确认 Python 版本（建议 3.10） | python --version |
| 2️⃣ | 根据你显卡驱动和 CUDA 安装适配 PyTorch | torch==2.2.0+cu121 |
| 3️⃣ | 选择与 torch 兼容的 transformers | 查看 transformers release notes |
| 4️⃣ | 再根据 transformers 选择兼容的 peft / accelerate | pip install transformers==4.41.2 peft==0.10.0 accelerate==0.29.2 |
| 5️⃣ | 查看项目中是否指定 requirements.txt 或 setup.py |
用 pip install -r requirements.txt |
版本冲突问题
本次实验课的执行过程遇到了几个工具包的版本冲突问题，这里将有冲突的几个工具包按照依赖关系的层级进行整理
Python 3.10
├── PyTorch 2.1–2.5 + CUDA 11.8
│ ├── transformers ≥4.39
│ │ ├── AutoTokenizer / AutoModelForCausalLM (支持 Qwen2)
│ │ └── Trainer + TrainingArguments
│ ├── accelerate ≥0.27 (建议 0.29.2)
│ ├── peft ≥0.10.0
│ │ ├── LoRA / QLoRA 微调支持
│ │ └── 调用 transformers API
│ ├── bitsandbytes 0.41.1 （Windows 专用 .whl）
│ │ └── 支持 GPU 精度量化（4bit/8bit）
│ └── huggingface_hub ≥0.29.2（非 egg）
经过多次调试，最终形成的版本组合如下：
Python 3.10.11
PyTorch 2.5.1
CUDA 11.8
transformers 4.39.3
accelerate 0.29.2
peft 0.10.0
bitsandbytes 0.46.1 (Windows whl)
huggingface_hub 0.29.2 (non-egg)使用到的升级命令（供参考）
pip install --upgrade transformers==4.39.3 peft==0.10.0 accelerate==0.29.2
pip uninstall bitsandbytes -y
pip install bitsandbytes‑0.41.1‑py3‑none‑win_amd64.whl
pip uninstall huggingface_hub -y
pip install huggingface_hub==0.29.2 --no-binary huggingface_hub说明：
- 做实验阶段，建议每个项目都配一个专用的虚拟环境，依赖冲突的问题与解决可限制在虚拟环境内，避免依赖影响全局运行。
- transformers、accelerate、peft、bitsandbytes 之间的版本必须统一匹配，老版本或混搭容易引发兼容性问题
- 本次安装的CUDA是12.6版本，与 CUDA 工具包 11.8 完全兼容（向下兼容）。
Windows与Linux的工具包冲突
在 Windows 系统中误用 Linux 编译的包 是很多 Python 工具包报错的常见根源。以下建议可以帮助减少与规避此类问题
✅ 一、优先使用 .whl（Windows Wheel）包安装
像 bitsandbytes、faiss 等 原生支持 Linux 的库，Windows 环境通常不支持默认的 pip install，解决办法：
✔ 正确做法：
到 https://www.lfd.uci.edu/~gohlke/pythonlibs/ 或 bitsandbytes · PyPI
下载.whl文件，如：bitsandbytes‑0.41.1‑py3‑none‑win_amd64.whl然后手动安装：
pip install 路径/文件名.whl❌ 部分工具包的安装，如
pip install bitsandbytes默认拉取 Linux 版，会引发错误
✅ 二、安装前检查平台支持
在安装前先确认该工具包是否支持 Windows：
查阅官方 GitHub 或 PyPI 页面（如 transformers、peft 等会写明支持平台）。
pip install时加上--only-binary限制使用预编译包：pip install peft --only-binary=:all:避免默认从源码构建（源代码构建一般偏向 Linux 环境）。
✅ 三、创建隔离环境（强烈推荐）
使用 Anaconda 或 venv 创建干净的虚拟环境：
conda create -n ollama_env python=3.10
conda activate ollama_env这样不会污染全局环境，也方便管理不同系统包的兼容性。
✅ 四、查依赖树与平台兼容
使用如下命令查看依赖包的来源与平台信息：
pip show bitsandbytespip list --format=columns还可以用：
pipdeptree来查看依赖冲突。
✅ 五、根据错误信息来判断
一些报错会有明显提示如：
.so: ELF format error ← Linux动态库被加载到WindowsNo module named ‘bitsandbytes.cuda_setup’ ← 缺少 Windows 编译部分出现 .so、ELF、libcuda.so 字样，就说明它拉的是 Linux 版。