JSON Toolkit

JSON이 아직 도착 중일 때 파싱하는 법: 스트리밍 미리보기와 증분 복구

핵심 요약: LLM은 토큰 단위로 JSON을 내놓고 API는 큰 응답을 청크로 보내지만, JSON.parse는 전체 문서가 도착할 때까지 동작하지 않습니다. 이 글은 전체 복구·진짜 증분·부분 파싱이라는 세 가지 구현 방식의 역할을 나누고, Allow 마스크로 미리보기 안정성을 확보하는 법과 제곱급 재실행을 대체하는 스트리밍 파이프라인의 실측 수치와 코드를 제공합니다.

중급약 5분 소요2026-11-16 발행2026-11-16 업데이트
스트리밍 JSON 청크에 대한 부분 파싱과 증분 복구 파이프라인 도식

JSON.parse의 계약은 "전체가 도착하면 움직인다"이고 스트리밍의 계약은 "청크 하나 오면 하나 처리한다"입니다. 이 갈등의 본질은 속도가 아니라 완전성 의미론에 있습니다. 아직 다 쓰이지 않은 문서에는 '올바른 파싱 결과'가 존재하지 않습니다.

증상: 전체를 기다릴 수 없는 세 가지 시나리오

첫 번째는 LLM 애플리케이션입니다. 모델은 토큰 단위로 JSON을 내놓기 때문에 8KB짜리 구조화 출력이 도착을 마치기까지 수십 초가 걸리고, 사용자는 빈 패널을 바라봅니다. 사실 1초 시점에 이미 첫 필드들을 보여줄 수 있습니다. 두 번째는 게이트웨이와 프록시입니다. 상류가 HTTP 청크로 수십 MB 응답을 밀어올 때, 전달 전에 필드를 골라내려는 프록시가 res.json()으로 전부 버퍼하면 메모리 피크가 몇 배로 뛰어오릅니다. 세 번째는 메시지 큐와 로그 파이프라인으로, NDJSON 레코드가 앞 레코드에 이어 도착하고 소비자는 배치를 모으고 싶어 하지 않습니다.

공통점은 분명합니다. 데이터는 점진적으로 도착하는데 표준 파서의 인터페이스는 완전한 문서만 받습니다. JSON.parse는 1번째 청크에서 Unexpected end of JSON input을 던지고, 65번째 청크에서도 같은 오류를 던지며, 마지막 청크에 이르러서야 결과를 돌려줍니다. 기다림이 유일한 선택지는 아니지만, '다 쓰이지 않은 문서'의 파싱 결과를 무엇이라 부를지 먼저 정해야 합니다.

접두사 파싱의 의미론: 각 청크는 합법적인가

7847바이트 주문 배열을 120자씩 잘라 스트리밍 도착을 흉내 내고(Node v22.13.1, jsonrepair 3.15.0, partial-json 0.1.7), 모든 접두사에 세 파서를 돌렸습니다.

파싱 방식 66개 접두사 중 성공 수 누적 시간 의미론
JSON.parse 1 (마지막 청크뿐) 2.1 ms 전부 아니면 전무
partial-json (Allow.ALL) 66 (1번째 청크부터) 14.3 ms "지금까지 알려진 값"을 항상 반환
jsonrepair 접두사마다 전체 재실행 66 23.8 ms 괄호를 메우면 파싱되지만 매번 처음부터 계산

결론은 두 가지입니다. 첫째, JSON.parse의 실패는 어떤 정보도 실어 오지 않습니다. 보고되는 위치는 언제나 끝이며, 얼마나 남았는지도, 도착한 부분이 스스로 모순 없는지도 알 수 없습니다. 둘째, 접두사마다 전체 복구를 다시 도는 방식은 가능하지만 손해입니다. 호출당 평균 텍스트 길이가 선형으로 늘어 누적 비용이 O(n²)로 자랍니다. 23.8ms는 무해해 보이지만, MB급에서는 같은 배수가 초 단위 낭비로 바뀝니다.

