시작하기 — Playground·API·스키마 설계·프로덕션 체크리스트

콘솔과 문서부터 확인합니다

6장에서 결정모델을 LLM 파이프라인 앞단에 끼워 비용·지연을 줄이는 아키텍처를 봤습니다. 이제 실제로 손을 대는 단계입니다. 제일 먼저 할 일은 공식 진입점을 정확히 찾는 것입니다.

공식 API 콘솔은 console.typesafe.ai, 문서는 docs.typesafe.ai 하나뿐입니다. 콘솔에서 키를 발급하고, 대화형으로 스키마를 실험해 보는 플레이그라운드도 콘솔 안(console.typesafe.ai/playground)에 있습니다.

API 키 발급

키는 console.typesafe.ai/keys에서 발급합니다. 발급한 키는 코드에 직접 박지 말고 TYPESAFE_API_KEY 환경변수로 넘기는 것이 SDK 기본 동작입니다.

무료 티어의 정확한 토큰 한도나 체험 기간은 공식 문서(quickstart)에 숫자가 명시돼 있지 않아, 여기서는 단정하지 않겠습니다. 콘솔 가입 화면에서 현재 조건을 직접 확인하시는 편이 정확합니다.

비공식 "플레이그라운드"를 조심하세요

1장에서 잠깐 언급했듯이, jev.works처럼 "공식 플레이그라운드"를 자처하는 도메인이 여럿 돌아다닙니다. 이들은 TypeSafe 소유가 아닙니다.

공식 진입점은 console.typesafe.ai · 공식 문서는 docs.typesafe.ai 뿐입니다. (typesafe.ai)

thejevai.com, jevai.org, jev-ai.net, jevplayground.com 같은 도메인에 API 키를 입력하는 일은 없어야 합니다. 결정모델을 도구로 비교해 보실 때도 카탈로그의 Jev (TypeSafe AI) 페이지에서 공식 링크를 확인하고 넘어가는 편이 안전합니다.

첫 요청 — SDK와 HTTP

가장 빠른 출발은 Python SDK로 질문 하나짜리 요청을 보내 보는 것입니다. 3장에서 다룬 질문 스키마(Choice·Score·Noul)를 그대로 코드에 옮기면 됩니다.

Python SDK 최소 예시

pip install typesafe-sdk 후, 아래는 문서(quickstart)를 참고한 예시입니다. 개념을 보여주는 수준이며 실제 필드명은 문서에서 최종 확인하세요.

# illustrative — docs.typesafe.ai/introduction/quickstart 참고
from typesafe_sdk import Noul, TypeSafeClient

client = TypeSafeClient()  # TYPESAFE_API_KEY 환경변수 사용
response = client.system_one(
    state="Stripe 연동을 3일째 시도 중인데 계속 실패합니다.",
    questions={"is_urgent": Noul(instructions="이 메시지가 긴급함을 나타내는가")},
)
print(response.answers["is_urgent"].noul)  # 0~1 확률

기본 모델은 jev-latest이고, 비동기 처리는 AsyncTypeSafeClient를 async with로 씁니다. Choice·Noul·Score를 한 questions에 섞어 한 번에 보내는 것도 같은 방식입니다.

Raw HTTP로 같은 요청

SDK 없이 붙일 때는 HTTP로 직접 호출합니다. 엔드포인트는 POST https://api.typesafe.ai/v1/systemone, 헤더에 Authorization: Bearer <API_KEY>를 담고 바디는 state+questions 형태입니다(아래는 문서 형태를 참고한 예시).

{
  "state": "Help! My payouts have been failing for 3 days.",
  "model": "jev-latest",
  "questions": {
    "is_urgent": { "type": "noul", "instructions": "Does this convey urgency?" }
  }
}

응답 필드 읽기

돌아오는 값에는 응답을 만든 실제 모델 버전(model), 각 질문의 답(answers), 토큰 사용량(usage)이 들어옵니다. 답의 모양은 질문 타입마다 다릅니다.

• Choice 선택값 choice, 옵션별 확률 probabilities(합 1.0), 보정된 신뢰도 confidence
• Score 가중평균 점수 score, 인덱스→설명 매핑 legend, probabilities, confidence
• Noul 0~1 확률값 noul 하나. Choice·Score와 달리 별도 confidence 필드가 없고, 확률 자체가 답입니다.

2장에서 정리한 신뢰도 임계값 자동화가 바로 이 필드들 위에서 돌아갑니다. confidence가 높으면 자동 실행, 애매하면 사람이나 LLM으로 넘기는 분기를 코드가 소유합니다.

다른 진입로 — Cloudflare와 LangChain

이미 쓰던 인프라에 Jev를 붙이는 경로도 열려 있습니다. 진입로가 달라도 질문 스키마는 동일해서, 스키마 코드를 그대로 재사용합니다.

