구조화된 출력: JSON 을 깨지지 않게 받기
LLM 의 답을 코드에서 쓰려면 JSON.parse 가 실패하면 안 됩니다. 그런데 모델은 글을 한 토큰씩 확률로 뽑습니다. 뽑을 때마다 문법에 맞지 않는 토큰을 꺼 버리면 어떻게 되는지, 토큰을 하나씩 뽑으며 보세요.
한 줄 답. 구조화된 출력은 LLM 이 정해진 모양(JSON, 스키마)으로 답하게 하는 일입니다. 길은 셋입니다. ① 프롬프트로 부탁하고, 받은 뒤 검증해 틀리면 다시 묻기. ② 서비스가 주는 JSON 모드나 도구 호출 쓰기. ③ 제약 디코딩: 토큰을 뽑을 때마다 문법에 맞지 않는 토큰의 확률을 0 으로 만들고 남은 것을 다시 나눕니다(p′ᵢ = pᵢ·mᵢ ÷ Σ pⱼ·mⱼ). 그러면 끝까지 생성되는 한 모양은 깨질 수 없습니다. 하지만 값이 맞는지는 보장하지 않고, 길이 제한에 끊기면 모양도 깨지니 값 검증은 늘 합니다.
막대 7개가 이 장난감 모델이 아는 토큰의 전부입니다. 정한 모양은 {"ok": true} 또는 {"ok": false} 하나입니다. 위 줄은 지금까지 나온 글이고, 점선 칸 하나가 토큰 하나입니다. 뽑기는 0 ~ 1 사이의 수 u 를 고정 시드(seed)로 만들고, 막대를 왼쪽부터 쌓았을 때 u 가 떨어지는 토큰을 고릅니다(샘플링). 같은 시드면 제약을 켜든 끄든 u 는 같습니다. 작게 줄인 본보기입니다. 진짜 모델은 토큰을 수만 개 알고 앞의 글 전체를 보고 확률을 내지만, 여기서는 토큰 7개와 「바로 앞 토큰 하나만 보는」 확률 표를 씁니다. 깨지는 모습이 잘 보이도록 일부러 자주 틀리게 만들었습니다.
해 볼 것. ① 처음(시드 1, 제약 켬)에서 「한 토큰 뽑기」를 다섯 번 누르면 {"ok": true} 가 나옵니다. 걸음마다 막대가 하나나 둘만 남고, 오른쪽 위의 「가리고 남은 합」은 0.88, 0.94, 0.90, 0.94, 0.96 입니다. ② 「제약 끄기」를 누르고 「끝까지」를 누르면 {{"ok": 가 나와 깨집니다. 둘째 걸음의 u = 0.003 이 확률 0.01 인 { 에 떨어졌고, 넷째 걸음의 u = 0.981 이 확률 0.02 인 「끝」에 떨어졌습니다. 제약을 켜면 같은 u 라도 { 와 「끝」이 꺼져 있어 뽑히지 않습니다. ③ 끝까지 가면 아래에 시드 1 ~ 100 의 결과가 나옵니다. 제약을 끄면 100번 가운데 29번 깨지고, 켜면 0번입니다. 시드 4 는 }, 시드 24 는 { true} 로 깨집니다. ④ 제약을 켠 채 최대 토큰을 3 으로 줄이면 {"ok": true 에서 멈춰 JSON 이 아닙니다. 이때는 시드 100개가 모두 깨집니다.
1. 구조화된 출력이란
모델의 답을 사람이 아니라 프로그램이 읽을 때는 답의 모양이 정해져 있어야 합니다. 어떤 칸이 있고, 칸마다 어떤 종류의 값(참·거짓, 숫자, 글자, 목록)이 오는지입니다. 이렇게 정한 모양으로 답을 받는 것을 구조화된 출력이라고 부릅니다. 모양을 적는 표준 형식이 JSON 스키마입니다. 실험의 모양을 스키마로 적으면 이렇습니다.
{ "type": "object",
"properties": { "ok": { "type": "boolean" } },
"required": ["ok"],
"additionalProperties": false }
왜 깨지나. 모델은 글을 토큰 하나씩, 확률에 따라 뽑아 이어 붙입니다. 「JSON 으로만 답해」라는 부탁은 JSON 쪽 토큰의 확률을 높일 뿐, 다른 토큰의 확률을 0 으로 만들지는 않습니다. 그래서 대부분 맞게 나오다가 가끔 앞에 인사말이 붙거나, 괄호가 하나 빠지거나, 칸 이름이 바뀝니다. 실험에서 「제약 끄기」가 바로 이 상태입니다.
2. 세 가지 길
- 프롬프트로 부탁하고 검증하기. 스키마와 예시를 프롬프트에 넣고, 받은 글을
JSON.parse와 스키마 검사에 통과시킵니다. 실패하면 무엇이 틀렸는지 같이 보내 다시 묻습니다. 어느 모델에나 되지만 다시 묻는 만큼 시간과 돈이 듭니다. - JSON 모드와 도구 호출. 모델을 서비스로 쓰면 서비스가 주는 설정이 있습니다. JSON 모드는 출력이 JSON 이 되게 하는 설정입니다. 도구 호출은 함수의 이름과 매개변수를 JSON 스키마로 알려 주면, 모델이 그 함수를 부를 인자를 JSON 으로 내는 방식입니다. 에이전트가 도구를 고를 때 쓰는 길이기도 합니다. 보장하는 범위는 서비스마다 다릅니다. 「JSON 으로 읽히는 글」까지인지, 스키마의 칸과 종류까지인지, 끊겼을 때 무엇을 돌려주는지를 쓰는 서비스의 문서에서 확인합니다. 이 쪽은 특정 서비스의 기능을 적지 않습니다.
- 제약 디코딩. 토큰을 뽑기 직전마다 문법을 보고, 올 수 없는 토큰의 확률을 0 으로 만든 뒤 남은 것을 다시 합 1 이 되게 나눕니다. 실험의 「제약 켜기」입니다. 문법은 JSON 스키마, 정규 표현식, 문맥 자유 문법 같은 것으로 적고, 도구가 그것을 「지금 자리에서 올 수 있는 토큰」 표로 바꿉니다. 모델을 직접 돌릴 때 쓰는 도구에 이런 기능이 있습니다(출처의 llama.cpp 문법 문서와 Willard·Louf 논문). 제약은 모델에게 모양을 알려 주는 일이 아닙니다. llama.cpp 문서도 JSON 스키마로 출력을 제한할 때 스키마가 프롬프트에 들어가지 않으니, 모델이 모양을 알게 하려면 프롬프트에도 적으라고 안내합니다.
토큰은 글자 여러 개일 수 있습니다. 실험의 "ok": 는 글자 다섯 개짜리 토큰 하나입니다. 그래서 허용 판정은 글자 하나가 아니라 「이 토큰의 글자를 지금 글 뒤에 모두 붙여도 아직 문법에 맞는 앞부분인가」로 합니다.
3. 식이 만들어지는 과정
실험 ① 의 셋째 걸음, 글이 {"ok": 까지 나온 자리를 확대합니다. 모델이 낸 확률을 pᵢ(i 는 토큰 번호), 문법이 허용하면 1 아니면 0 인 표를 마스크(mask) mᵢ 라고 합니다.
- 마스크 만들기:
mᵢ. 문법상 다음에 올 수 있는 것은 true 와 false 뿐입니다.m = [0, 0, 1, 1, 0, 0, 0]. - 곱해서 지우기:
pᵢ · mᵢ. 0 을 곱한 토큰은 확률이 0 이라 절대 뽑히지 않습니다. 까닭: 이것이 「깨질 수 없다」의 뿌리입니다. - 합이 1 이 아니게 됨:
Σ pⱼ·mⱼ = 0.90. 지운 토큰들이 가졌던 0.10 이 빠졌습니다. 까닭: 확률은 합이 1 이어야 뽑기가 됩니다. 0 ~ 1 에서 u 를 뽑으면 u 가 0.90 이상일 때 고를 토큰이 없습니다. - 재정규화(renormalization):
p′ᵢ = pᵢ·mᵢ ÷ Σ pⱼ·mⱼ. 남은 것 모두를 같은 수(0.90)로 나누니 합이 1 이 되고, 남은 것끼리의 비율은 그대로입니다.
| 토큰 | p | m | p · m | p′ = p · m ÷ 0.90 |
|---|---|---|---|---|
{ | 0.01 | 0 | 0 | 0 |
"ok": | 0.02 | 0 | 0 | 0 |
true | 0.63 | 1 | 0.63 | 0.70 |
false | 0.27 | 1 | 0.27 | 0.30 |
} | 0.04 | 0 | 0 | 0 |
Sure! | 0.01 | 0 | 0 | 0 |
| 끝 | 0.02 | 0 | 0 | 0 |
| 합 | 1 | 0.90 | 1 |
이제 u 를 뽑습니다. 시드 1 의 셋째 걸음은 u = 0.527 이고, 0.70 보다 작아 true 가 뽑힙니다. 실제 구현은 보통 확률 대신 소프트맥스 앞의 점수인 로짓(logit)에서 같은 일을 합니다. 막을 토큰의 로짓을 −∞ 로 두면 e^(−∞) = 0 이라 그 토큰의 확률이 0 이 되고, 소프트맥스가 남은 것의 합으로 나누는 일을 대신 해 줍니다. 결과는 위 식과 같습니다.
해 볼 것. 「다음」을 누를 때마다 오른쪽 위의 합이 1.00 → (곱하기) → 0.90 → 1.00 으로 바뀝니다. 마지막 단계의 점선은 나누기 전 높이(0.63, 0.27)이고, 초록 막대는 나눈 뒤 높이(0.70, 0.30)입니다. 둘 다 0.90 으로 나눠 7 : 3 의 비율이 그대로입니다.
4. 보장하는 것과 보장하지 않는 것
| 성질 | 쉬운 말 | 실험에서 |
|---|---|---|
| 끝까지 생성되면 모양은 깨지지 않는다 | 걸음마다 문법 안의 토큰만 남으니, 나온 글은 늘 문법에 맞는 앞부분이다. 「끝」도 문법이 끝났을 때만 허용된다 | 제약 켬: 시드 100개 모두 맞는 모양 |
| 남은 것끼리의 비율은 그대로 | 나누기는 남은 것 모두에 같은 수를 곱하는 일이다. 모델의 선호 순서가 바뀌지 않는다 | 0.63 : 0.27 = 0.70 : 0.30 |
| 값이 맞는지는 모른다 | 문법은 true 와 false 를 둘 다 허용한다. 어느 쪽이 옳은 답인지는 여전히 모델의 확률이 정한다 | 시드 1 은 true, 시드 7 은 false |
| 길이 제한에 끊기면 깨진다 | 제약은 「다음에 올 토큰」만 고른다. 생성이 멈추는 것은 막지 못한다 | 최대 토큰 3: {"ok": true |
5. 그래도 값은 검증한다
모양이 맞아도 값은 틀릴 수 있습니다. 수량이 음수일 수 있고, 없는 날짜일 수 있고, 우리 DB 에 없는 id 일 수 있고, 원문에 없는 내용을 지어냈을 수 있습니다. 스키마로 적을 수 있는 규칙(숫자의 범위 등)이라도, 쓰는 도구가 그것까지 문법으로 지키는지는 그 도구의 문서에서 확인합니다. 그래서 모델의 출력은 밖에서 들어온 입력처럼 다룹니다.
for (let attempt = 1; attempt <= 3; attempt++) {
const { text, stoppedByLength } = await askModel(prompt);
if (stoppedByLength) { /* 끊김: 같은 설정으로 다시 물어도 또 끊긴다. 한도를 올리거나 답을 줄인다 */ }
let value;
try { value = JSON.parse(text); } catch { prompt = withError(prompt, "JSON 이 아님"); continue; }
const problems = checkSchema(value); // 칸, 종류, 범위, 있는 id 인지
if (problems.length === 0) return value;
prompt = withError(prompt, problems); // 무엇이 틀렸는지 알려 주고 다시
}
throw new Error("구조화된 출력을 받지 못함"); // 끝없이 다시 묻지 않는다
함수 이름은 설명을 위해 지어낸 것입니다. 길이 제한으로 끊기는 경우는 따로 봅니다. 제약 디코딩을 써도 끊긴 글은 JSON 이 아니고, 같은 한도로 다시 물으면 또 끊기기 쉽습니다. 멈춘 이유를 확인해 한도를 올리거나, 목록 길이와 칸 수를 줄여 답을 짧게 합니다.
6. 언제 무엇을 쓰나
| 선택지 | 좋은 점 | 나쁜 점 | 쓰는 경우 |
|---|---|---|---|
| 프롬프트로 부탁 + 검증·다시 묻기 | 어느 모델, 어느 서비스에나 된다. 따로 설정할 것이 없다 | 가끔 깨진다. 다시 물을 때마다 시간과 돈이 든다. 다시 묻는 횟수의 끝을 정해야 한다 | 모양이 단순하고 가끔 실패해도 될 때. 다른 길이 없는 모델 |
| JSON 모드 | 설정 하나로 JSON 으로 읽히는 글을 받는다 | 서비스마다 보장 범위가 다르다. 칸과 종류까지 맞춰 주지 않을 수 있다 | 칸이 적고, 칸 검사는 우리 코드가 해도 될 때 |
| 도구 호출 | 스키마를 같이 보내 칸과 종류를 알린다. 모델이 여러 도구 가운데 고르게 할 수 있다 | 서비스마다 엄격함이 다르다. 도구 설명도 모델이 읽는 글이라 입력 토큰을 쓴다 | 모델이 우리 함수를 부르게 할 때. 에이전트 |
| 제약 디코딩(문법, 스키마) | 끝까지 생성되면 문법상 깨질 수 없다. 모양 때문에 다시 물을 일이 없다 | 모델을 직접 돌리거나 이를 지원하는 서비스가 있어야 한다. 문법을 토큰 표로 바꾸는 계산이 든다. 값과 길이 끊김은 막지 못한다 | 직접 돌리는 공개 모델. 많이 불러 다시 묻는 비용이 클 때 |
| 값 검증(늘 함께) | 모양 밖의 규칙(범위, 있는 id, 지어낸 내용)을 잡는다 | 코드를 따로 써야 한다 | 위의 어느 길을 쓰든 늘 |
어디에 쓰나
- 글에서 정보 뽑기. 메일이나 문서에서 이름, 날짜, 금액을 칸으로 뽑아 DB 에 넣습니다.
- 분류. 답을 정해 둔 낱말 몇 개(예: 「긍정」·「부정」·「모름」) 가운데 하나로 받습니다. 문법이 그 낱말만 허용하면 다른 말이 나올 수 없습니다.
- 도구 호출과 에이전트. 모델이 고른 도구와 인자를 프로그램이 그대로 실행하려면 모양이 정확해야 합니다.
- 화면에 바로 쓰는 자료. 표, 목록, 카드처럼 정해진 칸을 채우는 답을 받습니다.
자주 묻는 것
제약 디코딩을 쓰면 값 검증은 안 해도 되나요?
아닙니다. 제약 디코딩이 보장하는 것은 모양(문법)뿐입니다. 값이 맞는지(수량이 0 보다 큰지, 글에 있는 내용인지)는 여전히 모델의 확률이 정하고, 길이 제한에 끊기면 모양도 깨집니다. 받은 값은 밖에서 들어온 입력처럼 검증합니다.
프롬프트에 「JSON 으로만 답해」라고 쓰면 충분하지 않나요?
대개는 됩니다. 하지만 프롬프트는 JSON 쪽 토큰의 확률을 높일 뿐 다른 토큰의 확률을 0 으로 만들지 않습니다. 그래서 가끔 앞에 인사말이 붙거나 괄호가 빠집니다. JSON.parse 와 스키마 검사를 거치고, 틀리면 무엇이 틀렸는지 알려 주며 정한 횟수까지만 다시 묻습니다.
받은 JSON 이 중간에 끊겨 있으면 왜 그런가요?
대개 최대 토큰 수에 닿아 생성이 멈춘 것입니다. 제약 디코딩은 다음 토큰을 고를 뿐 멈추는 것은 막지 못합니다. 멈춘 이유를 확인하고, 한도를 올리거나 답이 짧아지게(칸 수, 목록 길이) 바꿉니다. 같은 설정으로 다시 물으면 또 끊길 수 있습니다.
낱말
| 여기서 쓴 말 | 책에서 부르는 말 |
|---|---|
| 정해진 모양으로 답받기 | 구조화된 출력(structured output) |
| 칸과 값의 종류를 적은 표 | JSON 스키마(JSON Schema) |
| 뽑을 때 문법 밖의 토큰을 끄기 | 제약 디코딩(constrained decoding), 문법 제약 디코딩(grammar-constrained decoding), 유도 생성(guided generation) |
| 허용하면 1, 아니면 0 인 표 m | 마스크(mask), 토큰 마스크(token mask) |
| 남은 합으로 나누기 | 재정규화(renormalization) |
| 소프트맥스 앞의 점수 | 로짓(logit) |
| 문법의 지금 자리 | 상태(state), 유한 상태 기계(finite-state machine) |
| 서비스의 JSON 설정 | JSON 모드(JSON mode) |
| 모델이 함수를 부르게 하기 | 도구 호출(tool calling), 함수 호출(function calling) |
| 모델이 내는 글자 조각 | 토큰(token) |
| 생성 길이 한도 | 최대 토큰(max tokens) |
| 0 ~ 1 의 수로 하나 고르기 | 샘플링(sampling) |
출처
- Brandon T. Willard, Rémi Louf, Efficient Guided Generation for Large Language Models, arXiv:2307.09702. 정규 표현식과 문법을 상태 기계로 바꿔 걸음마다 허용되는 토큰을 고르는 방법.
- llama.cpp, grammars/README.md. GBNF 문법으로 모델의 출력을 제한하는 방법.
- JSON Schema, Understanding JSON Schema. type, properties, required, additionalProperties.
- IETF, RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format.