이 글에서 다루는 것
Airflow + MLflow + FastAPI 연동 시 자주 발생하는 PermissionError, 404 에러, CLI 오류의 원인과 해결법을 정리합니다.
선수지식
- MLOps 플랫폼 구축 6단계: 실시간 모델 핫스왑 실험 — Airflow → MLflow → FastAPI E2E 흐름
이 단계에서 해결하려는 문제
Airflow DAG 내부에서 mlflow.sklearn.log_model()을 호출하고 Model Registry에 연동하는 과정에서, 볼륨 마운트 누락, API 미활성화, CLI 설정 오류 등 환경 구성 문제가 빈번하게 발생합니다. 이 문제들은 공식 문서만으로는 원인을 파악하기 어렵습니다.
에러 1. PermissionError: [Errno 13] Permission denied: ‘/mlflow’
원인 분석
| 증상 | 원인 |
|---|---|
/mlflow 경로 접근 실패 | Airflow 컨테이너에 mount되지 않음 |
mlruns 쓰기 실패 | 공유 볼륨 누락 → 쓰기 권한 없음 |
| 실험 생성 실패 | artifact 저장소 지정 실패 |
해결 방법
- Airflow 컨테이너에 공유 볼륨 추가
volumes:
- ./mlflow:/mlflow
- ./mlruns:/mlflow/mlruns
- 초기 실험 수동 생성 스크립트 실행
# init_experiments.py
from mlflow.tracking import MlflowClient
mlflow.set_tracking_uri("http://localhost:5000")
client = MlflowClient()
if not client.get_experiment_by_name("Iris_Model_Registry_Go"):
client.create_experiment(
name="Iris_Model_Registry_Go",
artifact_location="file:///mlflow/mlruns/Iris_Model_Registry_Go"
)
docker exec -it airflow_mlflow_1 python3 /mlflow/init_experiments.py
- Airflow DAG 내에서 동일한 이름 지정
mlflow.set_experiment("Iris_Model_Registry_Go")
에러 2. 404 Not Found on /api/2.0/mlflow/logged-models
원인 분석
| 핵심 문제 | 상세 설명 |
|---|---|
| Model Registry API 미탑재 | mlflow ui 또는 mlflow server의 옵션 누락 |
/logged-models 경로 없음 | 기본 실행 시에는 Registry 관련 API가 비활성화 |
해결 방법
| 실행 방식 | Registry API |
|---|---|
mlflow ui | 없음 |
mlflow server | 일부 없음 |
mlflow server --serve-artifacts | 모두 활성화 |
mlflow[extras] 패키지 | 커스텀 이미지 사용 필요 |
Dockerfile 예시 (커스텀 구성):
FROM python:3.10-slim
RUN pip install mlflow[extras]
CMD ["mlflow", "server", "--serve-artifacts", "--host", "0.0.0.0", "--port", "5000"]
에러 3. Airflow CLI 오류: the following arguments are required: GROUP_OR_COMMAND
원인 분석
| 증상 | 원인 |
|---|---|
| Airflow 컨테이너 실행 직후 종료 | 명령어 없이 airflow 실행됨 |
GROUP_OR_COMMAND 요구 | CMD, ENTRYPOINT 누락 |
해결 방법
- 개발/테스트 용도:
standalone모드 사용
command: standalone
- 실무 구성:
webserver,scheduler분리 실행
command: webserver
# 또는
command: scheduler
공유 볼륨 구조 요약
| Host 디렉토리 | MLflow 컨테이너 | Airflow 컨테이너 |
|---|---|---|
./mlflow | /mlflow | /mlflow |
./mlruns | /mlflow/mlruns | /mlflow/mlruns |
공통 저장소 구조가 필수입니다 — 실험 로깅, 모델 추론, 등록 경로가 통일되어야 합니다.
설계 판단 (Why This Way?)
Airflow와 MLflow 컨테이너가 동일한 파일 시스템 경로로 아티팩트에 접근해야 모델 로딩이 가능하며, MLflow의 –serve-artifacts 옵션 없이는 Registry API와 아티팩트 프록시가 비활성화되어 모델 등록/다운로드가 실패합니다. 프로덕션에서는 webserver/scheduler를 분리하여 독립 스케일링과 장애 격리를 확보합니다.
다음에 읽을 글
→ MLOps 운영 고도화: FastAPI A/B·Canary·Blue-Green 서빙 베이스 — Level 3: GitOps 기반 운영 고도화 시작