Module 5 · Project — Custom Training (fine-tuning)

5B.1 · What it builds

고객지원 티켓 하나를 담당 6개 팀 중 하나로 라우팅 — 같은 48개짜리 gold 테스트셋으로 채점해 방법끼리 숫자를 직접 비교합니다.

모델(또는 분류기)은 모든 티켓에 대해 팀 하나를 반드시 골라야 합니다 — 하지만 맞는다는 보장은 없어요. 그래서 같은 척도로 방법을 비교하는 게 핵심입니다.

5B.2 · 왜 어려운가 — 숨은 하우스룰

난이도는 팀 설명(taxonomy)에 일부러 안 적어 둔 조직 고유 규칙에서 나옵니다. 정의만 보고 추론하면 틀려요 — 이건 정의가 아니라 예시로 가르치는 지식입니다.

5B.3 · 신경망이 분류하는 법 (primer)

고전 예제 — 손글씨 숫자 인식 — 은 우리 티켓 라우터와 똑같은 모양이에요: 원시 입력 → 학습된 특징 → 클래스별 점수 하나씩.

5B.4 · 파일 지도 & 역할 — 무엇이 어디에 사는가

스타터 finetune.zip은 딱 두 덩어리예요: 데이터(taxonomy·gold·few-shot·train)와 코드(공용 common.py + 스테이지 셋 + 채점기). 세 스테이지가 같은 데이터·같은 채점기를 공유하는 게 핵심입니다.

5B.5 · 세 가지 방법 — 프롬프트에서 학습된 모델까지

같은 태스크를 푸는 세 가지 방법. 방법(method)만 바뀌고, 테스트셋과 지표는 고정입니다.

여기서 custom training이 말이 되는 이유

세 방법은 정확도 경쟁이 아니라 트레이드오프 공간이에요

custom-trained가 프롬프트 방법을 항상 이기는 건 아니에요(학습 데이터만큼만 잘함) — 볼 건 "누가 이기냐"가 아니라 어디서 이기고 지는가입니다. 축이 다르니까요:

5B.6 · 흐름 — stage 2 파이프라인을 함수 이름으로 ★

custom-trained 방법은 코드로 보면 다섯 함수의 직선이에요: 읽고 → 임베딩하고 → 학습하고 → 예측하고 → 채점. 그리고 점선 하나 — 사람이 다시 넘긴 티켓이 학습셋으로 되먹임되는 피드백 루프가 이 방법을 시간이 갈수록 좋아지게 만듭니다.

가운데 직선(load → embed → fit → predict → eval)은 한 번 도는 학습 파이프라인이에요. 진짜 가치는 점선 피드백에 있어요: 잘못 라우팅된 티켓을 사람이 올바른 팀으로 다시 넘기면, 그게 곧 새 라벨이 돼서 학습셋으로 흘러 들어갑니다 — 라벨을 사실상 공짜로 축적하는 되먹임 루프예요.

5B.7 · 내부 동작 — frozen embedder + trained head

두 단계뿐이에요: 라벨된 데이터를 얻고, 작은 모델을 학습. 학습이 건드리는 건 위에 얹은 작은 head 하나입니다.

# ① 라벨된 데이터 — (ticket → team) 쌍
# production: 해결된 티켓 로그에서 캡처. this project: 완제 세트가 동봉.
rows = load("data/synthetic_train.jsonl")   # ~240 rows

# ② 학습 — embed → logistic regression
X = embed(texts)                # MiniLM, 384-dim, local
clf = LogisticRegression().fit(X, y)
# inference: embed + multiply, API 호출 없음

다이어그램에서 EMBED는 채도가 빠진 채 가만히 있고 HEAD만 숨쉬듯 미세하게 움직여요 — 이게 frozen vs trained의 시각적 대비예요. 학습이 건드리는 건 작은 head뿐이라 gradient가 위의 분류기만 갱신합니다 — 빠르고, 싸고, 과적합도 잘 안 나요.

"임베딩"이 실제로 하는 일 — 텍스트가 숫자 벡터로

embed()는 티켓 문장을 384개의 숫자(벡터)로 바꿔요. 비슷한 뜻의 티켓은 비슷한 벡터가 되고, head는 그 숫자들 위에서 팀 경계를 긋습니다. 아래는 진짜 학습 티켓 하나가 벡터로 접히는 걸 축약한 모습이에요(8칸으로 줄임):

5B.8 · 코드로 보기 — 강제 tool + embed→fit

두 조각이면 프로젝트의 두 세계가 다 보여요: ① prompt 스테이지가 Claude를 강제 tool로 부르는 common.py, ② custom 스테이지가 embed→fit→predict하는 stage2_finetune.py. 각 코드 조각 위의 미니 다이어그램이 흐름 지도예요.

