byteforce

CPN 한국어 자습서 · 외부 문서 한국어 미러

UV 문서 · Guides

PyTorch와 함께 uv 사용하기

Using uv with PyTorch · 원문: docs.astral.sh/uv/guides/integration/pytorch/

아래는 원문을 한국어로 옮긴 미러입니다. 코드·명령은 원문 그대로이며, 가장 최신 정보는 하단 원문 링크에서 확인하세요.

개요

PyTorch는 인기 있는 딥러닝 프레임워크로, 패키징 측면에서 고유한 과제를 제시합니다. 이 생태계는 다음과 같은 특성을 가집니다: PyTorch 휠은 PyPI가 아닌 전용 인덱스에서 호스팅되며, 다양한 가속기(CPU, CUDA, ROCm 등)는 별도의 빌드를 필요로 하고, 이러한 빌드는 플랫폼별 인덱스에 게시됩니다.

PyTorch 설치하기

기본 구성

uv init과 uv add torch torchvision을 사용하면 기본 설정으로 PyPI에서 설치됩니다:

코드 · 명령
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.14"
dependencies = [
  "torch>=2.11.0",
  "torchvision>=0.26.0",
]

이 구성은 Windows와 macOS의 CPU 전용 휠, Linux의 GPU 가속 빌드(PyTorch 2.11.0 기준 CUDA 13.0 대상)에서 작동합니다.

PyTorch 인덱스 사용하기

플랫폼 간 일관된 빌드를 위해 pyproject.toml에 특정 PyTorch 인덱스를 설정합니다. 사용 가능한 옵션에는 CPU 전용, CUDA 변형(11.8, 12.6, 12.8, 13.0), ROCm 7.2, Intel GPU가 있습니다.

CPU 전용 예시

코드 · 명령
[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[tool.uv.sources]
torch = [
    { index = "pytorch-cpu" },
]
torchvision = [
    { index = "pytorch-cpu" },
]

explicit = true를 사용하면 해당 인덱스가 PyTorch 패키지에만 사용되고, 다른 의존성은 PyPI에서 가져옵니다.

환경 마커로 가속기 설정하기

플랫폼별 마커를 사용하여 플랫폼마다 다른 가속기를 선택합니다. PyTorch는 macOS용 CUDA 빌드를 게시하지 않으므로 CUDA 인덱스를 Linux와 Windows로 제한합니다:

코드 · 명령
[tool.uv.sources]
torch = [
  { index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]
torchvision = [
  { index = "pytorch-cu130", marker = "sys_platform == 'linux' or sys_platform == 'win32'" },
]

[[tool.uv.index]]
name = "pytorch-cu130"
url = "https://download.pytorch.org/whl/cu130"
explicit = true

Linux 전용 ROCm 지원:

코드 · 명령
[tool.uv.sources]
torch = [
  { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
]
torchvision = [
  { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
]
pytorch-triton-rocm = [
  { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
]
triton-rocm = [
  { index = "pytorch-rocm", marker = "sys_platform == 'linux'" },
]

[[tool.uv.index]]
name = "pytorch-rocm"
url = "https://download.pytorch.org/whl/rocm7.2"
explicit = true

선택적 의존성으로 가속기 설정하기

extras를 사용하여 사용자가 다양한 가속기 구성 중에서 선택할 수 있도록 합니다:

코드 · 명령
[project]
name = "project"
version = "0.1.0"
requires-python = ">=3.14.0"
dependencies = []

[project.optional-dependencies]
cpu = [
  "torch>=2.11.0",
  "torchvision>=0.26.0",
]
cu130 = [
  "torch>=2.11.0",
  "torchvision>=0.26.0",
]

[tool.uv]
conflicts = [
  [
    { extra = "cpu" },
    { extra = "cu130" },
  ],
]

[tool.uv.sources]
torch = [
  { index = "pytorch-cpu", extra = "cpu" },
  { index = "pytorch-cu130", extra = "cu130" },
]
torchvision = [
  { index = "pytorch-cpu", extra = "cpu" },
  { index = "pytorch-cu130", extra = "cu130" },
]

[[tool.uv.index]]
name = "pytorch-cpu"
url = "https://download.pytorch.org/whl/cpu"
explicit = true

[[tool.uv.index]]
name = "pytorch-cu130"
url = "https://download.pytorch.org/whl/cu130"
explicit = true

사용자는 uv sync --extra cpu 또는 uv sync --extra cu130으로 설치할 수 있습니다.

uv pip 인터페이스

PyTorch는 uv pip 명령으로도 설치할 수 있습니다. PyTorch의 표준 설치 명령에서 pip3를 uv pip로 대체합니다:

코드 · 명령
$ uv pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

자동 백엔드 선택

uv는 --torch-backend=auto를 통한 자동 PyTorch 백엔드 감지를 지원합니다:

코드 · 명령
$ uv pip install torch --torch-backend=auto
$ UV_TORCH_BACKEND=auto uv pip install torch

활성화되면 uv는 설치된 CUDA 드라이버, AMD GPU 버전, Intel GPU 유무를 조회하여 가장 호환 가능한 인덱스를 선택합니다. GPU가 감지되지 않으면 CPU 전용 빌드로 대체됩니다.

특정 백엔드를 명시적으로 지정합니다:

코드 · 명령
$ uv pip install torch torchvision --torch-backend=cu130
$ UV_TORCH_BACKEND=cu130 uv pip install torch torchvision

참고: --torch-backend 옵션은 현재 프로젝트 인터페이스가 아닌 uv pip 인터페이스에서만 사용할 수 있습니다.

원문(영어): https://docs.astral.sh/uv/guides/integration/pytorch/ · 본 문서는 학습용 한국어 번역이며 원본의 권리는 원저작자(Astral)에게 있습니다.

원문(영어): https://docs.astral.sh/uv/guides/integration/pytorch/