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:
- El truncado y las respuestas vacías lanzan una excepción antes de analizar nada, así que nunca se convierten en datos.
- Los bloques de código y de razonamiento se eliminan con dos expresiones regulares.
raw_decodees 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.- 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_reasonno lo dijera, y eso lanza una excepción. Las comas justo antes de}o]fuera de las cadenas se eliminan. ast.literal_evallee salida al estilo de Python con comillas simples,TrueyNone. Solo evalúa literales y nunca ejecuta código. Después, el resultado debe poder serializarse como JSON estricto.NaNeInfinitylanzan una excepción medianteparse_constant. Eljsonde Python los acepta por defecto; el RFC 8259 dice que “are not permitted” (Traducción: «no están permitidos»), y elJSON.parsede 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.