또 하나 주의할 점: 접두사 단위로 "파싱 가능"하다는 것이 "데이터가 완전"하다는 뜻이 아닙니다. 메워진 접두사의 마지막 숫자는 다음 청크에서 이어져 쓰일 수 있고, 마지막 문자열은 이스케이프 시퀀스 한가운데서 잘렸을 수 있습니다. 이것이 스트리밍 미리보기의 모든 안정성 문제의 뿌리입니다.

세 가지 구현 방식의 분업

스트리밍 진영의 라이브러리는 세 가지 자세로 나뉘며, 자세를 잘못 고르는 것이 라이브러리를 잘못 고르는 것보다 더 아픕니다.

라이브러리 자세 적합 부적합
jsonrepair (3.15.0) 전체 복구 + Transform 스트림 입력은 장래에 완성될 문서이고 무손실 출력이 필요 미리보기만 원할 때(복구 출력은 텍스트이지 데이터 객체가 아님)
partial-json (0.1.7) 부분 파싱, 미완성 꼬리를 버릴 수 있음 UI 미리보기: 모든 접두사에서 쓸 만한 객체가 필요 영속화(미리보기는 필드 누락과 숫자 흔들림을 포함할 수 있음)
jsonmend (0.1.3) 진짜 증분 복구, 공개 일관성 말뭉치 한 번 먹이면 한 판을 내놓고 앞부분을 다시 훑지 않는 파이프라인 끝난 문서(단순 전체 파싱이 더 빠름)

셋은 경쟁 관계가 아닙니다. jsonrepair의 ./stream 서브경로는 jsonrepairTransform이라는 표준 Transform 스트림을 내보냅니다. 왼쪽에서 청크를 붓으면 오른쪽에서 고쳐진 JSON 텍스트가 나오며, 연결 결과가 전체 문서를 한 번에 파싱한 것과 엄밀히 같음이 보장됩니다. decode(encode(x)) === x라는 약속을 지키는 쪽입니다. partial-json은 다른 약속을 지킵니다. 모든 접두사에서 즉시 객체를 돌려주되 "결과가 최종적으로 변하지 않는다"는 보장을 포기합니다. jsonmend는 공개 일관성 말뭉치로 세 번째 길을 묶습니다. 진짜 증분, 의미론 정합, 그리고 양쪽 구현이 같은 회귀 기반을 공유하는 것입니다.

Allow 마스크: 미리보기에 어떤 필드를 보여 줄 것인가

partial-json의 핵심은 "얼마나 망가진 입력을 파싱할 수 있는가"가 아니라 호출자가 어느 정도의 불완전을 감수할지 선언하는 것입니다. 마스크는 JSON 타입별 비트(STR, NUM, ARR, OBJ…)를 조합하고, 어떤 타입의 비트를 빼면 그 타입의 미완성 값은 미리보기에 들어가지 않습니다.

import { parse, Allow } from 'partial-json';

parse('{"price": 12', Allow.ALL);
// → { price: 12 }        12는 "지금까지 읽은 값"
parse('{"price": 1234.5', Allow.ALL);
// → { price: 1234.5 }    같은 필드가 변했다: 미리보기가 흔들린다
parse('{"price": 12', Allow.ALL & ~Allow.NUM);
// → {}                   NUM 비트를 빼면 미완성 숫자는 숨겨진다

실측에서 가장 공학적 가치가 큰 발견이 이것입니다. 뒤이어 이어 쓰이는 가격·카운터 같은 숫자는 화면에 나타나는 매 프레임마다 변할 수 있지만, Allow.ALL & ~Allow.NUM은 완성될 때까지 조용히 기다리게 만듭니다. 문자열도 마찬가지로, 유니코드 이스케이프 한가운데서 잘린 문자열은 partial-json 0.1.7에서 억지로 맞추는 대신 안전하게 버려집니다. 미리보기의 안정성은 파서가 주는 선물이 아니라 호출자가 마스크로 지불하는 대가입니다.

스트리밍 복구의 구현 비용: 룩백 버퍼와 제곱급 복사

스트리밍 파이프라인은 전체 API에 for 루프를 뒤집어씌운 것이 아닙니다. 같은 66청크 샘플에서 jsonrepairTransform 파이프라인 총 시간은 6.7ms, 접두사마다 전체 재실행의 누적은 23.8ms였습니다. 3.5배 격차는 구현 계층에 있습니다. 스트리밍 구현은 필요한 창 안에서만 뒤를 들여다보고, 출력은 증분 버퍼로 덧붙여 앞 텍스트를 다시 복사하지 않습니다.

