BroadRouter

Cómo corregir JSON inválido de un LLM: causas, reparación y reintento

Por el equipo de BroadNet Inference · 7 min de lectura · Publicado · Actualizado

Revise primero finish_reason: una respuesta cortada en max_tokens no se puede reparar con seguridad, así que suba el límite y reenvíe. Si no, quite los bloques de código y el texto alrededor, decodifique el primer valor JSON y corrija solo errores inequívocos, como las comas finales. Valide contra un esquema y, si falla, devuelva el error exacto una o dos veces. La salida estructurada evita casi todo esto donde se admite.

Su código llama a json.loads() sobre la respuesta de un modelo y obtiene JSONDecodeError: Expecting value: line 1 column 1. O se analiza bien, pero un campo es una cadena donde usted quería un número. Este artículo ordena las causas según lo que se puede hacer con seguridad en cada caso, ofrece una función de Python probada que repara solo los casos inequívocos y muestra un bucle de reintento que sabe cuándo reintentar no sirve de nada.

Cómo elegir entre el modo JSON y json_schema se explica en modo JSON frente a json_schema. Este artículo trata de qué hacer con la respuesta que realmente recibió.

¿Por qué los LLM devuelven JSON inválido?

Un modelo escribe el texto token a token. Salvo que el servidor restrinja la decodificación, nada le impide añadir una frase amable o quedarse sin espacio. Los fallos habituales:

Lo que ve Causa ¿Se puede reparar con seguridad en código?
```json … ``` alrededor del objeto Costumbre de formato del chat Sí: quite el bloque
“Here is the JSON:” antes, “Let me know…” después La misma costumbre Sí: lea solo el primer valor
<think>...</think> antes del objeto Texto de razonamiento en el campo de contenido en algunos servidores Sí: elimine el bloque
Termina a mitad de una cadena, con llaves abiertas Llegó a max_tokens No: reenvíe con más espacio
Contenido vacío El razonamiento agotó todo el presupuesto No: reenvíe con más espacio
{"a": 1,} Coma final; JavaScript la permite, el RFC 8259 no Sí: un solo significado
{'a': True, 'b': None} Sintaxis de Python Sí: ast.literal_eval lo lee con seguridad
NaN, Infinity No es JSON; Python los acepta por defecto No: rechace
JSON válido, con tipos erróneos o campos que faltan Esquema no impuesto No: vuelva a pedirlo con el error

La línea divisoria es la ambigüedad. Si solo hay una cosa que el modelo pudo querer decir, corríjala en código y registre que lo hizo. Si tendría que adivinar, rechace la respuesta.

¿Por qué no reparar el JSON truncado?

Porque la versión reparada parece correcta y no lo es. Ejecutamos json_repair 0.64.9, una biblioteca popular con licencia MIT, sobre una respuesta cortada a mitad de palabra:

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

Devolvió JSON válido con la ciudad “Jed”. Su README lo dice abiertamente: “automatically completes missing values in JSON fields with reasonable defaults” (Traducción: «completa automáticamente los valores faltantes en los campos JSON con valores por defecto razonables»). Eso es útil para leer registros. Para datos que usted guarda o con los que actúa, convierte un fallo visible en uno silencioso.

Revise finish_reason antes de analizar. "length" significa que la respuesta llegó a max_tokens. Reenviar la misma petición con el mismo límite falla igual, así que duplique el límite o pida menos por llamada. Los modelos de razonamiento lo hacen más frecuente: la referencia de la API de BroadNet indica que DeepSeek V4.1 Flash, GLM 5.3 y Qwen3.8 27B razonan antes de responder y que el razonamiento cuenta dentro de max_tokens. Con un límite pequeño, la respuesta puede volver vacía. Deje 1,000 tokens o más, o ponga reasoning_effort en low; el artículo sobre el presupuesto de razonamiento tiene las cifras.

Una función de reparación que solo corrige los casos seguros