① 강제 tool 사용 — 왜 라벨이 항상 유효한가 · common.py

def route_tool(names: list[str]) -> dict:
    """A forced tool whose only field is the team, constrained to a known enum."""
    return {
        "name": "route_ticket",
        "description": "Assign the support ticket to exactly one team.",
        "input_schema": {
            "type": "object",
            "properties": {"team": {"type": "string", "enum": names}},
            "required": ["team"],
        },
    }

def classify(text: str, system: str, names: list[str]) -> str:
    resp = get_client().messages.create(
        model=MODEL,
        max_tokens=256,
        system=system,
        messages=[{"role": "user", "content": text}],
        tools=[route_tool(names)],
        tool_choice={"type": "tool", "name": "route_ticket"},
    )
    block = next(b for b in resp.content if b.type == "tool_use")
    return block.input["team"]

강제 tool은 형식 문제가 아니라 보장이에요. tool_choice가 없으면 모델은 "이건 Billing 같네요…"처럼 서술할 수도, 오탈자를 낼 수도 있어요. enum + 강제 호출 덕분에 stage 0·1의 차이는 오직 정확도일 뿐, 절대 깨진 출력이 아닙니다 — 그래서 세 방법을 같은 척도로 공정하게 비교할 수 있어요.

② embed → fit → predict — 학습과 추론 · stage2_finetune.py

def train():
    train_path = common.DATA / "synthetic_train.jsonl"
    # … (raise if the training file is missing)
    rows = common.load_jsonl(train_path)
    X = common.embed([r["text"] for r in rows])
    y = [r["team"] for r in rows]
    clf = LogisticRegression(max_iter=2000, C=10.0)
    clf.fit(X, y)
    joblib.dump(clf, MODEL_PATH)
    return clf

def predict(tickets):
    clf = load_classifier()
    X = common.embed([t["text"] for t in tickets])
    preds = clf.predict(X)
    return [
        {"id": t["id"], "gold": t["team"], "pred": str(p), "text": t["text"]}
        for t, p in zip(tickets, preds)
    ]

train()과 predict()가 똑같은 common.embed()를 쓰는 데 주목하세요 — 학습 때 문장을 벡터로 만든 그 함수로 추론 때도 똑같이 벡터를 만들어요. 그래서 stage 2의 추론엔 Claude 호출이 한 번도 없습니다: 임베딩 한 번 + 행렬곱 한 번이면 팀이 나와요.

5B.9 · Build & run locally

스테이지를 순서대로 돌리면 세 방법의 F1과 confusion matrix가 나란히 나옵니다.

# 스타터: finetune.zip (taxonomy + gold set + few-shot + 학습셋 + 스테이지)
#   https://ksetp.netlify.app/assets/special-topics/finetune.zip
unzip finetune.zip && cd finetune
python3.11 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python stage0_zeroshot.py    # 베이스라인
python stage1_fewshot.py     # + 예시
python stage2_finetune.py    # 학습 + 채점
python evaluate.py           # 세 방법 나란히 (F1 + confusion matrix)

ANTHROPIC_API_KEY는 공유 .env를 그대로 씁니다(stage2 추론엔 필요 없지만 stage0/1엔 필요).

스코어보드 읽는 법 — evaluate.py가 찍는 것

각 스테이지는 자기 리포트를 찍고, evaluate.py는 캐시된 예측을 읽어(추가 Claude 호출 없음) 세 방법을 progression 표 하나로 모아요:

================  PROGRESSION  ================
stage                              accuracy  macro-F1
Stage 0 — zero-shot prompting          ...      ...
Stage 1 — few-shot prompting           ...      ...
Stage 2 — distilled classifier         ...      ...

• accuracy — 48개 gold 중 몇 개를 맞췄나. 한눈에 보는 총점.
• macro-F1 — 팀마다 F1을 구해 평균. 티켓이 많은 팀에 점수가 쏠리지 않게 해서, 소수 팀을 놓치는 방법을 드러내요.
• confusion matrix — 행=정답 팀, 열=예측 팀. 대각선 밖의 숫자가 곧 하우스룰 혼동(예: Sales로 샌 Billing)이라, 어디서 왜 틀리는지를 콕 집어줍니다.

5B.10 · The key idea — 큰 모델로 데이터를, 작은 모델로 배포를

"라벨만 필요하고 실패가 싼" 태스크라면, 프롬프팅을 넘어 작은 로컬 분류기가 더 싸고 빠를 수 있어요 — 값은 얼어붙은 embedder 위 작은 head 하나에 담깁니다.