JSON Toolkit

El JSON de un LLM llegó truncado: mira el motivo de parada antes de hablar de reparación

En resumen: El modelo devuelve un JSON que termina a mitad de un valor y el parser solo ofrece un número de columna. Cerrar las llaves lo hace analizable otra vez, pero cada campo ausente queda escondido dentro de los datos. Este artículo traza la frontera entre lo que una reparación de truncado puede recuperar con honestidad y lo que debe reintentarse: control por stop_reason, dimensionado del límite y orden de los campos del esquema.

Práctico~5 min de lecturaPublicado el 2026-11-14Actualizado el 2026-11-14
Cierre por pila de un JSON truncado tras un recorrido consciente de cadenas

Un truncado no es un error de sintaxis, es un dato que falta. La sintaxis se repara; el truncado solo se recupera en parte. En el instante en que una herramienta cierra el hueco, el resto del hueco deja de ser un error de análisis y pasa a ser algo que nadie ve.

Cómo se ve un truncado: un número de columna no basta

El modelo escribe JSON según tu esquema, alcanza el límite de salida y el texto se corta. Pasa esto al módulo json de Python 3.11:

{"scores": {"clarity": 8, "depth": 7}, "items": [{"name": "a", "qty": 2}, {"name": "b", "qty"

json.loads lanza Expecting ':' delimiter, col 94. La columna apunta a la clave "qty" sin valor, pero la causa real es que el documento no tiene final. Cerrarlo con una regex codiciosa que añade "} falla; un cierre por pila consciente de cadenas (sección seis) analiza, pero items queda con 2 entradas y el tercer registro parcial desaparece. La columna dice dónde se detuvo el texto. Nunca dice cuánto se perdió.

Esa es la primera diferencia real con un error JSON común. Una coma final tiene un estado final bien definido: la quitas y el documento está completo. Un truncado no tiene ese estado final. Lo reparas y sigue siendo un fragmento.

Truncado no es daño de sintaxis: el punto ciego de los reparadores

Reparadores como jsonrepair existen para convertir JSON roto en JSON legal: quitar vallas markdown, comas finales, convertir comillas simples. Ahí la intención está intacta y la reparación es limpieza. Una entrada truncada parece el mismo JSON roto para la misma herramienta, así que cierra la cadena, el array y el objeto abiertos y devuelve algo analizable. De 83 informes de Claude truncados, la herramienta "arregló" 79 y solo 4 fallaron de forma dura. El monitoreo veía una tasa veinte veces menor que la real.

¿Cómo era la salida reparada? El comentario de la pregunta 6 terminaba a mitad de frase, las preguntas 7 a 9 no existían, el array next_steps había desaparecido. Pydantic validó igual, porque next_steps tenía valor por defecto [] y la lista no tenía límite de longitud. Cada capa hizo su trabajo. El producto entregó un informe seguro y equivocado.

Pon reparación de sintaxis en una ruta de truncado y se desliza en silencio de la limpieza a la fabricación. La frontera va primero: un reparador solo debe tratar suciedad de formato de respuestas completas; una respuesta cortada nunca debe llegarle. Para la suciedad de formato, véase la guía de reparación de JSON.

El primer paso siempre es el motivo de parada

Toda API importante indica por qué se detuvo la generación, en los metadatos y gratis. También es la línea de código más ignorada en las integraciones de LLM. Anthropic expone stop_reason, la API de chat de OpenAI expone finish_reason: max_tokens significa truncado, end_turn o stop significa que el modelo terminó por sí solo.

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)

Con el truncado convertido en excepción explícita, el reintento tiene disparador y el monitoreo fuente de alertas. Los 83 informes se encontraron después con una sola consulta al campo stop_reason de registros que siempre estuvieron guardados y nunca se leían. Gemini señala length e incomplete con el mismo sentido; al añadir un proveedor nuevo, revisa la tabla de correspondencia en lugar de suponer.

max_tokens es una barandilla, no un presupuesto

La causa directa suele ser un límite dimensionado para una versión anterior del producto: 1500 tokens que cortan el 39 % de los informes largos en cuanto llegan sesiones largas. Subir el límite es gratis. El cobro sigue los tokens realmente generados, así que un límite de 4096 en un informe de 1100 tokens cuesta exactamente igual que 1500. El límite sirve para frenar generaciones desbocadas, no para ahorrar.

Diménsionalo con datos: observa una semana de distribución real, toma el p99 y deja margen. El equipo del incidente eligió 4096 porque su p99 tras la corrección era 2350. El otro camino es encoger la propia salida. Las claves repetidas en arrays homogéneos consumen la mayor parte de los tokens; cambiar a una codificación tabular antes de la llamada (véase la guía del formato TOON) reduce el volumen que debe caber bajo el límite.

El orden de los campos decide qué se corta

Los modelos escriben JSON de arriba abajo. Cuando se acaba el presupuesto, desaparece primero lo que está al final de la lista. Un esquema ordenado summary, per_question_feedback, scores, next_steps pierde primero scores, justo lo que el usuario captura y compara cada semana. La corrección es reordenar: campos cortos y críticos delante, detalle largo y regenerable después, texto libre al final.

El comportamiento de los proveedores también cambia la consecuencia del mismo truncado:

Proveedor Mecanismo de salida estructurada Comportamiento al truncarse
OpenAI response_format con strict: true Garantía en el muestreo, dialecto más estrecho; suele negarse a generar
Anthropic input_schema en tool use Sin garantía en la decodificación; puede devolver llaves sin cerrar
Gemini responseSchema con MIME JSON En decodificación solo impone enum y tipo; el truncado sigue siendo posible

"Salida estructurada activada, validación innecesaria" es una ilusión. Cuanto más floja la garantía del proveedor, más necesitas tu propia validación de esquema y un bucle de reintento. Cómo montar esa prueba de contrato está en pruebas de contrato con JSON Schema.

Cuando de verdad hace falta recuperación parcial: cierre por pila consciente de cadenas

Algunos casos obligan a sacar algo del fragmento: vistas previas en streaming, respuestas degradadas, colas de revisión humana. Ahí el cierre es el último peldaño de la escalera de reparación y necesita dos condiciones. Primero, el recorrido de llaves debe ser consciente de cadenas: sigue el estado de comillas y escapes carácter a carácter, o un { dentro de un valor rompe la pila. Segundo, borra los pares clave-valor incompletos antes de cerrar. Una clave "qty" sin valor no puede cerrarse como {"qty"}; el par entero debe irse.

def close_truncated(s: str) -> str:
    # 1) Recorrido consciente de cadenas; cerrar la cadena abierta
    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) Quitar pares parciales y dos puntos o coma colgantes
    text = re.sub(r',\s*"[^"]*"\s*$', '', text)
    text = re.sub(r'[{,]\s*"[^"]*"\s*:\s*$', '}', text)
    text = re.sub(r':\s*$', '', text)
    text = re.sub(r',\s*$', '', text)
    # 3) Reescanear la pila y cerrar en LIFO
    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))

