FastAPI

이 글에서 다루는 것 FastAPI와 Airflow가 흩어져 보내던 알림을 하나의 Slack 인터페이스로 통합하고, SealedSecret 기반으로 Webhook URL을 안전하게 주입하는 구조를 다룹니다. 선수지식 MLOps 운영 고도화 1단계: 핫스왑 고도화 — /reload 보안 강화와 DAG 자동화 이 단계에서 해결하려는 문제 운영 환경에서 가장 무서운 건 문제가 생겼는데 아무도 모르고 있는 상황이다. FastAPI와 Airflow가 각자 흩어져 보내던 알림을 하나의 Slack 인터페이스로 완전히 통합해서, 모델 학습·등록·센서·핫스왑·헬스체크까지 어디에서 무슨 일이 일어나도 즉시 눈에 들어오도록 만든다. ...

이 글에서 다루는 것 /reload 엔드포인트에 3중 보안(토큰·IP 화이트리스트·TLS)을 적용하고, Airflow DAG으로 학습→등록→감시→핫스왑 전체 시퀀스를 자동화하는 과정을 다룹니다. 선수지식 MLOps 운영 고도화 0단계: FastAPI A/B·Canary·Blue-Green 서빙 베이스 — 멀티 모델 라우팅 기반 설계 이 단계에서 해결하려는 문제 모델을 잘 학습시키는 것도 중요하지만, 잘못된 모델이 실수로 핫스왑되는 순간이 더 치명적이다. /reload를 확실하게 잠그고, 학습→등록→감시→핫스왑까지가 Airflow에서 자동으로 흘러가도록 만들어야 한다. 이 단계가 완성돼야 이후 단계에서 안전한 자동 운영(MLOps)을 구현할 수 있다. ...

이 글에서 다루는 것 MLflow Alias 기반으로 A/B·Canary·Blue-Green 세 가지 서빙 전략을 하나의 FastAPI 앱에서 처리하는 구조를 설계하고, 이후 운영 자동화의 공통 베이스를 만드는 과정을 다룹니다. 선수지식 [TS] Airflow 기초 자동화 트러블슈팅 — Airflow → MLflow → FastAPI 연동 기본 흐름 Level 3은 이 글부터 시작합니다. 이 단계에서 해결하려는 문제 운영 환경에서 모델은 언제든 교체될 수 있고, 그 순간이 서비스 품질이 가장 크게 흔들리는 위험 구간이다. 이후 모든 자동화(학습·등록·핫스왑·롤백)의 기반이 되는 A/B·Canary·Blue-Green 전략을 모두 처리할 수 있는 FastAPI 서빙 구조부터 잡아야 한다. 이 뼈대가 완성돼야 Airflow, MLflow, ArgoCD와 연결된 운영형 MLOps 파이프라인을 만들 수 있다. ...

🧩 실전 시나리오 기반 구성 배경 이 프로젝트는 단순 실습을 넘어서, 실제 발생하는 다음과 같은 문제들을 해결하기 위한 MLOps 인프라 구축을 목표로 설계되었습니다. 여러 모델 실험 결과가 뒤섞여 추적이 어려운 문제 → MLflow Tracking 서버 + PostgreSQL 메타데이터 저장소 구성 모델 파일 및 로그가 로컬에만 저장되어 협업 및 재현성이 떨어지는 문제 → S3 기반 artifact store 구성 + pyfunc 기반 모델 서빙 구조 설계 수작업 DAG 등록, 모델 배포 등의 비효율적 운영 문제 → Airflow + GitSync 연동으로 파이프라인 자동화 및 버전 관리 가능 ...

