jsonchunk: LLM 스트리밍 출력을 위한 타입 안전한 초경량 부분 JSON 파서

이 요약은 AI가 원문을 분석해 생성했습니다. 정확한 내용은 원문 기준으로 확인하세요.

핵심 요약

LLM은 데이터를 토큰 단위로 스트리밍하지만, 표준 JSON.parse는 데이터가 완전히 도착하기 전까지는 오류를 발생시켜 실시간 UI 업데이트를 어렵게 만든다. jsonchunk는 이러한 문제를 해결하기 위해 불완전한 문자열에서도 최선의 정보를 추출하는 관대한 파싱 로직을 제공한다. 이 라이브러리는 의존성 없이 5KB 미만의 크기로 설계되었으며, TypeScript의 DeepPartial을 통해 타입 안전성을 확보했다. 개발자는 이를 통해 RAG 시스템이나 챗봇에서 구조화된 데이터를 수신할 때 사용자에게 즉각적인 시각적 피드백을 제공할 수 있다.

배경

JavaScript/TypeScript 기초 지식, LLM 스트리밍 응답(ReadableStream)에 대한 이해, JSON 구조 및 파싱 개념

대상 독자

LLM의 구조화된 출력을 실시간으로 웹 UI에 렌더링하고자 하는 프론트엔드 및 풀스택 개발자

의미 / 영향

LLM 애플리케이션에서 '스트리밍'은 필수적인 요소가 되었으나 JSON 같은 구조화된 데이터는 스트리밍 처리가 까다로웠다. jsonchunk 같은 도구의 등장은 개발자들이 복잡한 파싱 로직을 직접 구현할 필요 없이 더 나은 UX를 제공할 수 있게 하며, 이는 LLM 기반 에이전트나 대시보드 도구의 응답성 표준을 높이는 결과로 이어질 것이다.

섹션별 상세

LLM 스트리밍 환경에서 발생하는 불완전한 JSON 구조 문제를 해결한다. 기존 JSON.parse는 중괄호가 닫히지 않거나 키-값 쌍이 완성되지 않으면 예외를 던지지만, jsonchunk는 현재까지 도착한 데이터만으로 유효한 객체를 구성하여 반환한다.

다양한 데이터 유형의 부분적 상태를 지능적으로 처리한다. 따옴표가 닫히지 않은 문자열, 값이 없는 키, 완성되지 않은 배열, 소수점이나 지수 표기법 도중의 숫자 등을 감지하여 안전하게 처리하며, true/false/null 같은 키워드도 첫 글자만으로 미리 예측하여 파싱 결과에 반영한다.

javascript

import { parseStream } from 'jsonchunk';

type User = { name: string; age: number; hobbies: string[] };
const response = await fetch('/api/user', { /* streaming */ });
const stream = response.body!.pipeThrough(new TextDecoderStream());

for await (const partial of parseStream(stream)) {
  console.log(partial.name); // 토큰이 도착함에 따라 실시간 업데이트
  console.log(partial.hobbies); // 배열 내용이 점진적으로 추가됨
}

ReadableStream을 통해 들어오는 LLM 응답을 실시간으로 파싱하여 부분 객체를 반환하는 예시

javascript

import { createParser } from 'jsonchunk';

const parser = createParser();
parser.push('{"name": "Ali');
console.log(parser.value); // { name: "Ali" }

parser.push('ce", "age": 30}');
console.log(parser.value); // { name: "Alice", age: 30 }

상태를 유지하는 파서를 생성하여 수동으로 데이터 조각을 추가하고 현재까지의 파싱 결과를 확인하는 방식

네 가지 주요 API를 통해 유연한 통합을 지원한다. 단순 문자열 파싱을 위한 parse, 상태를 유지하며 조각을 추가하는 createParser, ReadableStream과 연동되는 parseStream, 그리고 TransformStream 어댑터인 createStream을 제공하여 다양한 런타임 환경에 대응한다.

성능과 경량화를 최우선으로 설계되었다. 외부 의존성이 전혀 없는 Zero-dependency 라이브러리이며 번들 크기는 약 5KB에 불과하다. 매번 전체 문자열을 다시 파싱하는 단순한 구조를 채택했음에도 LLM 페이로드 수준의 데이터 크기에서는 충분히 빠른 성능을 보장한다.

TypeScript 사용자들을 위해 DeepPartial 타입을 제공한다. 파싱 결과물의 모든 필드가 재귀적으로 선택적(optional)임을 명시하여, 개발자가 런타임에 존재하지 않을 수 있는 데이터에 안전하게 접근하도록 강제하고 런타임 에러를 방지한다.

실무 Takeaway

LLM 응답 속도가 느린 환경에서 jsonchunk를 사용하면 전체 JSON이 완성되기 전에도 UI에 부분적인 정보를 노출하여 체감 대기 시간을 줄일 수 있다.
복잡한 정규식이나 임시 복구 로직 없이도 parseStream API 한 줄로 스트리밍되는 구조화된 데이터를 안정적으로 처리 가능하다.
5KB 미만의 초경량 라이브러리이므로 프론트엔드 번들 크기에 부담을 주지 않으면서 LLM 애플리케이션의 사용자 경험을 개선할 수 있다.

언급된 리소스

GitHubjsonchunk GitHub Repository