Usa solo la biblioteca estándar. Devuelve el valor analizado y una lista de las reparaciones que hizo, para que pueda contarlas.

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ómo funciona cada paso:

  1. El truncado y las respuestas vacías lanzan una excepción antes de analizar nada, así que nunca se convierten en datos.
  2. Los bloques de código y de razonamiento se eliminan con dos expresiones regulares.
  3. raw_decode es la herramienta clave. La documentación de Python dice que decodifica un documento “from a string that may have extraneous data at the end” (Traducción: «a partir de una cadena que puede tener datos sobrantes al final») y devuelve dónde se detuvo. Empezando en el primer { o [, salta el texto anterior al objeto e ignora el posterior. Si una llave que aparece en el texto no se puede decodificar, prueba con la siguiente.
  4. El recorrido de llaves avanza por el texto siguiendo cadenas y escapes. Las llaves que quedan abiertas indican que la respuesta se cortó aunque finish_reason no lo dijera, y eso lanza una excepción. Las comas justo antes de } o ] fuera de las cadenas se eliminan.
  5. ast.literal_eval lee salida al estilo de Python con comillas simples, True y None. Solo evalúa literales y nunca ejecuta código. Después, el resultado debe poder serializarse como JSON estricto.
  6. NaN e Infinity lanzan una excepción mediante parse_constant. El json de Python los acepta por defecto; el RFC 8259 dice que “are not permitted” (Traducción: «no están permitidos»), y el JSON.parse de JavaScript los rechaza.

La probamos con 17 cadenas de prueba: JSON limpio, JSON en un bloque de código, claves y valores en árabe dentro de un bloque, texto antes y después, un marcador {name} en el texto previo al objeto, un bloque <think>, comas finales en objetos y arrays, comas y llaves dentro de cadenas, comillas escapadas, una ruta de Windows que termina en barra invertida, literales de Python, NaN, una respuesta vacía, una respuesta cortada con y sin finish_reason: "length", y dos objetos seguidos. Todas se comportaron como indica la tabla anterior. Una prueba detectó un error real: una versión temprana cambiaba su indicador de escape antes de comprobar la comilla de cierre, así que "he said \"hi,]\"" perdía su coma. Pruebe su propio código de reparación con comillas escapadas.

Hay dos límites que conviene conocer. Con dos objetos seguidos, devuelve el primero; si quiere varios elementos, pida un único array JSON. Y la salida de Python con comillas simples que contiene una comilla doble dentro de una cadena puede confundir al recorrido de llaves y acabar rechazada. Rechazar es el fallo seguro.

¿Cómo reintentar cuando la reparación falla?

La reparación se ocupa del formato. La validación se ocupa del contenido: los campos correctos, los tipos correctos, valores razonables. Este bucle valida con el paquete jsonschema y elige el reintento según la causa:

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")

Las reglas de ese bucle:

  • Truncado: reenvíe los mismos mensajes con el doble de límite. Añadir un mensaje de «por favor, corríjalo» alargaría el prompt sin acortar la salida.
  • No es JSON, o tiene la forma equivocada: devuelva el error exacto. “amount: ‘1200’ is not of type ‘number’” le da al modelo algo concreto que corregir. Un reintento sin más a menudo repite el error.
  • Limite los intentos a tres. Cada reintento reenvía toda la conversación como tokens de entrada. Después de tres, registre la entrada y derívela a otro proceso.
  • Registre la lista de reparaciones. Si tras un cambio de prompt sube el número de “removed code fence”, el prompt ha empeorado, aunque nada haya fallado.

Ejecutamos este bucle contra un servidor simulado local que devolvía respuestas predefinidas. Una respuesta en un bloque de código con una coma final y "amount": "1200" como cadena se reparó, falló la validación y se corrigió en la segunda llamada tras devolver el error. Una respuesta cortada con finish_reason: "length" se reenvió con max_tokens subido de 1,500 a 3,000 y funcionó. El simulador registró la petición cada vez, lo que confirmó el número de mensajes y el límite que envió el bucle. Un modelo real puede fallar de otra forma, así que pruébelo con 100 de sus propias entradas antes de fiarse de las cifras.

¿La salida estructurada hace todo esto innecesario?

