happy_various AI 실전 기록

2026년 9월 22일 기준

이 글에는 제휴 링크가 없습니다. TypeSafe AI와 아무 관계가 없고, 예제와 수치는 2026년 9월 22일 공식 문서 기준입니다. 삽화는 GPT 이미지 생성, 도식은 직접 제작했습니다.

Jev 사용법 — 상태와 질문표를 보내면 확신도가 돌아온다, 확신도로 세 갈래 나누기

콜센터 접수 창구를 떠올려 보세요. 접수원은 문의를 읽고 도장 세 개를 찍습니다. 어느 팀, 얼마나 화남, 급한가. 그리고 자신 없는 건 팀장에게 넘깁니다. 이 접수원이 하루 10만 건을 0.5초씩에 처리하고, “자신 없다”를 숫자로 말해준다면 어떨까요.

1편에서 Jev가 ‘고르기만 하는 AI’라는 걸 봤습니다. 이 글은 그 접수원을 실제로 어떻게 부르고, 돌아온 숫자로 무엇을 하는지를 공식 문서의 예제 그대로 따라갑니다. 코드는 최소한만 보여드리고, 각 줄이 사람 말로 무엇인지 옆에 적을게요.

편지를 세 바구니(자동·확인·사람)로 나누는 접수 로봇 (GPT 이미지 생성)

결론 요약

📮 1. 한 번 불러 보기 — 공식 빠른 시작 예제

공식 문서의 빠른 시작은 고객 문의 한 통으로 시작합니다. 파이썬 SDK를 설치하고(pip install typesafe-sdk), API 키를 환경변수 TYPESAFE_API_KEY에 두고, 이렇게 부릅니다.

from typesafe_sdk import Choice, Noul, Score, TypeSafeClient

client = TypeSafeClient()
ticket = "3일째 Stripe 연동이 계속 실패해요. 매출이 빠지고 있어요. 빨리 도와주세요."  # 상태(state)

response = client.system_one(
    state=ticket,
    questions={
        "department": Choice(                       # 하나 고르기
            instructions="어느 팀이 맡아야 하나",
            criteria={"billing": "결제·구독 문제", "technical": "버그·연동 문제", "sales": "가격·계정 문의"},
        ),
        "frustration": Score(                       # 단계 매기기 (낮은 단계 → 높은 단계 순서)
            instructions="고객이 얼마나 화나 보이나",
            criteria=["차분히 사실만 말함", "화났지만 정중함", "매우 화남, 거친 표현"],
        ),
        "is_urgent": Noul(                          # 예/아니오
            instructions="급하다거나 시간이 촉박하다고 말하고 있나",
        ),
    },
)

(원문 예제는 영어 문의이고, 여기서는 뜻만 한국어로 옮겼습니다. 문서가 밝히듯 영어가 기본 언어이고 다른 언어는 정확도가 같지 않습니다.)

돌아오는 것은 질문 이름별 답입니다. 문서의 예시 값 그대로입니다.

response.answers["department"].choice        # "technical"  ← 고른 팀
response.answers["department"].confidence    # 0.78         ← 얼마나 확신하나
response.answers["department"].probabilities # {"technical": …, "billing": …, "sales": …}  보기별 확률, 합은 1
response.answers["frustration"].score        # 1.0          ← 0(차분)~2(격분) 중 1 = "화났지만 정중함"
response.answers["is_urgent"].noul           # 1.0          ← 급하다 100%

질문 셋을 한 번에 보냈고 답 셋이 한 번에 왔습니다. 문서 표현으로 “질문들은 독립적으로, 병렬로 평가”됩니다. 질문을 하나씩 세 번 보낼 이유가 없어요.

🔧 2. SDK 없이 보면 — 요청과 응답의 실제 모양

프로그램이 실제로 주고받는 것은 JSON 한 덩어리입니다. 공식 API 문서의 예시입니다.

// 요청  POST https://api.typesafe.ai/v1/systemone   (헤더 Authorization: Bearer <API 키>)
{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": { "type": "noul", "instructions": "Does this convey urgency?",
                   "criteria": { "true": "Explicitly time-sensitive", "false": "No urgency expressed" } }
  }
}
// 응답
{ "model": "jev-1.13.0",
  "answers": { "is_urgent": { "type": "noul", "noul": 0.95 } },
  "usage": { "input_tokens": 296, "output_tokens": 20 } }

세 가지가 눈에 들어옵니다. 첫째, model은 별명 jev-latest로 보내고 실제 버전 jev-1.13.0이 돌아옵니다. 둘째, 응답에 글이 한 줄도 없습니다. 숫자와 이름뿐이에요. 셋째, usage에 출력 토큰이 20으로 찍히지만 모델 문서상 출력 요금은 없습니다. 입력 100만 토큰당 $0.042만 냅니다.

🎚️ 3. 확신도 — 확률의 모양을 숫자 하나로

Choice와 Score에는 확률 목록 외에 확신도(confidence)가 따로 옵니다. 문서의 정의는 “확률 분포에서 계산한 통계”로, 확률이 한쪽에 얼마나 몰렸는가를 0~1로 접은 것입니다. 보기가 셋일 때 계산식은 (3 × 가장 큰 확률 − 1) ÷ 2예요.

Score의 확신도도 같은 뜻입니다. 문서 예시에서 “심각도” 세 단계의 확률이 0 · 0.57 · 0.43으로 갈리면 점수는 가중 평균 1.43, 확신도는 0.35로 낮게 나옵니다. 점수가 애매하면 확신도가 낮다 — 이 두 숫자를 같이 봐야 합니다.