이 글에서 다루는 것 Airflow DAG에서 조건부 모델 등록 후 FastAPI 핫스왑까지 E2E 자동화 흐름을 실험합니다. 선수지식 MLOps 플랫폼 구축 5단계: FastAPI 서빙 및 핫스왑 구조 구축 — FastAPI 모델 로딩과 /reload API 구조 이 단계에서 해결하려는 문제 개별 컴포넌트(Airflow, MLflow, FastAPI)를 각각 구성했지만, 학습부터 서빙까지의 자동화 흐름을 E2E로 검증해야 실제 운영 가능 여부를 판단할 수 있습니다. 이 단계에서는 Airflow DAG에서 모델 학습 → 성능 기준 분기 → MLflow 등록 → FastAPI 핫스왑까지 전체 파이프라인을 실험합니다. ...

이 글에서 다루는 것 MLflow에 등록된 모델을 FastAPI로 서빙하고, Stage 기반 핫스왑과 모델 정보 조회 API를 구축합니다. 선수지식 MLOps 플랫폼 구축 4단계: Airflow GitSync + Secret 연동 — Helm 배포와 Secret 마운트 패턴 이 단계에서 해결하려는 문제 모델을 수동으로 서빙 서버에 복사하면 배포 실수와 버전 불일치가 발생합니다. MLflow Registry에서 Stage별 모델을 자동 로딩하는 구조를 만들어, 코드 변경 없이 모델을 교체할 수 있도록 합니다. 📐 아키텍처 구성도 🐳 FastAPI 커스텀 이미지 Dockerfile FROM python:3.12 WORKDIR /app COPY app /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"] requirements.txt fastapi==0.110.2 uvicorn==0.29.0 mlflow==2.13.0 pandas==2.1.4 scikit-learn==1.6.1 pydantic==2.7.1 boto3==1.34.113 numpy==1.26.4 packaging==24.2 psutil==7.0.0 scipy==1.15.3 setuptools==69.5.1 빌드 & 푸시 docker build -t ghcr.io/hoizz/fastapi-ml:mlflow-model-info . docker push ghcr.io/hoizz/fastapi-ml:mlflow-model-info 📄 app/main.py (핵심 부분) app = FastAPI() model = None model_info = {} def load_model_from_mlflow(): global model, model_info tracking_uri = os.environ.get("MLFLOW_TRACKING_URI") model_name = os.environ.get("MODEL_NAME") model_stage = os.environ.get("MODEL_STAGE", "Production") mlflow.set_tracking_uri(tracking_uri) model_uri = f"models:/{model_name}/{model_stage}" model = mlflow.pyfunc.load_model(model_uri) client = MlflowClient() latest = client.get_latest_versions(name=model_name, stages=[model_stage])[0] model_info = { "model_name": model_name, "stage": model_stage, "version": latest.version, "run_id": latest.run_id, "model_uri": model_uri, } @app.on_event("startup") def startup_event(): load_model_from_mlflow() @app.get("/model-info") def get_model_info(): return model_info @app.post("/predict") async def predict(request: Request): input_data = await request.json() prediction = model.predict(input_data) return {"prediction": prediction.tolist()} 전체 코드: GitHub (main.py) ...

