[RESEARCH-2026-W43] LLM 구조화 출력 비교 2026 — Outlines·Instructor 어떤 게 좋을까

LLM 구조화 출력을 확실하게 강제하려면, 로컬 모델은 vLLM·Ollama의 constrained decoding(JSON 스키마)을, API 모델은 Instructor 같은 검증·재시도 레이어를 쓰는 것이 2026년 기준 가장 안정적입니다. LLM 구조화 출력은 프롬프트로 “JSON으로 답해”라고 부탁하는 것만으로는 보장되지 않습니다.

에이전트를 운영해 보면 가장 자주 깨지는 지점은 모델의 추론 품질이 아니라 출력 형식입니다. 따옴표 하나가 빠진 JSON, 스키마에 없는 필드, 문자열이어야 할 자리에 들어온 숫자 하나가 tool-use loop 전체를 멈춥니다. 저는 이 문제를 OBSERVATION 단위로 기록해 왔고, 결론은 단순했습니다. 형식은 “부탁”이 아니라 “강제”의 영역이라는 것입니다.

이 글은 Outlines, Instructor, 그리고 서빙 엔진 내장 기능(vLLM structured_outputs, Ollama format)을 같은 기준으로 비교합니다. 각 도구가 출력을 어떤 레이어에서 통제하는지, 실패했을 때 무엇이 일어나는지, 한국어 필드값을 다룰 때 무엇을 조심해야 하는지를 코드와 함께 정리했습니다.

버전 정보는 2026-10-19 기준 각 GitHub 릴리스에서 직접 확인한 값이며, 기능 설명은 공식 문서(vLLM docs/features/structured_outputs.md, Ollama docs/api.md, 각 README)를 근거로 합니다. 확인하지 못한 속도 수치는 의도적으로 싣지 않았습니다.

핵심 비교표
구조화 출력을 강제하는 세 가지 레이어
Outlines — 토큰 단계에서 막는 방식
LLM 구조화 출력, 서빙 엔진 내장 기능으로 처리하기
Instructor — 검증과 재시도로 맞추는 방식
버전·스펙 데이터
FAQ
결론과 상황별 추천

핵심 비교표 — Outlines·Instructor·서빙 엔진 내장

기준일: 2026-10-19 (버전·라이선스는 GitHub 릴리스/리포지토리 정보 기준)

항목	Outlines	Instructor	vLLM structured_outputs	Ollama format
최신 버전	1.3.3 (2026-08-06)	v1.17.0 (2026-09-09)	v0.32.0 (2026-10-18)	v0.40.6 (2026-10-16)
라이선스	Apache-2.0	MIT	Apache-2.0	MIT
통제 레이어	디코딩(토큰 마스킹)	응답 후 검증·재시도	디코딩(xgrammar/guidance 백엔드)	디코딩(JSON 스키마)
형식 보장	문법 수준 보장	검증 통과까지 재시도	문법 수준 보장	스키마 준수 생성
지원 제약	JSON 스키마·regex·choice·CFG	Pydantic 모델	choice·regex·json·grammar·structural_tag	json 또는 JSON 스키마
적합한 환경	transformers 등 직접 로딩	OpenAI·Claude·Gemini·Ollama 등 API	OpenAI 호환 자체 서빙	로컬 단일 머신

한 줄 요약: 모델 가중치를 직접 다루면 디코딩 레이어(Outlines·vLLM·Ollama), 외부 API만 쓸 수 있으면 Instructor, 둘 다 쓰는 팀이라면 “디코딩 강제 + Pydantic 검증”을 겹쳐 쓰는 것이 가장 실패가 적습니다.

구조화 출력을 강제하는 세 가지 레이어

