Hướng dẫn sửa JSON: cứu đầu ra lỗi của LLM mà không mất niềm tin
Kết luận: Đầu ra LLM bị bọc trong hàng rào markdown, có dấu phẩy cuối và literal của Python, parser nghiêm ngặt sẽ từ chối toàn bộ — file cấu hình chỉnh tay thiếu dấu ngoặc kép cũng vậy. Bài này vẽ ranh giới thật giữa chín lớp lỗi công cụ sửa chữa xử lý được và bốn lớp không bao giờ sửa được, giải thích vì sao máy trạng thái thắng regex, và đưa chuỗi parse sẵn sàng cho production với jsonrepair và json-repair.

Parser nghiêm ngặt không nhượng bộ chút nào với đầu vào hỏng: một thông báo lỗi, một số dòng — và không một byte dữ liệu nào của bạn. Công cụ sửa tồn tại để biến "thất bại hoàn toàn" thành "đủ tốt để chạy" — nhưng những gì nó vá lại chỉ là phỏng đoán tốt nhất về ý định, chưa bao giờ là bảo đảm tính đúng.
Một: đầu ra hỏng từ đâu đến
Sửa chữa không phải phép thuật — hãy nhìn đầu vào trước. Trong dự án thật, JSON không chuẩn đến từ ba nguồn tập trung:
- Đầu ra LLM. Mô hình ngôn ngữ sinh văn bản token từng token; chúng không chạy bộ tuần tự hóa JSON. Dù yêu cầu "chỉ JSON", mô hình vẫn bọc câu trả lời trong hàng rào
```json, chèn phía trước "Đây là dữ liệu của bạn", bỏ sót dấu phẩy cuối, hoặc đụng trần token và dừng giữa đối tượng. - Sao chép từ ngôn ngữ khác. Đối tượng JavaScript in qua
console.logmang dấu nháy đơn và khóa không có dấu ngoặc kép; dictionary Python in ra thànhTrue/False/None. Những chuỗi "giống JSON" này nổ tung ngay khi chạmJSON.parse. - Cấu hình JSON5/JSONC. File như tsconfig hợp lệ cho phép chú thích và dấu phẩy cuối. Dán vào parser nghiêm ngặt, cả file bị từ chối.
Ba nguồn cần cách xử lý khác nhau, nhưng công cụ sửa phủ được cả ba — với điều kiện lỗi nằm trong danh sách có thể sửa mà nó công bố.
Hai: chín lớp lỗi công cụ sửa thực sự xử lý được
Kết hợp tài liệu thư viện jsonrepair với danh sách năng lực công bố của các nhà cung cấp công cụ, các lỗi tự sửa được chia thành chín lớp:
| Lớp | Đầu vào hỏng | Kết quả sau sửa |
|---|---|---|
| Dấu phẩy cuối | [1, 2, 3,] |
[1, 2, 3] |
| Nháy đơn / nháy cong | {'a': 'b'}、{"a": "b"} |
{"a": "b"} |
| Khóa không có ngoặc kép | {name: 'Ada'} |
{"name": "Ada"} |
| Chú thích | {"a": 1 /* ghi chú */} |
{"a": 1} |
| Literal Python | {"ok": True, "v": None} |
{"ok": true, "v": null} |
| Hàng rào markdown | ```json {...} ``` |
{...} |
| Thiếu dấu phẩy | [1 2] |
[1, 2] |
| Ngoặc / nháy chưa đóng | {"a": [1, 2 |
{"a": [1, 2]} |
| JSONP / nối chuỗi | cb({...})、"x" + "y" |
{...}、"xy" |
Điểm chung của chín lớp này: dữ liệu vẫn nguyên vẹn; hỏng chỉ là cú pháp. Công cụ sửa chỉnh dấu câu và vỏ bọc mà không đụng một giá trị nào. Vài chi tiết đáng nhớ riêng:
- Số có số 0 đầu trở thành chuỗi.
007được sửa thành"007", không phải7, để không mất chữ số. Nếu trường thực sự là mã dạng văn bản thì đúng; nếu là số thật, quyết định thuộc về bạn. - Từ trần trở thành chuỗi.
NaNkhông sửa được thành số — một số hiện thực cho"NaN", số khác chonull. Hành vi khác nhau giữa các thư viện; thử của bạn trước khi nối vào pipeline. - Đầu vào hợp lệ đi qua nguyên vẹn. Mọi công cụ sửa nghiêm túc đều chạy đường nhanh parse nghiêm ngặt trước. JSON hợp lệ không bao giờ vào logic sửa chữa, nên "sửa tài liệu tốt thành xấu" là không thể.
Ba: bốn thứ công cụ sửa không sửa được
Ranh giới phía bên kia cũng rõ ràng như vậy. Đừng mong sửa cho:
- Trang lỗi HTML hoặc văn xuôi thuần. Đầu vào không có cấu trúc JSON nào, và không công cụ nào tạo được dữ liệu từ hư vô.
- Dữ liệu hợp lệ cú pháp nhưng sai nội dung. Khóa gõ sai chính tả, giá trị đặt sai chỗ, số lưu thành chuỗi — đây là vấn đề ngữ nghĩa mà mọi parser, kể cả công cụ sửa, sẽ để lọt không phản đối.
- Dữ liệu mất do bị cắt cụt. Hoàn thiện có thể biến
{"items": [{"id": 1}, {"nathành JSON hợp lệ, nhưng giá trị của trườngnamekhông bao giờ quay lại. Bạn nhận được đối tượng "hợp lệ nhưng thiếu". Trong production, kiểm trastopReason === "max_tokens"trước khi quyết định hoàn thiện hay thử lại. - Khóa trùng và cấu trúc mơ hồ. Trong hai khóa giống nhau, cái nào thắng phụ thuộc hiện thực của parser. Công cụ sửa có trách nhiệm cung cấp chế độ strict ném lỗi thay vì lặng lẽ chọn một.
Một câu chốt ranh giới tin cậy: sửa chữa là phỏng đoán tốt nhất, không phải bảo đảm đúng. Để kết quả sửa chưa kiểm chứng chạy tiếp xuống dưới là đổi lỗi cú pháp ồn ào lấy lỗi dữ liệu lặng lẽ.
Bốn: hai trường phái hiện thực — một URL giải xong tranh cãi
Công cụ sửa trên thị trường có hai kiểu, và khoảng chênh hiện ra ngay ở một loại đầu vào rất cụ thể.
Trường phái regex thay thế áp tìm-đ-và-thay toàn cục lên các mẫu hỏng. Xem đầu vào này:
{"url": "http://example.com", 'note': 'fine'}
Regex chuyển nháy đơn thành nháy kép sẽ nhai cả nội dung URL; regex dọn chú thích xóa mọi // sẽ cắt đôi http://. Trong chuỗi và ngoài cấu trúc, ký tự trông y hệt — regex không phân biệt nổi.
Trường phái máy trạng thái từng ký tự theo dõi trạng thái parse: đang trong chuỗi nháy kép, nháy đơn, trong chú thích dòng, chú thích khối, hay đang đợi giá trị. Thấy ', nó hỏi trước "mình có đang trong chuỗi không?" rồi mới quyết định chuyển nháy hay bỏ qua. http://example.com nằm trong chuỗi nháy kép, nên máy trạng thái biết // ở đó là dữ liệu chứ không phải chú thích, và giữ nguyên. jsonrepair và json-healer thuộc trường phái này, và câu cửa miệng của cộng đồng "công cụ sửa không phải tìm-và-thay" nói đúng về điều này.
Thứ tự đầy đủ của pipeline sửa (như hiện thực devkits công bố) cũng đáng xem: bóc hàng rào → chuẩn hóa nháy cong → tách khối cân đầu tiên → bỏ chú thích → bọc nháy cho khóa trần → bỏ dấu phẩy cuối → chuyển literal → cuối cùng tuần tự hóa lại bằng JSON.stringify. Bước tuần tự hóa lại cuối cùng là then chốt: dù các giai đoạn trước làm gì, đầu ra được sinh lại từ kết quả đã parse, nên parser nghiêm ngặt nào phía sau cũng nuốt được.
Năm: nối vào mã — chuỗi parse theo trình tự
Khi nối sửa chữa vào mã, thứ tự quan trọng hơn chọn thư viện. Theo các mẫu công bố của json2toon và aijsonmedic, trình tự nên là: kiểm tra cắt cụt → tách đoạn JSON → parse nghiêm ngặt → sửa làm phương án dự phòng → kiểm tra theo schema.
import { jsonrepair } from "jsonrepair";
export function parseModelJson(text, stopReason) {
if (stopReason === "max_tokens") {
// Sửa đầu ra bị cắt vẫn thiếu dữ liệu — thử lại với max_tokens cao hơn
throw new Error("Truncated output: retry with a higher max_tokens");
}
// Tách đoạn JSON: LLM có thể chém gió trước và sau
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); // đường nhanh cho đầu vào hợp lệ
} catch {
return JSON.parse(jsonrepair(candidate)); // sửa làm phương án dự phòng
}
}
Phía Python, gói json-repair (hơn 4.700 sao) có loads() trả thẳng đối tượng:
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}
Hai chi tiết kỹ thuật nữa:
- Cân bằng stack. Nếu cả frontend và backend đều sửa, chọn hiện thực cùng ngữ nghĩa — Python json-repair và bản port TypeScript
@yarmu/json-repair, hoặc jsonmend với bản Python và JS cùng vượt bộ ngữ liệu phù hợp 485 ca. Nếu không, cùng một đầu ra sẽ sửa thành A ở client và B ở server, và debug thành cơn ác mộng. - Bật log sửa chữa.
@yarmu/json-repairvớilogging: truetrả mảng mỗi thao tác sửa. Tỷ lệ sửa đột ngột tăng thường nghĩa là prompt hoặc phiên bản mô hình đã đổi — tín hiệu sớm hơn mọi báo cáo lỗi.
Một bước sau sửa không thể thương lượng: kiểm tra theo schema. Hợp lệ cú pháp chưa có nghĩa dùng được. Trường thiếu, kiểu sai, khóa thừa — schema bắt hết. Cách làm kiểm thử hợp đồng áp thẳng vào đây; xem bài kiểm thử hợp đồng JSON Schema của chúng tôi.
Sáu: checklist phòng ngừa — sửa rẻ nhất là sửa không cần
Sửa là phương án dự phòng. Thắng thật là sinh ít JSON hỏng hơn ở nguồn, theo thứ tự ưu tiên:
- Structured Outputs (chế độ json_schema). Giải mã bị schema ràng buộc nên dấu phẩy cuối đơn giản không thể sinh ra. Chế độ strict của OpenAI hỏng khoảng 0,1%, đổi lại là yêu cầu cứng như
additionalProperties: false. - Chế độ JSON (json_object). Chỉ bảo đảm hợp lệ cú pháp — không bảo đảm hình dạng — và cắt cụt do trần token vẫn xảy ra.
- Chỉ thị rõ ràng. Ở endpoint không có chế độ JSON, viết rõ "không hàng rào, không chú thích, không phẩy cuối, chỉ xuất đối tượng" giảm tỉ lệ lỗi 70–80%.
- Hạ temperature, nâng trần token. Thứ nhất giảm trôi thành văn xuôi; thứ hai giảm cắt cụt.
- Thử lại kèm lỗi. Khi kiểm tra hỏng, đính đầu ra xấu cùng "đường dẫn JSON + thông báo lỗi" vào hội thoại và hỏi lại. Có lỗi chính xác, mô hình thường tự sửa.
Trên thực tế, xếp lớp "structured outputs + sửa dự phòng + kiểm tra schema" phủ gần hết mọi kịch bản.
Bảy: phân công việc — chuyển đổi phương ngữ không phải là sửa chữa
Trong hộp công cụ của site này có hai điểm đến phủ hai đoạn khác nhau của pipeline:
- Vấn đề phương ngữ (chú thích, nháy đơn, phẩy cuối) đi thẳng vào bộ chuyển JSON5. Chuyển đổi JSON5 ↔ JSON chuẩn phủ đúng ba lớp này, ngữ nghĩa rõ ràng, không đoán mò. Nếu toàn bộ đầu vào là file JSONC/JSON5, chuyển đổi dễ dự đoán hơn sửa. Về cân nhắc của bản thân phương ngữ, xem bài hướng dẫn JSON5 và JSONC.
- Sau khi sửa, đẩy kết quả qua công cụ parse JSON để kiểm tra và định dạng — lỗi được xác định theo dòng cột, xác nhận parser nghiêm ngặt thật sự nhận đầu ra.
- Vấn đề hạng thư viện (literal Python, hoàn thiện cắt cụt, bọc JSONP, hàng rào markdown) vẫn cần jsonrepair / json-repair phía mã — chưa có sửa một cú nhấp tương đương trong trình duyệt, vì những sửa này phải suy ra ý định, và thư viện cục bộ là nơi an toàn hơn công cụ chuyển đổi phổ quát.
Nếu trong tay là thông báo lỗi chứ không phải dữ liệu hỏng, hãy bắt đầu từ bài sửa lỗi parse JSON để dịch thông báo thành tọa độ, rồi mới quyết định: sửa tay hay dùng công cụ.
FAQ
Sửa JSON có làm hỏng dữ liệu của tôi không?
Với chín lớp sửa được, chỉ dấu câu và vỏ bọc thay đổi — giá trị nguyên vẹn, còn //, phẩy và ngoặc nhọn trong chuỗi được máy trạng thái nhận diện và giữ lại. Nhưng hoàn thiện cắt cụt cho đối tượng thiếu dữ liệu, số có 0 đầu thành chuỗi, và cách xử lý NaN khác nhau giữa các thư viện. Kiểm tra các trường quan trọng sau khi sửa là bắt buộc.
Sửa và kiểm tra liên hệ thế nào?
Kiểm tra chỉ nói đầu vào ở đâu bất hợp pháp; sửa đưa thẳng một tài liệu hợp lệ. Quy trình đáng tin làm cả hai: sửa trước, kiểm sau — schema bắt kiểu và trường bắt buộc, kiểm cú pháp xác nhận parser nghiêm ngặt nhận kết quả. Sửa mà không kiểm là đổi lỗi cú pháp ồn ào lấy lỗi dữ liệu lặng lẽ.
LLM luôn bọc đầu ra bằng hàng rào ```json — làm sao?
Ngắn hạn: tách lấy. Lấy văn bản từ { hoặc [ đầu đến } hoặc ] cuối rồi parse; công cụ sửa có bóc hàng rào cũng nuốt được cả tin nhắn. Dài hạn: dùng structured outputs hoặc chỉ thị rõ "không hàng rào markdown" để hàng rào không được sinh ra.
jsonrepair hay json-repair — chọn cái nào?
JavaScript dùng gói npm jsonrepair (hỗ trợ transform dòng); Python dùng json-repair từ PyPI. Nếu hai đầu đều sửa, chọn cặp cùng ngữ nghĩa — ví dụ json-repair kèm bản port TS — để cùng một đầu vào sửa giống nhau ở cả hai bên.
Công cụ sửa xử lý được tiếng Việt và nháy cong không?
Được. Nháy typographic từ bàn phím tiếng Việt (“ ”), dấu cách toàn phần và BOM đầu file đều nằm trong danh sách sửa chuẩn; nháy cong được chuẩn hóa thành nháy thẳng. Đẩy kết quả qua trình kiểm tra một lần là xong.