BroadRouter

Sửa JSON không hợp lệ từ LLM: nguyên nhân, sửa lỗi, thử lại

Đội ngũ BroadNet Inference · 7 phút đọc · Đăng ngày · Cập nhật

Hãy kiểm tra finish_reason trước: phản hồi bị cắt ở max_tokens không thể sửa an toàn, nên hãy tăng giới hạn và gửi lại. Nếu không, hãy bỏ code fence và câu chữ xung quanh, giải mã giá trị JSON đầu tiên, rồi chỉ sửa lỗi rõ nghĩa như dấu phẩy thừa. Validate theo schema; nếu thất bại, gửi lại đúng lỗi một hai lần. Đầu ra có cấu trúc ngăn phần lớn lỗi này.

Code của bạn gọi json.loads() trên phản hồi của model và nhận JSONDecodeError: Expecting value: line 1 column 1. Hoặc parse được, nhưng một trường là chuỗi trong khi bạn cần số. Bài này phân loại các nguyên nhân theo việc bạn có thể làm an toàn với từng loại, đưa ra một hàm Python đã test chỉ sửa các trường hợp rõ nghĩa, và một vòng lặp retry biết lúc nào retry không giúp được gì.

Việc chọn giữa JSON mode và json_schema được trình bày trong JSON mode và json_schema. Bài này nói về việc xử lý phản hồi bạn thực sự nhận được.

Vì sao LLM trả về JSON không hợp lệ?

Model viết văn bản từng token một. Trừ khi server ràng buộc quá trình giải mã, không gì ngăn nó thêm một câu thân thiện hoặc hết chỗ. Các lỗi thường gặp:

Bạn thấy gì Nguyên nhân Sửa bằng code có an toàn không?
```json … ``` bao quanh object Thói quen định dạng kiểu chat Có: bỏ fence
“Here is the JSON:” ở trước, “Let me know…” ở sau Cùng thói quen đó Có: chỉ đọc giá trị đầu tiên
<think>...</think> trước object Văn bản suy luận nằm trong trường content ở một số server Có: bỏ khối này
Kết thúc giữa chuỗi, ngoặc còn mở Chạm max_tokens Không: gửi lại với nhiều chỗ hơn
Content rỗng Suy luận dùng hết ngân sách Không: gửi lại với nhiều chỗ hơn
{"a": 1,} Dấu phẩy thừa; JavaScript cho phép, RFC 8259 thì không Có: chỉ một nghĩa
{'a': True, 'b': None} Cú pháp Python Có: ast.literal_eval đọc an toàn
NaN, Infinity Không phải JSON; Python mặc định chấp nhận Không: từ chối
JSON hợp lệ nhưng sai kiểu hoặc thiếu trường Schema không được thực thi Không: yêu cầu lại kèm lỗi

Ranh giới là sự mơ hồ. Nếu chỉ có đúng một điều model có thể đã muốn nói, hãy sửa bằng code và ghi log là đã sửa. Nếu bạn phải đoán, hãy từ chối phản hồi.

Vì sao không nên sửa JSON bị cắt?

Vì bản đã sửa trông đúng nhưng không đúng. Chúng tôi chạy json_repair 0.64.9, một thư viện giấy phép MIT phổ biến, trên một phản hồi bị cắt giữa từ:

'{"name": "Omar", "city": "Jed'  ->  {'name': 'Omar', 'city': 'Jed'}

Nó trả về JSON hợp lệ với thành phố “Jed”. README của thư viện nói rõ điều này: nó “automatically completes missing values in JSON fields with reasonable defaults” (bản dịch: tự động hoàn thiện giá trị thiếu trong các trường JSON bằng giá trị mặc định hợp lý). Điều đó hữu ích khi đọc log. Với dữ liệu bạn lưu hoặc dùng để hành động, nó biến một lỗi nhìn thấy được thành một lỗi âm thầm.