jsonrepair 스트리밍 코어를 하모니 ArkTS로 이식한 실전기는 세 가지 구체적 비용을 밝힙니다. 상류 streaming 경로는 "룩백 버퍼"를 쌓기 때문에 작은 문서일수록 flush를 기다리는 역설이 생기고, 저자는 짧은 텍스트를 받으면서 미리보는 IncrementalRepairer를 별도로 작성했습니다. 상류 regular 경로는 출력 전체를 반복 복사하는 제곱급 동작이 있어 이식 시 OutputBuilder로 없앴습니다. 또 하나의 경계 문자 함정도 있습니다. text[i] === undefined로 끝을 판정하던 코드를 charAt으로 바꾸면 ''.includes('')가 늘 true라서 문자 멤버 판정을 속이므로, 범위 밖 읽기는 먼저 빈 문자열로 막아야 합니다. 스트리밍 복구가 분류표에서 독립 자리를 받는 이유는 공학 복잡도가 일회성 복구와는 자릿수가 다르기 때문입니다.

알려진 경계도 기록해 둡니다. jsonrepair 이슈 #214는 슬래시 접두 값 앞의 쉼표가 빠진 합법적 접두사를 스트리밍 복구가 거부하는 사례를 보고합니다. 스트림 상태에서는 "다음 문자가 아직 안 왔다"와 "입력이 불법"을 어휘적으로 구별하기 어렵고, 룩백 창이 바로 그 모호함에 지불하는 대가입니다.

적용 방법: 미리보기와 영속화는 각자의 길로

앞의 의미론을 한 파이프라인으로 합치면 원칙은 한 문장입니다. 미리보기는 부분 파싱, 영속화는 엄격한 파싱.

import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';

// 경로 1: 무손실 파이프라인. 청크가 들어오고 고쳐진 JSON이 나가며 마지막에 엄격 검증
const tr = jsonrepairTransform();
tr.pipe(finalSink);                 // finalSink에서 JSON.parse + 비즈니스 검증
chunkStream.pipe(tr);

// 경로 2: 미리보기 파이프라인. 접두사마다 UI 프레임, 미완성 숫자와 문자열은 마스크로 차단
function onChunk(buffer) {
  const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
  render(preview);                  // 안정적인 필드만 그린다
}

두 경로의 계약이 다르고 서로 대체할 수 없습니다. 미리보기 프레임은 필드 누락을 허용하지만 영속화 프레임은 허용하지 않습니다. 영속화는 스트림 종료를 기다렸다가 완전한 텍스트에 JSON.parse와 비즈니스 검증을 통과시켜야 하며, 미리보기 프레임은 결코 영속화되지 않습니다. 상류가 LLM 출력이라면 영속화 전에 중지 사유로 잘림 여부를 판정해야 합니다. "먼저 stop_reason을 보고 복구를 논한다"는 절차는 LLM JSON 잘림 복구에서 이미 다뤘습니다.

언제 스트리밍을 하지 말아야 하는가

거부 조건 세 가지, 하나라도 해당하면 얌전히 전체 파싱을 합니다. 파일이 작다. 22MB 이하라면 평범한 JSON.parse가 보통 1초 안에 끝나고 스트리밍은 코드 복잡도만 더합니다. 일회성 통계. 집계라면 jq의 --stream이나 행 단위 NDJSON이 더 간단합니다. JSONL 파일 핸드북을 보세요. 하류가 부분 데이터를 받아들이지 않는다. 합계 계산이 대표 사례로, 미리보기 프레임의 중간값을 한 번만 잘못 곱해도 금전 손실입니다. 이런 경우 스트리밍 미리보기의 가치는 진행 표시줄까지 줄어듭니다.

스트리밍이 해결하는 문제는 언제나 "기다릴 수 없음"이지 "더 빠르게"가 아닙니다. 같은 텍스트량이라면 전체 파싱의 총 CPU 시간은 어떤 스트리밍 방식보다도 적게 듭니다. 얻어지는 것은 첫 사용 가능 청크까지의 시간, 문서 길이에 따라 자라지 않는 메모리 수위, 그리고 받으면서 처리하는 능력입니다. 이 트레이드오프를 분명히 하면 라이브러리 선택이 흔들리지 않습니다.

