# LLM 구조화 출력 핸드북

> Clean Markdown view of GeekNews topic #25907. Use the original source for factual precision when an external source URL is present.

## Metadata

- GeekNews HTML: [https://news.hada.io/topic?id=25907](https://news.hada.io/topic?id=25907)
- GeekNews Markdown: [https://news.hada.io/topic/25907.md](https://news.hada.io/topic/25907.md)
- Type: GN+
- Author: [neo](https://news.hada.io/@neo)
- Published: 2026-01-18T01:36:57+09:00
- Updated: 2026-01-18T01:36:57+09:00
- Original source: [nanonets.com](https://nanonets.com/cookbooks/structured-llm-outputs)
- Points: 3
- Comments: 1

## Topic Body

- **대규모 언어 모델(LLM)** 이 JSON, XML, 코드 등 구조화된 형식을 생성할 때 발생하는 불안정성을 해결하기 위한 **개발자용 실무 가이드**  
- 확률적 특성으로 인해 출력이 비결정적으로 깨질 수 있으며, 이를 보완하기 위한 **결정적 구조화 기법**을 다룸  
- 내부 동작 원리, **도구 및 기술 선택**, **배포·확장·비용 최적화**, **출력 품질 개선** 등 전 과정을 포괄  
- 빠르게 변화하는 구조화 생성 분야의 최신 정보를 **지속적으로 갱신되는 문서 형태**로 통합 제공  
- **데이터 추출, 코드 생성, 도구 호출** 등 LLM을 프로그래밍적으로 활용하는 개발자에게 필수적인 참고 자료  

---
### 구조화된 LLM 출력의 필요성
- LLM은 JSON, XML, 코드 등 **구문적으로 유효한 출력**을 대부분 생성하지만, 확률적 특성으로 인해 **형식 오류나 불완전한 결과**가 발생할 수 있음  
  - 이는 데이터 추출, 코드 생성, 도구 호출 등 **자동화된 프로세스**에서 문제를 일으킴  
- 이러한 문제를 해결하기 위해 **결정적(Deterministic) 구조화 출력 방식**이 필요함  
- 핸드북은 개발자가 구조화 출력을 안정적으로 구현할 수 있도록 **도구와 기법 전반**을 다룸  

### 핸드북의 주요 내용
- 내부 동작 원리, **최적의 도구 및 기술**, **도구 선택 기준**, **시스템 구축·배포·확장 방법**, **지연 시간·비용 최적화**, **출력 품질 향상** 등 실무 중심의 주제 포함  
- 각 항목은 **개발자가 직접 적용 가능한 단계별 접근법**으로 구성  
- 구조화 출력 관련 최신 연구와 오픈소스 도구를 **한 문서에 통합 정리**  

### 최신성 및 업데이트
- 구조화 생성 기술이 **매우 빠르게 발전**하고 있어 기존 자료가 금세 **시대에 뒤처짐**  
- 본 핸드북은 **정기적으로 업데이트되는 살아있는 문서(living document)** 로 유지됨  
- 개발자는 여러 논문, 블로그, GitHub 저장소를 뒤질 필요 없이 **한 곳에서 최신 정보 접근 가능**  

### 활용 방법
- 전체를 순차적으로 읽거나, **필요한 주제를 즉시 찾아보는 참고서 형태**로 활용 가능  
- **실무 개발자 중심 구성**으로, 특정 문제 해결 시 빠른 참조 가능  

### 제작자 및 커뮤니티
- 핸드북은 **Nanonets 팀**이 제작  
  - 이들은 [Nanonets-OCR 모델](https://huggingface.co/nanonets/models)과 [docstrange](https://github.com/NanoNets/docstrange) 오픈소스 문서 처리 라이브러리를 유지 관리  
- **LLM 개발자 커뮤니티 뉴스레터**를 통해 격주로 최신 인사이트, 돌파구, 유용한 도구와 기술을 제공

## Comments



### Comment 49397

- Author: neo
- Created: 2026-01-18T01:36:57+09:00
- Points: 1

###### [Hacker News 의견들](https://news.ycombinator.com/item?id=46635309) 
- 정말 아름다운 가이드임. 여러 페이지의 **탭 전환 애니메이션**이 특히 마음에 들었음  
  나는 grammar-constrained generation을 꽤 잘 이해한다고 생각했는데 (llama.cpp grammar 구현에 몇 가지 기여도 했음), 그래도 이 가이드에서 새로운 통찰을 얻었음  
  구조화된 출력은 LLM 엔진의 **가장 과소평가된 기능** 중 하나라고 생각함. 문법 제약 덕분에 LLM을 더 큰 파이프라인(예: tool-calling agent)의 일부로 안정적으로 사용할 수 있음  
  출력이 의미적으로 틀릴 수는 있어도 문법적으로는 항상 올바름. 특히 로컬 모델을 사용할 때 이 점이 매우 중요함  
  예를 들어 [Jart의 Raspberry Pi 기반 스팸 필터 예시](https://justine.lol/matmul/)처럼, TinyLlama 모델에 `"yes"` 또는 `"no"`만 출력하도록 grammar를 적용하면, 작은 하드웨어에서도 안정적으로 동작함
  - 모델이 다른 출력을 내고 싶을 때는 어떻게 되는지, llamafile 내부에서 처리하는 게 나은지 아니면 외부 래퍼에서 하는 게 나은지 궁금함. **재시도 설정**이나 JSON 범위 지정은 어떻게 하는지도 알고 싶음

- 정말 훌륭한 가이드임. 나는 박사 과정에서 **structured generation** 연구를 했는데, 관심 있는 사람들을 위해 몇 가지 자료를 공유함  
  라이브러리로는 [Outlines](https://github.com/dottxt-ai/outlines), [Guidance](https://github.com/guidance-ai/guidance), [XGrammar](https://github.com/mlc-ai/xgrammar)가 있음  
  논문으로는 [Efficient Guided Generation for Large Language Models](https://arxiv.org/abs/2307.09702), [Automata-based constraints for language model decoding](https://arxiv.org/abs/2407.08103), [Pitfalls, Subtleties, and Techniques in Automata-Based Subword-Level Constrained Generation](https://openreview.net/pdf?id=DFybOGeGDS)를 추천함  
  블로그 글로는 [LLM Decoding with Regex Constraints](https://vivien000.github.io/blog/journal/llm-decoding-with-regex-constraints.html)과 [Coalescence: making LLM inference 5x faster](https://blog.dottxt.ai/coalescence.html)가 있음
  - Outlines가 스택 내에서 정확히 어떤 역할을 하는지 잘 모르겠음. 대형 모델 제공자들이 제공하는 **structured output API**와 비슷한 건지, 혹은 BAML 같은 프로젝트와 비교할 수 있는지 궁금함
  - [DFybOGeGDS 논문](https://openreview.net/pdf?id=DFybOGeGDS)의 canonical filtering 부분이 pretokenization을 고려하지 않은 것 같음. pretokenization regex를 실제로 반영한 canonical generation 연구가 있는지 알고 싶음
  - “다른 참고자료”라더니 이미 가이드에 다 있는 라이브러리 목록을 다시 나열한 것 같음
  - 정말 보물창고 같음. **Automata 기반 제약**은 흥미로운 주제임

- 잘 정리된 가이드임. **Guidance & llguidance 최적화**에 대해 더 알고 싶다면 우리가 작성한 [짧은 논문](https://guidance-ai.github.io/llguidance/llg-go-brrr)을 참고하면 좋음
  - 논문을 읽은 저자 중 한 명임. 특히 **dense token mask를 위한 slicing 구현**이 인상적이었음

- 이 가이드는 사람들이 주로 쓰는 두 가지 방법을 잘 다룸. 다만 **constrained generation**은 원래 LLM의 분포와 달라질 수 있음  
  예를 들어 LLM이 긴 구조적 객체를 생성할 때 ‘…’ 같은 패턴을 선호하는데, 제약된 생성은 이를 강제로 닫는 따옴표 등으로 보정해 오히려 잘못된 결과를 낼 수 있음  
  반면 **resampling**은 유효한 결과가 나올 때까지 반복하므로 더 안정적임  
  또 schema 오류를 문맥에 추가해가며 길이를 늘리는 것보다, 단순히 **재시도**하는 편이 품질과 비용 면에서 낫다고 생각함
  - 하이브리드 접근도 가능함. 먼저 비제약 생성(unconstrained)을 시도하고, 실패한 경우에만 제약 생성(constrained)을 적용하는 방식임

- SoTA 모델(Opus, Gemini 등)이 여전히 **output schema enforcement**가 필요한지 궁금함  
  요즘 모델들은 JSON이나 코드 생성 시 거의 문법 오류가 없는데, 내부적으로는 여전히 schema 검증을 하는지 알고 싶음  
  작은 모델에는 구조화된 생성이 필요하다는 건 이해함
  - 스키마가 복잡할수록 LLM이 **카운팅**에 약하기 때문에 여전히 유용함. 모델이 좋아졌어도 확률적 특성 때문에 완벽하지 않음
  - 최신 모델도 종종 ```json\n``` 같은 불필요한 토큰을 붙이는 경우가 있어서, 여전히 **JSON 응답 스키마**를 지정하는 게 안전함

- 구조화된 출력을 강제하면 **성능 저하**가 생김. 경우에 따라 2~3배 느려질 수 있음. 상황에 따라 감수할 만한 비용인지 판단해야 함

- 정말 놀라운 가이드임. 1년 전에 이런 자료가 있었다면 좋았을 것 같음. 주변 사람들에게 꼭 공유할 예정임

- 좋은 가이드임. 특히 [masked decoding 다이어그램](https://nanonets.com/cookbooks/structured-llm-outputs/basic-concepts/constrained-method/)이 마음에 듦  
  - 작성자 중 한 명임. 링크 문제를 확인해보겠음. 상용 모델 제공자들이 모두 **structured output 기능**을 추가 중이라, 가이드를 계속 업데이트할 예정임

- JSON보다 더 신뢰성 있고 **파싱이 쉬운 출력 포맷**이 있을지 궁금함. YAML이나 TOML은 각각 단점이 있지만, 토큰 수나 비용 면에서 나을 수도 있을 것 같음  
  - 그 목적을 위해 [TOON 포맷](https://github.com/toon-format/toon)을 사용함
  - 사람도 JSON 작성이 귀찮다고 느끼듯, LLM에게도 **TypeScript 같은 코드 형태**로 결과를 생성하게 하는 게 더 나을 수 있음. 다만 보안상 샌드박싱과 리소스 제한이 필요함
  - 우리는 **Markdown + YAML front matter** 기반의 콘텐츠 변환 파이프라인을 개발 중임. JSON 툴링이 부족하긴 하지만 검증은 어렵지 않음
  - 나는 **정규식으로 XML 스키마를 강제**하고, XML 파서로 디코딩함. 특히 코드 블록은 CDATA로 감싸서 자유도를 높임. OpenAI API의 regex structured output이 JSON보다 코드에 더 적합함
  - 직접 **평가(evaluation)** 를 해보는 게 좋음. 내 실험에서는 XML이 JSON보다 **out-of-distribution 작업**에서 항상 더 나은 결과를 냈음

- 문서/쿡북 페이지의 **기술 스택**이 궁금함. MkDocs나 GitBook 같지 않은데, 어떤 걸 썼는지 알고 싶음
  - **Docusaurus**를 사용했음