Hãy kiểm tra finish_reason trước khi parse. "length" nghĩa là phản hồi đã chạm max_tokens. Gửi lại cùng request với cùng giới hạn sẽ thất bại y như cũ, nên hãy nhân đôi giới hạn hoặc yêu cầu ít hơn mỗi lần gọi. Model suy luận khiến chuyện này phổ biến hơn: tài liệu API của BroadNet cho biết DeepSeek V4.1 Flash, GLM 5.3 và Qwen3.8 27B suy luận trước khi trả lời, và phần suy luận được tính vào max_tokens. Với giới hạn nhỏ, câu trả lời có thể rỗng. Hãy chừa từ 1.000 token trở lên, hoặc đặt reasoning_effort là low; bài về ngân sách suy luận có các con số cụ thể.

Hàm sửa lỗi chỉ sửa các trường hợp an toàn

Hàm này chỉ dùng thư viện chuẩn. Nó trả về giá trị đã parse và danh sách các lần sửa đã thực hiện, để bạn có thể đếm.

import ast, json, re

class Truncated(Exception): pass
class NotJSON(Exception): pass

FENCE = re.compile(r"```(?:json|JSON)?\s*\n(.*?)```", re.S)
THINK = re.compile(r"<think>.*?</think>", re.S)

def _reject_constant(name):                 # NaN, Infinity: Python accepts them, JSON does not
    raise NotJSON(f"non-standard constant {name}")

_decoder = json.JSONDecoder(parse_constant=_reject_constant)

def _first_value(s):
    """Decode the first JSON object or array in s, ignoring prose before and after it."""
    for i, ch in enumerate(s):
        if ch in "{[":
            try:
                return _decoder.raw_decode(s, i)[0]
            except json.JSONDecodeError:
                continue                    # a stray brace in prose; try the next one
    raise NotJSON("no JSON object or array found")

def _scan(s):
    """Drop commas before } or ] outside strings; report brackets left open."""
    out, stack, in_str, esc = [], [], False, False
    for i, ch in enumerate(s):
        if in_str:
            if esc:
                esc = False
            elif ch == "\\":
                esc = True
            elif ch == '"':
                in_str = False
        elif ch == '"':
            in_str = True
        elif ch in "{[":
            stack.append(ch)
        elif ch in "}]" and stack:
            stack.pop()
        elif ch == ",":
            rest = s[i + 1:].lstrip()
            if rest[:1] in ("}", "]"):
                continue                    # trailing comma: skip it
        out.append(ch)
    return "".join(out), len(stack) + (1 if in_str else 0)

def _python_literal(s):
    """Output in Python syntax: single quotes, True/False/None, trailing commas."""
    start = min((i for i in (s.find("{"), s.find("[")) if i >= 0), default=-1)
    end = max(s.rfind("}"), s.rfind("]"))
    if start < 0 or end <= start:
        raise NotJSON("no braces")
    value = ast.literal_eval(s[start:end + 1])       # literals only; never runs code
    if not isinstance(value, (dict, list)):
        raise NotJSON("not an object or array")
    json.dumps(value, allow_nan=False)               # must round-trip as strict JSON
    return value

def parse_llm_json(content, finish_reason=None):
    """Return (value, repairs). Raises Truncated or NotJSON."""
    if finish_reason == "length":
        raise Truncated("hit max_tokens; raise the limit or shorten the output")
    if not content or not content.strip():
        raise NotJSON("empty content (reasoning may have used the whole budget)")
    repairs = []
    s = content.strip().lstrip("\ufeff")
    if THINK.search(s):
        s = THINK.sub("", s).strip(); repairs.append("removed <think> block")
    m = FENCE.search(s)
    if m:
        s = m.group(1).strip(); repairs.append("removed code fence")
    try:
        value = _decoder.decode(s)
        return value, repairs
    except json.JSONDecodeError:
        pass
    try:
        value = _first_value(s); repairs.append("ignored text around JSON")
        return value, repairs
    except NotJSON:
        pass
    fixed, open_count = _scan(s)
    if open_count:
        raise NotJSON(f"incomplete JSON, {open_count} bracket(s) or string left open: treat as truncated")
    if fixed != s:
        try:
            value = _first_value(fixed); repairs.append("removed trailing commas")
            return value, repairs
        except NotJSON:
            pass
    try:
        value = _python_literal(s); repairs.append("parsed Python-style literal")
        return value, repairs
    except (ValueError, SyntaxError, TypeError, MemoryError, RecursionError, NotJSON) as e:
        raise NotJSON(f"unrepairable: {e}") from None

