---
title: "Modo JSON vs JSON Schema: salida estructurada, con código"
description: "El modo JSON da JSON válido; json_schema da su estructura. Cómo pedir cada uno en modelos compatibles con OpenAI, validar con Pydantic y reparar errores en un bucle."
url: https://broadrouter.com/es/blog/structured-output-json-schema/
lang: es
updated: 2026-11-14
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Traducido del inglés con ayuda de IA. [Lea el original en inglés](https://broadrouter.com/blog/structured-output-json-schema/) (actualizado el 2026-11-14).

# Modo JSON o json\_schema: salida estructurada que no falla

Por el equipo de BroadNet Inference · 4 min de lectura · Publicado 2026-11-14

El modo JSON (response\_format json\_object) solo promete JSON válido. La salida estructurada (response\_format json\_schema) promete además sus campos y tipos, cuando el proveedor la aplica. En ambos casos, compruebe finish\_reason, analice el JSON y valídelo contra un esquema, como un modelo de Pydantic. Si la validación falla, devuelva el error y vuelva a pedirlo, con un límite estricto de intentos.

## Puntos clave

-   Guía de OpenAI: ambos modos producen JSON válido, pero "only Structured Outputs ensure schema adherence" (Traducción: «solo las Structured Outputs garantizan que se respete el esquema»).
-   El soporte varía entre los proveedores compatibles con OpenAI. Pruebe primero json\_schema, luego json\_object y después solo el prompt.
-   Valide cada respuesta. Una respuesta cortada por max\_tokens es JSON roto, diga lo que diga el esquema.
-   Los bucles de reparación funcionan cuando devuelve el error de validación exacto. Limítelos a dos o tres intentos.
-   En BroadNet Inference, GLM 5.3 y Qwen3.8 27B listan salida estructurada.

**En esta página**

1.  ¿Qué diferencia hay entre el modo JSON y json\_schema?
2.  ¿Cómo se pide json\_schema?
3.  ¿Qué modo admite su proveedor?
4.  ¿Cómo se valida y se repara una salida incorrecta?
5.  ¿Qué funcionalidades del esquema dan problemas?
6.  ¿Cómo se supervisa la salida estructurada en producción?
7.  ¿Cuándo conviene usar una herramienta?
8.  Dónde encaja BroadNet Inference

Su código necesita datos, y los modelos escriben texto. La [salida estructurada](https://broadrouter.com/es/glossary/structured-output/) cierra esa brecha, pero «el modelo devuelve JSON» significa tres cosas distintas según cómo lo pida. Este artículo compara las opciones en modelos abiertos compatibles con OpenAI, muestra cómo pedir cada una y ofrece un bucle de validación y reparación que puede llevar directamente a producción.

## ¿Qué diferencia hay entre el modo JSON y json\_schema?

| Método | Solicitud | Qué se le garantiza |
| --- | --- | --- |
| Solo el prompt | «Responda en JSON con los campos…» | Nada; normalmente JSON, a veces con texto adicional |
| Modo JSON | `response_format: {"type": "json_object"}` | JSON válido, con cualquier forma |
| Salida estructurada | `response_format: {"type": "json_schema", ...}` | JSON que cumple su esquema, cuando se aplica |

La guía de Structured Outputs de OpenAI lo dice sin rodeos: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (Traducción: «Aunque ambos garantizan que se produzca JSON válido, solo las Structured Outputs garantizan que se respete el esquema».) Recomienda la salida estructurada en lugar del modo JSON siempre que sea posible.

En los proveedores de modelos abiertos, la garantía depende de cómo la implemente el servidor. Muchos usan decodificación restringida (constrained decoding), que bloquea los tokens que romperían el esquema. Algunos aceptan el campo pero no lo aplican. Por eso el código de abajo valida de todos modos.

## ¿Cómo se pide json\_schema?

```python
import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}
```

Pydantic genera el JSON Schema a partir de su clase, así que el esquema y el validador nunca se desincronizan. Si no usa Pydantic, el [generador de JSON Schema](https://broadrouter.com/tools/json-schema-generator/) crea un esquema en modo estricto a partir de un objeto de ejemplo. Para el modo estricto, OpenAI exige `additionalProperties: false` y que todas las propiedades figuren como obligatorias.

## ¿Qué modo admite su proveedor?

Ejecute esta prueba una vez por modelo antes de construir sobre él:

1.  Envíe `json_schema` con un prompt que invite a añadir un campo extra («añada también un comentario breve»).
2.  Si la solicitud da error, el proveedor no acepta `json_schema`. Pruebe `json_object`.
3.  Si la respuesta contiene el campo extra, el esquema no se aplica. Trátelo como modo JSON.
4.  Si `json_object` también da error, use solo el prompt, con validación.

En BroadNet Inference, la documentación lista salida estructurada para [GLM 5.3](https://broadrouter.com/es/models/glm-5.3/) y [Qwen3.8 27B](https://broadrouter.com/es/models/qwen3.8-27b/) ([comparados lado a lado](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)), pero no nombra el parámetro de la solicitud. Ejecute la prueba anterior con el modelo que vaya a usar en producción.

## ¿Cómo se valida y se repara una salida incorrecta?

```python
import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")
```

Qué hace que este bucle funcione:

-   **Compruebe primero `finish_reason`.** Una respuesta que llegó a [`max_tokens`](https://broadrouter.com/es/glossary/max-tokens/) es JSON truncado. Reintentar con el mismo límite falla igual. Ambos modelos de arriba razonan antes de responder, y [el razonamiento cuenta para el límite](https://broadrouter.com/es/guides/reasoning-tokens-empty-response/), así que deje margen.
-   **Trate los rechazos por separado.** La guía de OpenAI señala que un rechazo “does not necessarily follow the schema you have supplied” (Traducción: «no sigue necesariamente el esquema que usted proporcionó»).
-   **Devuelva el error exacto.** Un reintento a ciegas suele repetir el mismo fallo. «line\_items: field required» le da al modelo algo concreto que corregir.
-   **Compruebe las reglas de negocio en el código.** Un esquema no puede decir que un total debe ser igual a la suma de sus partidas. La comprobación de arriba sí puede.
-   **Limite los intentos.** Cada intento reenvía todo el prompt como [tokens de entrada](https://broadrouter.com/es/glossary/input-and-output-tokens/).

## ¿Qué funcionalidades del esquema dan problemas?

Mantenga los esquemas aburridos:

1.  **Plano mejor que anidado.** Dos niveles bastan para la mayoría de las extracciones.
2.  **Enums en lugar de cadenas libres** para las categorías.
3.  **Nada de objetos abiertos.** Los campos `dict` libres anulan el propósito.
4.  **Nombres de campo cortos con descripciones.** Las descripciones del esquema guían al modelo.
5.  **Campos opcionales como anulables.** En modo estricto, liste todos los campos como obligatorios y permita `null`.

La guía de OpenAI señala que algunas funcionalidades de JSON Schema no se admiten en modo estricto. Los servidores de modelos abiertos tienen sus propios límites. Si se rechaza un esquema, simplifíquelo antes de cambiar de modo.

## ¿Cómo se supervisa la salida estructurada en producción?

Un bucle que repara en silencio puede ocultar un problema que le cuesta tokens todos los días. Registre tres números por punto de llamada:

| Métrica | Qué le indica |
| --- | --- |
| Tasa de éxito en el primer intento | Qué tan bien encajan el modelo y el esquema; una caída suele seguir a un cambio de prompt o de modelo |
| Promedio de intentos por éxito | El costo en tokens de las reparaciones |
| Fallos finales | Entradas que su pipeline no puede manejar; revíselas a mano |

Si el éxito en el primer intento cae por debajo de lo habitual, simplifique el esquema o pruebe otro modelo antes de añadir más reintentos. Guarde una muestra de respuestas en bruto fallidas, para probar las correcciones con casos reales.

## ¿Cuándo conviene usar una herramienta?

Use salida estructurada para la **respuesta final**: una extracción, una clasificación, un plan. Use [llamadas a herramientas](https://broadrouter.com/es/blog/tool-calling-open-models/) cuando el modelo necesite que su código **haga** algo y luego continúe. Muchos agentes usan ambas: herramientas durante el bucle y un esquema para el último paso. Para un ejemplo de imagen a JSON, consulte [leer facturas en árabe con un modelo de visión](https://broadrouter.com/es/guides/read-arabic-invoices-with-vision/).

## Dónde encaja BroadNet Inference

BroadNet Inference lista salida estructurada para GLM 5.3 y Qwen3.8 27B, con el formato estándar de chat completions, así que el código de arriba funciona sin cambios con el [SDK de OpenAI para Python](https://broadrouter.com/es/guides/openai-python-sdk/). Qwen3.8 27B también acepta imágenes, lo que encaja con la extracción de documentos. La documentación de BroadNet no indica salida estructurada para DeepSeek V4.1 Flash ni para Gemma 4 VL 26B, así que en esos modelos use la vía de solo prompt con validación. Compare los precios por token en la [página de precios](https://broadrouter.com/es/pricing/).

Herramientas gratuitas sobre este tema (en inglés)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Herramientas gratuitas (en inglés)](https://broadrouter.com/tools/)

## Términos de este artículo

[Salida estructurada (structured output)](https://broadrouter.com/es/glossary/structured-output/)

La salida estructurada es una función de las APIs de LLM que restringe la respuesta del modelo a un formato que define el desarrollador, normalmente un JSON Schema, para que el código pueda procesarla de forma fiable. Es más estricta que JSON mode, que garantiza JSON válido pero no una forma concreta.

[Token](https://broadrouter.com/es/glossary/token/)

Un token es la unidad de texto que un modelo de lenguaje lee y escribe: una palabra, parte de una palabra, un signo de puntuación o una secuencia de bytes producida por el tokenizador del modelo. Las APIs de LLM cuentan, limitan y normalmente facturan el uso en tokens.

[JSON Schema (esquema JSON)](https://broadrouter.com/es/glossary/json-schema/)

JSON Schema es un vocabulario, escrito en JSON, para describir y validar la estructura de datos JSON: tipos, campos obligatorios, valores permitidos y anidamiento. La versión actual es la 2020-12. Las APIs de LLM lo usan para definir los parámetros de las herramientas y la forma exacta que debe seguir una salida estructurada.

[JSON mode (modo JSON)](https://broadrouter.com/es/glossary/json-mode/)

El modo JSON (JSON mode) es un ajuste de las APIs de LLM, response\_format {"type": "json\_object"} en las APIs al estilo de OpenAI, que hace que la respuesta del modelo sea JSON válido y procesable. A diferencia de la salida estructurada con un JSON Schema, no garantiza qué claves, tipos o valores contiene el objeto.

[Llamadas a herramientas (tool calling)](https://broadrouter.com/es/glossary/tool-calling/)

Las llamadas a herramientas (tool calling), también llamadas function calling, son una función de las APIs de LLM en la que el modelo devuelve una solicitud estructurada para ejecutar una función definida por el desarrollador, con argumentos JSON. La aplicación ejecuta la función y devuelve el resultado; el modelo nunca ejecuta código.

[API de Chat Completions](https://broadrouter.com/es/glossary/chat-completions-api/)

La API de Chat Completions es el endpoint HTTP de OpenAI, POST /v1/chat/completions, que recibe un nombre de modelo y una lista de mensajes etiquetados con su rol y devuelve el siguiente mensaje del modelo. Su forma de solicitud y respuesta se convirtió en el formato común que reutilizan los proveedores y SDKs compatibles con OpenAI.

[Modelo de visión y lenguaje (VLM)](https://broadrouter.com/es/glossary/vision-language-model/)

Un modelo de visión y lenguaje (VLM) es un modelo que recibe imágenes y texto a la vez y produce texto, por lo que puede describir imágenes, responder preguntas sobre ellas y leer documentos, gráficos o capturas de pantalla. También se les llama modelos image-text-to-text o multimodales.

[Prefill y decode (fases de inferencia de un LLM)](https://broadrouter.com/es/glossary/prefill-and-decode/)

Prefill y decode son las dos fases de la inferencia de un LLM. En el prefill, el modelo procesa todo el prompt en paralelo y llena su caché KV; en el decode, genera la respuesta token a token reutilizando esa caché. El prefill determina sobre todo el tiempo hasta el primer token; el decode, la velocidad de salida.

## Preguntas frecuentes

### ¿Qué diferencia hay entre el modo JSON y la salida estructurada?

El modo JSON, response\_format de tipo json\_object, solo promete que la respuesta se puede analizar como JSON. La salida estructurada, de tipo json\_schema, promete además los campos y tipos que usted definió, cuando el proveedor la aplica. OpenAI recomienda la salida estructurada en lugar del modo JSON siempre que sea posible.

### ¿Los modelos abiertos admiten response\_format json\_schema?

Depende del proveedor. Algunos aceptan json\_schema, otros solo json\_object y otros ignoran el campo. Envíe una solicitud de prueba con un esquema y un prompt que tiente al modelo a añadir un campo extra, y luego revise la respuesta.

### ¿Sigo necesitando validar la salida estructurada?

Sí. Las respuestas pueden cortarse por max\_tokens, pueden ser rechazos y pueden incumplir reglas de negocio que un esquema no puede expresar, como totales que deben cuadrar.

### ¿Cuántas veces debo reintentar un JSON no válido?

Dos o tres intentos incluyendo el error de validación suelen bastar. Después, registre la entrada y envíela a una alternativa: un modelo más potente o una persona. Los bucles sin límite desperdician tokens.

### ¿Debo usar salida estructurada o llamadas a herramientas?

Use salida estructurada cuando quiera la respuesta final con una forma fija. Use llamadas a herramientas cuando el modelo necesite que su código haga algo y luego continuar.

## Siga leyendo

-   [Clasificar texto en árabe con un LLM: sentimiento, intención, triaje](https://broadrouter.com/es/blog/arabic-text-classification-llm/)
-   [Tool calling con modelos abiertos: esquemas, paralelismo, reintentos](https://broadrouter.com/es/blog/tool-calling-open-models/)
-   [Cambiar a una API compatible con OpenAI: lista de verificación](https://broadrouter.com/es/blog/openai-compatible-api-migration-checklist/)
-   [AI Agent de n8n con un LLM barato: configuración, modelo y costo](https://broadrouter.com/es/blog/n8n-ai-agent-cheap-llm/)
-   [Cómo corregir JSON inválido de un LLM: causas, reparación y reintento](https://broadrouter.com/es/blog/fix-invalid-json-from-llm/)
-   [Extracción de entidades nombradas en árabe con un LLM: JSON y fechas](https://broadrouter.com/es/blog/arabic-named-entity-extraction-llm/)
-   [El hardware GPU de BroadNet y cómo sirve los modelos, según BroadNet](https://broadrouter.com/es/blog/broadnet-gpu-fleet-and-serving/)
-   [Caché de respuestas de APIs de LLM para reducir costos en Python](https://broadrouter.com/es/blog/cache-llm-responses-cut-cost/)
-   [Guía: Usar el SDK de OpenAI para Python con BroadNet Inference](https://broadrouter.com/es/guides/openai-python-sdk/)
-   [Guía: Lea facturas y recibos en árabe con un modelo de visión](https://broadrouter.com/es/guides/read-arabic-invoices-with-vision/)
-   [Guía: ¿Por qué un modelo de razonamiento devuelve una respuesta vacía?](https://broadrouter.com/es/guides/reasoning-tokens-empty-response/)

Pruébelo con su carga de trabajo real. Las cuentas nuevas empiezan con USD 5 de crédito para Gemma y transcripción. DeepSeek, GLM y Qwen3.8 requieren una recarga.

[Comenzar](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=es-blog-structured-output-json-schema&utm_content=page-cta) ·

**Fuentes**

-   [OpenAI, guía de Structured Outputs (consultado el 2026-11-14)](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [Referencia de la API de OpenAI, crear chat completion (response\_format)](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [Documentación de Pydantic, JSON Schema y validación](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [Referencia de la API de BroadNet Inference, modelos (en inglés)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=es-blog-structured-output-json-schema&utm_content=sources#models)
