NYC 택시 수요 예측 파이프라인 만들기 (2) 개발환경 세팅

uv 기반 Python 3.11 환경, 프로젝트 구조, Docker 스택 계획까지 파이프라인 개발환경 구성을 정리했습니다.

Posted 2026/07/17 Updated 2026/07/18

By 강호승

2 min read

이번 글에서 할 일

지난 글에서 프로젝트 설계를 정리했습니다. 코드를 쓰기 전에 개발환경부터 잡습니다.

Python 3.11 + uv로 가상환경과 의존성 관리
프로젝트 디렉토리 구조 잡기
Docker 스택 구성 계획

Python 3.11과 uv

맥의 시스템 Python은 3.9인데, 이미 EOL이 지난 버전이라 그대로 쓸 수 없습니다. 3.11을 선택했습니다. PyTorch, LightGBM, Airflow, MLflow가 모두 안정적으로 지원하는 버전이고, 3.12+는 아직 일부 라이브러리에 호환성 이슈가 남아 있기 때문입니다.

가상환경과 패키지 관리는 venv + pip 대신 uv를 썼습니다.

  
brew install uv
cd 2026_Machine_learning_study
uv python pin 3.11   # .python-version 생성
uv sync              # .venv 생성 + pyproject.toml 의존성 설치

uv를 선택한 이유:

Python 버전 관리까지 해결: 시스템 Python을 건드리지 않고 프로젝트별로 3.11을 씁니다. .python-version 파일 하나로 버전이 고정됩니다.
재현성: uv.lock에 전체 의존성 트리가 잠겨서, 어느 머신에서든 uv sync 한 번으로 같은 환경이 나옵니다.
속도: pip 대비 설치가 압도적으로 빠릅니다. torch 같은 무거운 패키지를 여러 번 재설치할 때 체감이 큽니다.

venv, conda, uv가 각각 뭐고 뭐가 다른지는 Python 환경 관리 도구 스터디 노트에 따로 정리했습니다.

의존성은 pyproject.toml에 선언합니다. 데이터 처리(pandas, pyarrow), 모델(scikit-learn, lightgbm, torch), 실험 관리(mlflow), 서빙(fastapi, uvicorn), DB와 스토리지 연동(sqlalchemy, psycopg2, boto3), 모니터링(evidently)까지 프로젝트에서 쓸 패키지를 한 번에 정의해뒀습니다.

단, Airflow는 여기 없습니다. 의존성 충돌이 심하기로 유명한 패키지라 가상환경에 설치하지 않고, Docker 컨테이너로만 구동할 계획입니다.

프로젝트 구조

2026_Machine_learning_study/
├── README.md
├── pyproject.toml        # 의존성 정의
├── uv.lock               # 의존성 잠금
├── .env.example          # 환경변수 템플릿
├── configs/
├── dags/                 # Airflow DAG
├── data/
│   ├── raw/              # 원본 데이터 (Git 제외)
│   ├── processed/        # 정제 데이터
│   └── features/         # 집계 결과
├── notebooks/            # EDA
├── src/
│   ├── data/             # 수집과 검증
│   ├── features/         # 집계와 피처 생성
│   ├── models/           # baseline, LightGBM, PyTorch
│   ├── serving/          # FastAPI
│   └── monitoring/
├── tests/
└── scripts/

데이터 파일, 모델 가중치, MLflow 아티팩트는 Git에 올리지 않고, .gitkeep으로 디렉토리 구조만 유지합니다.

Docker 스택 계획

인프라 서비스는 전부 Docker Compose로 띄웁니다. 최종 구성은 다음과 같습니다.

서비스	이미지	포트	역할
postgres	postgres:16	5432	Feature 테이블, Airflow/MLflow 메타 DB
minio	minio/minio	9000 / 9001	Raw 데이터 오브젝트 스토리지
mlflow	ghcr.io/mlflow/mlflow	5000	실험 추적 서버
airflow	apache/airflow	8080	수집과 집계 워크플로
api	자체 빌드 (FastAPI)	8000	예측 API
prometheus	prom/prometheus	9090	메트릭 수집
grafana	grafana/grafana	3000	대시보드

다만 처음부터 7개를 다 띄우지는 않습니다. postgres + minio + mlflow 세 개로 시작하고, Airflow와 모니터링 스택은 해당 단계에 진입할 때 추가합니다. Docker Desktop 리소스는 전체 스택 동시 구동 기준으로 메모리 8GB 이상을 권장합니다.

환경변수

DB 접속 정보, MinIO 키, MLflow URI 같은 값은 .env로 관리합니다. 저장소에는 .env.example만 올리고 실제 .env는 Git에서 제외합니다.

cp .env.example .env
# 값 채워서 사용

환경이 준비됐으니, 다음 글에서는 실제 데이터를 받아 스키마를 확인하고 수요 패턴을 탐색합니다.

Projects, ML Pipeline