자주 묻는 질문

미리보기 객체를 그대로 DB에 저장할 수 있나요?

안 됩니다. 미리보기는 "지금까지 알려진" 스냅숏입니다. 숫자는 다음 청크에서 이어 쓰일 수 있고, 문자열은 잘렸을 수 있고, 필드는 일시적으로 빠져 있을 수 있습니다. 저장 전에는 스트림 종료를 기다렸다가 완전한 텍스트에 엄격한 JSON.parse와 비즈니스 검증을 통과시키세요. 미리보기는 UI 계층 전용입니다.

partial-json과 jsonrepair 중 무엇을 고를까요?

텍스트가 필요한지 객체가 필요한지에 따라 갈립니다. 하류가 다시 파싱할 무손실 복구 텍스트라면 jsonrepair을 고르세요. 스트리밍 출력이 전체 파싱 결과와 같음이 보장됩니다. 모든 접두사에서 즉시 객체가 필요한 UI 미리보기라면 partial-json을 고르고 Allow 마스크로 필드별 불안정 허용도를 설정합니다.

스트리밍 파싱이 총 소요 시간을 줄여 주나요?

줄여 주지 않습니다. 총 CPU 시간 기준으로 전체 파싱이 언제나 가장 빠르고, 스트리밍은 상태 유지 오버헤드까지 추가로 지불합니다. 얻는 것은 세 가지입니다. 첫 사용 가능 청크까지의 시간, 문서 길이에 비례하지 않는 메모리 수위, 받으면서 전달·필터·표시하는 능력입니다.

배열 요소가 하나씩 도착할 때 하나씩 처리하고 싶다면?

그것은 다른 경로입니다. stream-json의 streamArray는 요소가 닫힐 때마다 {key, value}를 내보내고 for await와 결합하면 자연스러운 배압이 됩니다. 파싱 후 DB 일괄 입력에 적합한 입자이며, 본문의 문서 수준 미리보기와는 다른 격입니다.

참고 자료

관련 도구

관련 문서

JSON 복구 가이드:깨진 LLM 출력 구출과 신뢰 경계

markdown 펜스로 감싸이고 후행 쉼표와 Python 리터럴이 섞인 LLM 출력은 엄격한 파서가 전부 거부합니다. 복구기가 실제로 고칠 수 있는 9가지 오류와 고칠 수 없는 4가지 경계를 정리하고, 상태 머신과 정규식 두 구현 진영의 차이를 설명합니다. jsonrepair와 json-repair 이중 스택 연결 순서와 복구 결과를 스키마 검증으로 담보하는 방법까지 다룹니다.

중급약 6분 소요2026-11-08 업데이트

LLM이 뱉은 JSON이 중간에 잘렸을 때: 먼저 중지 이유를 보고, 그다음 복구를 이야기하자

모델이 돌려준 JSON이 중간에 끝나고 파서는 열 번호 하나만 알려 준다. 괄호를 닫으면 다시 파싱은 되지만 빠진 필드는 데이터 안에 숨어 버린다. 이 글은 stop_reason 판정, 출력 토큰 상한 산정, 스키마 필드 순서, 부분 복구의 정직한 공개까지 정리해 잘림 상황에서 고쳐도 되는 범위와 반드시 재시도해야 하는 범위를 나눈다.

실전약 5분 소요2026-11-14 업데이트

JSONL 파일 실전 가이드: 열기, 변환, 깨진 줄 찾기

.jsonl 파일 전체를 JSON.parse에 넣고 에러가 난다면 파일이 깨진 게 아니라 읽는 방식이 틀렸을 가능성이 높습니다. 이 글은 확인과 한 줄씩 읽기의 표준 패턴, JSON 배열과의 상호 변환 명령, 여섯 가지 깨진 줄의 진단 표, 스트리밍 API에서 NDJSON을 소비하는 올바른 방법을 다룹니다.

중급약 9분 소요2026-11-06 업데이트