Aplicado a la entrada del principio devuelve {"scores": {...}, "items": [{"name": "a", "qty": 2}, {"name": "b"}]} con Python 3.11 y solo la biblioteca estándar. Analiza, y el tercer registro se pierde. En modelos locales, bibliotecas dedicadas como partial-json-parser hacen lo mismo: cerrar por pila, podar por completitud.

Lo esencial es divulgar. La función de cierre debe informar en qué peldaño se obtuvo el resultado; todo lo que sale del peldaño truncation es resultado parcial y debe marcarse: volver a pedir el ámbito que falta, reintentar con más límite o decir al usuario que sus datos están incompletos. Fingir que no pasó nada es fabricar alucinaciones con código determinista.

Reparar o reintentar: una tabla de frontera

Forma de la entrada Acción correcta Por qué
Vallas, comas finales, comillas simples Reparador La intención está completa, solo la sintaxis está sucia
Cortado a mitad de cadena Reintento o recuperación parcial con divulgación Falta el valor mismo
Cortado a mitad de estructura Recuperación parcial con divulgación Los campos terminados sobreviven, los pares parciales se van
Analiza pero parece mal Validación de negocio No es truncado, pero suele ocurrir a la vez

Un equipo financiero puso cifra al coste. Se truncaban facturas largas, el cierre producía JSON válido, el campo total ausente tomaba 0 por defecto, y un sistema con 98,2 % de conformidad de formato generaba unas 200 facturas erróneas al mes. Tras tratar el truncado como degradación dura y añadir una comprobación de identidad (total == suma de líneas), la tasa de error monetario bajó del 0,8 % al 0,02 %, mientras la conformidad de formato solo subió al 99,1 %. Tres meses optimizando "conformidad de formato" apuntaban a la métrica equivocada. Pasar el parser no es pasar el negocio.

