解决 NVIDIA RTX 50 系列 (sm_120) 架构下的 PyTorch 与 Unsloth 依赖冲突
1. 摘要
在 NVIDIA RTX 50 系列（Compute Capability sm_120）硬件发布初期，部署基于 Unsloth 和 vLLM 的大模型训练环境面临严峻的依赖冲突。主要表现为：标准安装流程默认拉取不支持 sm_120 的旧版 PyTorch (2.5.x)，导致 CUDA 内核无法加载；强制升级 PyTorch 至适配版本 (2.9.x) 后，会导致 Poetry/Pip 的依赖解析器因版本不匹配而死锁。本文档详细记录了绕过 Poetry 依赖锁机制，通过'外科手术式'手动构建环境的完整解决方案。
2. 环境规格
本解决方案仅适用于以下或更新的'Bleeding Edge'前沿开发环境：
- Hardware (GPU): NVIDIA GeForce RTX 5060 Ti (架构代号：sm_120)
- Driver Version: CUDA Driver 13.1
- OS: Linux (Ubuntu 24.04 LTS / Debian 12)
- Python Runtime: Python 3.12
- Package Manager: Poetry (作为虚拟环境管理器), Pip (作为实际安装工具)
- Target Software Stack:
- PyTorch >= 2.9.1 (必须支持 sm_120)
- Unsloth (Nightly/Dev Branch)
- vLLM >= 0.12.0
3. 问题描述
在使用标准命令 pip install unsloth 或配置 pyproject.toml 进行安装时，遇到以下阻断性错误：
3.1 核心错误：架构不兼容
当 PyTorch 版本低于 2.9.0 时，Python 能够导入 torch，但在初始化 CUDA 时抛出警告并导致后续计算失败：
UserWarning: NVIDIA GeForce RTX 5060 Ti with CUDA capability sm_120 is not compatible with the current PyTorch installation. The current PyTorch install supports CUDA capabilities sm_50 ... sm_90.
3.2 依赖地狱 (Dependency Hell)
尝试强制安装 PyTorch 2.9.1 后，Unsloth 和 vLLM 的标准安装脚本因检测到版本'过新'（超出 pyproject.toml 定义的范围）而拒绝安装，或触发无限降级循环，试图将 PyTorch 回滚至 2.5.1。
3.3 组件缺失
由于自动安装脚本无法识别 cu128 或 torch290 等新标签，unsloth_zoo 未被下载，或 vLLM 缺少核心依赖库。
4. 根本原因分析
- 硬件代差 (Hardware Generation Gap): Unsloth 和 vLLM 的稳定版发布滞后于 NVIDIA RTX 50 系列硬件的发布。上游库默认依赖的 PyTorch 2.5.x 尚未包含
sm_120的二进制内核。 - 构建标签缺失: Unsloth 的自动安装脚本 (
_auto_install.py) 在 2025 年 12 月尚未完全适配 PyTorch 2.9+ 的构建标签，导致无法自动拉取对应的 Wheels。 - 解析器僵化: Poetry 和 Pip 的依赖解析器在面对'非正式发布'的预览版库（如 PyTorch 2.9.1+cu128）时，无法正确处理版本约束，导致必须手动干预。
5. 解决方案
警告： 请严格按照以下顺序执行。不要使用 poetry add，必须在 Poetry 虚拟环境中使用 pip 直接操作以绕过锁文件检查。
步骤 1：环境重置 (Clean Slate)
由于之前的尝试导致环境混杂了不同版本的二进制文件，必须彻底重建。
# 移除当前的 Python 环境
poetry env remove python
# 重新安装基础依赖（仅基于 pyproject.toml 中的最简配置）
poetry install
步骤 2：强制安装适配 sm_120 的 PyTorch
这是最关键的一步。必须显式指定 Index URL 并锁定版本。 (注：根据 2025 年 12 月的实际情况，cu124/cu126 仓库可能兼容 cu128 驱动)
poetry run pip install torch==2.9.1 torchvision==0.24.1 torchaudio==2.9.1 --index-url https://download.pytorch.org/whl/cu124
验证标准： 运行 python -c "import torch; print(torch.cuda.get_device_capability())"，必须输出 (12, 0) 或更高，且无 Warning。
步骤 3：手动安装 Unsloth 主程序与组件
由于自动脚本失效，需分别从 GitHub 源码安装主程序和组件库。
# 安装 Unsloth 主程序（跳过依赖检查）
poetry run pip install "unsloth[cu124-torch290] @ git+https://github.com/unslothai/unsloth.git"
# 关键：手动补全 Unsloth Zoo（解决 No module named 'unsloth_zoo'）
poetry run pip install "unsloth_zoo @ git+https://github.com/unslothai/unsloth_zoo.git"
步骤 4：修复 vLLM 及其依赖链
标准安装会触发 PyTorch 降级。需采用 --no-deps 策略安装 vLLM 主程序，随后手动补全依赖链。
# 1. 强制安装 vLLM 主程序，不检查依赖
poetry run pip install vllm --no-deps
# 2. 手动补全 vLLM 所需的依赖树（忽略 Torch 版本冲突）
poetry run pip install fastapi uvicorn openai sentencepiece numpy<3 requests tqdm ray pandas prometheus-client prometheus-fastapi-instrumentator tiktoken protobuf pydantic py-cpuinfo cloudpickle diskcache jsonschema outlines partial-json-parser xgrammar blake3 gguf lark mistral-common msgspec ninja pyzmq scipy transformers>=4.57.0
6. 验证与已知问题
6.1 最终验证脚本
运行以下 Python 脚本进行验收：
import torch
from unsloth import FastLanguageModel
import vllm
print(f"✅ PyTorch Version: {torch.__version__}")
print(f"✅ CUDA Capability: {torch.cuda.get_device_capability()}")
print(f"✅ Unsloth Loaded: True")
print(f"✅ vLLM Version: {vllm.__version__}")
输出： 验证输出显示 CUDA Capability 为 (12, 0)，PyTorch 版本正常。
6.2 已知非阻断性报错 (Non-Blocking Error)
初始化 Unsloth 时可能会出现以下红色报错：
ImportError: cannot import name 'DDPOStableDiffusionPipeline' from 'trl.models'
- 状态：可忽略 (Safe to Ignore)。
- 原因： Unsloth 尝试加载图像生成模型的训练器，但最新的
transformers/diffusers库结构发生了微调。 - 影响： 仅影响 Stable Diffusion 的训练。对于 LLM（如 Qwen, Llama）的训练没有任何副作用。请勿因此尝试降级 Transformers。
7. 结论
在 NVIDIA RTX 50 系列等次世代硬件上配置开发环境时，传统的依赖管理工具往往失效。通过解耦 PyTorch 的底层安装与上层应用库的依赖检查，并采用'源码构建'或'无依赖安装'的策略，可以在官方正式适配前通过'混合版本'方案成功运行训练任务。