Cách từng bước hoạt động:

  1. Bị cắt và phản hồi rỗng gây exception trước khi parse, nên không bao giờ trở thành dữ liệu.
  2. Fence và khối suy luận được bỏ bằng hai biểu thức chính quy.
  3. raw_decode là công cụ then chốt. Tài liệu Python cho biết nó giải mã một tài liệu “from a string that may have extraneous data at the end” (bản dịch: từ một chuỗi có thể có dữ liệu thừa ở cuối), và trả về vị trí nó dừng. Bắt đầu từ { hoặc [ đầu tiên, nó bỏ qua câu chữ trước object và phớt lờ câu chữ sau. Nếu một dấu ngoặc nhọn trong câu chữ không giải mã được, nó thử dấu tiếp theo.
  4. Bước quét ngoặc duyệt văn bản, theo dõi chuỗi và ký tự escape. Ngoặc còn mở nghĩa là phản hồi đã bị cắt dù finish_reason không báo vậy; khi đó hàm gây exception. Dấu phẩy ngay trước } hoặc ] bên ngoài chuỗi bị bỏ đi.
  5. ast.literal_eval đọc đầu ra kiểu Python với dấu nháy đơn, True và None. Nó chỉ đánh giá literal và không bao giờ chạy code. Kết quả sau đó phải serialize được thành JSON chặt chẽ.
  6. NaN và Infinity gây exception thông qua parse_constant. json của Python mặc định chấp nhận chúng; RFC 8259 nói chúng “are not permitted” (bản dịch: không được phép), và JSON.parse của JavaScript từ chối chúng.

Chúng tôi chạy hàm trên 17 chuỗi test: JSON sạch, JSON trong fence, key và value tiếng Ả Rập trong fence, câu chữ trước và sau, placeholder {name} trong câu chữ trước object, một khối <think>, dấu phẩy thừa trong object và mảng, dấu phẩy và ngoặc bên trong chuỗi, dấu nháy đã escape, một đường dẫn Windows kết thúc bằng dấu gạch chéo ngược, literal Python, NaN, một phản hồi rỗng, một phản hồi bị cắt có và không có finish_reason: "length", và hai object liên tiếp. Tất cả đều hoạt động đúng như bảng ở trên. Một bài test đã bắt được lỗi thật: phiên bản đầu đảo cờ escape trước khi kiểm tra dấu nháy đóng, nên "he said \"hi,]\"" bị mất dấu phẩy. Hãy test code sửa lỗi của bạn với dấu nháy đã escape.

Có hai giới hạn cần biết. Khi có hai object liên tiếp, hàm trả về object đầu tiên; nếu bạn cần nhiều mục, hãy yêu cầu một mảng JSON. Và đầu ra Python dùng nháy đơn có chứa nháy kép bên trong chuỗi có thể bị bước quét ngoặc đọc sai và từ chối. Từ chối là kiểu thất bại an toàn.

Nên retry thế nào khi sửa lỗi thất bại?

Sửa lỗi xử lý định dạng. Validate xử lý nội dung: đúng trường, đúng kiểu, giá trị hợp lý. Vòng lặp này validate bằng gói jsonschema và chọn cách retry theo nguyên nhân:

import json, os
from jsonschema import Draft202012Validator
from openai import OpenAI
from llm_json import parse_llm_json, Truncated, NotJSON

client = OpenAI(base_url=os.environ.get("BASE_URL", "https://inference.broadnet.ai/v1"),
                api_key=os.environ["BROADNET_API_KEY"])
SCHEMA = {"type": "object", "additionalProperties": False,
          "required": ["name", "city", "amount"],
          "properties": {"name": {"type": "string", "minLength": 1},
                         "city": {"type": ["string", "null"]},
                         "amount": {"type": "number", "minimum": 0}}}
validator = Draft202012Validator(SCHEMA)

