使用 uv 管理 PyTorch 项目
PyTorch 生态系统的包管理具有特殊性，uv 提供了灵活的方式来管理其依赖，支持跨 Python 版本和环境，并能控制加速器类型（如 CPU-only 或 CUDA）。
PyTorch 的包管理特点
- 专用索引：许多 PyTorch 轮子发布在专用索引（如
https://download.pytorch.org/whl/*），而非默认的 PyPI。
- 加速器标识：不同加速器（CPU、CUDA、ROCm、XPU）的构建通过本地版本说明符区分（如
+cpu、+cu130）。
- 分散发布：不同加速器的构建发布在不同的索引上。
使用 uv 项目接口配置
默认配置（uv init 后 uv add torch）会从 PyPI 安装，该索引在 Windows/macOS 提供 CPU 轮子，在 Linux 提供 CUDA 轮子。
指定 PyTorch 索引
若需在所有平台使用特定变体（如全部使用 CPU 构建），需在 pyproject.toml 中添加索引并配置源。
- 添加索引：在
[tool.uv.index] 下添加对应加速器的索引 URL，并设置 explicit = true，确保该索引仅用于 PyTorch 相关包。[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true
- 配置源：在
[tool.uv.sources] 中为 torch 和 torchvision 指定索引。[tool.uv.sources]
torch = [{ index = "pytorch-cpu" }]
torchvision = [{ index = "pytorch-cpu" }]
- 平台限制：对于不支持某些加速器的平台（如 macOS 不支持 CUDA），需使用
marker 字段限制索引应用范围。[tool.uv.sources]
torch = [{ index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" }]
通过环境标记配置加速器
可通过 sys_platform 标记为不同平台指定不同索引。例如，Linux 使用 CUDA 13.0，其他平台使用 CPU：
[tool.uv.sources]
torch = [
{ index = "pytorch-cpu", marker = "sys_platform != 'linux'" },
{ index = "pytorch-cu130", marker = "sys_platform == 'linux'" },
]
通过可选依赖配置加速器
可将不同加速器配置为可选依赖，用户通过 uv sync --extra 选择。需在 [tool.uv.conflicts] 中声明互斥的 extras。
[project.optional-dependencies]
cpu = ["torch>=2.11.0"]
cu130 = ["torch>=2.11.0"]
[tool.uv.sources]
torch = [
{ index = "pytorch-cpu", extra = "cpu" },
{ index = "pytorch-cu130", extra = "cu130" },
]
注意：GPU 加速构建在 macOS 上不可用，启用对应 extra 会导致安装失败。
使用 uv pip 接口
也可通过 uv pip 直接安装，使用 PyTorch 官方提供的索引 URL。
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cpu
自动后端选择
uv pip 支持自动检测系统 GPU 并选择最合适的 PyTorch 索引。
# 自动检测
uv pip install torch --torch-backend=auto
# 或指定后端
uv pip install torch --torch-backend=cu130
该功能仅适用于 uv pip 接口。