JSON Toolkit

JSONを受け取り中でも解析できる:ストリーミング・プレビューとインクリメンタル修復

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

中級約 5 分で読めます2026-11-16 公開2026-11-16 更新
ストリーミングJSONのチャンクに対する部分解析と増分修復のパイプライン図

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一括投入に適した粒度で、本稿の文書レベル・プレビューとは別物です。

参考資料

対応ツール

関連記事

JSON修復ガイド:壊れたLLM出力の救出と信頼の境界線

markdownコードフェンスで囲まれ、末尾カンマやPythonリテラルを含むLLM出力は、厳密なパーサーには一切受け付けられません。修復ツールが実際に直せる9種類のエラーと直せない4種類の境界を整理し、状態機械と正規表現という2つの実装方式の違いを解説。jsonrepairとjson-repairの二重スタック接続手順と、修復結果をスキーマ検証で裏付ける方法までを扱います。

中級約 6 分で読めます2026-11-08 更新

LLM の JSON 出力が途中で切れたら:まず停止理由を見て、それから修復を語る

モデルが返す JSON が途中で終わり、パーサーは列番号しか教えてくれない。括弧を閉じれば再びパースは通るが、欠けたフィールドはデータの中に隠れてしまう。本記事は停止理由による判定、出力トークン枠の見積もり、スキーマのフィールド順、部分復元の正直な開示までを整理し、途中切断で修復してよい範囲と再試行すべき範囲を切り分ける。

実践約 5 分で読めます2026-11-14 更新

JSONL ファイル実践:開き方・変換・壊れた行の調査

.jsonl 全体を JSON.parse に渡してエラーが出るのは、ファイルが壊れているからではなく、読み方が違うからです。この記事では、確認と行単位読み取りの標準パターン、JSON 配列との相互変換コマンド、6 種類の壊れた行の対処表、ストリーミング API で NDJSON を消費する正しい書き方を解説します。

中級約 9 分で読めます2026-11-06 更新