데이터 중심 프로젝트를 위한 견고한 Git 워크플로우 구축하기

데이터 중심 프로젝트를 위한 견고한 Git 워크플로우 구축하기

많은 팀에서 버전 관리 (Version Control)는 데이터, 코드, 그리고 배포를 잇는 접착제 역할을 합니다. 프로젝트가 데이터 처리, 실험, 그리고 모델 아티팩트 (Model Artifacts)를 중심으로 돌아갈 때, Git 워크플로우는 대용량 바이너리 파일, 빈번한 데이터 갱신, 그리고 재현 가능한 환경 (Reproducible Environments)을 수용할 수 있어야 합니다. 이 튜토리얼은 브랜치 전략 (Branch Strategies), 데이터/버전 관리 컨벤션 (Data/Versioning Conventions), CI 고려 사항, 그리고 재현성 훅 (Reproducibility Hooks)을 포함하여 데이터 중심 프로젝트에 맞춤화된 실질적인 엔드 투 엔드 (End-to-End) Git 워크플로우를 제시합니다. 여기에는 여러분의 스택에 맞춰 적용할 수 있는 구체적인 명령어들이 포함되어 있습니다.

1) 명확한 저장소 구조로 시작하기

잘 조직된 저장소 (Repository)는 팀이 데이터, 코드, 모델에 대해 논리적으로 사고하는 데 도움을 줍니다.

• src/ 또는 notebooks/: 분석 스크립트 또는 노트북 (Notebooks)
• data/: 버전 관리가 되는 작은 데이터셋 또는 외부 소스로의 포인터 (Pointers)
• data-raw/: 원천 데이터 (보통 커밋하지 않음; 데이터 출처 (Data Provenance) 사용 권장)
• data-processed/: 파이프라인 (Pipeline)의 결과물
• models/: 학습된 아티팩트 (Git LFS 또는 외부 아티팩트 저장소 고려)
• pipelines/: 데이터 처리 및 모델 학습 파이프라인 (예: Snakemake, Airflow 또는 커스텀 스크립트)
• configs/: 실험 및 파이프라인 설정 (Configurations)
• tests/: 데이터 품질 및 실험을 위한 검증 테스트
• docs/: 재현 단계 (Reproduction Steps)를 포함한 문서화

가이드 원칙: 가능한 한 대용량 아티팩트는 Git에서 제외하십시오. 포인터, 해시 (Hashes), 또는 아티팩트 저장소 (Artifact Stores)를 사용하십시오.

2) 실험과 일치하는 브랜치 모델 선택하기

데이터 집약적인 프로젝트의 경우, 탐색 (Exploration)과 안정성 (Stability) 사이의 균형을 맞추어야 합니다.

• main (또는 master): 프로덕션 준비가 된 베이스라인 및 검증된 실험
• develop: 진행 중인 실험의 통합; 불안정하지만 릴리스에 가까운 상태
• feature/experiment-xyz: 격리된 실험
• release/vX.Y.Z: 릴리스 후보 (Release Candidate)를 위한 스테이징 (Staging)
• hotfix/issue-123: 프로덕션에서의 빠른 수정

팁:

• 각 데이터 실험(data experiment) 또는 파이프라인 변경 사항에 대해 기능 브랜치(feature branch)를 생성하세요.
• 데이터 검증(data validation) 및 재현성(reproducibility) 확인을 통과한 후에만 develop 브랜치로 머지(Merge)하세요.
• 재현 가능한 실행을 위해 전용 태그(tag)를 사용하세요 (재현성 훅(reproducibility hooks) 참조).

3) 데이터 및 아티팩트(artifacts)를 적절하게 버전 관리하기

Git은 대규모 데이터나 바이너리 아티팩트(binary artifacts)를 관리하기에는 최적화되어 있지 않습니다. 다음과 같은 하이브리드 접근 방식을 사용하세요:

• 소규모 데이터 및 델타(deltas): 명확한 버전 관리와 함께 Git에 저장 (바이너리 안전(binary-safe) 관행 준수).
• 대용량 파일 또는 모델: Git LFS를 사용하거나 외부 아티팩트 저장소(예: DVC, MLflow 또는 S3 호환 저장소)를 사용하세요.
• 데이터 출처(Data provenance): 불변 참조(immutable references, 해시, URL 및 타임스탬프)를 통해 데이터 소스를 추적하세요.

구체적인 설정 옵션:

• Git LFS: 대용량 바이너리 파일용
  • 활성화: git lfs install
  • 추적: git lfs track "_.pt" "_.csv" "\*.bin"
  • 평소처럼 커밋(Commit)하세요. LFS는 대용량 객체를 Git 외부에서 저장합니다.
