Su código necesita datos, y los modelos escriben texto. La salida estructurada 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?
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 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:
- Envíe
json_schemacon un prompt que invite a añadir un campo extra («añada también un comentario breve»). - Si la solicitud da error, el proveedor no acepta
json_schema. Pruebejson_object. - Si la respuesta contiene el campo extra, el esquema no se aplica. Trátelo como modo JSON.
- Si
json_objecttambién da error, use solo el prompt, con validación.
En BroadNet Inference, la documentación lista salida estructurada para GLM 5.3 y Qwen3.8 27B (comparados lado a lado), 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?
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ó amax_tokenses 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, 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.
¿Qué funcionalidades del esquema dan problemas?
Mantenga los esquemas aburridos:
- Plano mejor que anidado. Dos niveles bastan para la mayoría de las extracciones.
- Enums en lugar de cadenas libres para las categorías.
- Nada de objetos abiertos. Los campos
dictlibres anulan el propósito. - Nombres de campo cortos con descripciones. Las descripciones del esquema guían al modelo.
- 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 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.
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. 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.
