JSONを受け取り中でも解析できる:ストリーミング・プレビューとインクリメンタル修復
要点:LLMはトークンごとにJSONを出し、APIは大規模レスポンスをチャンクで返しますが、JSON.parseは全文が揃うまで動きません。本稿では全量修復・真の増分・部分解析という三つの実装形態の分担を整理し、Allowマスクによるプレビュー安定化と、平方級の再実行を置き換えるストリーミングパイプラインの実測値と実装コードを示します。

JSON.parseの契約は「全文が揃ってから動く」、ストリーミングの契約は「1チャンク届くたびに処理する」——この矛盾の本質は速度ではなく完全性の意味論にあります。書き終わっていない文書に「正しい解析結果」は存在しません。
症状:全文を待てない三つのシナリオ
一つ目は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 の失敗は情報を何も運びません。報告される位置は常に末尾であり、あとどれだけ足りないのか、届いた部分が自己無矛盾かどうかも分かりません。第二に、プレフィックスごとの全量再実行は可能だが割に合わない。1回あたりの平均テキスト長は線形に増え、累積コストはO(n²)で伸びます。23.8msは無害に見えますが、1MB規模では同じ倍率が秒単位の無駄に変わります。
さらに重要な注意点として、プレフィックス単位で「解析できる」ことは「データが完全」であることを意味しません。補完されたプレフィックスの最後の数字は次チャンクで書き足されるかもしれず、最後の文字列はエスケープシーケンスの途中で切れているかもしれません——これがプレビュー安定性の問題の根源です。
三つの実装形態の分担
ストリーミング側のライブラリは三つの姿勢に分かれ、姿勢を誤るほうがライブラリを誤るより傷が深い。
| ライブラリ | 姿勢 | 向いている | 向いていない |
|---|---|---|---|
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 ビットを落とすと未完成の数値は非表示
実測の中で最も工学的価値が高いのがこれです。続きを書き足される価格やカウンタは、UIに現れる毎フレームで変わりえますが、Allow.ALL & ~Allow.NUM は完成するまで静かに待たせられます。文字列も同様で、Unicodeエスケープの途中で切れた文字列は partial-json 0.1.7 では推測ではなく安全に捨てられます。プレビューの安定性はパーサーの恵みではなく、呼び出し側がマスクで支払うものです。
ストリーミング修復の実装コスト:ルックバックバッファと平方コピー
ストリーミングパイプラインは全量APIにforループを被せたものではありません。同じ66チャンクのサンプルで、jsonrepairTransform パイプラインの総時間は6.7ms、プレフィックスごとの全量再実行は23.8ms——この3.5倍の差は実装層にあります。ストリーミング実装は必要な窓内でのみ後方参照し、出力は増分バッファで追記して前文を再コピーしません。
jsonrepairのストリーミング核心をHarmonyOS ArkTSへ移植した実践は、三つの具体的コストを明かします。上流のstreaming経路は「ルックバックバッファ」を溜めるため、小さい文書ほどflush待ちになる逆説があり、著者は短文を取り込みながらプレビューする IncrementalRepairer を別途書きました。上流のregular経路は出力全体を繰り返しコピーする平方級動作があり、移植時は OutputBuilder で解消しました。さらに境界文字の罠——text[i] === undefined による終端判定を charAt に替えると ''.includes('') が常にtrueになり文字メンバ判定を欺くため、範囲外読み出しはまず空文字列でブロックする必要があります。ストリーミング修復が一分類を与えられるのは、その工程複雑度が一回きりの修復とは桁違いだからです。
既知の境界も記します。jsonrepairのissue #214は、スラッシュ前置値の前のカンマ欠落という合法プレフィックスをストリーミング修復が拒否する例を報告しています。ストリーム状態では「次の文字が未到達」と「入力が不正」を語彙的に区別しにくく、ルックバック窓はこの曖昧さに払う代償です。
落地方法:プレビューと永続化は別経路で
前節の意味論を一本のパイプラインにまとめると、原則は一句だけです。プレビューは部分解析、永続化は厳密解析。
import { jsonrepairTransform } from 'jsonrepair/stream';
import { parse as partialParse, Allow } from 'partial-json';
// 経路一:無損パイプライン。チャンクが入り、修復済みJSONが出て、最後に厳密検証
const tr = jsonrepairTransform();
tr.pipe(finalSink); // finalSink で JSON.parse + 業務検証
chunkStream.pipe(tr);
// 経路二:プレビュー経路。プレフィックスごとにUIフレーム、未完成数値と文字列はマスク
function onChunk(buffer) {
const preview = partialParse(buffer, Allow.ALL & ~Allow.NUM & ~Allow.STR);
render(preview); // 安定したフィールドだけ描画する
}
二つの経路の契約は異なり、互いに代替できません。プレビューフレームはフィールド欠落を許し、永続化フレームは許しません。永続化はストリーム終了を待ち、完全テキストへの JSON.parse と業務検証を通す必要があり、プレビューフレームは決して永続化しません。上流がLLM出力なら、永続化前に停止理由で切断判定も要ります——「まず stop_reason を見てから修復を語る」流れはLLMの切断修復で展開済みです。
いつストリーミングをやめるか
三つの否決条件、一つでも当てはまれば素直に全量解析です。ファイルが小さい——22MB以下なら通常の JSON.parse は一秒以内に終わり、ストリーミングはコード複雑度を増すだけです。一回きりの集計——集約なら 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一括投入に適した粒度で、本稿の文書レベル・プレビューとは別物です。