README.md

metadata

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 설정

설치:

python -m venv venv && source venv/bin/activate
pip install -r requirements.txt

또는 Conda:

conda env create -f environment.yml
conda activate freshqa-leaderboard

---

환경 변수(.env)

env.example를 .env로 복사 후 값 채우기:

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()가 누락된 필수 설정을 검사합니다.

---

실행

로컬:

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에서 영감을 받아 제작되었습니다.

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