DEVELOPMENT.md

🧗‍♂️ 개발 과정 및 문제 해결 (Development Journey)

이 문서에서는 Emotion Diary 프로젝트를 진행하며 겪었던 주요 기술적 도전 과제와 이를 해결하기 위한 과정을 상세히 기록합니다.

---

1. 대용량 AI 모델 관리 및 배포 전략 수립

• 문제점: 1GB가 넘는 AI 모델 파일을 Git LFS로 관리했으나, Hugging Face Spaces의 1GB 저장 공간 한계(Storage limit reached)와 LFS 파일-포인터 불일치(LFS pointer does not exist) 등 배포 과정에서 지속적인 오류가 발생했습니다.
• 해결 과정: 모델과 앱 코드의 완전한 분리 전략을 채택했습니다.
  • 대용량 모델은 Hugging Face Hub에 별도로 업로드하여 버전 관리합니다.
  • GitHub 저장소에서는 Git LFS 추적을 완전히 제거하고 순수 앱 코드만 관리하도록 변경했습니다.
  • GitHub Actions 워크플로우(sync-to-hub.yml)의 lfs 옵션을 false로 설정하여, 배포 시에는 앱 코드만 Spaces로 푸시하도록 수정했습니다.
• 결론: Spaces 앱 실행 시점에서 emotion_engine.py가 Hub로부터 모델을 다운로드하도록 구현했습니다. 이를 통해 저장 공간 문제를 근본적으로 해결하고, 코드 변경 시 모델을 다시 업로드할 필요가 없는 효율적인 배포 파이프라인을 완성했습니다.

---

2. CI/CD 파이프라인의 분산 환경 인증 문제 해결

• 문제점: 로컬에서 git push로 트리거된 GitHub Actions가 Hugging Face Spaces에 접근할 때 Invalid credentials 인증 오류가 발생했습니다. 이는 Spaces의 Secret과 GitHub Actions의 Secret 역할에 대한 혼동 때문이었습니다.
• 해결 과정: '배포 로봇(GitHub Actions)'과 '빌드 로봇(Spaces)'의 개념으로 역할을 명확히 분리하여 접근했습니다.
  • GitHub Actions Secret (HF_TOKEN): '배포 로봇'이 Hugging Face 저장소(Repository)에 코드를 푸시할 때 필요한 write 권한 토큰을 등록했습니다.
  • Hugging Face Spaces Secret (HF_TOKEN): '빌드 로봇'이 내부적으로 LFS 파일 처리나 다른 private 저장소에 접근할 때 필요한 토큰을 등록했습니다. (이 프로젝트에서는 모델을 분리하면서 Spaces Secret의 필요성은 낮아졌습니다.)
• 결론: 각기 다른 실행 환경에서 필요한 인증 정보를 명확히 분리하고 올바른 권한의 토큰을 제공함으로써 CI/CD 파이프라인의 인증 문제를 해결했습니다.

---

3. Flask 애플리케이션 구조 설계 및 런타임 오류 디버깅

• 문제점: 개발 초기, 모든 로직이 담긴 단일 파일 구조(app.py)로 인해 순환 참조(Circular Import) 및 ModuleNotFoundError가 발생했습니다. 또한, API가 호출될 때마다 AI 모델을 로딩하여 응답 속도가 매우 느렸습니다.
• 해결 과정: Flask의 Application Factory 패턴을 도입하여 프로젝트 구조를 체계적으로 재설계했습니다.
  • src/__init__.py의 create_app 함수를 통해 앱의 모든 구성요소(DB, 블루프린트, 설정)를 조립하도록 변경했습니다.
  • 앱이 시작되는 시점(create_app 내부)에서 AI 모델을 단 한 번만 로드하여 app 객체에 저장(app.emotion_classifier)했습니다.
• 결론: 각 API 요청에서는 current_app 프록시를 통해 미리 로드된 모델을 참조하게 하여, 메모리 효율성과 응답 속도를 극대화했습니다. 이를 통해 확장 가능하고 안정적인 백엔드 구조를 완성할 수 있었습니다.

---

4. 모델 성능 하락 및 정확도 개선 과정

• 문제점: 개발 과정에서 원본 학습 데이터가 유실되어 모델을 재학습하자, 정확도가 초기 모델보다 현저히 낮아지는 문제에 직면했습니다.
• 해결 과정: 성능을 복원하고 개선하기 위해 다음과 같은 다양한 방법을 체계적으로 실험했습니다.
  • 혼동 행렬(Confusion Matrix) 분석: 모델이 어떤 감정들을 서로 혼동하는지 파악하여 문제의 원인을 진단했습니다.
  • 레이블 재구성 (Label Remapping): 세분화된 감정 레이블을 6개 또는 4개의 주요 감정으로 그룹화하여 분류 문제의 복잡도를 조절했습니다.
  • 데이터 불균형 해소: 소수 클래스의 데이터를 증강하는 오버샘플링(Oversampling) 및 각 클래스에 다른 중요도를 부여하는 수동 클래스 가중치(Manual Class Weights)를 적용했습니다.
  • 전이 학습(Transfer Learning) 강화: 감성 분석에 특화된 NSMC(Naver Movie Corpus) 데이터셋으로 1차 사전 학습한 모델을 기반으로, 최종 감정 데이터에 2차 미세조정(Fine-tuning)을 수행했습니다.
• 결론: 여러 실험 결과, '한국어 감성대화 말뭉치' 데이터의 레이블을 6개의 주요 감정으로 매핑하고, 데이터 불균형 문제를 해결하기 위해 수동으로 클래스 가중치를 정교하게 조정하여 학습하는 방식이 약 80%의 정확도를 회복하며 가장 안정적이고 효과적임을 확인했습니다.