README.md

---
title: Ko-FreshQA Leaderboard
emoji: 🚀
colorFrom: blue
colorTo: green
sdk: gradio
app_file: app.py
pinned: false
license: apache-2.0
hf_oauth: true
---

## Ko-FreshQA Leaderboard
한국어 FreshQA 기반 자동 평가/리더보드 시스템입니다. 참가자가 업로드한 CSV의 `model_response`를 기준 데이터와 매칭하고, Upstage Solar 모델로 Relaxed/Strict 평가를 수행한 뒤 결과를 리더보드에 반영합니다. Gradio UI로 실행됩니다.

### 핵심 기능
- 데이터셋 배포: DEV/TEST CSV 다운로드 탭 제공
- 제출 및 자동 평가: 업로드된 CSV를 병합 → 평가 → 지표 집계 → 리더보드 반영
- 상세 지표: fact type, 전제 유효성(vp/fp), hop(one/multi), 연도(old/new), 도메인별 정확도
- 제출 제한(옵션): 사용자별 하루 3회 제한 기능 (Hugging Face 저장소 기반)

---

## 디렉터리 구조
- `app.py`: Gradio 앱 초기화 및 탭 구성
- `config.py`: 환경변수 로드 및 필수 설정 검증
- `freshqa/`
  - `fresheval.py`: 단일 샘플 평가 로직
  - `fresheval_parallel.py`: 데이터프레임 병렬 평가 래퍼
  - `freshqa_acc.py`: 평가 결과 집계(정확도 계산 및 도메인별 통계)
  - `merge_csv_with_model_response.py`: 기준 데이터와 사용자 CSV 병합
- `src/`
  - `submission_handler.py`: 제출부터 리더보드 반영까지 전체 오케스트레이션
  - `submission_tracker.py`: 제출 이력 추적(HF repo 기반, 옵션)
  - `leaderboard_manager.py`: 리더보드 CSV 로드/저장/표시용 정리
  - `quick_csv_loader.py`, `hf_private_csv_loader.py`: HF Private repo에서 CSV 로드 유틸
  - `api_key_rotator.py`, `utils.py`: 유틸리티
- `ui/`
  - `leaderboard_tab.py`, `submission_tab.py`, `dataset_tab.py`, `styles.css`
- `data/leaderboard_results.csv`: 리더보드 누적 데이터

---

## 요구 사항
- Python 3.10
- Upstage API 키(단일 또는 다중)
- Hugging Face 토큰(HF Private repo 접근용)
- Hugging Face Dataset repo
  - 기준 데이터: `FRESHQA_DATA_REPO_ID` / `FRESHQA_DATA_FILENAME`
  - (옵션) 제출 추적 저장소: `SUBMISSION_TRACKER_REPO_ID`
  - (옵션) 리더보드를 Hugging Face dataset에 백업하려면 `UPLOAD_LEADERBOARD_TO_HF=true` 설정


설치:
```bash
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
```

또는 Conda:
```bash
conda env create -f environment.yml
conda activate freshqa-leaderboard
```

---

## 환경 변수(.env)
`env.example`를 `.env`로 복사 후 값 채우기:
```bash
cp env.example .env
```

필수/주요 변수
- HF_TOKEN
- FRESHQA_DATA_REPO_ID
- FRESHQA_DATA_FILENAME (기본값: ko-freshqa_2025_total.csv)
- UPSTAGE_API_KEY 또는 UPSTAGE_API_KEYS(콤마 구분)
- ENABLE_SUBMISSION_LIMIT (기본: true)
- SUBMISSION_TRACKER_REPO_ID (제출 제한 사용 시 필요)
- UPLOAD_LEADERBOARD_TO_HF  
  - true: 리더보드를 HF Private Dataset에도 백업(권장: 운영 환경)
  - false: 로컬 CSV에만 저장(권장: 로컬 개발)


검증: 앱 시작 시 `Config.validate_required_configs()`가 누락된 필수 설정을 검사합니다.

---

## 실행
로컬:
```bash
python app.py
```
기본 포트: 7860

Hugging Face Spaces:
- 환경변수 `SPACE_ID`가 존재하면 Spaces 모드로 동작합니다.

Docker(옵션):
- `Dockerfile`, `docker-compose.yml` 제공 (필요 시 설정에 맞게 수정)

---

## 사용 방법(Gradio UI)
1) 데이터셋 탭
- DEV/TEST CSV 다운로드

2) 제출 및 평가 탭
- 업로드: TEST CSV에 `model_response`가 채워진 파일
- 입력: 제출자 이름, 사용 모델, 설명
- 평가: Upstage Solar 모델로 Relaxed/Strict 동시 수행
- 출력: 전체/세부 지표가 계산되어 리더보드에 반영

3) 리더보드 탭
- 제출 결과가 `data/leaderboard_results.csv`에 누적
  - (옵션) `UPLOAD_LEADERBOARD_TO_HF=true`인 경우 Hugging Face Dataset에도  
  `leaderboard_results.csv`로 자동 업로드됩니다.
- 검색/새로고침 가능

---

## 동작 흐름(내부)
1) 제출 접수: `src/submission_handler.py::process_submission`
2) 사용자 CSV 로드 → 기준 데이터와 병합:
   - `freshqa/merge_csv_with_model_response.py::merge_dataframe_with_model_response_df`
3) 평가:
   - `freshqa/fresheval_parallel.py::evaluate_dataframe` → `freshqa/fresheval.py::FreshEval`
4) 정확도 집계:
   - `freshqa/freshqa_acc.py::calculate_accuracy`, `process_freshqa_dataframe`
5) 저장:
   - 리더보드: `src/leaderboard_manager.py::append_to_leaderboard_data`
      - (옵션) 리더보드 HF 저장소 백업: `UPLOAD_LEADERBOARD_TO_HF=true`일 때만
   - (옵션) 제출 이력: `src/submission_tracker.py` (ENABLE_SUBMISSION_LIMIT=true 일 때만)

주의: `ENABLE_SUBMISSION_LIMIT=false`인 경우, 제출 이력 추적용 Hugging Face 저장소 접근을 시도하지 않도록 코드가 반영되어 있습니다.

---

## 제출 제한(옵션)
- 설정: `ENABLE_SUBMISSION_LIMIT=true`(기본)
- 저장소: `SUBMISSION_TRACKER_REPO_ID`에 `user_submissions.json` 관리
- 로직:
  - 한 사용자 하루 3회 성공 제출까지 카운트
  - 한국 시간 기준 00:00에 일자 단위로 카운트
  - 비활성화 시(HF 저장소 접근 없음): `SubmissionHandler`가 추적기를 생성하지 않음

---

## 트러블슈팅
- 시작 시 “필수 설정 누락” 오류
  - `.env`에서 `UPSTAGE_API_KEY(or KEYS)`, `HF_TOKEN`, `FRESHQA_DATA_REPO_ID` 확인
- 제출 제한 비활성화인데 HF 404 경고가 보임
  - 현 버전은 `ENABLE_SUBMISSION_LIMIT=false`일 때 제출 추적기를 초기화하지 않도록 수정됨
- HF 404 (제출 제한 활성화)
  - `SUBMISSION_TRACKER_REPO_ID` 저장소에 `user_submissions.json`이 없으면 최초 접근 시 404가 날 수 있습니다. 파일을 빈 JSON `{}`으로 생성해 두세요.

---

## 라이선스/출처
- 본 리더보드는 FreshQA에서 영감을 받아 제작되었습니다.

문의 사항은 이슈로 등록해 주세요.