🤗 34. 실습편 10: smolagents 평가루프 미니프로젝트 핸즈온 1

이번 실습은 smolagents 에이전트를 실행하고, 정답 검증기(evaluator)로 품질을 점수화하는 미니 프로젝트다.

• 이전 편: 🤗 33. 본편 20

flowchart TD
  A[사용자 질문 세트] --> B[CodeAgent 실행]
  B --> C[예측 답변 생성]
  C --> D[Evaluator 채점]
  D --> E{점수 >= 임계값?}
  E -- 예 --> F[PASS 로그 저장]
  E -- 아니오 --> G[실패원인 기록 후 프롬프트/도구 보정]

실습 목표

1. smolagents CodeAgent를 실행한다.
2. 테스트셋(질문/정답) 기반 자동 채점을 구현한다.
3. PASS 기준(예: 80점) 미달 시 실패 원인을 확인한다.

---

1) 준비

Step 1-1. 작업 폴더 생성

• 도구: 터미널
• 입력: 없음
• 실행명령:

mkdir -p ~/hf-agents-day34 && cd ~/hf-agents-day34

• 성공판정:

pwd

출력에 hf-agents-day34 포함

Step 1-2. 가상환경 + 패키지 설치

• 도구: Python 3.10+
• 입력: 없음
• 실행명령:

python3 -m venv .venv
source .venv/bin/activate
pip install -U smolagents

• 성공판정:

python -c "import smolagents; print('OK')"

OK 출력

Step 1-3. HF 토큰 설정

• 도구: 환경변수
• 입력: Hugging Face Access Token
• 실행명령:

export HF_TOKEN="hf_xxx"

• 성공판정:

echo ${HF_TOKEN:+set}

set 출력

---

2) 미니 프로젝트 코드 작성

Step 2-1. day34_eval_loop.py 저장

• 도구: 파일 편집기
• 입력: 아래 코드

import json
from pathlib import Path
from datetime import datetime
 
from smolagents import CodeAgent, HfApiModel
 
DATASET = [
    {"q": "대한민국 수도는?", "a": "서울"},
    {"q": "2+2는?", "a": "4"},
    {"q": "파이썬 파일 확장자는?", "a": ".py"},
]
 
RESULT_PATH = Path("eval_result.json")
 
 
def build_agent() -> CodeAgent:
    model = HfApiModel("Qwen/Qwen2.5-72B-Instruct")
    return CodeAgent(
        tools=[],
        model=model,
        max_steps=4,
        additional_authorized_imports=["json"],
    )
 
 
def ask(agent: CodeAgent, question: str) -> str:
    prompt = f"""
너는 짧고 정확하게 답하는 어시스턴트다.
질문: {question}
설명 없이 정답만 한 줄로 출력해.
"""
    out = agent.run(prompt)
    return str(out).strip()
 
 
def score(pred: str, gold: str) -> int:
    return 100 if gold.strip().lower() == pred.strip().lower() else 0
 
 
if __name__ == "__main__":
    agent = build_agent()
 
    rows = []
    total = 0
    for item in DATASET:
        pred = ask(agent, item["q"])
        s = score(pred, item["a"])
        total += s
        rows.append({
            "question": item["q"],
            "gold": item["a"],
            "pred": pred,
            "score": s,
        })
 
    avg = total / len(DATASET)
    passed = avg >= 80
 
    result = {
        "checked_at": datetime.utcnow().isoformat() + "Z",
        "average_score": avg,
        "pass": passed,
        "rows": rows,
    }
 
    RESULT_PATH.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
    print("saved: eval_result.json")
 
    if not passed:
        raise SystemExit(f"eval_failed:average_score={avg}")

• 성공판정:

python -m py_compile day34_eval_loop.py

오류 없이 종료

---

3) 실행

Step 3-1. 평가 루프 실행

• 도구: Python
• 입력: 기본 DATASET 3개
• 실행명령:

python day34_eval_loop.py
cat eval_result.json

• 성공판정:
  • saved: eval_result.json 출력
  • average_score 확인
  • pass가 true면 통과

Step 3-2. 실패 유도 테스트

• 도구: 코드 편집기 + Python
• 입력: DATASET의 정답 하나를 일부러 틀리게 수정(예: 서울 → 부산)
• 실행명령:

python day34_eval_loop.py

• 성공판정:
  • eval_failed:average_score=...로 종료
  • eval_result.json에 어떤 문항이 0점인지 기록됨

---

트러블슈팅 (3개 이상)

1. 401 Unauthorized 또는 모델 호출 실패

• 원인: HF_TOKEN 미설정/권한 부족
• 해결:

echo ${HF_TOKEN:+set}

set 아니면 토큰 재설정 후 재실행

2. ModuleNotFoundError: smolagents

• 원인: 가상환경 미활성화 또는 설치 누락
• 해결:

source .venv/bin/activate
pip install -U smolagents

3. eval_failed:average_score=...

• 원인: 프롬프트가 장황해서 정답 형식 불일치
• 해결: 프롬프트를 정답만 출력으로 더 강하게 제한, 필요 시 score 함수에 후처리(strip, 소문자화) 보강

4. 응답에 코드블록/설명이 섞임

• 원인: 모델 출력 형식 불안정
• 해결: ask()에서 백틱 제거 정규화 추가

---

체크리스트

• venv 생성 및 smolagents 설치 완료
• day34_eval_loop.py 문법 검사 통과
• eval_result.json 생성 확인
• 평균점수 및 PASS/FAIL 기준 확인
• 실패 유도 테스트로 에러 경로 검증

참고 링크 (우선순위)

1. https://github.com/huggingface/agents-course
2. https://huggingface.co/learn/agents-course
3. https://huggingface.co/docs/smolagents

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성했고, 실습 절차(도구/입력/실행명령/성공판정)와 코드는 사람이 검토해 확정했다.