TL;DR

  • typia가 TypeScript 타입과 주석을 바탕으로 Jev 질문 스키마와 답변 디코더를 컴파일 시점에 생성하며, 디코딩 결과는 선언된 타입으로 복원됨.
  • 프로퍼티 주석은 질문 지침을, 열거형 멤버 주석은 선택지 설명을 제공하고 @probability로 확률을 지정함.
  • @typesafe-ai/sdk로 Jev를 직접 호출하거나 @ai-sdk/typesafe-ai와 Vercel AI SDK의 experimental_decide()로 호출할 수 있음.
  • 같은 TypeScript 타입으로 OpenAI Structured Outputs용 JSON Schema를 생성하고 공식 openai SDK에서 사용할 수 있지만, 이 경로는 Jev 답변 맵을 반환하거나 평가 전용 확률 주석을 적용하지 않음.
  • ttsc 또는 ttsx로 typia의 컴파일 시점 변환을 적용하며, 예제 실행에는 해당 SDK 패키지와 API 키 설정이 필요함.

질문 정의

  • typia의 llm.evaluation<ITicketTriage>()가 컴파일 시점에 질문 맵과 답변 디코더를 생성함. 불리언 속성은 예/아니요 질문이 되고, Department 열거형은 선택 질문이 됨.
  • 속성 주석은 질문의 지침을 제공하고, 열거형 멤버 주석은 각 선택지의 설명을 제공함. 예제의 Department 선택지는 결제·청구(billing, 확률 0.3), 기술 문제(technical, 확률 0.5), 영업(sales, 확률 0.2)임.
  • 티켓 분류 타입에는 긴급성 여부, 담당 부서, 환불 요청 여부가 포함됨. 환불 속성은 boolean & tags.Probability<0.8>로 선언됨.
  • 예제 티켓은 “오늘 아침 두 번 청구됐으며, 지금 환불하지 않으면 떠나겠다”는 내용임.
  • 아래 방식들은 같은 티켓을 사용해 질문에 답하며, triage.decode()가 답변을 검사해 result.data에 ITicketTriage 객체를 반환하거나 result.errors에 검증 오류를 반환함.

Jev 직접 호출

  • @typesafe-ai/sdk의 TypeSafeClient로 Jev 모델 jev-1.13.0을 호출하고, @typia/jev의 toJevQuestions()로 triage.questions를 Jev 질문 형식으로 변환함.
  • toJevQuestions()는 예/아니요 질문의 형식 "boolean"을 Jev의 기본 형식인 "noul"로 변환하며, 선택 질문과 점수 질문은 그대로 전달함.
  • 반환된 answers를 triage.decode()에 전달하면 ITicketTriage에 선언된 필드를 복원할 수 있음. Jev의 확률도 필요하면 원래 답변 맵을 보존해야 함.
  • 직접 SDK를 사용하는 클라이언트는 TYPESAFE_API_KEY를 읽음.

Vercel AI SDK

  • @ai-sdk/typesafe-ai의 TypeSafe 제공자와 AI SDK의 experimental_decide()를 사용해 Jev를 호출함.
  • triage.questions를 그대로 전달하면 제공자가 Jev의 기본 형식으로 변환하며, response.answers는 동일한 triage.decode() 함수로 디코딩함.
  • 이 제공자에는 직접 SDK의 TYPESAFE_API_KEY가 아닌 TYPESAFE_AI_API_KEY를 설정해야 함. 예제는 AI SDK 7의 의사결정 API를 사용함.

OpenAI

  • 공식 openai SDK는 Structured Outputs용 JSON Schema를 받으며, typia.llm.structuredOutput<ITicketTriage, { strict: true }>()가 같은 타입과 주석에서 스키마를 생성함.
  • 생성한 스키마를 text.format에 전달하고, gpt-5.6-luna 모델에 시스템 지침과 사용자 티켓을 입력함. 클라이언트는 OPENAI_API_KEY를 읽음.
  • OpenAI는 분류 객체를 JSON 텍스트로 반환함. 응답 상태가 completed가 아니거나 출력 텍스트가 없으면 오류를 발생시키며, 파싱한 객체는 output.validate()로 검사함.
  • 이 경로는 Jev의 답변 맵을 반환하지 않으며 평가 전용 확률 주석도 적용하지 않음.

설치 및 실행

  • 빌드 도구와 타입스크립트는 npm install -D ttsc typescript로 설치하고, typia와 @typia/jev는 npm install typia @typia/jev로 설치함.
  • npx ttsc로 빌드하거나 npx ttsx src/index.ts로 실행하며, ttsc 또는 ttsx를 통해 typia의 컴파일 시점 변환을 적용함.
  • 사용할 예제의 SDK 패키지를 설치하고, 공유 선언과 SDK 예제 하나를 src/index.ts에 저장한 뒤 해당 API 키를 설정함.
  • 가이드: typia.llm.evaluation, @typia/jev; 저장소: GitHub.