La lista de cuatro puntos: comprueba el motivo de parada antes de analizar; dimensiona el límite por p99 y no como presupuesto; pon los campos críticos del esquema delante; deja al reparador solo la suciedad de formato de respuestas completas. Con los cuatro, el truncado vuelve de corrupción silenciosa a fallo ruidoso y reintentable.

¿Puedo cerrar las llaves y usar el resultado tal cual

No. Cerrar solo garantiza legalidad sintáctica; los datos siguen siendo un fragmento con frase a medias, registros finales perdidos y valores por defecto en lugar de los reales. Marca la salida como parcial, dispara reintento o degradación y registra la tasa de recuperación.

¿Cómo distingo un truncado de un error de sintaxis real

Lee el motivo de parada en los metadatos: max_tokens, length o incomplete es truncado; end_turn o stop con fallo de análisis es daño real de sintaxis. Sin metadatos, mira el final: cortado dentro de comillas o llaves con la estructura externa sin cerrar casi siempre es truncado.

¿Por qué un truncado reparado es más peligroso que un fallo ruidoso

El reparador optimiza "que analice", y un truncado cerrado analiza, así que el monitoreo calla y la validación posterior pasa gracias a los valores por defecto. Así, 83 informes truncados produjeron solo 4 errores. La herramienta no tiene noción de intención y no sabe qué falta, así que el truncado debe interceptarse aguas arriba.

¿Subir max_tokens cuesta más dinero

No. El cobro sigue los tokens realmente generados; el límite es solo una barandilla. 4096 sobre 1100 tokens generados cuesta exactamente igual que 1500. Ajusta por el p99 real con margen e invierte en evitar generaciones desbocadas.

Referencias

Herramientas relacionadas

Artículos relacionados

Guía de reparación JSON: rescatar salidas rotas de LLM sin perder confianza

Salidas de LLM envueltas en cercas de markdown, con comas finales y literales de Python, no sobreviven a un parser estricto — igual que configuraciones editadas a mano sin comillas. Esta guía traza la frontera real entre nueve clases de errores que un reparador corrige y cuatro que nunca corregirá, explica por qué una máquina de estados vence a las regex, y entrega una cadena de parseo lista para producción con jsonrepair y json-repair.

Intermedio~6 min de lecturaActualizado el 2026-11-08

Guía del formato TOON: aligerar el JSON antes de dárselo a un LLM

Al pasar un array uniforme a un modelo de lenguaje en JSON, los nombres de clave repetidos y los corchetes consumen tokens. TOON declara la estructura una sola vez mediante objetos indentados y arrays tabulares, y despliega los datos línea por línea. Los benchmarks oficiales muestran cerca de un 40 % menos de tokens con mayor precisión de análisis. Esta guía cubre la sintaxis, cuándo aplican los ahorros, cuándo no conviene convertir y cómo conectar encode y decode.

Intermedio~6 min de lecturaActualizado el 2026-11-10

Tests de contrato con JSON Schema: soldar las reglas de validación en CI

Un esquema no termina cuando se escribe — ahí es donde empieza a degradarse. Una errata relaja la validación en silencio, una refactorización rompe todos los fixtures. Esta guía disecciona un sistema de tests de contrato que se puede ejecutar: fixtures positivos, negativos y de snapshot, lint del propio esquema, compilación única con reutilización y cuatro gates de CI que convierten los cambios que rompen contratos en builds rojos.

Intermedio~8 min de lecturaActualizado el 2026-11-05