README.md

---
title: Cafeteria Multimodal Menu Classifier
emoji: 🍱
colorFrom: pink
colorTo: purple
sdk: gradio
sdk_version: "3.41.2"
app_file: app.py
pinned: false
---

# 학식 이미지 기반 멀티모달 메뉴 분석 웹앱  
ConvNeXt · CLIP · BLIP 기반 자동 학식 분류 & 캡션 생성 & 칼로리 분석 시스템

본 웹 애플리케이션은 학식(구내식당) 메뉴 이미지를 업로드하면,  
이미지 분류 모델과 멀티모달 모델을 활용하여 메뉴를 자동으로 예측하고  
칼로리, 유사 메뉴, 이미지 설명 등을 제공하는 프로젝트입니다.

---

##  프로젝트 개요

이 시스템은 총 3개의 AI 모델을 결합하여 완성된 멀티모달 분석 서비스입니다.

### 1) ConvNeXt-Base 
- 17개의 “병합 대분류” 메뉴를 분류  
- 학식 이미지 5,120장으로 직접 재학습  
- Top-1 및 Top-3 확률 제공

### 2) CLIP 
- 텍스트 임베딩과 이미지 임베딩 비교  
- 대분류 기준 유사 메뉴 Top-3 추천

### 3) BLIP 
- 이미지 캡션 생성 (영문 설명 제공)

### 4) 칼로리 + 활동량 기반 맞춤 코멘트  
- 세부 메뉴별 대략적인 칼로리를 제공하며,  
  칼로리 추정치는 식약처·국가표준식품성분 DB(Korean Food Composition Database)의 ‘유사 음식군’ 1인분 열량 값을 기반으로 산출되며, 실제 학식 메뉴와 동일하지 않을 수 있습니다.
- 사용자가 선택한 오늘의 활동량(거의 안 움직임 / 보통 활동 / 많이 움직임)에 따라  
  “적절해요 / 조금 많아요 / 조금 적어요” 등의 간단한 피드백을 제공합니다.  
- 해당 코멘트는 건강·의학적 조언이 아니며 참고용으로만 제공됩니다.


---

## 기능 요약

| 기능 | 설명 |
|------|------|
| 이미지 업로드 | 학식 사진 입력 |
| ConvNeXt 메뉴 분류 | 17개 병합 클래스 중 1개 예측 |
| 세부 메뉴 선택 | 27개 세부 메뉴 중 선택 가능 |
| 칼로리 분석 | 식약처·국가표준식품성분 DB 기반 ‘비슷한 음식’의 1인분 열량을 바탕으로 학식 메뉴에 가장 가까운 값으로 추정한 칼로리 제공 |
| 활동량 기반 피드백 | 오늘 활동량 기준 "적절/과함/부족" 표시 |
| CLIP 유사 메뉴 | 유사 메뉴 Top-3 추천 |
| BLIP 캡션 | 이미지 캡션 생성 (영문) |

---

## 사용하는 AI 모델

- ConvNeXt-Base  
  학습 완료된 17클래스 음식 분류 모델  
- CLIP  
  텍스트 유사도 기반 멀티모달 분류  
- BLIP  
  이미지 캡션 생성  

---

## 프로젝트 구조
├── app.py # Gradio 웹앱 메인 코드
├── requirements.txt # 필요한 Python 패키지
├── models/
│ └── convnext_base_merged_ema.pth # 학습된 ConvNeXt 가중치
├── multimodal_assets/
│ └── clip_text_embeds.pt # CLIP 텍스트 임베딩
└── system_card.md # 모델·시스템 설명 문서


---

## 사용 방법

1. 학식 사진 업로드 
2. 활동량(거의 안 움직임 / 보통 / 많이 움직임) 선택  
3. 세부 메뉴 직접 선택 또는 “모델에 맡기기” 유지  
4. “분석 실행” 버튼 클릭  
5. 결과 확인

---

## 제한 사항

- 칼로리 정보는 참고용이며 실제 음식과 다를 수 있습니다.  
- BLIP 캡션은 이미지 특성에 따라 부정확하거나 단순한 설명을 제공할 수 있습니다.  
- 학식 이미지 중심으로 학습되었기 때문에 일반 음식 이미지에는 정확도가 낮을 수 있습니다.

---

## 라이선스 & 저작권

- ConvNeXt: MIT  
- CLIP: OpenAI License  
- BLIP: BSD  
- 학식 이미지 데이터셋: 직접 수집 (개인정보 없음)  
- 본 프로젝트는 교육·연구 목적입니다.

---

## 시스템 카드 (System Card)
본 웹 데모는 학식 스캐너 시스템을 기반으로 하며,
시스템에 대한 상세 설명과 설계 내용은 아래 시스템 카드에서 확인할 수 있습니다.

시스템 카드:
https://huggingface.co/simkyuri/cafeteria-food-scanner-system


Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference