🤗 19. 실습편 05: 정책 FAQ 에이전트 미니프로젝트 핸즈온 1편

이번 편은 실무형 미니 프로젝트/핸즈온으로, 사내 정책 문서(환불/요금제/보안)를 읽고 질문에 답하는 FAQ 에이전트를 만든다.

• 이전 편: 🤗 18. 본편 10
• 다음 편 예고: FAQ 응답 품질 점수화(정확성/근거/금지어) 자동 리포트

한 줄 목표

로컬 정책 파일(JSON) + 질문셋(JSONL) + smolagents CodeAgent로 답변 생성 후, 형식/근거/정확도 기준을 자동 검증한다.

flowchart LR
  A[policy_kb.json] --> B[Python Tool: search_policy]
  C[questions.jsonl] --> D[CodeAgent]
  B --> D
  D --> E[answers.json]
  E --> F[validator.py]
  F --> G{PASS/FAIL}

---

0) 실습 범위(고정)

• 범위 포함
  • 정책 KB 조회 도구 1개(search_policy)를 만들어 에이전트에 연결
  • 질문 8건에 대해 answer, evidence(근거 policy_id) 출력
  • 자동 검증 스크립트로 PASS/FAIL 판단
• 범위 제외
  • 벡터DB/임베딩
  • 외부 API 연동(n8n, Slack)
  • 다국어 답변 튜닝

---

1) 환경 준비

• 도구: 터미널
• 입력: Python 3.10+, 가상환경
• 실행명령:

mkdir -p ~/hf-agents-lab19
cd ~/hf-agents-lab19
python3 -m venv .venv
source .venv/bin/activate
pip install -U smolagents litellm

• 성공판정:
  • (.venv) 프롬프트가 보임
  • python -V 실행 시 버전 출력
  • pip show smolagents 결과가 존재

2) 모델 키 설정

• 도구: 터미널
• 입력: API 키, 모델 ID
• 실행명령:

export OPENAI_API_KEY="YOUR_API_KEY"
export MODEL_ID="openai/gpt-4o-mini"

• 성공판정:

echo "$MODEL_ID"
python - <<'PY'
import os
print("OPENAI_API_KEY set:", bool(os.getenv("OPENAI_API_KEY")))
PY

• 모델 ID 문자열 출력
• OPENAI_API_KEY set: True 출력

3) 정책 KB와 질문셋 만들기

• 도구: 터미널
• 입력: 정책 6개 + 질문 8개
• 실행명령:

cat > policy_kb.json <<'JSON'
[
  {"policy_id":"P-REFUND-7D","topic":"refund","content":"결제 후 7일 이내, 사용량 10% 미만이면 환불 가능하다."},
  {"policy_id":"P-REFUND-EXC","topic":"refund","content":"디지털 다운로드 상품은 결제 즉시 사용으로 간주되어 환불 대상에서 제외된다."},
  {"policy_id":"P-PLAN-UP","topic":"plan","content":"요금제 업그레이드는 즉시 반영되며, 차액은 일할 계산된다."},
  {"policy_id":"P-PLAN-DOWN","topic":"plan","content":"요금제 다운그레이드는 다음 결제 주기부터 적용된다."},
  {"policy_id":"P-SEC-MFA","topic":"security","content":"관리자 계정은 MFA를 반드시 활성화해야 한다."},
  {"policy_id":"P-SEC-LOG","topic":"security","content":"보안 로그는 최소 90일간 보관한다."}
]
JSON
 