def extract(text, model="broadnet/qwen3.8-27b", max_tokens=1500, attempts=3, log=print):
    messages = [{"role": "system", "content": "Extract name, city and amount. Reply with one JSON object only, no code fence. "
                                              "Schema: " + json.dumps(SCHEMA)},
                {"role": "user", "content": text}]
    for attempt in range(1, attempts + 1):
        r = client.chat.completions.create(model=model, messages=messages, max_tokens=max_tokens,
                                           reasoning_effort="low", temperature=0)
        c = r.choices[0]
        try:
            value, repairs = parse_llm_json(c.message.content, c.finish_reason)
            errors = [f"{'/'.join(map(str, e.path)) or '(root)'}: {e.message}" for e in validator.iter_errors(value)]
            if not errors:
                log({"attempt": attempt, "repairs": repairs, "ok": True})
                return value
            problem = "The JSON does not match the schema: " + "; ".join(errors)
        except Truncated:
            log({"attempt": attempt, "ok": False, "why": "truncated"})
            max_tokens *= 2                 # same prompt, more room; a re-ask would be cut off too
            continue
        except NotJSON as e:
            problem = f"That reply was not valid JSON ({e})."
        log({"attempt": attempt, "ok": False, "why": problem})
        messages += [{"role": "assistant", "content": c.message.content or ""},
                     {"role": "user", "content": problem + " Return the corrected JSON object only."}]
    raise RuntimeError(f"no valid JSON after {attempts} attempts")

Các quy tắc trong vòng lặp đó:

  • Bị cắt: gửi lại đúng các tin nhắn đó với giới hạn gấp đôi. Thêm một tin nhắn “hãy sửa” chỉ làm prompt dài hơn mà đầu ra không ngắn đi.
  • Không phải JSON, hoặc sai cấu trúc: gửi lại đúng thông báo lỗi. “amount: ‘1200’ is not of type ‘number’” cho model một điều cụ thể để sửa. Retry trơn thường lặp lại đúng lỗi cũ.
  • Giới hạn ở ba lần thử. Mỗi lần retry gửi lại toàn bộ hội thoại dưới dạng token đầu vào. Sau ba lần, hãy ghi log đầu vào và chuyển nó sang hướng xử lý khác.
  • Ghi log danh sách sửa lỗi. Số lần “removed code fence” tăng lên sau khi đổi prompt cho bạn biết prompt đã tệ đi, dù không có gì thất bại.

Chúng tôi chạy vòng lặp này với một mock server cục bộ phát lại các phản hồi soạn sẵn. Một phản hồi trong fence có dấu phẩy thừa và "amount": "1200" dạng chuỗi đã được sửa, không qua được validate, và được khắc phục ở lần gọi thứ hai khi gửi lại lỗi. Một phản hồi bị cắt với finish_reason: "length" được gửi lại với max_tokens tăng từ 1.500 lên 3.000 và thành công. Mock server ghi lại request mỗi lần, xác nhận số tin nhắn và giới hạn mà vòng lặp đã gửi. Model thật có thể thất bại theo cách khác, nên hãy chạy trên 100 đầu vào của chính bạn trước khi tin các con số.

Đầu ra có cấu trúc có khiến việc này thừa không?

Nó loại bỏ phần lớn. Server ràng buộc giải mã theo schema của bạn không thể sinh ra fence, dấu phẩy thừa hay trường bị thiếu. vLLM, một server phổ biến cho model mở, làm việc này với backend xgrammar hoặc guidance. Dù vậy vẫn còn hai kiểu lỗi: bị cắt ở max_tokens, và từ chối. OpenAI lưu ý rằng đầu ra JSON mode hợp lệ “except for in some edge cases” (bản dịch: trừ một số trường hợp biên) và ứng dụng của bạn “must detect and handle” (bản dịch: phải phát hiện và xử lý) đầu ra không phải object hoàn chỉnh. Vì vậy hãy giữ bước kiểm tra finish_reason và validator, kể cả khi dùng json_schema.

Mỗi cách ngăn được gì:

Cách làm Fence và câu chữ Lỗi cú pháp Sai cấu trúc Bị cắt
Chỉ prompt (“trả lời bằng JSON”) Giảm Giảm Giảm Không
JSON mode (json_object) Có Có Không Không
Đầu ra có cấu trúc (json_schema, có thực thi) Có Có Có Không

