JSON 工具箱

LLM 輸出的 JSON 被截斷了怎麼辦:先看停止原因,再談修復

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

實戰約 5 分鐘發佈於 2026-11-14更新於 2026-11-14
截斷 JSON 的堆疊式閉合示意:字串感知掃描後按括號堆疊補全

截斷不是語法錯誤,是資料不完整。語法壞可以修,截斷只能恢復一部分——修復器把缺口閉合的那一刻,剩下的缺口就從「解析報錯」變成了「沒人知道」。

截斷長什麼樣:一個欄號救不了你

模型按你的 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 留餘量定容即可。

參考資料

同系列工具

相關文章

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

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

實戰約 6 分鐘更新於 2026-11-08

TOON 格式指南:給 LLM 餵資料前,先把 JSON 瘦下來

把同構陣列餵給大模型時,JSON 裡重複的鍵名與括號都在消耗 token。TOON 用縮進物件加表格陣列把結構宣告一次、資料逐行鋪開,官方基準以少約 40% 的 token 換來更高解析準確率。本文講清語法規則、省 token 的適用邊界、何時不該轉,以及 encode 與 decode 的接入方式。

入門約 6 分鐘更新於 2026-11-10

JSON Schema 契約測試:把校驗規則焊進 CI

schema 寫完不改就是壞的起點:一個 typo 讓校驗器靜默放行,一次重構讓 fixture 全線誤報。本文給出一套可落地的契約測試方案——正例、負例、快照三件套,schema 本身先進 lint,編譯一次複用,再把四道閘門焊進 CI,讓契約壞了構建先紅。

實戰約 8 分鐘更新於 2026-11-05