cat > questions.jsonl <<'JSONL'
{"qid":"Q1","question":"결제 3일 지났고 거의 안 썼는데 환불 가능해?","expected_policy":"P-REFUND-7D"}
{"qid":"Q2","question":"다운로드형 리포트 샀는데 바로 환불돼?","expected_policy":"P-REFUND-EXC"}
{"qid":"Q3","question":"요금제 올리면 언제 반영돼?","expected_policy":"P-PLAN-UP"}
{"qid":"Q4","question":"요금제 내리면 바로 내려가?","expected_policy":"P-PLAN-DOWN"}
{"qid":"Q5","question":"관리자 계정에 2단계 인증 필수야?","expected_policy":"P-SEC-MFA"}
{"qid":"Q6","question":"보안 로그는 얼마나 보관해야 해?","expected_policy":"P-SEC-LOG"}
{"qid":"Q7","question":"환불은 무조건 30일 이내면 돼?","expected_policy":"P-REFUND-7D"}
{"qid":"Q8","question":"업그레이드 차액 계산 방식은?","expected_policy":"P-PLAN-UP"}
JSONL

• 성공판정:

python - <<'PY'
import json
print('kb:', len(json.load(open('policy_kb.json'))))
print('q :', sum(1 for _ in open('questions.jsonl')))
PY

• kb: 6, q : 8 출력

4) 에이전트 코드 작성

• 도구: 에디터/터미널
• 입력: 아래 코드
• 실행명령:

cat > lab19_policy_faq_agent.py <<'PY'
from __future__ import annotations
 
import json
import os
from pathlib import Path
from typing import List, Dict, Any
 
from smolagents import CodeAgent, LiteLLMModel, tool
 
KB_PATH = Path("policy_kb.json")
Q_PATH = Path("questions.jsonl")
OUT_PATH = Path("answers.json")
 
KB: List[Dict[str, Any]] = json.loads(KB_PATH.read_text(encoding="utf-8"))
 
@tool
def search_policy(query: str) -> str:
    """질문(query)에 가장 관련 높은 정책 3개를 문자열로 반환한다."""
    q = query.lower()
    scored = []
    for row in KB:
        txt = (row["topic"] + " " + row["content"]).lower()
        score = 0
        for token in ["환불", "refund", "요금제", "upgrade", "down", "보안", "mfa", "로그"]:
            if token in q and token in txt:
                score += 1
        if score == 0:
            # 토큰이 하나도 안 맞으면 약한 기본점수
            score = 0.1
        scored.append((score, row))
    top = [r for _, r in sorted(scored, key=lambda x: x[0], reverse=True)[:3]]
    return json.dumps(top, ensure_ascii=False)
 
 
def load_questions() -> List[Dict[str, Any]]:
    items = []
    for line in Q_PATH.read_text(encoding="utf-8").splitlines():
        if line.strip():
            items.append(json.loads(line))
    return items
 
 
def build_agent() -> CodeAgent:
    model = LiteLLMModel(model_id=os.getenv("MODEL_ID", "openai/gpt-4o-mini"))
    system_prompt = """
너는 정책 FAQ 답변 에이전트다.
반드시 search_policy 도구를 먼저 호출해 근거를 찾는다.
출력은 JSON 배열만 반환한다.
각 원소 키:
- qid
- answer (한글 1~2문장)
- evidence (policy_id 1개)
금지:
- KB에 없는 정책을 사실처럼 단정
- evidence 누락
""".strip()
    return CodeAgent(model=model, tools=[search_policy], system_prompt=system_prompt)
 
 
def main() -> None:
    questions = load_questions()
    agent = build_agent()
 
    prompt = f"""
아래 질문 목록에 답변해.
질문 목록:
{json.dumps(questions, ensure_ascii=False)}
 
반드시 JSON 배열만 출력해.
""".strip()
 
    result = agent.run(prompt)
 
    if isinstance(result, str):
        s = result.find("[")
        e = result.rfind("]")
        if s != -1 and e != -1 and e > s:
            result = json.loads(result[s:e+1])
        else:
            raise ValueError("JSON 배열 파싱 실패")
 
    OUT_PATH.write_text(json.dumps(result, ensure_ascii=False, indent=2), encoding="utf-8")
    print(f"saved: {OUT_PATH}")
    print(f"count: {len(result)}")
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lab19_policy_faq_agent.py 생성
  • search_policy 도구 정의 확인