Cloudflare Workers AI

Cloudflare Workers AI에 typesafe/jev 이름으로 공식 등재돼 있습니다. Worker 바인딩에서는 await env.AI.run('typesafe/jev', { state, questions }) 형태로 호출하고, 응답은 result에 답이 래핑돼 돌아옵니다.

REST 호출의 정확한 경로 형식(모델을 URL 경로에 넣는지 바디에 넣는지)은 fetch에 따라 표기가 갈려 여기서는 단정하지 않겠습니다. 다만 Cloudflare 문서 기준 컨텍스트 윈도는 32,000 토큰, 모델 버전은 jev-1.13.0으로 명시돼 있습니다.

LangChain TypeSafeClassifier.invoke()

LangChain 통합은 langchain-typesafe 패키지의 TypeSafeClassifier가 담당합니다. LangChain 생태계의 다른 컴포넌트와 같은 .invoke() 인터페이스라 붙이기가 매끄럽습니다. 다만 이 통합은 공식적으로 알파 단계로 안내되고 있으니, 프로덕션 투입 전 버전 안정성을 확인하세요.

# illustrative — docs.langchain.com 참고
from langchain_typesafe import TypeSafeClassifier, Noul

classifier = TypeSafeClassifier()  # TYPESAFE_API_KEY 사용
result = classifier.invoke({
    "state": "...",
    "questions": {"is_urgent": Noul(instructions="...")},
})

응답에서는 nouls[id].noul, choices[id].choice/.confidence, scores[id].score/.legend를 읽고, 최상위 request_id로 LangSmith 트레이스를 추적합니다. 4장에서 본 ModelRouterMiddleware·AutoModeMiddleware도 이 패키지 위에서 동작합니다.

프로덕션 체크리스트

콘솔에서 첫 응답을 받는 것과 트래픽을 받는 서비스에 올리는 것은 다른 문제입니다. 올리기 전에 아래 항목을 점검하세요.

운영 전 점검표

버전 고정과 신뢰도 임계값이 핵심입니다

체크리스트에서 실전 사고가 가장 자주 나는 두 지점은 버전과 임계값입니다. jev-latest는 편하지만 조용히 새 버전으로 바뀌고, 그 순간 튜닝해 둔 신뢰도 임계값이 어긋날 수 있습니다.

레이트리밋 250,000 tokens/sec · 1,200 req/min · 초과 시 429. 컨텍스트는 요청당 최대 64k 토큰(state+질문 32k). 모델 버전 jev-1.13.0. (docs.typesafe.ai)

TypeSafe가 말하는 '보정된 신뢰도'는 예측 그룹 단위로 확률이 실제 빈도와 맞도록 최적화됐다는 의미이지, 개별 답 하나하나가 늘 옳다는 보장은 아닙니다. 임계값은 도메인마다 직접 재야 하고, 제3자 독립 검증 수치는 아직 공개 자료로 확인되지 않았습니다. 자체 평가셋으로 검증한 뒤 올리는 것이 안전합니다.

시리즈 전체 정리

일곱 장을 지나오며 결정모델이 무엇이고, 언제 쓰며, 분류·라우팅·스코어링·안전 점검에 어떻게 붙이고, 비용·지연을 어떻게 설계하는지까지 훑었습니다. 전체 흐름을 한 번에 되짚어 봅니다.

1~7장 한눈에

다음 행동 제안

읽기만 하고 덮으면 남는 게 적습니다. 지금 서비스에서 LLM으로 처리하던 작은 판단 하나를 골라 결정모델로 옮겨 보시길 권합니다. 부담 없이 시작하는 순서는 이렇습니다.

• 후보 하나 고르기 문의 분류, 우선순위 스코어링, 탈옥 탐지처럼 답이 라벨·점수·참거짓으로 떨어지는 작업 중 대량·반복인 것 하나
• 스키마로 옮기기 3장 방식으로 Choice/Score/Noul 질문을 정의하고 콘솔 플레이그라운드에서 실제 입력으로 확인
• 임계값 붙여 병행 운영 기존 LLM 경로와 나란히 돌리며 신뢰도 임계값을 조정, 결과가 맞으면 트래픽을 점진 이전

라우팅·자동화를 실제 조합으로 엮는 구체적 사례는 moket.kr의 /tools/recipes에서, 이 주제 외 다른 연재는 /series에서 이어 보실 수 있습니다.

Jev는 LLM을 대체하는 물건이 아니라, LLM이 과하게 쓰이던 '판단' 자리를 더 빠르고 싸게 메우는 조각입니다. 이 시리즈가 그 조각을 여러분의 파이프라인 어디에 끼울지 판단하는 지도가 됐기를 바랍니다.