🧭 전체 흐름 예시 [AIRFLOW DAG 실행] ↓ [train_mlflow.py] - iris 모델 학습 - 파라미터/메트릭 로깅 - 모델 Registry 등록 ↓ [promote_mlflow.py] - 최신 모델을 Production으로 전환 ↓ [FastAPI] - models:/IrisModel/Production → 실시간 예측 👉 실습 코드는 🔗 GitHub (Airflow + MLflow + FastAPI) ✅ [1단계] 프로젝트 기본 폴더 구조 설계 📁 1. 전체 디렉토리 구성도 mlops_project/ ├── airflow/ 🛫 Airflow 설정 및 DAG 스케줄러 │ ├── dags/ ← DAG 정의 디렉토리 │ │ └── train_with_mlflow.py ← 학습 DAG (MLflow 연동) │ ├── Dockerfile.airflow ← Airflow용 Dockerfile │ ├── requirements.txt ← Airflow 의존성 │ └── .dockerignore │ ├── fastapi/ ⚡ FastAPI 예측 API 서버 │ ├── app/ │ │ └── main.py ← 모델 서빙 엔드포인트 │ ├── Dockerfile.api ← FastAPI용 Dockerfile │ ├── requirements.txt ← FastAPI 의존성 │ └── .dockerignore │ ├── ml_code/ 🧠 ML 학습 및 프로모션 코드 │ ├── train_mlflow.py ← 모델 학습 및 MLflow 로깅 │ └── promote_mlflow.py ← 모델 프로모션 (Staging → Production) │ ├── mlflow_store/ 🗂️ MLflow 저장소 경로 (볼륨) │ ├── Dockerfile.mlflow ← MLflow 서버 커스터마이징 │ ├── mlflow.db ← Model Registry DB (sqlite) │ ├── mlruns/ ← 실험 로그 디렉토리 │ ├── artifacts/ ← 모델 아티팩트 저장소 │ └── .dockerignore │ ├── docker-compose.yaml 🧩 전체 서비스 구성 정의 ├── .env 🔐 민감 정보 (.env로 분리) ├── README.md 📝 전체 프로젝트 문서화 ├── .gitignore └── .dockerignore ✅ [2단계] docker-compose.yaml 통합 구성 🧭 구성 목표 서비스명 설명 포트 airflow DAG 실행 환경 (webserver/scheduler) 8080 postgres Airflow 메타데이터 저장용 DB 내부 통신 mlflow MLflow UI + Registry 기능 5000 fastapi 추론 API 서버 (모델 로딩) 8000 이미지 사용시 주의 (UI만 제공하는 이미지 존재) 📄 docker-compose.yaml 전체 예시 version: '3.8' services: # 📦 PostgreSQL: Airflow 메타데이터 저장용 DB postgres: image: postgres:13 container_name: postgres env_file: - .env # ← 민감정보 분리 (아이디/비번) environment: POSTGRES_USER: ${POSTGRES_USER} POSTGRES_PASSWORD: ${POSTGRES_PASSWORD} POSTGRES_DB: ${POSTGRES_DB} volumes: # ← 코드/데이터 공유 및 영속성 보장 - postgres_data:/var/lib/postgresql/data # ← DB 데이터 유지 (재시작 대비) # 🛫 Airflow: DAG 스케줄러 및 태스크 실행 airflow: build: context: ./airflow # → Airflow 전용 Dockerfile 경로 dockerfile: Dockerfile.airflow container_name: airflow command: standalone # → 로컬 테스트용 간단 실행 명령 # (- Scheduler + Webserver + DB 초기화까지 자동으로 한번에 실행) # (- 실무/운영에서는 airflow-webserver, airflow-scheduler 필드 분리) ports: - "8080:8080" # → Airflow 웹 UI (localhost:8080) depends_on: - postgres # → DB가 먼저 올라와야 Airflow 시작 가능 env_file: - .env environment: # Airflow 메타데이터 DB 연결 주소 AIRFLOW__CORE__SQL_ALCHEMY_CONN: ${AIRFLOW__CORE__SQL_ALCHEMY_CONN} # Airflow 예제 DAG 불러올지 여부 AIRFLOW__CORE__LOAD_EXAMPLES: ${AIRFLOW__CORE__LOAD_EXAMPLES} MLFLOW_TRACKING_URI: http://mlflow:5000 # → DAG 코드에서 MLflow 연동 volumes: - ./airflow/dags:/opt/airflow/dags # DAG 파일 mount - ./ml_code:/opt/airflow/ml_code # 학습 코드 공유 - ./mlflow_store:/mlflow # 모델 저장소 공유 # 🔬 MLflow: 실험 추적 + 모델 레지스트리 서버 mlflow: build: context: ./mlflow_store # 커스텀 Dockerfile 위치 dockerfile: Dockerfile.mlflow ports: - "5000:5000" # → MLflow UI (localhost:5000) volumes: - ./mlflow_store:/mlflow # 실험 로그 + DB + artifacts 저장 environment: - MLFLOW_TRACKING_URI=http://0.0.0.0:5000 # 내부 컨테이너 기준 URI # ⚡ FastAPI: 모델 서빙 API fastapi: build: context: ./fastapi dockerfile: Dockerfile.api container_name: fastapi ports: - "8000:8000" # → 예측 API 엔드포인트 (localhost:8000) volumes: - ./fastapi/app:/app/app # FastAPI app 디렉토리 mount - ./ml_code:/app/ml_code # 학습/모델 코드 공유 - ./mlflow_store:/mlflow # 저장된 모델 불러오기 위한 mount # 🗂️ 볼륨 정의 (Postgres DB 영속성 유지) volumes: postgres_data: 🎁 추가로 해야 할 것 Airflow 첫 실행 후엔 보통 관리자 계정 생성도 해줘야 함: # airflow 컨테이너 접속 docker exec -it airflow bash # 관리자 계정 생성 airflow users create \ --username airflow \ --password airflow \ --firstname Keoho \ --lastname Ban \ --role Admin \ --email airflow@example.com 🔁 [구축 Tip] Airflow, FastAPI, MLflow 간 공유 볼륨 구조 확인 공유 리소스 설명 ./mlflow_store:/mlflow (MLflow) MLflow 서버가 쓰는 로그/모델 저장소 ./mlflow_store:/mlflow (Airflow) 학습 후 모델 저장 위치 공유 ./mlflow_store:/mlflow (FastAPI) 모델 추론 시 로드 경로 공유 ➡ 경로 통일성이 중요함! 지금은 모두 ./mlflow로 공유 (./mlflow 하위에 /mlruns 존재) ...

