로컬 모델의 JSON 출력 오류 유형 분석 및 해결 라이브러리 공개
I catalogued every way local models break JSON output and built a repair library, here's what I found across 288 model calls
핵심 요약
LLM의 JSON 출력 오류 유형을 분석하고 이를 자동으로 복구하는 파이썬 라이브러리 outputguard를 소개함.
- 오류 유형 분석 — 마크다운 펜스, 후행 쉼표, 파이썬 자료형 혼용 등 7가지 주요 JSON 파손 패턴을 식별함.
- outputguard 라이브러리 — JSON 스키마 검증과 15단계 복구 전략을 통해 LLM의 비정형 출력을 정형화함.
- 범용성 확보 — JSON 외에도 YAML, TOML, 파이썬 리터럴 등 다양한 출력 형식을 지원함.
- 커뮤니티 반응 — 기존 도구와의 비교 및 LLM 활용에 대한 개발자들의 다양한 의견이 오감.
지난 몇 달 동안 OpenRouter에서 Llama 3, Mistral, Command R, DeepSeek, Qwen 등 모든 모델과 일반적인 폐쇄형 모델들을 대상으로 구조화된 출력 프롬프트를 실행해 봤음. 총 288번의 호출임. 무엇이 실제로 깨지는지, 얼마나 자주 깨지는지, 오픈 모델이 API 전용 모델과 다르게 실패하는지 알고 싶었음.
짧게 말하자면: 별 차이 없음. 실패 모드는 전반적으로 거의 동일함. 비율은 다름 — 어떤 모델은 거의 매번 마크다운 펜스를 씌우고, 어떤 모델은 프롬프트를 특정 방식으로 작성할 때만 그러지만, 파손의 범주는 어디서나 같음.
가장 많이 본 것들(대략 순서대로):
- JSON을 감싸는 마크다운 펜스 (모델은 자기가 도움이 된다고 생각함)
- 후행 쉼표 (학습 데이터에서 묻어난 JS 습관)
- JSON의 true/false/null 대신 파이썬의 True/False/None 사용
- 응답 중간에 토큰이 소진되어 잘린 객체
- 문자열 값 내부의 이스케이프되지 않은 따옴표
- JSON 내부의 // 또는 # 주석
- 모델이 게을러져서 데이터를 다 생성하지 않고 남긴 리터럴 ...
여기에 글을 올린 이유: 이걸 처리하는 방법에 대해 내가 본 조언 대부분은 "그냥 JSON 모드를 써라" 혹은 "제약 문법을 써라"였음. 물론 사용 가능할 때는 도움이 됨. 하지만 로컬에서 실행하는 많은 것들은 신뢰할 수 있는 JSON 모드가 없고, 문법 기반 생성은 그 자체로 트레이드오프(속도, 호환성)가 있으며, 구문적으로 유효한 JSON을 얻더라도 스키마 위반이나 잘림 현상이 발생할 수 있음.
그래서 JSON 스키마를 검증하고 문제가 발생했을 때 15가지 복구 전략을 특정 순서로 실행하는 파이썬 라이브러리(outputguard)를 만들었음. 순서가 생각보다 훨씬 중요했음: 인코딩을 구조보다 먼저 수정하고, 각 전략 사이마다 재파싱을 해서 나중의 수정이 이전 수정을 망치지 않게 하는 것임.
또한 JSON 모드가 없고 그냥 자기 마음대로 출력하는 모델들과 작업하다 보니 생각보다 더 자주 마주치게 된 YAML, TOML, 파이썬 리터럴도 처리함.
자세한 내용은 블로그에 정리해 뒀음: What Breaks When You Ask an LLM for JSON
2,001개의 테스트, MIT 라이선스, LLM 제공자 의존성 없음. pip install outputguard
다른 사람들의 경험은 어떤지 궁금함 — 내가 설명한 것과 같은 실패 패턴을 보고 있는지, 아니면 다르게 동작하는 모델/퀀트가 있는지?
