🤗 16. 실습편 04: 지원티켓 트리아지 미니프로젝트 핸즈온 1편

이번 편은 실무형 미니 프로젝트 1편으로, 들어오는 고객 문의를 자동 분류해 billing / bug / feature / other로 라우팅하는 티켓 트리아지 에이전트를 만든다.

• 이전 편: 🤗 15. 본편 08
• 다음 편 예고: 트리아지 결과를 Slack/Notion/n8n으로 전달하는 자동화 확장

한 줄 목표

입력(JSON Lines) → 분류 에이전트 실행 → 결과(JSON) 생성 → 성공 판정까지 한 번에 재현한다.

flowchart LR
  I[tickets.jsonl] --> A[CodeAgent]
  A --> T[분류 규칙 + 샘플 근거]
  T --> O[triage_output.json]
  O --> C[정확도/형식 체크]
  C --> R[수동검토 또는 다음 자동화]

---

0) 실습 범위(고정)

• 범위 포함
  • 단일 파일 입력(tickets.jsonl)을 읽어 문의를 카테고리 분류
  • 각 티켓에 category, priority, reason 필드 생성
  • 결과를 triage_output.json으로 저장
• 범위 제외
  • DB/Slack/Notion 연동
  • 다국어 분류 고도화

---

1) 환경 준비

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

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

• 성공판정:
  • (.venv) 프롬프트 표시
  • pip install 에러 없음

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(bool(os.getenv("OPENAI_API_KEY")))
PY

• 모델 ID 출력됨
• True 출력

3) 실습 입력 데이터 만들기

• 도구: 터미널
• 입력: 샘플 티켓 6개
• 실행명령:

cat > tickets.jsonl <<'JSONL'
{"ticket_id":"T-1001","text":"결제는 됐는데 영수증 메일이 안 왔어요"}
{"ticket_id":"T-1002","text":"앱 업데이트 후 로그인 버튼 누르면 앱이 꺼집니다"}
{"ticket_id":"T-1003","text":"대시보드에 CSV 내보내기 기능 추가 부탁합니다"}
{"ticket_id":"T-1004","text":"요금제 업그레이드했는데 반영이 안 됩니다"}
{"ticket_id":"T-1005","text":"첨부파일 업로드 시 500 에러가 떠요"}
{"ticket_id":"T-1006","text":"서비스 소개 자료를 받아볼 수 있나요?"}
JSONL

• 성공판정:

wc -l tickets.jsonl

• 6 tickets.jsonl 출력

4) 에이전트 코드 작성

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

cat > lab16_ticket_triage.py <<'PY'
from __future__ import annotations
 
import json
import os
from pathlib import Path
from smolagents import CodeAgent, LiteLLMModel
 
INPUT_PATH = Path("tickets.jsonl")
OUTPUT_PATH = Path("triage_output.json")
 
 
def load_tickets(path: Path):
    rows = []
    for line in path.read_text(encoding="utf-8").splitlines():
        if line.strip():
            rows.append(json.loads(line))
    return rows
 
 
def build_agent() -> CodeAgent:
    model_id = os.getenv("MODEL_ID", "openai/gpt-4o-mini")
    model = LiteLLMModel(model_id=model_id)
 
    system_prompt = """
너는 고객지원 티켓 분류 에이전트다.
카테고리는 billing/bug/feature/other 중 하나만 사용한다.
priority는 high/medium/low 중 하나만 사용한다.
반환은 반드시 JSON 배열이며 각 원소는 아래 키를 포함한다.
- ticket_id
- category
- priority
- reason (한글 1문장)
""".strip()
 
    return CodeAgent(model=model, tools=[], system_prompt=system_prompt)
 
 
def main() -> None:
    tickets = load_tickets(INPUT_PATH)
    agent = build_agent()
 
    prompt = f"""
다음 티켓 목록을 규칙에 맞춰 분류해.
티켓 목록:
{json.dumps(tickets, ensure_ascii=False)}
""".strip()
 
    result = agent.run(prompt)
 
    # smolagents 출력이 문자열일 수 있어 보정
    if isinstance(result, str):
        start = result.find("[")
        end = result.rfind("]")
        if start != -1 and end != -1 and end > start:
            result = json.loads(result[start:end+1])
        else:
            raise ValueError("JSON 배열 파싱 실패")
 
    OUTPUT_PATH.write_text(
        json.dumps(result, ensure_ascii=False, indent=2),
        encoding="utf-8",
    )
 
    print(f"saved: {OUTPUT_PATH}")
    print(f"count: {len(result)}")
 
 
if __name__ == "__main__":
    main()
PY

• 성공판정:
  • lab16_ticket_triage.py 파일 생성
  • 코드에 CodeAgent, LiteLLMModel 존재

5) 실행 및 결과 확인

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

python lab16_ticket_triage.py
cat triage_output.json

• 성공판정:
  • saved: triage_output.json 출력
  • 결과 항목 수 6
  • 각 항목에 ticket_id/category/priority/reason 4개 키 존재

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

• 도구: Python
• 입력: triage_output.json
• 실행명령:

python - <<'PY'
import json
from pathlib import Path
 
data = json.loads(Path("triage_output.json").read_text(encoding="utf-8"))
allowed_cat = {"billing", "bug", "feature", "other"}
allowed_pri = {"high", "medium", "low"}
 
assert isinstance(data, list) and len(data) == 6, "건수 불일치"
for row in data:
    assert set(["ticket_id","category","priority","reason"]).issubset(row.keys()), f"키 누락: {row}"
    assert row["category"] in allowed_cat, f"category 오류: {row}"
    assert row["priority"] in allowed_pri, f"priority 오류: {row}"
print("PASS: 형식/값 검증 완료")
PY

• 성공판정:
  • PASS: 형식/값 검증 완료 출력

---

트러블슈팅 (최소 3개)

1. AuthenticationError / 401

• 원인: API 키 미설정 또는 잘못된 키
• 해결:

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

2. ValueError: JSON 배열 파싱 실패

• 원인: 모델이 설명문+JSON 혼합 출력
• 해결:
  • 시스템 프롬프트에 “JSON 배열만 출력” 문구 강화
  • 필요 시 json schema 예시를 프롬프트에 추가

3. 분류 라벨이 규칙 외 값으로 나옴 (예: payment_issue)

• 원인: 허용 라벨 집합 강제 부족
• 해결:
  • 프롬프트에 “허용값 외 금지” 명시
  • 6단계 검증 스크립트로 실패 즉시 탐지

4. 속도가 느리거나 타임아웃 발생

• 원인: 입력 티켓 수 증가/모델 응답 지연
• 해결:
  • 배치 분할(예: 50개 단위)
  • 재시도 로직(백오프) 추가

---

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

• triage_output.json을 n8n Webhook으로 POST
• priority=high만 슬랙 알림 채널로 분기
• 분류 정확도 샘플셋(정답 라벨) 붙여 주간 품질 리포트 자동화

체크리스트

• 가상환경/패키지 설치 완료
• API 키/모델 ID 설정 완료
• tickets.jsonl 6건 생성 확인
• triage_output.json 저장 확인
• 자동 검증 스크립트 PASS
• 트러블슈팅 3개 이상 점검 완료

참고 링크 (우선순위)

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

생성형 AI 활용 고지

이 문서는 생성형 AI를 활용해 초안을 작성하고, 실습 절차/코드/검증 단계를 구조화했다. 최종 반영 전 사람 검토로 명령 재현성, 링크 유효성, 포맷 일관성을 점검했다.