Dacon LLM Starter (W&B-first)

프롬프트 레지스트리/롤백, 재현 가능한 실행, 팀 대시보드를 최소 설정으로 제공합니다.

• 모델: OpenAI gpt-4o-mini
• 목표: 뉴스 기사(제목+내용)의 자동차 관련 여부를 0/1 한 글자로 분류
• 평가: accuracy / precision / recall / F1 + 혼동행렬(csv) 로깅
• MLOps: Weights & Biases(W&B) 우선, 없으면 로컬 CSV/대시보드로 동작
• 프롬프트 관리: promptctl.py로 버전/활성/롤백

---

✨ 기능 요약

• CSV/엑셀 입력 지원, title+content 자동 유저 프롬프트 조립
• 시스템 프롬프트 레지스트리: publish / activate / rollback / list
• 정확도/정밀도/재현율/F1 로깅 + 혼동행렬 CSV 산출
• W&B 대시보드(자동) 또는 로컬 Streamlit 대시보드(옵션)
• Docker로 Windows/Mac 동일 환경 보장

---

📁 프로젝트 구조

.
├─ data/
│  ├─ samples.csv              # 예시 데이터 (title, content, label)
│  └─ test.xlsx                # (옵션) 엑셀 데이터
├─ prompts/
│  ├─ auto-binary.md           # 시스템 프롬프트(자동차 0/1)
│  └─ manifest.json            # 프롬프트 레지스트리
├─ src/
│  ├─ run.py                   # 실행/평가/로깅 (W&B 우선)
│  ├─ promptctl.py             # 프롬프트 publish/activate/rollback/list
│  └─ dashboard.py             # 로컬 대시보드(옵션)
├─ Dockerfile
├─ requirements.txt
├─ .env.example
└─ README.md

---

🔧 준비물

• Python 3.11+
• OpenAI API 키
• (선택) W&B 계정 및 API 키

환경 변수는 .env 파일에 넣습니다:

변수	설명	예시
OPENAI_API_KEY	OpenAI 키(필수)	sk-...
WANDB_API_KEY	W&B 키(선택)	xxxxxxxx
WANDB_ENTITY	W&B 워크스페이스(선택)	koreaworldclass 또는 공백
WANDB_PROJECT	W&B 프로젝트명(선택)	dacon-llm-starter

WANDB_API_KEY가 비어 있으면 자동으로 로컬 모드(CSV/Streamlit)만 사용합니다.

---

🧱 설치

로컬(권장)

python -m venv .venv
# Windows PowerShell: . .\.venv\Scripts\Activate.ps1
source .venv/bin/activate
pip install -r requirements.txt
cp .env.example .env  # OPENAI_API_KEY 채우기

Docker

docker build -t dacon-llm-starter .

---

🏃 실행

기본값: data/samples.csv 사용, title+content를 자동으로 유저 프롬프트로 조립, temperature=0.4, max_tokens=1, match-mode=exact로 고정.

가장 간단

python src/run.py

엑셀 사용할 때

python src/run.py --input-file data/test.xlsx --sheet-name 0 --label-col label

특정 프롬프트 버전 고정

python src/run.py --prompt active
# 또는
python src/run.py --prompt auto-binary@1

Docker로 실행

docker run --rm -it --env-file .env -v "$PWD":/app dacon-llm-starter \
  python src/run.py

---

📊 출력/대시보드

• 결과 CSV: outputs/preds_<promptid>_v<ver>.csv

• 혼동행렬: outputs/confusion_matrix_<promptid>_v<ver>.csv

• W&B 실행 링크: 콘솔에 자동 출력

• 로컬 미니 대시보드(옵션):

  streamlit run src/dashboard.py

---

🧪 메트릭

run.py는 아래를 로깅합니다.

• accuracy, precision, recall, f1, rows, elapsed_sec
• 혼동행렬 CSV 파일(Artifacts로 업로드)
• 프롬프트 메타: prompt_id, prompt_version, prompt_sha → W&B에서 프롬프트 버전별 비교/필터 가능

---

🧩 프롬프트 레지스트리 & 롤백

시스템 프롬프트는 prompts/*.md로 파일 관리하고, manifest.json으로 버전/활성화를 기록합니다.

# 현재 상태
python src/promptctl.py list

# 새 버전 등록 + 즉시 활성화
python src/promptctl.py publish --id auto-binary --path prompts/auto-binary.md --notes "car 0/1" --activate

# 특정 버전 활성화
python src/promptctl.py activate auto-binary@2

# 롤백(활성 버전 기준 바로 이전으로)
python src/promptctl.py rollback

대회 규정 형식(유저 프롬프트 템플릿) run.py가 title/content를 감지하면 자동으로 아래 형식으로 조립합니다.

[기사]

제목: {title}

내용: {content}

---

🔒 보안/주의

• .env(키)는 절대 커밋하지 마세요. .gitignore에 포함되어 있습니다.
• 대용량 outputs/나 원본 대회 데이터도 커밋 금지 권장.
• 레이트 리밋/요금 고려: CI에서는 **소량(예: 10행)**으로만 검증하세요.

---