JSON 工具箱

JSON 修復指南:LLM 壞輸出的救回與信任邊界

結論:LLM 輸出被 markdown 圍欄包裹、帶著尾逗號和 Python 字面量,手改過的設定少了引號,這些 JSON 嚴格解析器一概拒收。本文按修復器真實能力劃清九類可修與四類不能修的邊界,講狀態機與正則兩派實現的差別,給出 jsonrepair 與 json-repair 雙棧接入順序,以及修復結果如何用校驗器兜底。

實戰約 6 分鐘發佈於 2026-11-08更新於 2026-11-08
JSON 修復流程圖:圍欄剝離、引號規範化、括號配平到最終校驗

嚴格解析器對壞輸入是零寬容的:只給你一條報錯和一個行號,一個位元組的資料都不給。修復器存在的意義,就是把「完全失敗」變成「先跑起來再說」——但它補出來的東西永遠只是對意圖的最佳猜測。

一、壞 JSON 從哪來:三個來源,問題高度集中

修復不是全能的,先看輸入是什麼。工程裡非標準 JSON 的來源集中在三處:

  1. LLM 輸出。模型逐 token 生成文字,並不執行 JSON 序列化器。即使要求「只輸出 JSON」,它也會包一層 ```json 圍欄、加一句「好的,這是你要的資料」、落下尾逗號,或者命中 token 上限停在物件中間。
  2. 從別的語言複製。console.log 印出來的 JavaScript 物件帶單引號和不帶引號的鍵;Python 字典印出來是 True/False/None;這些「長得像 JSON」的文字一餵給 JSON.parse 就炸。
  3. JSON5/JSONC 設定。tsconfig 這類檔案允許註釋和尾逗號,拷出來直接給嚴格解析器同樣拒收。

三類來源的修法不同,但修復器都能覆蓋——前提是錯誤落在它聲明的可修清單裡。

二、九類可修:修復器真正擅長什麼

綜合 jsonrepair 庫文件與各家工具頁的能力聲明,可自動修復的錯誤可以歸納為九類:

類別 壞輸入示例 修復結果
尾逗號 [1, 2, 3,] [1, 2, 3]
單引號 / 彎引號 {'a': 'b'}、{"a": “b”} {"a": "b"}
未加引號的鍵 {name: 'Ada'} {"name": "Ada"}
註釋 {"a": 1 /* 說明 */} {"a": 1}
Python 字面量 {"ok": True, "v": None} {"ok": true, "v": null}
markdown 圍欄 ```json {...} ``` {...}
缺失逗號 [1 2] [1, 2]
括號 / 引號未閉合 {"a": [1, 2 {"a": [1, 2]}
JSONP / 字串拼接 cb({...})、"x" + "y" {...}、"xy"

這九類的共同點是:資料都在,只是語法不對。修復器只需要調整標點和包裝,不改任何值。有幾條細節值得單獨記住:

  • 前導零數字會被轉成字串:007 修復成 "007" 而不是 7,為的是不丟數字位。如果你的欄位本來就是文字編號,這是正確行為;如果它真是數字,得自己決定。
  • 裸詞會被變成字串:NaN 修不成數字,有的實作直接變 "NaN",有的變 null。不同庫行為不同,接進管線前先試一遍。
  • 輸入已是合法 JSON 則原樣返回:修復器都內建嚴格解析快路徑,合法輸入不經過修復邏輯,不存在「越修越壞」。

三、四類不能修:信任邊界的另一側

修復器的能力邊界同樣明確,下面四類別指望它:

  1. HTML 錯誤頁或純散文。輸入裡根本沒有 JSON 結構,沒有任何工具能憑空造出資料。
  2. 語法合法但資料錯誤。鍵拼錯、值放錯位、數字存成字串——這些是語義問題,語法層面完全合法,任何修復器都會放行。
  3. 截斷丟掉的資料。截斷補全能把 {"items": [{"id": 1}, {"na 修成合法 JSON,但 name 欄位的值永遠不會回來。修出來的是「合法但不完整」的物件,生產環境必須先查 stopReason === "max_tokens" 再決定是補全還是重試。
  4. 重複鍵與歧義結構。兩個同名鍵哪個生效取決於解析器實現,負責任的修復器提供 strict 模式直接拋錯而不是靜默二選一。

一句話總結信任邊界:修復是「最佳猜測」,不是「正確保證」。修完不校驗就進下游,等於把語法風險換成了更隱蔽的資料風險。

四、實現兩派:狀態機與正則的差別,一個 URL 就能試出來

市面修復器有兩種實現流派,能力差距在特定輸入上會立刻顯形。

正則替換派對壞模式做全域查找替換。考慮這個輸入:

{"url": "http://example.com", 'note': 'fine'}

一條「把單引號換雙引號」的正則會把 URL 裡的內容一起處理;一條「刪掉所有 //」的註釋清理正則會把 http:// 腰斬。字串內部和結構外部的長相一模一樣,正則區分不了。

逐字元狀態機派維護一個解析狀態:當前在雙引號字串內、單引號字串內、行註釋內、塊註釋內,還是在等值。看到 ' 時先判斷自己在不在字串裡,再決定是轉引號還是跳過。http://example.com 位於雙引號字串內,狀態機知道裡面的 // 是資料不是註釋,原樣保留。jsonrepair、json-healer 這類庫都是這一派,社群教程裡反覆強調的「修復器不是查找替換」說的就是這件事。

修復管線的完整次序(以 devkits 披露的鏈路為例)也值得看一眼:剝圍欄 → 彎引號規範化 → 提取首個配平塊 → 去註釋 → 補鍵引號 → 去尾逗號 → 字面量轉換 → 最後用 JSON.stringify 重序列化。最後一步重序列化是關鍵:不管前面怎麼修,輸出都從解析結果重新生成,保證下游任何嚴格解析器都能吃。

五、程式碼裡怎麼接:一條順序化的解析鏈

在程式碼裡接修復,順序比選庫更重要。按 json2toon 與 aijsonmedic 給出的模式整理,順序應該是:截斷檢查 → 提取 JSON 區間 → 嚴格 parse → repair 兜底 → schema 校驗。

import { jsonrepair } from "jsonrepair";

export function parseModelJson(text, stopReason) {
  if (stopReason === "max_tokens") {
    // 截斷的輸出修復出來也是缺資料的,直接重試
    throw new Error("Truncated output: retry with a higher max_tokens");
  }
  // 提取 JSON 區間:LLM 可能在前後加寒暄
  const start = text.search(/[[{]/);
  const end = Math.max(text.lastIndexOf("}"), text.lastIndexOf("]"));
  const candidate = start >= 0 && end > start ? text.slice(start, end + 1) : text;
  try {
    return JSON.parse(candidate);   // 合法輸入走快路徑
  } catch {
    return JSON.parse(jsonrepair(candidate));  // 兜底修復
  }
}

Python 側對應 json-repair 套件,4700+ star,loads() 直接返回物件:

from json_repair import repair_json
import json

broken = "{name: 'Ada', tags: ['x',], active: True}"
data = json.loads(repair_json(broken))
# {'name': 'Ada', 'tags': ['x'], 'active': True}

兩個工程細節:

  • 雙棧對齊。前後端都要修時,選同源語義的實現(Python json-repair 與它的 TS 移植 @yarmu/json-repair,或雙端通過同一一致性語料的 jsonmend),否則同一段輸出在前端修成 A、在後端修成 B,問題會更難查。
  • 開啟修復日誌。@yarmu/json-repair 的 logging: true 返回每次修復操作的陣列。線上修復率突然升高,通常意味著提示詞或模型版本變了——這是比報錯更早的信號。

修復之後還有一步不能省:schema 校驗。語法修好不等於資料可用,缺欄位、型別錯、多出來的鍵都要靠 schema 抓。契約測試的思路完全適用於這裡,參見《JSON Schema 契約測試怎麼做》。

六、預防清單:能不修就不修

修復是兜底,源頭少產出壞 JSON 才是上策。按優先級排:

  1. Structured Outputs(json_schema 模式):解碼階段就按 schema 約束,尾部逗號根本生成不出來。OpenAI 的 strict 模式失敗率約 0.1%,代價是 additionalProperties: false 等硬性要求。
  2. JSON mode(json_object):只保證語法合法,不保證形狀,token 上限導致的截斷依然存在。
  3. 顯式指令:沒有 JSON mode 的端點,寫明「不要圍欄、不要註釋、不要尾逗號、只輸出物件」能降 70-80% 的錯誤率。
  4. 降低 temperature、加大 token 上限:前者減少跑偏成散文的機率,後者減少截斷。
  5. 帶報錯的重試:校驗失敗時,把壞輸出和「JSON path + 報錯」一起回傳給模型再要一次,模型通常能據此自糾。

實踐中「structured outputs + repair 兜底 + schema 校驗」三層疊著用,幾乎沒有修不住的場景。

七、線上工具怎麼分工:方言轉換不等於修復

本站工具箱在這條鏈路裡有兩個落點,各管一段:

  • **方言類問題(註釋、單引號、尾逗號)**直接用 JSON5 轉換:JSON5 與標準 JSON 互轉正好覆蓋這三類,轉換語義明確、不猜測。如果輸入整體就是一份 JSONC/JSON5 檔案,這比「修復」更可控。方言本身的取捨見《JSON5 與 JSONC 指南》。
  • 修完之後用 JSON 解析工具校驗並格式化,錯誤定位到行列,確認修復結果真的能被嚴格解析器接受。
  • **庫類問題(Python 字面量、截斷補全、JSONP 包裝、markdown 圍欄)**目前得靠程式碼側的 jsonrepair / json-repair,瀏覽器端沒有等價的一鍵修復——這兩類修復涉及「推斷意圖」,交給本地庫比塞進通用轉換工具更穩。

如果拿到手的是一段報錯而不是一段壞資料,先去《JSON 解析報錯怎麼修》把報錯翻譯成座標,再決定是手改還是修復。

常見問題

JSON 修復會把我的資料改壞嗎?

九類可修錯誤只動標點和包裝,不動值;字串內部的 //、逗號、花括號由狀態機識別,原樣保留。但截斷補全得到的物件缺資料,前導零數字會變成字串,NaN 的處理各庫不同——修復後檢查關鍵欄位是必要動作。

修復和校驗是什麼關係?

校驗只告訴你「哪裡不合法」,修復直接給出「一份合法的」。可靠的做法是兩個都做:先修復再校驗,schema 校驗抓型別與必填欄位,語法校驗確認解析器能吃。只修不校驗,等於把語法錯誤換成更隱蔽的資料錯誤。

LLM 輸出總是被 ```json 圍欄包著,怎麼辦?

短期用提取:取首個 { 或 [ 到最後一個 } 或 ] 之間的內容再解析;帶圍欄剝離的修復器也能直接吃整段輸出。長期靠 structured outputs 或顯式指令「不要 markdown 圍欄」,從生成階段就避免。

jsonrepair 和 json-repair 選哪個?

JS 棧用 npm 的 jsonrepair(支援流式 transform),Python 棧用 PyPI 的 json-repair。前後端都要修就選語義同源的組合,比如 json-repair 加它的 TS 移植,保證同一輸入兩側修復結果一致。

修復器能處理中文和彎引號嗎?

能。中文輸入法打出來的彎引號(“”)和全形空格、檔案開頭的 BOM 都在常見修復清單裡,彎引號會被規範化成直引號。修復後用校驗器過一遍即可確認。