Docs/admin ops systemdesign

[baekyutae]

진행 내역

docs/system-design.md의 admin-ops 영역을 정리해 운영 기준선과 후속 spec 작성 기준을 확정했습니다.

변경 사항 요약

1. Admin & Ops 책임 정리

• Admin Dashboard의 책임을 운영 모니터링, 제한된 운영 액션, 모델 운영 지원으로 정리
• Observability의 역할을 운영 판단용 로그/메트릭 수집과 장애 분석 지원으로 명시
• 운영자 -> Message Broker -> ML Lifecycle Worker, 운영자 -> Model Artifact Files -> Managed Embedding Endpoint 같은 주요 연결 관계를 추가

2. 피드백 루프 / 모델 운영 흐름 정리

• Feedback 수집 -> 피드백 데이터셋 생성 -> 모델 재학습 및 재색인 흐름을 분리
• 데이터셋은 누적 저장 후 운영자가 사용할 버전을 선택하는 구조로 정리
• 모델 운영 흐름을 학습 -> 평가 -> 서빙 전환 후보 선정 -> 재색인 -> 서빙 전환으로 구분
• 재색인 중에는 기존 활성 모델로 서빙을 유지

3. 운영 산출물 저장 책임 추가

• Object Storage: 학습용 데이터셋, 평가 상세 아티팩트 저장
• Metadata DB: 모델 평가 결과와 운영 메타데이터 저장
• Model Artifact Files: 후보 모델 파일과 버전 메타데이터 보관(로컬)

4. 문서 추상화 수준 조정

• admin-ops 영역에서 구현 디테일이 강한 표현을 줄이고 역할/경계/절차 중심으로 재작성
• 불필요하게 상세한 필드 설명이나 구현 방식 표현은 spec 단계로 위임

Why

이번 admin-ops 설계는 의도적으로 보수적으로 잡았습니다.

• 일상적인 운영 가시성은 Admin Dashboard + Observability로 확보
• 비용이 크거나 영향 범위가 큰 작업(학습, 재색인, 서빙 전환)은 비동기 worker와 수동 운영 절차로 분리
• 파이프라인 상태, 실패, 삭제, 서빙 가능 여부는 Metadata DB 상태를 기준으로 판단

즉, 운영자가 상태를 보고 판단할 수 있게 하고 파이프라인은 구축하되 전과정 자동화나 대시보드 ui를 통한 전 과정 제어는 후순위로 미뤄뒀습니다.

Trade-offs / Alternatives

선택한 방향

• 운영 모니터링은 dashboard 중심
• 모델 lifecycle은 수동 체크포인트를 포함한 비동기 흐름

대안으로 가능했던 것

• 학습/평가/승격/재색인을 더 자동화한 control plane
• terminal failure에 대해 별도 app-level DLQ와 자동 remediation 추가
• 대시보드에서 모델 운영 액션을 더 적극적으로 직접 제어

왜 선택하지 않았는가

• 미디어 처리와 모델 전환은 비용과 영향 범위가 커서 잘못된 자동화의 운영 비용이 큼
• 현재 단계에서는 full MLOps/control plane보다 명시적 human checkpoint가 더 안전함
• 시스템 복잡도 증가 없이 후속 spec/diagram 작성이 가능한 수준의 기준선을 먼저 확보하는 것이 우선이었음

관련 이슈

Close #57

[baekyutae]

0408 system desgin 문서 수정 사항

1. Core API 권한 분리

• Core API Server 책임을 End-User 기능 / Admin 기능으로 그룹 분리
• Admin 기능은 JWT claim의 role 기준으로 별도 검증, 소유권 제한 없이 동작
• 연결 관계에서 Admin Dashboard → Core API Server (Admin 기능) 명시

2. 모델 릴리스 SOT 도입 (ModelRelease)

• 서빙 모델 버전의 SOT를 artifact path → Metadata DB 릴리스 레코드로 변경

  사유: 모델 배포 이후 재인덱싱을 위해 서빙하는 모델 버전을 바꿔야 하는데 경로 변수로 받아오니 서버를 항상 재시작 해야하는 문제가 예상됩니다. 때문에 최초 서비 기동시엔 경로 변수에서 가져와 db에 기록후 변동이 생겨 참조해야 할땐 항상 db를 sot로 삼게 설계하였습니다.

• Endpoint는 최초 기동 시 환경변수로 폴백, 이후 DB가 SOT

• ML Lifecycle Worker가 재색인 완료 후 릴리스 레코드 갱신으로 서빙 전환

• Data Model에 ModelRelease 테이블 추가 (3.10)

3. 피드백 파이프라인 재설계

• Core api server →Feedback Ingestion Pipeline(vector) → Storage 로 피드백 흐름 수정
• 피드백 저장소를 Metadata DB → Object Storage 원본 이벤트 로그로 변경
• 검색 응답 스냅샷 단기 보존 + 피드백 검증 흐름 추가
• ML 파이프라인을 수동 트리거 → 자동 연쇄 실행으로 전환
• 실행 제어: 동시 활성 MLPipelineRun 1개 제한, 최신 데이터셋 기준으로 학습

[f-lab-jesse]

아래 커멘트는 중요한 운영 의사결정이므로 다시 한 번 고민해봐주세요.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud