⚙️환경설정-딥러닝 스택 버전 맞추기

---

0. 전체 프레임

1. GPU & 하드웨어
   • GPU 모델, VRAM 용량, Compute Capability
2. CUDA & 드라이버 레벨
   • NVIDIA Display Driver (Windows)
   • CUDA Driver (드라이버에 포함)
   • (필요 시) CUDA Toolkit (nvcc)
3. Python & PyTorch
   • Python 3.x 버전
   • torch / torchvision / torchaudio + 포함된 CUDA 버전
4. 상위 라이브러리
   • transformers, diffusers, accelerate, peft, deepspeed …
5. 특수 라이브러리 / 레포
   • flash-attn, xFormers, GroundingDINO, 각종 GitHub 연구 코드

---

1. 🍔 STEP 1️⃣ : 나의 GPU 스펙 확인

1-1. GPU 이름 & VRAM 확인

• 💻 Windows 작업 관리자
  • 작업 관리자 → 성능 → GPU

• 🐧WSL/리눅스

  nvidia-smi

[나의 스펙 정리]
GPU: NVIDIA GeForce RTX 4060 Laptop GPU
VRAM: 8GB (8188 MiB)
Driver Version: 566.14
CUDA Version: 12.7

---

2. 🍟 STEP 2️⃣ : Compute Capability(CC)

2-1. 방법 1️⃣ : nvidia-smi

🐧 In Terminal

nvidia-smi --query-gpu=name,compute_cap --format=csv

—

2-2. 방법 2️⃣ : NVIDIA 공식 표

1. 브라우저에서 NVIDIA CUDA GPU Compute Capability 페이지 열기

🔗 https://developer.nvidia.com/cuda-gpus

2. 내 GPU 이름 찾기
3. 옆 열에 있는 Compute Capability 값 확인

—

2-3. 방법 3️⃣ : PyTorch 설치 후 코드로 확인

나중에 환경 만든 뒤 코드로도 한번 더 검증하고 싶을 때 사용하는 방법

import torch
print(torch.cuda.get_device_name(0))
print(torch.cuda.get_device_capability(0))

—

2-4. 방법 4️⃣ : CC로 최소 CUDA 버전 찾기

• NVIDIA 포럼의 Minimum required CUDA version by GPU Threads 참고:
  

🔗 https://forums.developer.nvidia.com/t/minimum-required-cuda-version-by-gpu/276955

---

3. 🌭 STEP 3️⃣ : PyTorch + CUDA 조합

3-1. PyTorch 공식 사이트

1. 브라우저에서 PyTorch Start Locally 페이지 열기

🔗 https://pytorch.org/get-started/locally/

2. 아래 항목 선택:
   - OS: Linux (WSL 사용이면 Linux)
   - Package: pip 또는 conda
   - Language: Python
   - Compute Platform: CUDA 11.8, CUDA 12.1, CUDA 12.6 등 옵션 중 선택
   

🖇️ 내 드라이버 CUDA Version과 매칭

• nvidia-smi 상단의 CUDA Version: X.Y → 이 드라이버가 지원하는 최대 CUDA 런타임 버전 의미
  
• 드라이버의 CUDA 버전보다 낮은 런타임(CUDA 11.8, 12.1, 12.6 등) 모두 호환
• 더 높은 버전(예: 드라이버 12.7인데 CUDA 12.8 wheel)은 공식 지원 범위 밖

💻 현재 내 노트북

• nvidia-smi → CUDA Version: 12.7
• PyTorch 사이트 옵션이 11.8 / 12.6 / 12.8 이라면:
  • ✅ 12.6 (12.6 ≤ 12.7, 안전)
  • ✅ 11.8 (당연히 OK)
  • ⚠️ 12.8 (12.8 > 12.7 → 피하는 게 좋음)

✔️ 규칙 정리

• 드라이버 CUDA 버전 ≥ 선택할 CUDA 런타임 버전 이 되도록 고름
• 가능한 한 가장 높은 버전 중에서 이 조건을 만족하는 것을 선택⇒페이지 하단에 정확한 설치 명령어가 자동 생성됨

⇒ Linux & pip & Python & CUDA 12.6 조합

pip install torch torchvision --index-url https://download.pytorch.org/whl/cu126

—

3-2. wheel 안에 무엇이 들어있는지

• PyTorch wheel (cu11x, cu12x 등) 안에는 CUDA 런타임 + cuDNN이 이미 포함되어 있음.
• 즉, 시스템에 CUDA Toolkit을 따로 안 깔아도 PyTorch는 GPU를 쓸 수 있다.
• CUDA Toolkit (nvcc) 은 나중에

  • flash-attn / GroundingDINO 같은 C++/CUDA ****확장 컴파일

  • 직접 CUDA 코드 작성

    을 할 때만 필요

—

3-3. 예전 torch 버전이 필요한 경우

1. PyTorch Previous Versions 페이지 열기

🔗 https://pytorch.org/get-started/previous-versions/

2. 원하는 버전 섹션을 찾음

---

4. 🍕 STEP 4 : Python 버전

어떤 Python으로 환경을 만들지 정하는 단계

4-1. 일반 기본값

• Python 3.10 을 기본값으로 씀(2025년 기준)

—

4-2. 라이브러리가 Python 버전을 제한하는 경우

예시:

• transformers 최신 버전(2025 기준)
  

🔗 https://pypi.org/project/transformers/

---

5. 🥞 STEP 5 : 라이브러리별 버전 맞추기

5-1. Transformers

🔗 https://huggingface.co/docs/transformers/index

설치 기본:

pip install "transformers[torch]"

—

5-2. flash-attn

파이토치 + CUDA + GPU 아키텍처(Compute Capability) 버전에 예민

5-2-1. 요구스펙

• FlashAttention-2: 일반적으로 CUDA 12.0 이상 요구

🔗 https://github.com/Dao-AILab/flash-attention

➡️ GitHub의 README.md 읽기

5-2-3. 빌드 에러 발생 시 체크 포인트

• nvcc: command not found → CUDA Toolkit 없음 or PATH 문제
  • 해결: conda cuda-toolkit 설치 + CUDA_HOME=$CONDA_PREFIX 설정
• cuda_runtime.h: No such file or directory → CUDA 헤더 인식 실패
  • 해결: CUDA_HOME / CUDA_PATH 환경변수 설정
• sm_XX is not supported → 내 GPU Compute Capability가 요구사항보다 낮음 (하드웨어 한계)
  

—

5-3. diffusers, xFormers 등 기타 라이브러리

공통 패턴

1. PyPI / GitHub README에서
   • 최소 torch / Python / CUDA 조건 확인

---

6. 🍖 STEP 6 : 모델 버전 맞추는 워크플로우

처음 보는 레포인데, 어떤 버전 조합으로 env를 만들지 정하는 루틴

6-1. 먼저 읽을 파일

• README.md
  • Installation / Requirements / Environment 섹션
• requirements.txt
• pyproject.toml / setup.cfg
• environment.yml (conda 환경 스냅샷)

—

6-2. 뽑아야 할 정보

항목	값 예시
Python	3.9+
torch	2.1.0 ~ 2.3.x
CUDA	11.8 / 12.1
transformers	≥ 4.39.0
기타	xFormers 0.0.23, flash-attn 2.5

---

7. 🥤 STEP 7 : 문제 발생 시 역추적 디버깅 플로우

7-1. torch.cuda.is_available() == False

1. 드라이버 레벨 확인

   nvidia-smi
   

2. torch CUDA 정보 확인 명령어
   

🐹 저는 지금 True로 나오지만 이 명령어를 쳤을 때, False가 나온다면 cuda를 사용 못한다는 뜻입니다!

---

7-3. C++/CUDA 확장 빌드 에러 (flash_attn, GroundingDINO, custom ops …)

• nvcc: command not found → CUDA Toolkit 없음
  • 해결: conda cuda-toolkit 설치 또는 PATH 설정

⚙️ Path설정은…

• cuda_runtime.h: No such file or directory → CUDA 헤더 경로 인식 실패
  • 해결:

    export CUDA_HOME=$CONDA_PREFIX
    export CUDA_PATH=$CONDA_PREFIX
    

• sm_XX is not supported → 내 GPU Compute Capability가 요구 버전보다 낮음
  • 사실상 GPU를 바꾸지 않는 이상 해결 불가

---

🐹 Hamzzi_lover가 배운 점 🐹

💦 GPU를 쓰는 모델들은 라이브러리 버전에 매우 민감하다

💦 해당 모델에 대한 설치 버전을 상세히 알고 싶으면 GitHub의 README.me를, Hugging Face의 모델 설명을 잘 읽어보자

💦 그냥 무턱대고 버전 안맞추고 conda 환경을 맞추면 개고생🐕 한다

💦 모델마다 맞춤형 conda를 맞추고 내 그래픽 스펙을 잘 기억하고 있자

💦 버전은 항상 찾아보면서 맞춰보자! ⇒ Nvidia 공홈에 잘 나와있다

💦 버전 맞추기는 익숙해지지 않는다.. ⇒ 받아들이자!