JSONをテキストに変換する:構文を捨てて、読みやすい中身だけを残す
JSONのエクスポートをテキストエディタで開いて、中身の内訳を数えてみてください。波かっこ、角かっこ、 すべてのキーと文字列値を囲む二重引用符、ペアごとのカンマ、あいだのコロン、そして整形済みのファイルなら 数千個分の行頭スペース。レコードが並ぶ典型的なエクスポートでは、バイト数のかなりの割合が、 知りたい情報を何も持たない構造用の文字です。
このページがやることは1つだけです。.jsonファイルを受け取り、そうした記号をすべて取り除いた
人が読める中身を返します。見出しも表もパイプもなく、意味が通る程度のラベルをつけた値が順番に並ぶだけです。
渡す先が埋め込みモデル、検索インデックス、テキスト分析のスクリプト、そのほか記号がノイズにしかならない
パイプラインなら、これが正解の出力です。無料、登録不要、1ファイル50MBまで、何も保存しません。
JSONをテキストに変換すると、消えるものと残るもの
規則は頭に入れておける程度に単純です。自分のパイプラインに合う出力かどうかを判断するとき、この単純さが 効いてきます。
- 消えるもの:すべての
{、}、[、]、 引用符、カンマ、コロン。それにインデント——整形済みファイルでは、これが全体サイズの意外な割合を 占めています。 - 残るもの:文字列値、数値、真偽値。つまり中身そのものです。
- 残るが平坦になるもの:キー名。まるごと削るのではなく短いラベルとして残します。
文の前に
refund_reasonと書いてあることは、読み手にとっても埋め込みモデルにとっても 実際に情報だからです。消えるのは入れ子のパスであって、名前ではありません。 - まとめて畳まれるもの:
null、空文字列、空配列。生のJSONではそれを持つ レコードごとに何度も現れますが、テキスト出力では場所を取らなくなります。 - 1次元化されるもの:入れ子の深さ。6階層下の値とトップレベルの値が、隣り合う行として 並びます。これが取引です——きれいな散文と引き換えに、木構造を失います。
構文が埋め込みの精度を下げる理由
ここは、変換が「見た目が整う」だけでなく結果そのものを変える場面です。テキストのチャンクを埋め込むとき、 モデルはそこにあるすべてを符号化します。生のJSONレコードを渡せば、ベクトルのうち無視できない部分が 「JSONを見た」という事実——波かっこ、引用符つきのキー、データ構造の全体的な形——を記述することに 使われます。まったく別の話題を扱う2件のレコードが、スキーマを共有しているというだけでベクトル空間で 近くに来ることさえあります。
構文を落とせば、埋め込みは中身についてのものになります。サポートのチケットは顧客が実際に書いた言葉と いくつかのラベルになり、それに対するセマンティック検索は期待どおりに振る舞います。効果が最も大きいのは 短いレコードで、構文と中身の比率が最悪だからです。値が2語しかない5フィールドのオブジェクトは、 ほとんどが記号です。
チャンク分割にも同じ理屈があてはまります。生のJSONは固定長のチャンカーと相性が悪く、分割点が オブジェクトの途中に落ちて、かっこだけの孤児のような断片ができます。平坦なテキストなら、チャンカーが 前提にしているとおり、文や行の境界で分割されます。
検索インデックスとテキスト分析
全文検索エンジンは単語境界でトークン化し、記号は結局捨てます——ただし常にきれいに捨てられるわけではなく、 単語統計を歪めた後で捨てられることもあります。あらかじめ構文を取り除いたテキストを入れておけば、 出現頻度は予想どおりになり、アナライザーに無駄な仕事をさせずに済みます。
統計的な処理になると、この主張はもっと強くなります。単語頻度の集計、商品レビューのエクスポートに対する 感情スコアリング、サポートチケットのダンプに対するトピックモデリング、スクレイピングしたデータセットからの 固有表現抽出——どれも構造用のトークンと、数えたくないフィールドに汚染されます。JSONを 読みやすいテキストに変換しておけば、手元に残るのはデータ構造ではなくコーパスです。
可能なら分析の前に消しておきたいもの:ISO形式のタイムスタンプ、UUID、数値のID。どれも意味のない断片に トークン化され、しかもすべてのレコードに現れます。頻度表を歪めるものの条件を、そのまま満たしています。
トークン予算の観点から
大きなエクスポートをモデルに押し込むなら、同じ内容を表す最も安い形が平坦なテキストです。節約の理由は2つ。 1つは構造用の文字が消えること。もう1つは——レコードの多いファイルではこちらが効きます——オブジェクトごとに キーが繰り返される分を払わなくて済むことです。8つのフィールド名を毎回書き直す1000件のレコードは、 生のファイルの中で8000個の冗長なラベルを運んでいます。
トークンカウンターは出力の下にあるので、どこかに貼る前に変換して確認できます。最小化されたAPIの ダンプやNDJSONのログファイルでは、差がかなり大きくなりがちです。とはいえ、上限に近い理由が単純に ファイルが巨大だからという場合、どんな変換も救ってくれません。必要なレコードを先に絞ってから変換して ください。
平坦なテキストが正解ではない場面
変換がいつでも勝つふりをするより、正直に書くほうが役に立ちます。モデルは生のJSONを流暢に読みます。 学習中に最も多く見た形式の1つだからです。取り除くべきでない状況が3つあります。
- データに対するコードを書かせるとき。型定義、パーサー、マッピング関数、 バリデーションスキーマ——どれも正確なキー名、正確な入れ子、正確な型を必要とします。生のペイロード、 または間引いたサンプルをそのまま貼ってください。平坦化は、モデルが必要としているまさにその情報を 捨てます。
- 入れ子が意味を持つとき。どの親の下にある値なのかが本題なら——ロールごとの権限、 環境ごとの設定、カテゴリの木——平坦化は答えそのものを壊します。かわりに JSONをMarkdownに 変換してください。階層は見出しとして保たれ、形の揃ったレコードの配列は目で追える表になります。
- 人が読むとき。平坦なテキストは機械向けの最適化です。人がレビューするなら、 Markdownの圧勝です。
ページ上部の形式切り替えは両者を行き来し、選択済みのファイルもそのまま残るので、比較にかかるのは クリック1回で、2度目のアップロードではありません。
扱いにくいファイルと、その挙動
- Unicodeエスケープ。古いライブラリが書き出したファイルは、非ASCII文字を文字のまま
ではなく
日本語のような形で持っています。これらは実際の文字に復号されます。 日本語のデータを扱う人にとっては、そのまま検索できるかどうかを分ける違いです。 - Base64の塊。JSONのフィールドに紛れ込んだ画像、PDF、添付ファイルは巨大なうえ、 読めるテキストを一切含みません。アップロード前に取り除かないと、ファイルサイズもトークン数も そればかりになります。
- JSONの中のエスケープされたJSON。Webhookのペイロードやログ行でよく見ます。 文字列フィールドの中身が、それ自体シリアライズされたオブジェクトになっているものです。長い エスケープ済み文字列として1つ出てくるので、そこが本題ならまず外側をほどいてください。
- 壊れたファイル。末尾のカンマ、シングルクォート、Python由来の
NoneやNaN。これらはパースの時点で失敗します。出どころがはっきりしないファイルは先に チェックしてください。 - JSON Lines。NDJSONのエクスポートはここと相性が良く、形の揃ったレコードが1行に1件、
もともと欲しい形に近い状態です。アップロード前に
.jsonにリネームするか、行を配列で 包んでください。
よくある質問
JSONファイルをテキストに変換するには?
上の変換ツールに.jsonをドロップすれば、波かっこ、角かっこ、引用符、カンマ、コロンを取り除いた読めるテキストとして値が返ってきます。.txtとしてダウンロードできます。無料、登録不要、1ファイル50MBまで、変換後は何も残しません。
JSONのまま使わず、わざわざテキストに変換する理由は?
構造ではなく意味を読む相手にとって、構文用の文字は完全な死荷重だからです。埋め込みモデル、分類器、全文インデックスは引用符もカンマも一つずつトークン化し、情報を足さないままベクトルを薄め、コストを押し上げます。受け手がJSONをパースするならJSONのままで結構です。これは、そうではないパイプラインのための機能です。
入れ子のオブジェクトや配列は平坦になりますか?
なります。入れ子は構造そのものであり、この変換が落とすのは構造です。深く入れ子になったレコードは、ラベル付きの値が文書順に並ぶ平坦な列として出てきます。値の解釈ができるようキー名はラベルとして残りますが、親子関係は表現されません。深い入れ子の設定ファイルが、いちばん痛い相手です。
JSON LinesやNDJSONは扱えますか?
ファイル全体が妥当なJSONである場合だけです。NDJSONは1行に1オブジェクトで、包む配列がなく、そもそも単一のJSON文書ではないと決められているため、そのままではパースできません。行を[ ]で包んでカンマで区切ってください——jqかsedの1行で済みます——それで普通に変換できます。
非常に大きなエクスポートの場合は?
上限は1ファイル50MBで、JSONとしてはかなりの量です。整形済みのエクスポートは大半が空白と構造なので、中に入っている読めるテキストはファイルサイズのごく一部です。超えてしまう場合は、適当に分割して包む配列を壊すのではなく、jqで必要なレコードを絞ってから変換してください。
関連する変換ツール
そのJSONが実は表の変装なら、CSVに書き出してから CSVをテキストにを使うほうが きれいな結果になります。同じ問題を別の形で抱えるもう1つの構造化形式には XMLをテキストにがあり、 保存したページならHTMLをテキストに です。ページを選ぶのが面倒なら、 File2Txtが対応形式を まとめて引き受けます。
そのファイルがプロジェクトの中の1つにすぎないなら、単体で変換するのはたぶん作業の単位を間違えています。 ローカルディレクトリ変換と GitHubリポジトリをテキストに変換するツールなら、 JSONとそれを読むコードを一度に選べます。公開中のページなら Web2TxtがURLから直接取得しますし、 LLM向けに文書を整える方法のガイド では一般的な話をまとめています。
Repo2Txtを開発・運営しているのは v12hero、 プライバシー最優先のネイティブアプリとWebアプリを作る独立系デベロッパーです。