한눈에 요약
- 프리미티브는 Jev에게 던질 수 있는 세 가지 질문 타입으로, 각각 선택지 하나·기준표 위의 점수·참일 확률을 돌려준다.
- 평가할 내용인 state와 판단을 요구하는 질문을 분리해서 보내는 것이 이 API의 기본 구조다.
- 한 요청에 여러 질문을 섞어도 되고 모두 병렬로 평가된다. 대신 질문끼리 서로의 답을 참조할 수는 없다.
- 확률과 **신뢰도(confidence)**는 다른 값이다. 신뢰도는 확률 분포에서 뽑아낸 통계이고, Noul에는 아예 없다.
- 공식 문서가 이 모델이 어디서 틀리는지 아홉 가지로 공개해 뒀으니 쓰기 전에 그 목록부터 보는 편이 빠르다.
state와 질문을 나눈다
먼저 왜 나누는지부터. 같은 재료를 놓고 여러 가지를 물을 일이 대부분이기 때문이다.
state는 모델이 평가할 내용이다. 고객 문의 한 통일 수도 있고, 애플리케이션의 현재 상태일 수도 있다. 문자열·JSON 객체·배열 중 아무 형태나 된다 52.
질문은 그 재료에 대해 내릴 판단을 정의한다. 한 요청은 하나의 state를 여러 질문으로 평가하고, 모든 질문은 같은 state를 본다 52.
| 형태 | 쓰기 좋은 경우 |
|---|---|
| 문자열 | 메시지·글·문단 하나 |
| 객체 | 이름 붙은 필드, 연관 레코드, 애플리케이션 상태 |
| 배열 | 메시지나 레코드의 나열 |
문서는 대부분의 요청에 객체를 권한다. 각 부분에 이름이 붙어 관계가 분명해지기 때문이다. state가 객체일 때는 질문 안에서 백틱으로 ticket.messages[0].text 처럼 경로를 찍어 어느 부분을 판단하라는 건지 지정할 수 있다 52.
세 가지 질문 타입
질문에는 ID, type, instructions가 들어간다. Choice와 Score는 criteria로 선택지나 레벨을 정의하고, Noul은 criteria를 참·거짓의 뜻을 풀어 주는 선택 항목으로 쓴다. 질문 ID는 응답을 찾아오기 위한 내 코드의 열쇠일 뿐 모델에는 전달되지 않는다 52.
| 타입 | 무엇을 묻나 | 입력 | 응답 필드 |
|---|---|---|---|
| Choice | 이 중 어느 것인가 | instructions + 선택지 맵 criteria |
choice, probabilities, confidence |
| Score | 어느 레벨인가 | instructions + 순서 있는 레벨 목록 criteria |
score, legend, probabilities, confidence |
| Noul | 이것이 참인가 | instructions (+ 선택적 criteria) |
noul (0~1) |
읽는 법도 조금씩 다르다 52.
- Choice —
choice는 확률이 가장 높은 선택지다.probabilities는 모든 선택지에 걸친 분포이고 합이 1이다. - Score —
score는 레벨들에 대한 확률가중 값이라 레벨 사이에 떨어질 수 있다.legend는 레벨 번호를 내가 쓴 설명으로 되돌려 준다. - Noul — 참일 확률 하나다. 1에 가까우면 강한 참, 0에 가까우면 강한 거짓, 0.5 근처면 모르겠다는 뜻이다. 별도의 신뢰도 필드가 없다.
Noul의 0.5는 "중간 정도"가 아니다. 참과 거짓에 같은 확률을 줬다는 뜻이다. 정도를 재고 싶으면 Noul이 아니라 레벨을 정의한 Score를 써야 한다 52.
한 요청에 여러 질문을 섞는다
같은 state를 쓰는 질문은 전부 한 요청에 넣는 것이 문서가 권하는 기본값이다. 타입을 섞어도 된다. 모든 질문이 병렬로 평가되므로 질문을 늘려도 응답 시간은 거의 변하지 않고, 추가된 질문 토큰 값만 더 든다 52.
그래서 문서는 아예 쓸지 안 쓸지 모르는 질문까지 미리 물어 두라고 한다. 버그 리포트가 아닌 것으로 밝혀지면 심각도 답을 무시하면 그만이다. 쿡북 하나는 질문 13개를 한 번에 묶었더니 13번 따로 부른 것보다 11.5배 싸고 9.6배 빨랐다고 보고한다 52.
한 가지 제약이 있다. 질문끼리 서로의 답을 참조할 수 없다. 한 질문의 답은 다른 질문의 숨은 맥락이 되지 않는다. 앞선 답이 있어야 다음 질문을 만들 수 있을 때만 요청을 두 번 나누고, 그렇지 않으면 한 번에 묻고 코드에서 골라 쓰면 된다 52 55.
원자적 질문으로 쪼갠다
질문 하나는 "제대로 된 맥락만 주면 아는 사람이 몇 초 안에 내릴 판단" 크기여야 한다. "이 메시지가 급한가"는 좋은 질문이고 "이 메시지를 분석해서 최선의 대응을 정하라"는 나쁜 질문이다 52.
여러 요인이 얽힌 판단이라면 요인별로 따로 묻고 코드에서 합치면 된다. 스타트업 피치를 통째로 평가하게 하는 대신 시장 규모·기술 실현성·차별성을 따로 묻고 내 공식으로 가중치를 주는 식이다. 우선순위가 바뀌면 프롬프트를 다시 쓰는 대신 코드의 계수를 고치면 된다 52.
비공식 매뉴얼은 같은 원칙을 오류 비용으로 설명한다. "급한가, 유효한가, 환불 대상인가"를 한 질문에 묶으면 서로 다른 비용을 가진 세 오류가 한 라벨 뒤에 숨는다는 것이다 (#53 Jev 매뉴얼(비공식)).
신뢰도는 확률과 다르다
**신뢰도(confidence)**는 확률 분포에서 파생된 통계다. 0에서 1 사이의 한 숫자로, 분포가 한 선택지에 몰릴수록 1에 가깝고 고르게 퍼질수록 0에 가깝다 52.
쉽게 말하면 확률은 "무엇을 골랐나"를, 신뢰도는 "그 선택이 얼마나 또렷한가"를 말해 준다. Choice에서 신뢰도가 낮다는 건 어느 선택지도 확실한 승자가 아니라는 뜻이고, Score에서 낮다는 건 레벨이 모호하거나 state에 판단 근거가 부족하다는 뜻이다 52.
신뢰도는 TypeSafe가 정한 기본 계산일 뿐이다. 문서는
probabilities전체를 돌려주는 이유가 바로 다른 척도를 쓸 수 있게 하기 위해서라고 적는다 52.
위험도에 따라 문턱을 다르게 둔다
문서가 권하는 출발 패턴은 신뢰도를 세 구간으로 나누는 것이다 52.
| 구간 | 코드가 할 일 |
|---|---|
| 높음 | 자동 실행. 사람 손 없이 진행한다 |
| 중간 | 조심해서 진행. 사용자 확인, 검토 표시, 근거 추가 수집 |
| 낮음 | 실행하지 않는다. 사람에게 넘기거나 다른 시스템으로 대체한다 |
경계를 어디에 그을지는 걸린 것이 무엇이냐에 달렸다. 문서의 예제는 같은 시스템 안에서도 문턱을 나눈다. 신뢰도 0.5 미만이면 무조건 사람에게 넘기고, 잔액 조회처럼 되돌릴 수 있는 동작은 그 위에서 바로 실행하되, 송금 승인은 0.9를 넘어야 확인 후 실행한다 52.
비공식 매뉴얼은 여기에 한 문장을 덧붙인다. 0.8 같은 숫자는 예시일 뿐이다. 튜토리얼에서 베낀 한 숫자는 안전 보증이 아니다. 라벨링된 자체 데이터로 임계값을 훑어 오작동·놓침·검토 물량을 재 보고 정하라고 한다 (#53 Jev 매뉴얼(비공식)).
jev-1.13이 공개한 9가지 실패 모드
1차 문서가 직접 공표한 목록이다 (2026-09 기준, 문서 최종 검토일 2026-09-17). 빠르고 보정돼 있고 상식적 판단에 강하지만 완벽하지는 않다는 전제로 시작한다 52.
| # | 실패 모드 | 대신 이렇게 |
|---|---|---|
| 1 | 문자 그대로 읽기 | 의도가 아니라 조건을 그대로 쓴다. 경계 사례는 criteria에 넣는다 |
| 2 | 수·계산 | 산술은 코드에 둔다. 세기도 코드로 한다 |
| 3 | 날짜·시각 비교 | 구성 요소만 추출시키고 비교는 코드에서 한다 |
| 4 | 간접 참조 | 참조를 미리 풀어 두고 관련 state를 이름으로 가리킨다 |
| 5 | 쓸데없이 큰 state | 먼저 걸러서 질문에 필요한 것만 보낸다 |
| 6 | 적대적 입력 | state를 신뢰하지 않는다. 배포 전에 경계 사례를 시험한다 |
| 7 | 모순된 지시·기준 | criteria를 지시문의 연장으로 보고 둘을 맞춘다 |
| 8 | 구조적 불변식 | 한 번만 묻고 항등식은 코드에서 강제한다 |
| 9 | 생성 | 생성 모델을 쓴다 |
8번은 특히 걸리기 쉬운 함정이다. 같은 질문을 Noul과 Choice로 각각 물었을 때 두 값이 서로 맞아떨어지리라는 보장이 없다. 어떤 문장과 그 부정을 각각 Noul로 물으면 합이 1을 넘기도 한다 52.
문서가 덧붙이는 정리가 명확하다. 선택지에 대한 Choice는 상대적이어서 어느 쪽이냐를 가리고, 선택지마다 붙인 Noul은 절대적이어서 전부 낮게 나올 수도 있다. 서로 다른 질문이니 한쪽에서 맞춘 임계값을 다른 쪽으로 옮겨 쓰지 말라는 것이다 52.
API 표면
엔드포인트는 POST /v1/systemone 하나다. 요청에는 state, 어느 모델이 처리할지 고르는 model, 그리고 내가 이름 붙인 질문들의 맵 questions가 들어간다 52.
응답에는 실제로 처리한 버전을 알려 주는 model, 질문과 같은 ID로 키가 잡힌 answers, 그리고 usage(입력·출력 토큰)가 담긴다. 과금은 입력 토큰 기준이고 출력 토큰은 무료다 (2026-09 기준) 52.
오류는 표준 HTTP 코드를 쓴다. 한도를 넘기면 429, 서버가 밀리면 529가 돌아오고, 둘 다 지수 백오프로 재시도하라고 안내한다. 공식 SDK는 기본으로 재시도한다 52.
함께 읽기
- 시스템 원 모델 — 이 질문·답 구조가 나온 모델 갈래의 정의와 훈련 경로
- Jev — 이 프리미티브를 실제로 처리하는 모델의 버전·가격·한도
- Jev vs LLM vs 코드 — 어떤 판단을 이 질문들로 옮기는 게 이득인지
- LLM 기초 — 확률 분포라는 말이 낯설 때 먼저 읽을 배경