diff --git a/docs/Diagram/Admin Operations & Observability Architecture.png b/docs/Diagram/Admin Operations & Observability Architecture.png new file mode 100644 index 0000000..93d9c5c Binary files /dev/null and b/docs/Diagram/Admin Operations & Observability Architecture.png differ diff --git a/docs/Diagram/Architecture_Diagram_Feedback_loop.png b/docs/Diagram/Architecture_Diagram_Feedback_loop.png new file mode 100644 index 0000000..bc4e1eb Binary files /dev/null and b/docs/Diagram/Architecture_Diagram_Feedback_loop.png differ diff --git a/docs/Diagram/sequence_diagram/SD-04-FeedBack_loop.png b/docs/Diagram/sequence_diagram/SD-04-FeedBack_loop.png new file mode 100644 index 0000000..f14fa03 Binary files /dev/null and b/docs/Diagram/sequence_diagram/SD-04-FeedBack_loop.png differ diff --git a/docs/Diagram/sequence_diagram/SD-05-Admin_Video_Ops.png b/docs/Diagram/sequence_diagram/SD-05-Admin_Video_Ops.png new file mode 100644 index 0000000..148ae3e Binary files /dev/null and b/docs/Diagram/sequence_diagram/SD-05-Admin_Video_Ops.png differ diff --git a/docs/Diagram/sequence_diagram/SD-06-Admin_ML(feedback_loop)_Ops.png b/docs/Diagram/sequence_diagram/SD-06-Admin_ML(feedback_loop)_Ops.png new file mode 100644 index 0000000..ef42bce Binary files /dev/null and b/docs/Diagram/sequence_diagram/SD-06-Admin_ML(feedback_loop)_Ops.png differ diff --git a/docs/Diagram/sequence_diagram/SD_Mermaid.md b/docs/Diagram/sequence_diagram/SD_Mermaid.md index b9aa053..54cd08f 100644 --- a/docs/Diagram/sequence_diagram/SD_Mermaid.md +++ b/docs/Diagram/sequence_diagram/SD_Mermaid.md @@ -141,4 +141,220 @@ SS->>LLM: LLM 답변 생성 직접 요청 (Direct SDK)
generate_answer(query LLM-->>SS: answer (+ cited_chunk_ids) SS-->>C: 최종 응답 반환
{answer, timestamps, topk_chunk_ids, cited_chunk_ids} +``` + +# 4. Feedback Loop + +```mermaid + +sequenceDiagram + participant Client + participant CoreAPI as Core API Server + participant MetaDB as Metadata DB + participant FIP as Feedback Ingestion Pipeline + participant ObjStore as Object Storage + participant MLWorker as ML Lifecycle Worker + participant ModelFiles as Model Artifact Files + participant MEE as Managed Embedding Endpoint + participant VS as Vector Store + + %% === 피드백 수집 (2.6) === + rect rgb(230, 245, 255) + Note over Client, ObjStore: 피드백 수집 + Client ->> CoreAPI: 검색 응답 단위 피드백 (req_id, rating) + CoreAPI ->> CoreAPI: 사용자 권한 검증 + CoreAPI ->> MetaDB: req_id 검색 응답 스냅샷 조회 + MetaDB -->> CoreAPI: 스냅샷 + CoreAPI ->> CoreAPI: 피드백 유효성 검증
(동일 사용자, 허용 시간, 무효화 여부) + CoreAPI ->> FIP: 검증된 피드백 이벤트 전달
(질의, 응답, 활성 모델/인덱스 정보 포함) + FIP ->> ObjStore: 원본 이벤트 로그 적재 + end + + %% === 데이터셋 전처리 (2.7) === + rect rgb(245, 255, 230) + Note over MLWorker, ObjStore: 피드백 데이터셋 생성 - 정기 배치
운영자 수동 트리거도 가능 + MLWorker ->> ObjStore: 신규 피드백 원본 로그 읽기 + ObjStore -->> MLWorker: 원본 로그 + MLWorker ->> MLWorker: 서빙 맥락(모델 버전, 인덱스)이 기록된 이벤트만
학습 데이터셋으로 변환 + MLWorker ->> ObjStore: 학습용 피드백 데이터셋 저장 + + alt 실행 중인 MLPipelineRun 없음 + MLWorker ->> MLWorker: 학습 파이프라인 자동 트리거 + else 실행 중인 MLPipelineRun 존재 + MLWorker ->> MLWorker: 최신 데이터셋 기준 다음 실행 대기 등록 + Note over MLWorker: 이전 대기 실행은 SUPERSEDED 처리 + end + end + + %% === 모델 재학습 및 재색인 (2.8) === + rect rgb(255, 245, 230) + Note over MLWorker, VS: 모델 재학습 및 재색인 + + %% 학습 + MLWorker ->> ObjStore: 학습용 데이터셋 읽기 + ObjStore -->> MLWorker: 학습 데이터셋 + MLWorker ->> MLWorker: 후보 임베딩 모델 학습 + MLWorker ->> ModelFiles: 후보 모델 저장 + MLWorker ->> MetaDB: MLPipelineRun 생성 + + %% 평가 + MLWorker ->> ObjStore: 평가용 데이터셋 읽기 + ObjStore -->> MLWorker: 평가 데이터셋 (immutable versioned artifact) + MLWorker ->> MLWorker: 후보 모델 vs 기준 모델 비교 평가 + MLWorker ->> MetaDB: 평가 결과 집계 저장 + MLWorker ->> ObjStore: 평가 질의별 상세 아티팩트 저장 + + alt 평가 PASS + MLWorker ->> MEE: 후보 모델 로드 요청 + MEE ->> ModelFiles: 후보 모델 아티팩트 조회 + ModelFiles -->> MEE: 후보 모델 아티팩트 + MEE -->> MLWorker: readiness 확인 + MLWorker ->> MEE: 재색인용 임베딩 요청 (후보 모델) + MEE -->> MLWorker: 임베딩 벡터 + MLWorker ->> VS: 후보 모델 전용 인덱스 구축 + Note over MLWorker, VS: 전체 데이터의 즉시 재색인은 필수 아님 + Note over MLWorker, VS: 신규 유입 데이터와 고활성 데이터부터 우선 반영 + Note over MLWorker, VS: 이 과정에서도 사용자 검색은 기존 서빙 유지 + MLWorker ->> MetaDB: 마지막 정상 서빙 조합 스냅샷 저장 + Note over MetaDB: active/previous 조합을 롤백 복구 기준으로 보존 + MLWorker ->> MEE: 서빙 모델 전환 + MLWorker ->> MetaDB: ModelRelease 갱신
(active=candidate, previous=직전 active) + Note over MLWorker, VS: 서빙 전환 후 남은 오래된 세대 데이터는
최신 active 기준으로 점진 재임베딩 + Note over MLWorker, VS: 온라인 검색은 active와 previous의 최대 2세대까지만 병행 지원 + else 평가 FAIL 또는 시스템 ERROR + MLWorker ->> MetaDB: MLPipelineRun 실패 단계 및 유형 기록 + Note over MLWorker, MetaDB: 기존 서빙 유지,
Admin Dashboard에서 실패 상태 확인 가능 + end + end + + +``` + +# 5. Admin_Video_Ops +```mermaid +sequenceDiagram + participant Admin as Admin Dashboard + participant CoreAPI as Core API Server + participant MetaDB as Metadata DB + participant Broker as Message Broker + participant PipelineWorker as Media & AI Pipeline Worker + participant ObjStore as Object Storage + + Note over Admin, CoreAPI: 모든 Admin 요청은 JWT claim role 기반 운영자 권한 검증,
소유권(user_id) 제한 없이 모든 리소스 접근 + + %% === 파이프라인 상태 조회 === + rect rgb(230, 245, 255) + Note over Admin, MetaDB: 파이프라인 상태 조회 + Admin ->> CoreAPI: 임의 video_id 처리 현황 조회 + CoreAPI ->> MetaDB: Video 상태 및 실패 상세 조회 + MetaDB -->> CoreAPI: 처리 현황, failed_stage, error_message + CoreAPI -->> Admin: 처리 현황 및 실패 상세 응답 + end + + %% === 재처리 === + rect rgb(245, 255, 230) + Note over Admin, PipelineWorker: 비디오 재처리 + Admin ->> CoreAPI: 임의 video_id 재처리 요청 + CoreAPI ->> MetaDB: 현재 Video.status 확인 + MetaDB -->> CoreAPI: 현재 상태 + Note over CoreAPI: 재처리 가능 상태인지 검증 후 진행 + CoreAPI ->> MetaDB: Video.status를 PENDING으로 초기화 + CoreAPI ->> Broker: PREPROCESS_REQUEST 발행 + CoreAPI -->> Admin: 202 Accepted + Broker ->> PipelineWorker: PREPROCESS_REQUEST 전달 + PipelineWorker ->> MetaDB: Video 정보 로드, failed_stage 확인 + MetaDB -->> PipelineWorker: failed_stage, 보존 산출물 정보 + PipelineWorker ->> PipelineWorker: 완료된 작업 Skip, 안전한 재개 지점부터 Resume + end + + %% === 삭제 === + rect rgb(255, 245, 230) + Note over Admin, ObjStore: 비디오 삭제 + Admin ->> CoreAPI: 임의 video_id 삭제 요청 + CoreAPI ->> MetaDB: Video.status를 DELETING으로 전이 + Note over MetaDB: 이 시점부터 검색 범위에서 즉시 제외 + CoreAPI ->> Broker: DELETE_REQUEST 발행 + CoreAPI -->> Admin: 202 Accepted + Broker ->> PipelineWorker: DELETE_REQUEST 전달 + PipelineWorker ->> MetaDB: VectorIndexEntry, Chunk,
TranscriptSegment, Asset 삭제 (단일 트랜잭션) + PipelineWorker ->> MetaDB: Video 레코드 hard-delete + PipelineWorker ->> ObjStore: 원본 영상, 오디오, 키프레임 삭제 (비동기) + Note over PipelineWorker: 수집 피드백 이벤트 및 학습 데이터셋은 보존 + end +``` + +# 6. Admin_ML_ops + +```mermaid + +sequenceDiagram + participant Admin as Admin Dashboard + participant CoreAPI as Core API Server + participant MetaDB as Metadata DB + participant Broker as Message Broker + participant MLWorker as ML Lifecycle Worker + participant ModelFiles as Model Artifact Files + participant IndexSnaps as Index Snapshot Files + participant MEE as Managed Embedding Endpoint + participant VS as Vector Store + + Note over Admin, CoreAPI: 모든 Admin 요청은 JWT claim role 기반 운영자 권한 검증 + + %% === ML 파이프라인 상태 조회 === + rect rgb(230, 245, 255) + Note over Admin, MetaDB: ML 파이프라인 상태 조회 + Admin ->> CoreAPI: MLPipelineRun 상태 조회 + CoreAPI ->> MetaDB: MLPipelineRun 진행 상태 및 실패 현황 조회 + MetaDB -->> CoreAPI: 실행 상태, 실패 단계/유형,
대기 실행 유무, FAIL/ERROR 구분 + CoreAPI -->> Admin: ML 파이프라인 현황 응답 + end + + %% === ML 파이프라인 수동 재트리거 === + rect rgb(245, 255, 230) + Note over Admin, MLWorker: ML 파이프라인 수동 재트리거 + Admin ->> CoreAPI: ML 파이프라인 재트리거 요청 + CoreAPI ->> MetaDB: MLPipelineRun 상태 확인 + MetaDB -->> CoreAPI: 현재 실행 상태 + CoreAPI ->> MetaDB: MLPipelineRun 상태 갱신 + CoreAPI ->> Broker: ML 재트리거 작업 발행 + CoreAPI -->> Admin: 202 Accepted + Broker ->> MLWorker: 재트리거 작업 전달 + MLWorker ->> MLWorker: 파이프라인 재트리거
(실패한 경우 실패 지점부터 재개) + end + + %% === 모델 롤백 === + rect rgb(255, 245, 230) + Note over Admin, VS: 모델 롤백 + Admin ->> CoreAPI: 모델 롤백 요청 + CoreAPI ->> Broker: ROLLBACK_REQUEST 발행 + CoreAPI -->> Admin: 202 Accepted + Broker ->> MLWorker: 롤백 작업 전달 + + MLWorker ->> MetaDB: ModelRelease 조회 + MetaDB -->> MLWorker: 마지막 정상 서빙 조합 스냅샷 + + MLWorker ->> MetaDB: 문제 모델 버전으로 생성된 데이터 식별 + MLWorker ->> MetaDB: 영향 영상 search_serving_state=ROLLBACK_EXCLUDED + Note over Admin, CoreAPI: 일부 영상이 복구 중이라
현재 검색 범위에서 제외될 수 있음 + + MLWorker ->> ModelFiles: 스냅샷 기준 롤백 대상 모델 아티팩트 조회 + ModelFiles -->> MLWorker: 롤백 대상 모델 아티팩트 + MLWorker ->> MEE: 롤백 대상 모델 로드 요청 + MEE -->> MLWorker: readiness 확인 + + MLWorker ->> IndexSnaps: 스냅샷 기준 인덱스 조회 + IndexSnaps -->> MLWorker: 롤백 대상 인덱스 스냅샷 + MLWorker ->> VS: 스냅샷 인덱스 복원 + VS -->> MLWorker: 복원 완료 + + MLWorker ->> MetaDB: ModelRelease 갱신
(스냅샷 기준 active/previous 복원) + Note over MetaDB: candidate 관련 메타데이터 초기화 + + MLWorker ->> VS: 영향 데이터 백그라운드 재임베딩 및 인덱스 반영 + MLWorker ->> MetaDB: 복구 완료 영상부터 SERVABLE 복귀 + Note over VS: 문제 모델 인덱스와 불필요해진 데이터는 이후 비동기 정리 가능 + end + + + ``` \ No newline at end of file