개발 환경 설정
Object Detection 모델을 실행하려면 Python, PyTorch, CUDA 등 여러 라이브러리를 올바른 버전 조합으로 설치해야 합니다. 이 문서에서는 초보자가 가장 빠르게 시작할 수 있는 Google Colab 방법부터, 로컬 PC 설정, 그리고 Docker/Conda 고급 옵션까지 단계별로 안내합니다.
| 항목 | 내용 |
|---|---|
| 권장 Python | 3.10 ~ 3.12 |
| 권장 PyTorch | 2.3 이상 |
| 권장 CUDA | 12.1 ~ 12.4 |
| 핵심 라이브러리 | PyTorch, ultralytics, OpenCV, NumPy |
| 초보자 추천 환경 | Google Colab (설치 불필요, 무료 GPU 제공) |
| 로컬 추천 환경 | Python venv + pip 설치 |
문서 탐색
필수 라이브러리
| 라이브러리 | 용도 | 최소 버전 | 설치 명령 |
|---|---|---|---|
| Python | 전체 실행 환경 | 3.9 | 별도 설치 |
| PyTorch | 딥러닝 프레임워크, GPU 연산 | 2.0 | pip install torch |
| torchvision | 이미지 변환, 사전학습 모델 | 0.15 | PyTorch와 함께 설치 |
| ultralytics | YOLO 모델 전체 파이프라인 | 8.0 | pip install ultralytics |
| OpenCV (cv2) | 이미지/영상 읽기·쓰기·시각화 | 4.8 | pip install opencv-python |
| NumPy | 배열 연산, 좌표 처리 | 1.24 | pip install numpy |
| Pillow | 이미지 포맷 변환 (PNG, JPEG) | 10.0 | pip install Pillow |
| matplotlib | 결과 시각화, 손실 그래프 | 3.7 | pip install matplotlib |
| PyYAML | data.yaml 설정 파일 파싱 | 6.0 | pip install pyyaml |
| tqdm | 학습 진행률 표시 | 4.65 | pip install tqdm |
ultralytics를 설치하면 NumPy, OpenCV, PyYAML, tqdm, Pillow 등 대부분의 의존성이 자동으로 함께 설치됩니다.
GPU 설정 (CUDA/cuDNN)
GPU를 사용하면 CPU 대비 학습 속도가 10~50배 빨라집니다. CUDA 버전과 PyTorch 버전은 반드시 호환되는 조합을 사용해야 합니다.
PyTorch-CUDA 호환 매트릭스
| PyTorch 버전 | CUDA 버전 | cuDNN 버전 | 설치 명령 예시 |
|---|---|---|---|
| 2.5.x | 12.4 | 9.x | pip install torch --index-url https://download.pytorch.org/whl/cu124 |
| 2.4.x | 12.1 | 8.9 | pip install torch --index-url https://download.pytorch.org/whl/cu121 |
| 2.3.x | 12.1 | 8.9 | pip install torch --index-url https://download.pytorch.org/whl/cu121 |
| 2.2.x | 11.8 | 8.7 | pip install torch --index-url https://download.pytorch.org/whl/cu118 |
| 2.1.x | 11.8 | 8.7 | pip install torch --index-url https://download.pytorch.org/whl/cu118 |
CUDA 설치 확인 순서
# 1. NVIDIA 드라이버 및 CUDA 버전 확인
nvidia-smi
# 2. PyTorch에서 CUDA 인식 여부 확인
python -c "import torch; print(torch.cuda.is_available())"
# True 출력되면 정상
# 3. CUDA 버전 확인
python -c "import torch; print(torch.version.cuda)"
# 4. GPU 이름 확인
python -c "import torch; print(torch.cuda.get_device_name(0))"환경 비교
| 환경 | 장점 | 단점 | 비용 | 추천 대상 |
|---|---|---|---|---|
| Google Colab (무료) | 설치 불필요, T4 GPU 제공, 브라우저만 있으면 OK | 세션 12시간 제한, 대용량 데이터 불편 | 무료 | 입문자, 빠른 실험 |
| Google Colab Pro | A100까지 사용 가능, 긴 세션 | 유료 | $10~50/월 | 중급자, 대용량 실험 |
| 로컬 PC (GPU) | 데이터 보안, 세션 제한 없음, 커스터마이징 자유 | 초기 설정 복잡, GPU 구매 비용 | GPU 구매비 | 지속적 연구·개발 |
| AWS EC2 (p3/p4) | 강력한 GPU, 스케일 아웃 | 비용 높음, 설정 필요 | $3~32/시간 | 대규모 학습, 기업 |
| RunPod / Vast.ai | AWS보다 저렴한 GPU 클라우드 | 인터페이스 낯섦 | $0.3~2/시간 | 예산 절약형 |
초보자 추천: Google Colab 시작법
Google Colab은 별도 설치 없이 브라우저에서 바로 GPU를 사용할 수 있어 처음 시작하기에 가장 적합합니다.
1단계: Colab 접속 및 GPU 활성화
colab.research.google.com 접속 → 상단 메뉴 런타임 → 런타임 유형 변경 → 하드웨어 가속기를 T4 GPU로 변경 후 저장
2단계: ultralytics 설치
!pip install ultralytics3단계: GPU 확인
import torch
print(f"CUDA 사용 가능: {torch.cuda.is_available()}")
print(f"GPU 이름: {torch.cuda.get_device_name(0)}")4단계: 첫 추론 실행
from ultralytics import YOLO
model = YOLO("yolo11n.pt") # 자동 다운로드
results = model("https://ultralytics.com/images/bus.jpg")
results[0].show()로컬 PC 설정
최소 사양
| 구성 요소 | 최소 사양 | 권장 사양 |
|---|---|---|
| CPU | Intel i5 / AMD Ryzen 5 | i7 / Ryzen 7 이상 |
| RAM | 8 GB | 16 GB 이상 |
| GPU | NVIDIA GTX 1060 6GB | RTX 3070 / RTX 4070 이상 |
| 저장공간 | SSD 50 GB | SSD 200 GB 이상 |
| OS | Windows 10 / Ubuntu 20.04 | Ubuntu 22.04 권장 |
AMD GPU(ROCm)는 일부 지원되지만 NVIDIA CUDA 대비 호환성이 낮습니다. 가능하면 NVIDIA GPU를 사용하세요.
설치 순서 (Python venv 사용)
# 1. Python 3.10 이상 설치 확인
python --version
# 2. 가상환경 생성 (프로젝트 폴더에서 실행)
python -m venv od_env
# 3. 가상환경 활성화
# Windows:
od_env\Scripts\activate
# macOS/Linux:
source od_env/bin/activate
# 4. PyTorch 설치 (CUDA 12.1 기준, pytorch.org에서 본인 환경에 맞는 명령 확인)
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
# 5. ultralytics 설치 (주요 의존성 자동 포함)
pip install ultralytics
# 6. 추가 라이브러리
pip install matplotlib jupyter
# 7. 설치 확인
python -c "from ultralytics import YOLO; print('설치 완료')"Conda/Docker 옵션
Conda 환경 (패키지 충돌 방지에 유리)
# conda 환경 생성
conda create -n od_env python=3.11 -y
conda activate od_env
# PyTorch 설치 (conda-forge 채널)
conda install pytorch torchvision torchaudio pytorch-cuda=12.1 -c pytorch -c nvidia -y
# ultralytics 설치
pip install ultralyticsDocker 환경 (재현성 보장, 팀 협업에 유리)
# Dockerfile 예시
FROM ultralytics/ultralytics:latest
WORKDIR /workspace
# 추가 패키지 설치
RUN pip install jupyter matplotlib
# 포트 노출 (Jupyter용)
EXPOSE 8888
CMD ["jupyter", "notebook", "--ip=0.0.0.0", "--allow-root"]# Docker 이미지 빌드 및 실행
docker build -t railway-od .
docker run --gpus all -p 8888:8888 -v $(pwd):/workspace railway-od