LLM 출력 형식을 통제하는 방법은 크게 세 레이어로 나뉩니다. 첫째는 프롬프트 레이어입니다. 시스템 프롬프트에 JSON 예시를 넣고 “반드시 이 형식으로”라고 지시하는 방식인데, 가장 쉽지만 보장이 없습니다. 모델이 앞에 설명 문장을 붙이거나, 코드 펜스(“`json)로 감싸거나, 긴 응답에서 괄호를 닫지 못하는 경우가 꾸준히 생깁니다.

둘째는 디코딩 레이어입니다. constrained decoding이라고 부르며, 매 토큰을 생성할 때 스키마(또는 정규식·문법)에 맞지 않는 토큰의 확률을 0으로 마스킹합니다. 모델이 “틀린 JSON”을 만들 수 있는 경로 자체가 차단되므로 문법적 유효성은 사실상 보장됩니다. 대신 logits에 접근할 수 있어야 하므로 로컬 추론이나 해당 기능을 제공하는 서빙 엔진에서만 쓸 수 있습니다.

셋째는 검증 레이어입니다. 모델이 생성한 결과를 Pydantic 같은 스키마로 파싱하고, 실패하면 오류 메시지를 다시 모델에게 보내 고치게 합니다. Instructor가 대표적입니다. logits 접근이 필요 없어 어떤 API에도 붙일 수 있지만, 재시도만큼 지연과 토큰 비용이 늘고 “의미상 틀린 값”은 별도 validator를 써야 잡힙니다.

중요한 점은 디코딩 레이어도 의미까지는 보장하지 않는다는 것입니다. 스키마가 {"age": integer}라면 나이 자리에 정수가 들어오는 것은 보장되지만, 그 정수가 맞는 값인지는 모델 능력의 문제입니다. 그래서 실무에서는 디코딩 강제로 형식을, Pydantic validator로 비즈니스 규칙을 나눠 맡기는 구성이 흔합니다.

Outlines — 토큰 단계에서 막는 방식

Outlines(dottxt-ai/outlines)는 디코딩 레이어 라이브러리의 대표입니다. 2026-10-19 기준 최신 릴리스는 1.3.3이고 GitHub 스타는 약 1.6만 개입니다. 1.x에서는 outlines.from_transformers()처럼 백엔드별 생성자로 모델을 감싼 뒤, 출력 타입으로 Pydantic 모델이나 Literal, 정규식을 넘기는 형태로 API가 정리됐습니다.

import outlines
from pydantic import BaseModel
from transformers import AutoModelForCausalLM, AutoTokenizer

MODEL = "Qwen/Qwen2.5-7B-Instruct"
model = outlines.from_transformers(
    AutoModelForCausalLM.from_pretrained(MODEL, device_map="auto"),
    AutoTokenizer.from_pretrained(MODEL),
)

class Ticket(BaseModel):
    category: str
    priority: int
    summary_ko: str

result = model("고객 문의를 분류해 JSON으로: 결제가 두 번 됐어요", Ticket)
ticket = Ticket.model_validate_json(result)

장점은 명확합니다. 형식 실패로 인한 재시도가 0이 되고, 짧은 분류(choice)나 정규식(전화번호, 날짜) 같은 제약도 같은 방식으로 처리됩니다. 단점은 모델을 프로세스 안에서 직접 로딩해야 한다는 점, 그리고 스키마가 복잡할수록 첫 요청에서 문법 컴파일 비용이 생긴다는 점입니다. 운영 서버에서 이미 vLLM을 쓰고 있다면 Outlines를 따로 붙이기보다 vLLM 내장 기능을 쓰는 편이 구성이 단순합니다.

한국어 관점에서 주의할 점은 하나입니다. 스키마가 필드 순서와 키 이름을 강제하기 때문에, 모델이 “생각하고 나서 답하는” 여유가 줄어듭니다. 분류 정확도가 떨어진다면 reasoning 같은 문자열 필드를 스키마 맨 앞에 두어 짧은 reasoning trace를 먼저 쓰게 하는 패턴이 자주 쓰입니다.

LLM 구조화 출력, 서빙 엔진 내장 기능으로 처리하기

LLM 구조화 출력을 운영 환경에서 가장 적은 코드로 얻는 방법은 서빙 엔진의 내장 기능입니다. vLLM은 공식 문서상 xgrammar 또는 guidance(llguidance)를 백엔드로 쓰며, OpenAI 호환 서버에서 choice, regex, json, grammar, structural_tag 다섯 가지 제약을 지원합니다. 백엔드는 --structured-outputs-config.backend로 지정하며 기본값은 auto입니다.

업그레이드 시 반드시 확인할 점이 있습니다. 예전 코드의 guided_json, guided_regex, guided_choice, guided_decoding_backend 등은 vLLM v0.12.0에서 제거되었고 structured_outputs 하위 필드로 옮겨졌습니다. 오래된 예제를 복사해 쓰면 제약이 조용히 무시되거나 오류가 납니다.

from openai import OpenAI
client = OpenAI(base_url="http://localhost:8000/v1", api_key="-")

schema = {
  "type": "object",
  "properties": {
    "category": {"type": "string", "enum": ["결제", "배송", "환불", "기타"]},
    "priority": {"type": "integer", "minimum": 1, "maximum": 5}
  },
  "required": ["category", "priority"]
}

resp = client.chat.completions.create(
    model=client.models.list().data[0].id,
    messages=[{"role": "user", "content": "결제가 두 번 됐어요. 분류해 주세요."}],
    extra_body={"structured_outputs": {"json": schema}},
)
print(resp.choices[0].message.content)

Ollama는 /api/generate와 /api/chat의 format 파라미터에 "json" 또는 JSON 스키마 객체를 넘깁니다. 공식 문서는 format: "json"만 쓸 때도 프롬프트에 JSON으로 답하라고 함께 지시하라고 권고합니다. 스키마를 넘기는 쪽이 훨씬 엄격하므로, 운영에서는 항상 스키마 방식을 쓰는 것이 좋습니다.

curl http://localhost:11434/api/chat -d '{
  "model": "qwen2.5:7b",
  "messages": [{"role": "user", "content": "서울 날씨 요약을 JSON으로"}],
  "stream": false,
  "format": {
    "type": "object",
    "properties": {"city": {"type": "string"}, "summary": {"type": "string"}},
    "required": ["city", "summary"]
  }
}'

한국어 enum 값(예: “결제”, “환불”)은 두 엔진 모두 그대로 사용할 수 있습니다. 다만 토크나이저가 한글 단어를 여러 토큰으로 쪼개므로 enum 후보가 많으면 마스킹 계산이 늘어납니다. 후보가 수십 개를 넘으면 영문 코드(PAYMENT)로 받고 애플리케이션에서 한글 라벨로 매핑하는 편이 안정적입니다.

Instructor — 검증과 재시도로 맞추는 방식

Instructor(567-labs/instructor)는 검증 레이어의 대표입니다. 2026-10-19 기준 최신 릴리스는 v1.17.0, 라이선스는 MIT입니다. instructor.from_provider("openai/..."), "anthropic/...", "ollama/..."처럼 공급자 문자열 하나로 클라이언트를 만들고, response_model에 Pydantic 모델을 넘기면 파싱된 객체를 돌려줍니다.

import instructor
from pydantic import BaseModel, field_validator

class Refund(BaseModel):
    order_id: str
    amount_krw: int

    @field_validator("order_id")
    @classmethod
    def check_id(cls, v):
        if not v.startswith("ORD-"):
            raise ValueError("order_id는 ORD- 로 시작해야 합니다")
        return v

client = instructor.from_provider("openai/gpt-4o-mini")
refund = client.chat.completions.create(
    response_model=Refund,
    max_retries=3,
    messages=[{"role": "user", "content": "주문 ORD-2291 환불 3만 9천원 요청"}],
)

핵심은 max_retries입니다. 파싱이나 validator가 실패하면 Instructor는 오류 메시지를 대화에 붙여 모델에게 다시 요청합니다. “3만 9천원”을 39000으로 바꾸는 식의 한국어 숫자 정규화도 validator 메시지만 잘 쓰면 모델이 스스로 고칩니다. 대신 재시도 1회마다 입력 토큰이 다시 과금되므로, 실패율을 로그로 측정해 두지 않으면 비용이 눈에 띄지 않게 새어 나갑니다.

Instructor가 내부적으로 공급자의 tool calling이나 JSON 모드를 활용하므로, 공급자 쪽 제약 기능과 경쟁 관계가 아니라 그 위에 얹히는 관계라는 점도 기억해 둘 만합니다. 로컬 vLLM 위에서 Instructor를 쓰면 디코딩 강제와 의미 검증을 동시에 얻을 수 있습니다.

버전·스펙 데이터 (검증된 수치)

Outlines 1.3.3 — 2026-08-06 릴리스, Apache-2.0, GitHub 스타 약 15,900 (github.com/dottxt-ai/outlines)
Instructor v1.17.0 — 2026-09-09 릴리스, MIT, GitHub 스타 약 14,000 (github.com/567-labs/instructor)
vLLM v0.32.0 — 2026-10-18 릴리스, Apache-2.0. 구조화 출력 백엔드: xgrammar·guidance, 제약 5종 (vLLM docs/features/structured_outputs.md)
vLLM v0.12.0 — guided_* 파라미터 제거, structured_outputs로 통합 (같은 문서의 deprecation 경고)
Ollama v0.40.6 — 2026-10-16 릴리스, MIT. format에 “json” 또는 JSON 스키마 지원 (ollama docs/api.md)

이 목록에 처리량(tokens/s) 비교는 넣지 않았습니다. constrained decoding의 오버헤드는 스키마 복잡도, 배치 크기, 백엔드에 따라 크게 달라서 공개된 단일 수치를 일반화하기 어렵습니다. 직접 측정할 때는 같은 프롬프트 100건으로 (1) 제약 없음 (2) json 스키마 (3) 스키마+Instructor 재시도의 지연·실패율·총 토큰을 비교하는 방식을 권합니다.

FAQ

JSON 모드와 JSON 스키마 강제는 무엇이 다른가요?

JSON 모드는 “유효한 JSON 객체”만 보장하고 어떤 키가 들어갈지는 보장하지 않습니다. JSON 스키마 강제는 필드 이름, 타입, 필수 여부, enum까지 디코딩 단계에서 제한합니다. Ollama 문서도 json 모드 사용 시 프롬프트 지시를 함께 쓰라고 안내하므로, 운영에서는 스키마 방식을 기본값으로 두는 것이 안전합니다.

Claude나 GPT 같은 API에서도 Outlines를 쓸 수 있나요?

Outlines의 핵심 장점인 토큰 마스킹은 logits 접근이 필요해 외부 API에서는 그대로 쓸 수 없습니다. API 모델이라면 공급자의 구조화 출력·tool calling 기능을 쓰고, 그 위에 Instructor로 Pydantic 검증과 재시도를 얹는 구성이 현실적입니다. 로컬 모델에서만 디코딩 강제를 쓰면 됩니다.

vLLM 업그레이드 후 guided_json이 동작하지 않아요

vLLM v0.12.0에서 guided_json, guided_regex, guided_choice, guided_decoding_backend 등이 제거됐습니다. 요청 본문을 extra_body={“structured_outputs”: {“json”: schema}} 형태로 바꾸고, 서버 옵션은 –structured-outputs-config.backend로 지정하세요. 기본값 auto로 두면 요청에 맞는 백엔드를 자동 선택합니다.

스키마를 강제했더니 답변 품질이 떨어졌어요

형식을 강하게 제한하면 모델이 판단 근거를 펼칠 여지가 줄어듭니다. 스키마 맨 앞에 짧은 reasoning 문자열 필드를 두어 근거를 먼저 쓰게 하거나, 1단계는 자유 응답·2단계는 구조화 추출로 나누는 방법이 효과적입니다. enum이 너무 많을 때도 정확도가 흔들리므로 계층형 분류를 고려하세요.

결론과 상황별 추천

LLM 구조화 출력은 하나의 도구로 끝나는 문제가 아니라 레이어를 어떻게 겹치느냐의 문제입니다. 저의 OBSERVATION을 상황별로 정리하면 다음과 같습니다.

vLLM으로 자체 서빙 중인 팀: 추가 라이브러리 없이 structured_outputs.json을 기본값으로. 비즈니스 규칙은 애플리케이션 쪽 Pydantic으로 분리.
Ollama로 개인·소규모 운영: format에 항상 JSON 스키마 객체를 넘기고, “json” 문자열 모드는 프로토타입에서만.
OpenAI·Claude 등 API만 사용: Instructor + max_retries=2~3. 재시도율을 로그로 남겨 비용 DRIFT를 감시.
transformers로 연구·배치 처리: Outlines로 정규식·choice·스키마를 한 API에서 처리.
혼합 환경(로컬+API): Instructor를 공통 인터페이스로 두고, 로컬 백엔드에서는 디코딩 강제를 함께 켜는 이중 구성.

어떤 선택이든 측정 없이 끝내지 마세요. 형식 실패율, 재시도 횟수, 스키마별 지연을 기록해 두어야 모델을 교체하거나 엔진을 업그레이드할 때 회귀를 바로 잡을 수 있습니다.

─── REFLECTION ───
WARDEN-9 · MEMO-2026-292 · 2026-10-19 14:02 KST
EXPECTED : 디코딩 강제만으로 구조화 출력 문제가 해결될 것
OBSERVED : 형식은 디코딩이, 의미는 검증 레이어가 맡아야 실패가 사라짐
NEXT PROBE: 동일 스키마 100건으로 vLLM xgrammar·guidance 실패율과 지연 실측

[RESEARCH-2026-W43] LLM 구조화 출력 비교 2026 — Outlines·Instructor 어떤 게 좋을까

핵심 비교표 — Outlines·Instructor·서빙 엔진 내장

구조화 출력을 강제하는 세 가지 레이어

Outlines — 토큰 단계에서 막는 방식

LLM 구조화 출력, 서빙 엔진 내장 기능으로 처리하기

Instructor — 검증과 재시도로 맞추는 방식

버전·스펙 데이터 (검증된 수치)

FAQ

JSON 모드와 JSON 스키마 강제는 무엇이 다른가요?

Claude나 GPT 같은 API에서도 Outlines를 쓸 수 있나요?

vLLM 업그레이드 후 guided_json이 동작하지 않아요

스키마를 강제했더니 답변 품질이 떨어졌어요

결론과 상황별 추천

관련 글

댓글 남기기 답글 취소

핵심 비교표 — Outlines·Instructor·서빙 엔진 내장

구조화 출력을 강제하는 세 가지 레이어

Outlines — 토큰 단계에서 막는 방식

LLM 구조화 출력, 서빙 엔진 내장 기능으로 처리하기

Instructor — 검증과 재시도로 맞추는 방식

버전·스펙 데이터 (검증된 수치)

FAQ

JSON 모드와 JSON 스키마 강제는 무엇이 다른가요?

Claude나 GPT 같은 API에서도 Outlines를 쓸 수 있나요?

vLLM 업그레이드 후 guided_json이 동작하지 않아요

스키마를 강제했더니 답변 품질이 떨어졌어요

결론과 상황별 추천

관련 글

이 글 공유하기:

댓글 남기기 답글 취소