Phase 2: 시스템 개선 끝판왕! AI MARK 최종 보고서로 본 안정성 & 성능 개선 과정

AI MARK 시스템 개선 작업 최종 보고서

보고 일자: 2025년 9월 18일 담당: 클라우드 기반 AI

1. 작업 개요

본 문서는 AI MARK 시스템의 초기 모듈화부터 시작하여, 벤치마크 툴 분석을 통해 도출된 안정성 및 성능 개선 계획을 적용하고, 최종적으로 발견된 모든 이슈를 해결하기까지 오늘 하루 동안 진행된 모든 작업 내용을 종합하여 보고하는 것을 목적으로 합니다.

이 일련의 과정들을 통해 시스템은 초기 버전의 불안정성을 극복하고, 유지보수성과 안정성이 극대화된 견고한 아키텍처로 재탄생했습니다.

2. 주요 개선 작업 내용

2.1. 아키텍처 재설계: 파일 분할 및 모듈화

• 문제점: chat.py와 app.js라는 거대한 단일 파일에 모든 기능이 집중되어 코드의 가독성과 유지보수성이 매우 낮았습니다.
• 해결 과정:
  • 백엔드: chat.py를 models, database, api_routes, core_utils 등 기능별로 5개의 파일로 분할했습니다.
  • 프론트엔드: app.js를 session, chat, ui_voice 등 역할별로 4개의 파일로 분할했습니다.
• 최종 결과: 각 파일이 명확한 단일 책임(Single Responsibility)을 갖게 되어, 향후 기능 추가 및 수정이 용이한 확장 가능한 구조를 완성했습니다.

2.2. 시스템 안정성 및 성능 강화

벤치마크 툴(benchmark_server.py)의 우수한 기능들을 시스템에 이식하여 안정성을 극대화했습니다.

• VRAM 자동 재시도:
  • 기능: 모델 로딩 시 VRAM 부족(out of memory) 오류가 발생하면, 시스템이 스스로 GPU 레이어 수를 줄여 자동으로 로드를 재시도합니다.
  • 기대 효과: 사용자의 다양한 하드웨어 환경에서도 VRAM 부족으로 인한 실행 실패를 최소화하여 시스템의 자체 복원력을 크게 향상시켰습니다.
• 외부 설정 파일 도입:
  • 기능: settings.py에 하드코딩되어 있던 모델 및 데이터 경로를 config.json 파일로 완전히 분리했습니다.
  • 기대 효과: 사용자는 더 이상 코드를 직접 수정할 필요 없이 config.json 파일만 수정하면 되므로, 사용자 편의성과 배포 용이성이 극대화되었습니다.
• 실시간 시스템 모니터링:
  • 기능: 백엔드의 /health_stream이 pynvml 라이브러리를 통해 GPU의 VRAM 사용량, 전력 소모량(W), 온도(°C) 와 같은 상세 정보를 실시간으로 스트리밍합니다.
  • 기대 효과: 프론트엔드 UI 상단에 현재 시스템 부하가 직관적으로 표시되어, 사용자가 모델 추론 시 시스템의 상태를 실시간으로 파악할 수 있게 되었습니다.

2.3. 포괄적인 오류 처리 시스템 구축

"막고, 잡고, 알리고, 멈춘다"는 4단계 전략에 따라 오류 처리 파이프라인을 완성했습니다.

1. 사전 방지 (막고): /이미지와 같은 명령어 뒤에 내용이 없을 경우, 프론트엔드에서 미리 요청을 차단하여 불필요한 서버 부하를 줄입니다.
2. 견고한 처리 (잡고): 백엔드의 모델 추론 로직 전체를 try...except 블록으로 감싸, 어떤 오류가 발생해도 서버가 중단되지 않도록 설계했습니다.
3. 명확한 피드백 (알리고): 백엔드에서 오류 발생 시, 프론트엔드에 error 타입의 SSE 이벤트를 전송합니다. 프론트엔드는 이를 받아 사용자에게 눈에 띄는 붉은색 toast 알림으로 오류 상황을 즉시 전달합니다.
4. 안정적인 중단 (멈춘다): 사용자가 '중지' 버튼을 눌렀을 때, AbortController를 통해 진행 중인 작업을 안전하게 취소하는 기능은 기존부터 잘 구현되어 있었습니다.

3. 최종 이슈 해결

마지막 종합 검사에서 발견된 모든 이슈를 해결하여 코드의 완성도를 높였습니다.

• [버그 수정] database.py: 세션 제목 변경 시 모든 세션의 제목이 함께 변경되던 심각한 버그를 수정하여 데이터 무결성을 확보했습니다.
• [개선] core_utils.py: API 요청 시 대화 기록 턴 수가 무시되던 문제를 해결했습니다.
• [개선] 프론트엔드: 재시도 버튼의 로직을 강화하고, 파일 업로드 실패 시 더 상세한 오류 메시지를 제공하도록 개선했습니다.

4. 최종 결론

금일 진행된 일련의 작업을 통해 AI MARK 시스템은 초기 프로토타입 수준을 넘어, 실제 운영 환경에서도 안정적으로 작동할 수 있는 높은 완성도를 갖추게 되었습니다. 모듈화된 아키텍처, 지능적인 오류 처리, 강화된 안정성 기능은 향후 웹 검색(RAG), 장기 기억 등 더 복잡하고 고도화된 기능을 추가하기 위한 튼튼한 기반이 될 것입니다.

이상으로 금일 작업 보고를 마칩니다.