Skip to main content

​
dl-env

딥러닝 기본 학습, 평가, 해석 워크플로우를 위한 공통 환경입니다.

​
문서 기준

  • 기준일: 2026-02-23
  • Python: 3.12
  • 운영체제: macOS, Ubuntu, Windows
  • 동기화 명령: uv sync

​
호환성 메모

환경PyTorch 백엔드설명
Ubuntu x86_64 (CUDA)cu130NVIDIA GPU 학습/추론 전체 지원
macOS Apple SiliconmpsMetal Performance Shaders 가속 (M1/M2/M3/M4)
macOS Intel / WindowscpuCPU 전용, GPU 가속 없음
torch==2.10.0은 OS에 관계없이 동일 버전을 설치합니다. GPU 백엔드는 시스템의 CUDA 또는 MPS 런타임에 의해 자동 결정됩니다.

​
주요 패키지 역할

패키지역할비고
torch / torchvision / torchaudio딥러닝 프레임워크 핵심모델 정의, 학습, 추론
scikit-learn전통 ML 알고리즘 및 전처리분류, 회귀, 클러스터링, 파이프라인
xgboost / lightgbm그래디언트 부스팅 앙상블정형 데이터 모델링
statsmodels통계 모델링 및 시계열 분석ARIMA, OLS, 가설 검정
shap모델 해석 (SHAP values)피처 중요도, 의사결정 설명
mlflow실험 추적 및 모델 레지스트리파라미터, 메트릭, 아티팩트 기록
gradio모델 데모 웹 UI빠른 프로토타입 공유
jupyterlab인터랙티브 노트북실험, EDA, 시각화

​
pyproject.toml

[project]
name = "dl-env"
version = "0.1.0"
description = "Deep learning baseline environment"
requires-python = "==3.12.*"
dependencies = [
  "torch==2.10.0",
  "torchvision==0.25.0",
  "torchaudio==2.10.0",
  "scikit-learn==1.8.0",
  "xgboost==3.2.0",
  "lightgbm==4.6.0",
  "statsmodels==0.14.6",
  "shap==0.50.0",
  "mlflow==3.10.0",
  "gradio==6.6.0",
  "jupyterlab==4.5.4",
  "ipykernel==7.2.0",
  "pytest==9.0.2",
  "ruff==0.15.2",
]

[tool.uv]
package = false

​
설치

1

프로젝트 생성

uv init dl-env
cd dl-env
2

의존성 락 및 동기화

uv lock
uv sync
3

Jupyter 커널 등록

uv run python -m ipykernel install --user --name dl-env --display-name "UV dl-env"

​
설치 확인

uv run python -c "import torch, sklearn, xgboost, lightgbm, shap; print('torch', torch.__version__); print('cuda', torch.cuda.is_available()); print('sklearn', sklearn.__version__)"

​
기본 사용 예시

모델 학습부터 SHAP 해석, MLflow 기록까지의 기본 워크플로우입니다. 
import torch
import torch.nn as nn
from sklearn.datasets import load_iris
from sklearn.model_selection import train_test_split
from sklearn.preprocessing import StandardScaler
import shap
import mlflow

# 1) 데이터 준비
X, y = load_iris(return_X_y=True)
X_train, X_test, y_train, y_test = train_test_split(X, y, test_size=0.2)
scaler = StandardScaler().fit(X_train)
X_train, X_test = scaler.transform(X_train), scaler.transform(X_test)

# 2) 모델 정의 및 학습
model = nn.Sequential(nn.Linear(4, 32), nn.ReLU(), nn.Linear(32, 3))
optimizer = torch.optim.Adam(model.parameters(), lr=0.01)
criterion = nn.CrossEntropyLoss()

for epoch in range(50):
    out = model(torch.tensor(X_train, dtype=torch.float32))
    loss = criterion(out, torch.tensor(y_train))
    optimizer.zero_grad(); loss.backward(); optimizer.step()

# 3) 평가
with torch.no_grad():
    preds = model(torch.tensor(X_test, dtype=torch.float32)).argmax(dim=1)
    acc = (preds.numpy() == y_test).mean()

# 4) SHAP 해석
explainer = shap.Explainer(lambda x: model(torch.tensor(x, dtype=torch.float32)).detach().numpy(), X_train)
shap_values = explainer(X_test[:10])

# 5) MLflow 기록
with mlflow.start_run():
    mlflow.log_param("epochs", 50)
    mlflow.log_metric("accuracy", acc)
    mlflow.pytorch.log_model(model, "model")

​
트러블슈팅

증상원인해결
torch.cuda.is_available() == FalseGPU 드라이버 미설치 또는 CUDA 런타임 누락nvidia-smi 확인 후 드라이버/CUDA 설치
torch.backends.mps.is_available() == FalsemacOS 12.3 미만 또는 Intel MacmacOS 업데이트 또는 CPU 모드 사용
uv sync 의존성 충돌기존 락 파일과 버전 불일치uv lock --refresh 후 uv sync
SHAP 연산이 느림대규모 데이터에 KernelExplainer 사용샘플 수를 줄이거나 TreeExplainer 사용
MLflow UI 미표시서버 미실행 상태uv run mlflow ui --port 5000 실행
lightgbm import 오류 (Linux)libomp 라이브러리 누락sudo apt install libomp-dev