LLM 輸出的 JSON 被截斷了怎麼辦:先看停止原因,再談修復
結論:模型回傳的 JSON 少了結尾,解析器只給一個欄號,補上括號就能跑——但缺口被藏進了資料裡。本文按停止原因判定、輸出額度定容、schema 欄位排序與部分恢復的誠實揭露,劃清截斷場景下能修與必須重試的邊界。

截斷不是語法錯誤,是資料不完整。語法壞可以修,截斷只能恢復一部分——修復器把缺口閉合的那一刻,剩下的缺口就從「解析報錯」變成了「沒人知道」。
截斷長什麼樣:一個欄號救不了你
模型按你的 schema 回傳 JSON,生成到一半撞上輸出上限,文字戛然而止。用 Python 3.11 的 json 模組實測這樣一段輸入:
{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"
json.loads 報錯是 Expecting ':' delimiter, col 94——欄號指向 "qty" 後面缺值的位置,但真正的病因是整份文件沒有結尾。同一份輸入用貪婪正則補一個 "} 閉合,解析直接失敗;用字串感知的堆疊式閉合(下文第六節)能解析成功,但 items 只剩 2 筆,第三筆殘缺紀錄被捨棄。報錯欄號告訴你「哪裡斷了」,不告訴你「丟了多少」。
這就是截斷和普通 JSON 報錯的第一個區別:它沒有明確的修復終點。尾逗號修完就完整了,截斷修完仍然是殘本。
截斷和語法壞不是一回事:修復器的盲區
修復器(如 jsonrepair)的設計目標是把語法壞的 JSON 變成合法 JSON:剝 markdown 圍欄、去尾逗號、單引號轉雙引號,這些場景裡「意圖」是完整的,修復只是去污。截斷輸入在修復器眼裡也是「壞 JSON」,於是它同樣閉合未完成的字串、陣列和物件,回傳一個能通過解析的結果——83 份被截斷的 Claude 報告裡,修復器「修好」了 79 份,只有 4 份硬失敗。錯誤監控看到的失敗率被低估了 20 倍。
修完的結果長什麼樣?問題 6 的回饋字串停在半句話,問題 7 到 9 整個消失,next_steps 陣列不存在。Pydantic 驗證照樣通過,因為欄位給了預設值 []、清單沒有長度約束。每一層都在正常工作,產出是一份自信的錯誤報告。語法修復的邏輯放進截斷場景,就從「去污」變成了「偽造」。
所以邊界必須先劃清:修復器只該處理完整回答上的格式污漬;被切斷的輸出不該進修復器。同類的格式污漬怎麼修,見本站《JSON 修復指南》。
第一步永遠是看停止原因
所有主流 API 都在回應中繼資料裡告訴你為什麼停止,這個欄位存在且免費,卻是最常被忽略的一行程式碼。Anthropic 是 stop_reason,OpenAI 舊版是 finish_reason,取值 max_tokens 即截斷、end_turn/stop 才是自然結束:
resp = client.messages.create(model=MODEL, max_tokens=4096, ...)
if resp.stop_reason != "end_turn":
raise TruncatedOutput(
f"stop_reason={resp.stop_reason}, "
f"output_tokens={resp.usage.output_tokens}"
)
data = json.loads(resp.content[0].text)
把截斷變成顯式例外後,重試路徑才有觸發條件,監控才有告警來源。上面的 83 份報告就是事後從日誌裡的 stop_reason 欄位撈出來的——中繼資料一直在存,只是從來沒人讀。同理,length、incomplete 這類取值在 Google 與 OpenAI 的回應裡含義相同,接新廠商時先核對這張對照,別靠猜。
max_tokens 不是預算:按最壞情況定額度
截斷的直接原因通常是一個為早期產品定的輸出上限:1500 token 的上限在長會話上線後,39% 的長報告被切斷。加額度是免費的——計費只按實際生成的 token 算,4096 的上限對一份實際只用 1100 token 的報告,成本與 1500 的上限完全一樣。上限的作用是防止失控輸出,不是省錢閥門。
定容方法:上線後觀察一週真實的輸出分布,取 p99 再留餘量。那份事故覆盤裡的選擇是 4096,因為其後實測 p99 是 2350。另一個方向是壓縮輸出本身:同構陣列的鍵名重複是 token 大頭,餵模型前先換成表格化編碼(本站《TOON 格式指南》),同樣的資訊量能省下可觀額度,從源頭降低撞頂機率。
schema 欄位順序就是截斷順序
模型自上而下寫 JSON,輸出耗盡時被切掉的永遠是 schema 末尾的欄位。一份把 scores 放在 per_question_feedback 之後的教學報告 schema,截斷時最先丟的就是使用者會截圖對比的分數。改動只需把屬性重新排序:關鍵且短的欄位在前,長而可再生的明細在後,notes 類自由文字墊底。
廠商行為差異也決定了同樣截斷、不同後果:
| 廠商 | 結構化輸出方式 | 截斷時的表現 |
|---|---|---|
| OpenAI | response_format + strict: true |
取樣級保證,但方言最窄;通常直接拒絕生成 |
| Anthropic | tool use 的 input_schema |
無解碼期保證,可能交出未閉合的括號 |
| Gemini | responseSchema + JSON MIME |
解碼期只保證 enum 與型別,截斷同樣可能發生 |
所以「開了 structured output 就不用驗證」是錯覺:約束越鬆的廠商越要在你這邊補一道 schema 驗證與重試閉環,契約測試怎麼搭見《JSON Schema 契約測試》。
真要部分恢復:字串感知的堆疊式閉合
有些場景必須榨出殘本——串流展示、降級回應、人工複核。此時修復梯子的最後一級才是閉合操作,且必須滿足兩個條件。第一,括號掃描必須字串感知:逐字元維護引號與跳脫狀態,否則值裡的 { 會把堆疊弄亂。第二,殘缺的鍵值對要先刪再閉:"qty" 後面沒有值時,直接閉合會產生 {"qty"} 這種非法結構,正確做法是整對捨棄。
def close_truncated(s: str) -> str:
# 1) 字串感知掃描,截斷在字串內則先補引號
out, in_str, esc = [], False, False
for ch in s:
out.append(ch)
if esc: esc = False; continue
if ch == '\\' and in_str: esc = True; continue
if ch == '"': in_str = not in_str
text = ''.join(out) + ('"' if in_str else '')
# 2) 刪除殘缺鍵值對與懸空冒號/逗號
text = re.sub(r',\s*"[^"]*"\s*$', '', text)
text = re.sub(r'[{,]\s*"[^"]*"\s*:\s*$', '}', text)
text = re.sub(r'[:,\s*$', '', text)
# 3) 重掃堆疊,按後進先出補閉合符
stack, in_str, esc = [], False, False
for ch in text:
if esc: esc = False; continue
if ch == '\\' and in_str: esc = True; continue
if ch == '"': in_str = not in_str; continue
if not in_str:
if ch in '{[': stack.append(ch)
elif ch in '}]' and stack: stack.pop()
return text + ''.join('}' if c == '{' else ']' for c in reversed(stack))
本機對第六節開頭那段輸入跑這段程式碼(Python 3.11、標準庫),產出 {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]}——可解析,第三筆紀錄殘缺被捨棄。本地模型側的同類實踐用 partial-json-parser 這類專用庫,思路相同:按堆疊補全、按完整性裁剪。
關鍵在揭露:閉合函式必須回傳「我是從哪一級修好的」的報告,truncation 級的產物只能標記為部分結果——繼續追問缺失範圍、提額度重試、或明示使用者資料不完整。靜默假裝什麼都沒發生,等於用確定性程式碼製造幻覺。
什麼該修、什麼必須重試:一張邊界表
| 輸入形態 | 正確動作 | 原因 |
|---|---|---|
| 圍欄包裹、尾逗號、單引號 | 修復器處理 | 意圖完整,只是語法髒 |
| 截斷在字串中間 | 重試或部分恢復+揭露 | 值本身缺了一截,補不回來 |
| 截斷在結構中間 | 部分恢復+揭露 | 能救回已完成欄位,殘缺對要刪 |
| 解析通過但語義可疑 | 業務驗證 | 與截斷無關,但常與其並發 |
中文側的財務發票案例把代價量化了:長發票被截斷後補括號變成合法 JSON,total 欄位缺失取預設值 0,格式合規率 98.2% 的系統每月錯約 200 張發票;改為截斷即降級、加合計恆等驗證後,金額錯誤率從 0.8% 降到 0.02%。盯著「格式合規率」優化三個月,方向從一開始就是偏的——能通過解析器的東西不等於能通過業務的東西。
落地清單四條:解析前先查停止原因;額度按 p99 定容而不是按預算省;schema 關鍵欄位前置;修復器只處理完整回答的格式污漬。四條都做到,截斷才會從靜默的資料腐蝕變回一個響亮的、可重試的失敗。
截斷的 JSON 閉合括號後能直接用嗎
不能直接用。閉合只保證語法合法,資料仍是殘本:被切斷的字串停在半句、末尾紀錄被捨棄、依賴預設值的欄位拿到的不是真實值。正確做法是把閉合產物標記為部分結果,觸發重試或降級,並記錄恢復率。
怎麼判斷 JSON 是被截斷而不是寫錯了
看回應中繼資料裡的停止原因欄位:max_tokens/length/incomplete 即截斷,end_turn/stop 卻解析失敗才是語法問題。沒有中繼資料的場景可以看文字結尾形態——斷在引號或括號中間、最後一級結構未閉合,基本是截斷。
為什麼修復器會把截斷的資料「修好」得更危險
修復器的目標函式是「讓解析通過」,截斷文件閉合後恰恰能通過,於是錯誤監控零告警、下游驗證有預設值也會放行。83 份截斷報告只報錯 4 次就是這個機制。修復器沒有意圖概念,它不知道資料缺了多少,所以截斷必須在上游攔截。
max_tokens 調大會不會多花錢
不會。計費按實際生成的 token 數結算,上限只是安全閥門。4096 的上限對實際 1100 token 的輸出,帳單與 1500 上限完全相同。真正要控制的是失控輸出,按 p99 留餘量定容即可。