감정 구름의 높이를 세 구간 자로 재는 로봇 (GPT 이미지 생성)

🚦 4. 세 갈래 — 자동으로, 확인받고, 사람에게

확신도가 있으니 코드가 갈림길을 만들 수 있습니다. 공식 문서 “확신도” 페이지가 권하는 세 구간입니다.

확신도문서의 지침접수 창구로 치면
0.9 초과사람 없이 자동으로 실행도장 찍고 바로 전달
0.5 ~ 0.9“조심해서 진행” — 확인 요청, 검토 표시, 정보 더 모으기“기술팀 맞나요?” 한 번 묻기
0.5 미만실행하지 않는다 — 사람에게, 다시 묻기, 다른 시스템으로팀장에게

문턱값은 일의 무게에 따라 다르게 두라는 게 문서의 핵심 조언입니다. “확신도 기반 라우팅” 패턴 페이지의 예제는 은행 앱인데, 잔액 조회는 0.6만 넘어도 실행하고(틀려봐야 잔액을 한 번 더 듣는 정도), 송금 승인은 0.85를 넘어야 자동 실행하고 그 아래면 “확인하시겠어요?”를 띄웁니다. 문서의 코드 골격은 이렇습니다.

action = response.answers["intent"]
if action.confidence < 0.6:                 # 갈리면 사람에게
    route_to_support_agent(account_id)
elif action.choice == "check_balance":      # 가벼운 일은 그냥
    show_balance(account_id)
elif action.choice == "approve_transfer":   # 무거운 일은 문턱 높게
    if action.confidence > 0.85: approve_transfer(account_id)
    else: ask_user_to_confirm("확인해 주세요…")

문서는 이렇게 못 박습니다. “올바른 문턱값은 당신의 도메인과, 당신 용도에서의 모델 성능에 달려 있다.” 0.9와 0.5는 출발점이지 정답이 아니에요.

상태와 질문표 → Jev → 답·확률·확신도 → 코드가 세 갈래로 (직접 제작)

🧩 5. 잘 쓰는 법 — 문서의 네 가지 패턴

TypeSafe 문서의 “패턴” 절은 넷을 권합니다. 비개발자용으로 한 줄씩 옮깁니다.

넷의 공통 원칙이 문서의 이 문장입니다. “넓은 판단을 좁고 타입이 정해진 질문들로 쪼개고, 지시와 기준을 명시하라.” 그리고 “코드가 결정론적인 일을 처리하고 흐름을 소유한다”— 판단은 Jev가, 결정은 코드가.

📏 6. 한도와 오류 — 알고 시작할 것

모델 문서와 API 문서에 적힌 값입니다(2026-09-22 기준).

항목값
상태 크기요청 전체 64k 토큰, 그중 상태 + 가장 긴 질문이 32k 토큰
입력 형식글자만 — 문자열, JSON 객체, 문자열 배열. 이미지·음성·영상 불가
Choice 보기최대 255개
Score 단계2~10개
속도 한도초당 25만 토큰, 분당 1,200 요청 (수요에 따라 조정 중이라고 명시)
오류401 키 없음/잘못됨 · 422 요청 형식 오류 · 429 속도 초과 · 529 과부하

429와 529는 “바로 재시도하지 말고 지수 백오프로” 재시도하라는 게 문서 지침입니다. 잠깐 쉬고, 다음엔 두 배 쉬고.

⚠️ 7. 흔한 실수 — 문서의 안티패턴 그대로

수학 문제지 앞에서는 어깨를 으쓱하고, 편지 앞에서는 엄지를 드는 로봇 (GPT 이미지 생성)

🎯 시작 코스 — 문의 분류기 하나

  1. 최근 문의 10건을 모읍니다. 그게 상태입니다
  2. 질문 셋을 적습니다 — 어느 팀(Choice, 보기 3~5개, 각 보기에 한 줄 설명), 얼마나 급한가(Score 3단계, 상황으로), 환불 요구인가(Noul)
  3. 공식 빠른 시작대로 SDK를 설치하고 API 키를 받아(문서 기준 발표 당시 얼리액세스 대기열, 이날 모델 문서는 정식 제공 표기) 10건을 돌려 봅니다
  4. 답과 확신도를 표로 놓고 사람이 매긴 것과 비교합니다. 확신도가 낮았던 건이 실제로 애매했는지 봅니다
  5. 그 표를 보고 문턱값 둘을 정합니다. 자동 처리 문턱과 사람에게 넘길 문턱. 그다음 코드에 넣습니다

접수원이 유능한지보다 중요한 건 접수원이 “모르겠다”를 숫자로 말해주느냐입니다. Jev의 확신도가 그 숫자이고, 그 숫자로 갈림길을 만드는 건 여러분의 코드입니다.

이전 편: System One 모델 Jev란 · 다음 편: LLM 게이트웨이에 판정 창구를 더 낸 기록

기준: 2026-09-22. 예제 코드·응답 값·계산식·문턱값·패턴·한도·오류 코드는 TypeSafe AI 공식 문서(docs.typesafe.ai — 빠른 시작, HTTP API 레퍼런스, Choice·Score·Noul, 확신도, 확신도 기반 라우팅 패턴, 패턴 개요, 상태 개념, 모델 페이지)를 이날 직접 확인했습니다. 빠른 시작 예제의 문의 문장과 보기 설명은 뜻만 한국어로 옮겼고, 응답 값(technical·0.78·1.0·1.0)은 문서 그대로입니다. 삽화는 GPT 이미지 생성, 도식은 직접 제작했습니다.