• DVC (data version control): 재현 가능한 단계(stages)를 통해 데이터, 모델 및 파이프라인을 관리
  • 초기화: dvc init
  • 데이터 추가: dvc add data/large-dataset.csv
  • 데이터 푸시: dvc push (원격 저장소 설정 필요)
  • 재현: dvc repro

하나를 선택하거나 조합하여 사용하세요: 단순한 대용량 파일에는 LFS를, 엔드 투 엔드(end-to-end) 데이터 계보(lineage) 및 파이프라인 재현성에는 DVC를 권장합니다.

4) 최우선 사항으로서의 재현성 (Reproducibility)

재현 가능한 실행을 위해서는 명시적인 환경, 데이터 버전 및 파이프라인 단계가 필요합니다.

• 환경 캡처:
  • Python 의존성 관리를 위한 Poetry 또는 pip-tools
  • Conda environment.yml
  • 일관된 실행을 위한 Dockerfile 또는 docker-compose.yml
• 설정(configurations) 캡처:
  • configs/ 디렉토리에 실험별 YAML/JSON 설정 파일 작성
  • 타임스탬프, 데이터 버전 및 시드(seed)를 포함
• 재현 스크립트 추가:
  • 데이터를 가져오고, 의존성을 설치하며, 파이프라인을 실행하고, 결과를 보고하는 scripts/reproduce.py와 같은 단일 스크립트 작성

예시: Python 기반 재현 스크립트 개요

• 데이터 버전 가져오기 (fetch data version): data/versions/latest.json
• 설정 로드 (load config): configs/exp-2026-06-01.yaml
• 실행 (run): python -m pipelines.run config configs/exp-2026-06-01.yaml

5) 데이터 제약 조건을 준수하는 CI/CD

코드, 데이터 품질, 그리고 경량화된 재현성 검사를 검증하기 위한 CI (지속적 통합, Continuous Integration)를 설정합니다.

• CI 단계:
  • 코드 체크아웃 (Checkout code)
  • 의존성 설치 (거대한 데이터를 다운로드하지 않고 수행)
  • 데이터 처리 함수에 대한 단위 테스트 (Unit tests) 실행
  • 데이터 스키마 (Data schema) 검증 및 기본 무결성 검사
  • (선택 사항) 파이프라인 작동 여부를 확인하기 위한 경량 데이터 샘플 처리 실행
• 아티팩트 (Artifacts) 및 캐시 (Caches):
  • Python 휠 (Wheels), conda 환경 (envs) 캐싱
  • 검증을 위해 데이터를 가져와야 하는 경우 CI에서 DVC 또는 LFS 사용
• 게이트키퍼 (Gatekeepers):
  • develop 브랜치로 머지(Merge)하기 전 데이터 품질 검사 통과를 필수 조건으로 설정
  • 필수 상태 검사 (Status checks)를 통해 main 브랜치 보호

GitHub Actions 스켈레톤 예시 (상위 수준):

• name: CI
  on: [push, pull_request]
  jobs:
  build:
  runs-on: ubuntu-latest
  steps:
  - uses: actions/checkout@v4
  - name: Set up Python
  uses: actions/setup-python@v4
  with: {python-version: '3.11'}
  - name: Install deps
  run: |
  python -m pip install -U pip
  pip install -r requirements.txt
  - name: Run tests
  run: |
  pytest -q
  - name: Lint
  run: |
  flake8

DVC를 사용하는 경우, dvc pull을 통해 하위 데이터(downstream data)를 가져오는 단계를 추가하고 경량 테스트 데이터셋을 사용할 수 있도록 합니다.

6) 커밋 위생 (Commit hygiene) 및 리뷰 관행

커밋은 작고, 의미 있으며, 결정론적(Deterministic)으로 유지하십시오.

• 원자적 커밋 (Atomic commits): 커밋당 하나의 논리적 변경 사항 반영
• 커밋 메시지:
  • feat: 새로운 실험 추가
  • fix: 데이터 전처리 버그 수정
  • chore: 문서 업데이트
  • ci: 워크플로우 조정
• PR (Pull Request) 체크리스트:
  • 데이터 검증 검사 통과 여부
  • 재현 스크립트 실행 여부
  • 의존성 버전 고정(Pinned) 및 확인 여부
  • 데이터 출처(Data provenance) 및 저장소 문서화 여부

단순한 코드 차이(Diff)뿐만 아니라, 데이터 중심의 변경 사항이 리뷰될 수 있도록 풀 리퀘스트(Pull requests)를 활용하십시오.

7) 출처 및 추적 가능성 (Provenance and traceability)

실험을 협업할 때는 결정 사항을 출처로 추적할 수 있어야 합니다.

