DVC 실무 스터디 가이드

1. DVC란?

DVC (Data Version Control)는 머신러닝 프로젝트를 위한 오픈소스 버전 관리 시스템입니다. Git과 함께 동작하며, 데이터셋, 모델, 파이프라인을 추적하고 재현 가능하게 만듭니다.

📦 데이터 버전

대용량 파일도 Git처럼 버전 관리, S3/GCS/SSH 등 원격 저장소와 연동

⚙️ 파이프라인

DAG 기반 단계를 코드로 정의, 변경된 부분만 재실행 (캐싱)

🧪 실험 추적

하이퍼파라미터, 메트릭, 모델 아티팩트를 Git 커밋과 연결

2. 왜 써야 하는가?

기존 방식(Git LFS, 수동 스크립트)과 비교한 DVC의 강점:

영역	Git LFS / 수동	DVC
데이터 버전	파일 단위, diff 어려움	포인터 기반, Git과 완벽한 히스토리
파이프라인	직접 Makefile/Airflow	dvc.yaml + 캐싱, 변경 감지 자동
실험 관리	수동 로깅	`dvc exp run` + 메트릭 비교
원격 저장소	별도 동기화	통합 push/pull (S3, GCS, SSH 등)

✅ MLOps 핵심 — 재현성, 협업, CI/CD 파이프라인과 자연스럽게 통합됩니다.

3. 핵심 개념

DVC는 Git 위에서 동작하며, 데이터와 파이프라인을 메타파일(.dvc, dvc.lock, dvc.yaml)로 관리합니다.

┌─────────────────────────────────────────────────────┐ │ Git Repository │ │ ┌────────────┐ ┌──────────────┐ ┌────────────┐ │ │ │ data.dvc │ │ dvc.yaml │ │ dvc.lock │ │ │ │ (포인터) │ │ (파이프라인) │ │ (고정 버전)│ │ │ └─────┬──────┘ └──────┬───────┘ └──────┬─────┘ │ │ │ │ │ │ │ ▼ ▼ ▼ │ │ ┌────────────┐ ┌──────────────┐ ┌────────────┐ │ │ │ .dvc/cache │ │ data/ │ │ metrics/ │ │ │ │ (로컬 캐시)│ │ (실제 파일) │ │ (평가 결과)│ │ │ └────────────┘ └──────────────┘ └────────────┘ │ │ │ │ │ ▼ 원격 (S3, GCS, SSH, ...) │ └─────────────────────────────────────────────────────┘

.dvc 파일 — 데이터셋 하나의 포인터 (해시, 원격 경로)
dvc.yaml — 파이프라인 단계(stage) 정의
dvc.lock — 의존성 해시 고정, 재현성 보장
캐시 / 원격 — 실제 콘텐츠 저장소

4. 퀵스타트

설치

pip install dvc          # Python 3.8+
# 또는 conda: conda install -c conda-forge dvc
dvc --version            # 3.58.x

프로젝트 초기화 & 데이터 추적

cd my-ml-project
git init
dvc init                 # .dvc/ 디렉토리 생성
git commit -m "dvc init"

# 데이터 추가 (예: images/)
dvc add data/images      # data/images.dvc 생성, .gitignore 업데이트
git add data/images.dvc .gitignore
git commit -m "track images"

# 원격 저장소 연결 (예: S3)
dvc remote add myremote s3://my-bucket/dvc-store
dvc push

파이프라인 예제 (Python)

# dvc.yaml
stages:
  preprocess:
    cmd: python src/preprocess.py
    deps:
      - data/raw
    outs:
      - data/processed
  train:
    cmd: python src/train.py
    deps:
      - data/processed
    params:
      - lr
      - epochs
    metrics:
      - metrics/accuracy.json
    outs:
      - models/model.pkl

# 실행 및 비교
dvc repro                 # 변경된 stage만 재실행
dvc metrics show          # 정확도 등 확인
dvc exp run --set-param lr=0.01  # 실험 실행
dvc exp show              # 실험 목록, 메트릭 비교

⚠️ 주의: dvc add 후 반드시 .dvc 파일과 .gitignore 변경을 Git에 커밋하세요.

5. 핵심 설정 레퍼런스

명령 / 설정	설명	예시
`dvc init`	프로젝트 DVC 초기화	—
`dvc remote add`	원격 저장소 등록	`dvc remote add myremote gs://bucket`
`dvc cache dir`	캐시 위치 변경	`dvc cache dir /mnt/ssd/.dvc-cache`
`dvc.yaml` params	하이퍼파라미터 파일 (params.yaml)	`params: - lr`
`dvc.lock`	자동 생성, 의존성 해시 고정	—
`dvc repro`	파이프라인 재현	`dvc repro train`
`dvc exp run`	실험 실행 (Git 브랜치처럼)	`dvc exp run -S lr=0.001`
`dvc push/pull`	원격과 데이터 동기화	`dvc push -r myremote`

6. 실무 팁 & 트러블슈팅

🐛 자주 겪는 문제 1: dvc add 후 Git에 .dvc 파일을 커밋하지 않음 → 팀원이 데이터를 복원할 수 없음.
✅ 해결: git status로 .dvc 파일과 .gitignore 변경을 항상 함께 커밋.

🐛 자주 겪는 문제 2: dvc repro가 모든 stage를 다시 실행함 (캐시 미스).
✅ 해결: dvc.yaml의 deps/outs 경로가 정확한지 확인. 대소문자, 절대경로 주의.

🐛 자주 겪는 문제 3: 원격 저장소 권한 오류 (S3/GCS).
✅ 해결: dvc remote modify로 credential 파일 경로 지정 또는 환경 변수 설정.

💡 실무 팁: .dvcignore로 캐시 제외 패턴 지정. dvc gc로 오래된 캐시 정리. dvc diff로 데이터 변화 추적.

DVC · 데이터 버전 관리

1. DVC란?

2. 왜 써야 하는가?

3. 핵심 개념

4. 퀵스타트

설치

프로젝트 초기화 & 데이터 추적

파이프라인 예제 (Python)

5. 핵심 설정 레퍼런스

6. 실무 팁 & 트러블슈팅

7. 참고 자료