5) 실행 및 출력 확인

• 도구: Python, 터미널
• 입력: policy_kb.json, questions.jsonl
• 실행명령:

python lab19_policy_faq_agent.py
cat answers.json

• 성공판정:
  • saved: answers.json
  • count: 8
  • 각 항목에 qid/answer/evidence 키 존재

6) 자동 검증 스크립트(성공 판정)

• 도구: Python
• 입력: answers.json, questions.jsonl
• 실행명령:

cat > validator.py <<'PY'
import json
from pathlib import Path
 
answers = json.loads(Path("answers.json").read_text(encoding="utf-8"))
expected = [json.loads(x) for x in Path("questions.jsonl").read_text(encoding="utf-8").splitlines() if x.strip()]
emap = {x["qid"]: x["expected_policy"] for x in expected}
 
assert isinstance(answers, list), "answers must be list"
assert len(answers) == len(expected), "질문/응답 건수 불일치"
 
for row in answers:
    assert {"qid", "answer", "evidence"}.issubset(row.keys()), f"키 누락: {row}"
    assert row["qid"] in emap, f"알 수 없는 qid: {row['qid']}"
    assert isinstance(row["answer"], str) and len(row["answer"].strip()) > 0, f"빈 answer: {row}"
    assert isinstance(row["evidence"], str) and row["evidence"].startswith("P-"), f"evidence 형식 오류: {row}"
 
# 단순 정답률
ok = sum(1 for row in answers if row["evidence"] == emap[row["qid"]])
acc = ok / len(expected)
print(f"accuracy={acc:.2f} ({ok}/{len(expected)})")
 
assert acc >= 0.75, "정답률 0.75 미만"
print("PASS: 형식/근거/정답률 검증 완료")
PY
 
python validator.py

• 성공판정:
  • accuracy=... 출력
  • PASS: 형식/근거/정답률 검증 완료 출력

---

트러블슈팅 (최소 3개)

1. AuthenticationError / 401 Unauthorized

• 원인: API 키 누락/만료
• 해결:

echo ${OPENAI_API_KEY:+SET}
export OPENAI_API_KEY="정상키"

2. ValueError: JSON 배열 파싱 실패

• 원인: 모델이 설명문 + JSON을 혼합 출력
• 해결:
  • 시스템 프롬프트에 JSON 배열만 출력 반복 명시
  • 결과에서 [~] 구간 추출 보정 유지(현재 코드 반영)

3. evidence가 P- 형식이 아님

• 원인: 모델이 정책 ID 대신 자연어를 반환
• 해결:
  • 프롬프트에 evidence는 policy_id 1개 강제
  • validator.py에서 형식 검증으로 즉시 실패 처리

4. 정답률이 0.75 미만으로 FAIL

• 원인: search_policy 토큰 매칭 단순화로 회수율 저하
• 해결:
  • 동의어 토큰 추가(예: 업그레이드/상향, 다운그레이드/하향)
  • top-k를 3→4로 조정 후 재평가

5. ModuleNotFoundError: smolagents

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

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

---

운영 확장 포인트 (다음 편 연결)

• 정책 KB를 Markdown 폴더에서 자동 수집해 policy_kb.json로 빌드
• accuracy 추이를 주간 리포트로 저장(품질 회귀 감시)
• 실패 케이스를 별도 큐로 보내 사람 검토(HITL) 적용

체크리스트

• 환경/패키지 설치 완료
• API 키/모델 설정 완료
• KB/질문셋 파일 생성 완료
• answers.json 생성 확인
• validator.py PASS 확인
• 트러블슈팅 3개 이상 점검 완료

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI로 초안을 작성한 뒤, 사람 검토를 통해 실습 재현성(명령/입력/성공판정), 링크 유효성, 포맷 일관성을 점검해 확정했다.