목표 MLflow Tracking Server 구성 실험(Experiment), 파라미터, 메트릭, 아티팩트 기록 모델 등록 → Stage 이동 → API 연동까지 👉 실습 코드는 🔗 GitHub (Mlflow - Tracking + FastAPI) 🧭 실습 전체 흐름 요약 [1단계] MLflow Tracking Server 구성 (로컬 환경에서 실행) [2단계] 실험 실행 (train.py) → 모델 학습, 기록 [3단계] 모델 등록 및 Stage 설정 (Production 이동) [4단계] FastAPI 연동 → 예측 API 서비스 🧩 실습 디렉토리 예시 mlops-mlflow/ ├── app/ │ ├── train.py # 모델 훈련 및 실험 기록 │ └── model.pkl # 저장된 모델 ├── mlruns/ # 실험 데이터 자동 생성 ├── fastapi_app/ │ └── app.py # FastAPI 예측 API ├── Dockerfile (선택) └── README.md ✅ [1단계] MLflow 설치 & 실행 🛠️ 가상 환경 설정 # 1. venv 설치 sudo apt install python3-venv -y # 2. 가상환경 생성 python3 -m venv .venv # 3. 가상환경 활성화 source .venv/bin/activate # 4. 패키지 설치 pip install mlflow scikit-learn pandas fastapi uvicorn # 5. 나갈 때 deactivate 🔧 MLflow 서버 실행 mlflow ui --port 5000 # http://localhost:5000 에서 UI 확인 🧪 [2단계] 실험 실행 (train.py) # app/train.py import mlflow import mlflow.sklearn from sklearn.ensemble import RandomForestClassifier from sklearn.datasets import load_iris from sklearn.model_selection import train_test_split # MLflow 설정 mlflow.set_tracking_uri("http://localhost:5000") mlflow.set_experiment("iris-rf-exp") with mlflow.start_run(): iris = load_iris() X_train, X_test, y_train, y_test = train_test_split(iris.data, iris.target, test_size=0.2) clf = RandomForestClassifier(n_estimators=100, max_depth=3) clf.fit(X_train, y_train) acc = clf.score(X_test, y_test) mlflow.log_param("n_estimators", 100) mlflow.log_param("max_depth", 3) mlflow.log_metric("accuracy", acc) mlflow.sklearn.log_model(clf, "model") # 실험 실행 python app/train.py 실험이 끝나면 mlruns/ 폴더에 실험 기록 및 모델이 저장 ...