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

嚴格解析器對壞輸入是零寬容的:只給你一條報錯和一個行號,一個位元組的資料都不給。修復器存在的意義,就是把「完全失敗」變成「先跑起來再說」——但它補出來的東西永遠只是對意圖的最佳猜測。
一、壞 JSON 從哪來:三個來源,問題高度集中
修復不是全能的,先看輸入是什麼。工程裡非標準 JSON 的來源集中在三處:
- LLM 輸出。模型逐 token 生成文字,並不執行 JSON 序列化器。即使要求「只輸出 JSON」,它也會包一層
```json圍欄、加一句「好的,這是你要的資料」、落下尾逗號,或者命中 token 上限停在物件中間。 - 從別的語言複製。
console.log印出來的 JavaScript 物件帶單引號和不帶引號的鍵;Python 字典印出來是True/False/None;這些「長得像 JSON」的文字一餵給JSON.parse就炸。 - 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 則原樣返回:修復器都內建嚴格解析快路徑,合法輸入不經過修復邏輯,不存在「越修越壞」。
三、四類不能修:信任邊界的另一側
修復器的能力邊界同樣明確,下面四類別指望它:
- HTML 錯誤頁或純散文。輸入裡根本沒有 JSON 結構,沒有任何工具能憑空造出資料。
- 語法合法但資料錯誤。鍵拼錯、值放錯位、數字存成字串——這些是語義問題,語法層面完全合法,任何修復器都會放行。
- 截斷丟掉的資料。截斷補全能把
{"items": [{"id": 1}, {"na修成合法 JSON,但name欄位的值永遠不會回來。修出來的是「合法但不完整」的物件,生產環境必須先查stopReason === "max_tokens"再決定是補全還是重試。 - 重複鍵與歧義結構。兩個同名鍵哪個生效取決於解析器實現,負責任的修復器提供 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 才是上策。按優先級排:
- Structured Outputs(json_schema 模式):解碼階段就按 schema 約束,尾部逗號根本生成不出來。OpenAI 的 strict 模式失敗率約 0.1%,代價是
additionalProperties: false等硬性要求。 - JSON mode(json_object):只保證語法合法,不保證形狀,token 上限導致的截斷依然存在。
- 顯式指令:沒有 JSON mode 的端點,寫明「不要圍欄、不要註釋、不要尾逗號、只輸出物件」能降 70-80% 的錯誤率。
- 降低 temperature、加大 token 上限:前者減少跑偏成散文的機率,後者減少截斷。
- 帶報錯的重試:校驗失敗時,把壞輸出和「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 都在常見修復清單裡,彎引號會被規範化成直引號。修復後用校驗器過一遍即可確認。