• 데이터 출처 기록: 출처, 버전 및 체크섬(checksum)을 설명하는 data_sources.json을 포함합니다.
• 실험과 설정(configs) 연결: 설정 파일 이름에 날짜와 Git SHA를 포함합니다.
• 재현 가능한 결과에 태그 지정: 커밋에 실행 ID(run-id), 데이터 버전(data-version) 및 요약을 태그로 지정합니다.
  • git tag run-2026-06-01-v1
  • git push origin tags

간결한 실행 메타데이터(run metadata) 파일의 예시 (runs/2026-06-01-expA.json):

• run_id: expA-2026-06-01
• commit: abc123...
• data_version: data-v1.2.3
• config: configs/exp-2026-06-01.yaml
• seed: 42
• metrics: {accuracy: 0.923, f1: 0.911}
• notes: 피처 엔지니어링(feature engineering)을 적용한 베이스라인(baseline)

8) 예시 워크플로우: 아이디어부터 재현 가능한 결과까지의 엔드 투 엔드(end-to-end) 과정

1. 새로운 실험 브랜치 생성

• git checkout -b feature/experiment-ensemble

2. 적절한 도구를 사용하여 데이터 및/또는 모델 추가

• DVC를 사용하는 경우: dvc add data/ensemple.csv
• Git LFS를 사용하는 경우: git lfs track "*.pt" && git add .gitattributes

3. 파이프라인(pipeline) 변경 사항 구현

• 앙상블(ensemble) 방법을 통합하도록 scripts/pipeline.py 업데이트
• 매개변수(parameters) 및 random_seed를 포함하여 configs/exp-ensemble.yaml 업데이트

4. 로컬 체크 실행

• python -m pytest tests/
• python scripts/reproduce.py config configs/exp-ensemble.yaml

5. 집중된 메시지와 함께 커밋

• git add .
• git commit -m "feat(pipeline): implement ensemble method and config for exp-ensemble"

6. PR(Pull Request)을 열고 리뷰 요청

• 리뷰어가 데이터 유효성 및 재현성 단계를 검증하는지 확인합니다.

7. 체크를 통과하면 develop 브랜치에 병합(merge)하고, 검증 후 릴리스 태그(release tag)를 생성합니다.

8. 프로덕션과 유사한 환경(production-like environment)에 푸시(push)하고 실행 내용을 기록합니다.

• 재현성 스크립트(reproducibility script)를 사용하여 최종 결과를 재현하고 메트릭(metrics)을 저장합니다.

9) 실무 팁 및 흔히 발생하는 실수

• 실수: 대용량 데이터가 Git 히스토리에 몰래 포함됨

  • 해결책: DVC 또는 Git LFS를 사용하세요. 필요한 경우 히스토리를 정리(prune)하세요 (git filter-repo).

• 실수: 환경 드리프트(environment drift)로 인해 재현성이 깨짐

  • 해결책: 의존성(dependencies)을 고정(lock)하세요. 환경 사양을 저장하고 컨테이너화(containerization)를 사용하세요.

• 실수: 데이터 버전 관리가 실험 속도를 따라가지 못함

  • 해결책: 데이터 버전을 실행 메타데이터(run metadata)에 포함시키세요. 실험 시 데이터 버전 업데이트를 자동화하세요.

• 팁: 감사 추적(audit trails)을 자동화하세요

  • CHANGELOG를 유지하고, 각 실험별 실행 노트(run notes)를 runs/ 디렉토리에 간략한 설명과 함께 저장하세요.

10) 빠른 시작 체크리스트

• 저장소 구조와 명확한 브랜칭 모델(branching model)을 설정합니다.

• 데이터/버전 관리 방식(DVC, Git LFS 또는 둘 다)을 결정합니다.

• 환경 및 구성 관리(requirements, env.yml, Dockerfile)를 추가합니다.

• 가벼운 재현성 스크립트(reproducibility script)를 구현합니다.

• 데이터 품질 검사를 실행하도록 CI를 구성합니다.

• 출처(provenance) 규범을 수립합니다 (데이터 소스, 설정 명명 규칙, 실행 태그).

원하신다면, 이 워크플로우를 귀하의 스택(Python vs. R vs. 데이터 엔지니어링 파이프라인)에 맞게 조정하거나, 선택한 도구(DVC, MLflow 또는 일반 Git LFS)에 대한 구체적인 명령어를 제안하거나, 저장소를 위한 초기 설정 템플릿 및 CI 파일 세트를 초안으로 작성해 드릴 수 있습니다. 어떤 부분을 가장 먼저 맞춤 설정하고 싶으신가요?

Rizwan Saleem | https://rizwansaleem.co