Với JSON mode, OpenAI cũng cho biết bạn “must always instruct the model to produce JSON” (bản dịch: luôn phải yêu cầu model tạo JSON) trong một tin nhắn; nếu không, model có thể sinh khoảng trắng cho tới khi chạm giới hạn token. Các server tương thích OpenAI khác hoạt động không giống nhau, nên hãy test chế độ này trên model bạn đưa vào production. Cách test có trong bài về đầu ra có cấu trúc.

Để kiểm tra một phản hồi bằng tay, hãy dán nó vào công cụ validate đầu ra JSON của LLM, hoặc tạo schema chặt chẽ từ một object mẫu bằng công cụ tạo JSON schema.

BroadNet Inference phù hợp ở đâu?

BroadRouter là website của BroadNet. Tài liệu API của BroadNet chỉ liệt kê đầu ra có cấu trúc cho GLM 5.3 và Qwen3.8 27B, và không nêu tên tham số request, nên hãy test json_schema trên model trước khi dựa vào nó. Với DeepSeek V4.1 Flash và Gemma 4 VL 26B, hãy yêu cầu JSON bằng prompt kèm hàm sửa lỗi và validator ở trên. Ba trong bốn model suy luận trước khi trả lời, nên hãy tính ngân sách max_tokens cho phần đó. Với trích xuất hàng loạt, bài về batch runner chỉ cách ghi log finish_reason cho từng mục. Prompt và phản hồi không được lưu giữ sau mỗi request.

Câu hỏi thường gặp

Vì sao LLM trả về JSON nằm trong khối code markdown?

Model chat thường định dạng code cho người đọc, và code fence là cách giao diện chat hiển thị code. Hãy yêu cầu “chỉ JSON, không code fence”, nhưng vẫn bỏ fence trong code: lời dặn giảm tần suất, không loại bỏ hẳn.

Sửa lỗi JSONDecodeError trên đầu ra LLM thế nào?

Hãy xem finish_reason trước. Nếu là “length”, phản hồi đã bị cắt: tăng max_tokens và gửi lại. Nếu không, bỏ code fence và giải mã giá trị JSON đầu tiên bằng raw_decode, hàm này bỏ qua văn bản phía sau. Sửa dấu phẩy thừa rồi validate. Nếu vẫn lỗi, hãy yêu cầu lại kèm thông báo lỗi.

Có nên dùng thư viện sửa JSON không?

Với log và debug thì có. Với dữ liệu bạn dùng để hành động thì hãy cẩn thận. Các thư viện như json_repair điền giá trị thiếu bằng giá trị mặc định, nên tên thành phố bị cắt “Jed” trở về thành một “Jed” hợp lệ. Hãy từ chối đầu ra bị cắt và gửi lại.

Vì sao đầu ra JSON của LLM bị cắt giữa chừng?

Phản hồi đã chạm max_tokens. Với model suy luận như DeepSeek V4.1 Flash, GLM 5.3 và Qwen3.8 27B, phần suy luận được tính vào giới hạn đó, nên suy nghĩ dài có thể để lại quá ít chỗ. Hãy tăng giới hạn, đặt reasoning_effort là low, hoặc yêu cầu ít đầu ra hơn mỗi lần gọi.

JSON mode có đảm bảo JSON hợp lệ không?

Gần như vậy. OpenAI cho biết đầu ra JSON mode là JSON hợp lệ “except for in some edge cases” (bản dịch: trừ một số trường hợp biên), chẳng hạn khi chạm giới hạn token, và không thực thi schema của bạn. Đầu ra có cấu trúc với json_schema bổ sung việc tuân thủ schema ở nơi nhà cung cấp thực thi. Dù cách nào cũng hãy validate.

Model nào của BroadNet hỗ trợ đầu ra có cấu trúc?

Tài liệu API của BroadNet liệt kê đầu ra có cấu trúc cho GLM 5.3 và Qwen3.8 27B, kiểm tra ngày 15 tháng 11 năm 2026. Tài liệu không liệt kê cho DeepSeek V4.1 Flash hay Gemma 4 VL 26B, nên với hai model này hãy yêu cầu JSON bằng prompt kèm sửa lỗi và validate.

Đọc dạng MarkdownHỏi ChatGPTHỏi ClaudeHỏi Perplexity