Elimina la mayor parte. Un servidor que restringe la decodificación a su esquema no puede emitir un bloque de código, una coma final ni un campo faltante. vLLM, un servidor habitual para modelos abiertos, lo hace con los backends xgrammar o guidance. Aun así quedan dos fallos: el truncado en max_tokens y los rechazos. OpenAI señala que la salida del modo JSON es válida “except for in some edge cases” (Traducción: «salvo en algunos casos límite») y que su aplicación “must detect and handle” (Traducción: «debe detectar y gestionar») la salida que no sea un objeto completo. Así que mantenga la comprobación de finish_reason y el validador, incluso con json_schema.

Lo que evita cada enfoque:

Enfoque Bloques de código y texto extra Errores de sintaxis Forma equivocada Truncado
Solo el prompt (“reply with JSON”) Se reducen Se reducen Se reduce No
Modo JSON (json_object) Sí Sí No No
Salida estructurada (json_schema, impuesta) Sí Sí Sí No

Con el modo JSON, OpenAI también dice que usted “must always instruct the model to produce JSON” (Traducción: «debe indicar siempre al modelo que produzca JSON») en algún mensaje; si no, puede emitir espacios en blanco hasta llegar al límite de tokens. Otros servidores compatibles con OpenAI varían, así que pruebe el modo con el modelo que vaya a poner en producción. La prueba está en el artículo sobre salida estructurada.

Para revisar una respuesta a mano, péguela en el validador de salida JSON de LLM, o genere un esquema estricto a partir de un objeto de ejemplo con el generador de JSON Schema.

Dónde encaja BroadNet Inference

BroadRouter es el sitio web de BroadNet. La referencia de la API de BroadNet lista salida estructurada solo para GLM 5.3 y Qwen3.8 27B, y no nombra el parámetro de la petición, así que pruebe json_schema con el modelo antes de depender de él. En DeepSeek V4.1 Flash y Gemma 4 VL 26B, use JSON pedido en el prompt con la función de reparación y el validador anteriores. Tres de los cuatro modelos razonan antes de responder, así que reserve max_tokens para ello. Para extracción masiva, el artículo sobre el ejecutor por lotes muestra cómo registrar finish_reason por elemento. Los prompts y las respuestas no se conservan después de cada petición.

Preguntas frecuentes

¿Por qué mi LLM devuelve el JSON dentro de un bloque de código markdown?

Los modelos de chat suelen formatear el código para personas, y un bloque de código es como lo muestran las interfaces de chat. Pida «solo JSON, sin bloque de código», pero quite los bloques en el código de todos modos: la instrucción reduce la frecuencia, no la elimina.

¿Cómo soluciono un JSONDecodeError en la salida de un LLM?

Mire primero finish_reason. Si es "length", la respuesta se cortó: suba max_tokens y reenvíe. Si no, quite los bloques de código y decodifique el primer valor JSON con raw_decode, que ignora el texto que va detrás. Corrija las comas finales y valide. Si sigue fallando, vuelva a pedirlo con el error.

¿Debo usar una biblioteca de reparación de JSON?

Para registros y depuración, sí. Para datos con los que va a actuar, con cuidado. Bibliotecas como json_repair completan los valores faltantes con valores por defecto, así que una ciudad cortada, "Jed", vuelve como un "Jed" válido. Rechace la salida truncada y reenvíe.

¿Por qué se corta la salida JSON de mi LLM?

La respuesta llegó a max_tokens. En modelos de razonamiento como DeepSeek V4.1 Flash, GLM 5.3 y Qwen3.8 27B, el razonamiento cuenta dentro de ese límite, así que pensar mucho puede dejar poco espacio. Suba el límite, ponga reasoning_effort en low o pida menos salida por llamada.

¿El modo JSON garantiza JSON válido?

Casi. OpenAI dice que la salida del modo JSON es JSON válido "except for in some edge cases" (Traducción: «salvo en algunos casos límite»), como alcanzar el límite de tokens, y no impone su esquema. La salida estructurada con json_schema añade la adherencia al esquema donde el proveedor la aplica. Valide en ambos casos.

¿Qué modelos de BroadNet admiten salida estructurada?

La referencia de la API de BroadNet lista salida estructurada para GLM 5.3 y Qwen3.8 27B, según la consulta del 15 de noviembre de 2026. No la lista para DeepSeek V4.1 Flash ni Gemma 4 VL 26B, así que en esos use JSON pedido en el prompt con reparación y validación.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity