Instructor es una biblioteca de Python que convierte las respuestas de un LLM en objetos Pydantic validados y puede reintentar cuando la validación falla. Modifica (patch) el cliente de OpenAI, y su documentación cubre servidores compatibles con OpenAI mediante base_url. BroadNet Inference sirve chat completions en https://inference.broadnet.ai/v1 e indica herramientas y salida estructurada para GLM 5.3 y Qwen3.8 27B. BroadRouter es el sitio de la propia BroadNet; esta guía sigue la documentación de Instructor en su versión 1.17.0.
Instalación
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
Extraer un objeto
import os
import instructor
from openai import OpenAI
from pydantic import BaseModel
class Invoice(BaseModel):
vendor: str
total: float
currency: str
client = instructor.from_openai(
OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"]),
mode=instructor.Mode.TOOLS,
)
invoice = client.chat.completions.create(
model="broadnet/glm-5.3",
response_model=Invoice,
max_tokens=4000,
messages=[{"role": "user", "content": "Acme Trading invoice, total 1,250.00 SAR"}],
)
print(invoice)
Instructor convierte Invoice en un esquema de herramienta, obliga al modelo a llamarla con tool_choice y valida los argumentos. Pase max_retries para controlar cuántas veces vuelve a preguntar, junto con el error de validación, cuando el objeto no valida.
O use from_provider
pclient = instructor.from_provider(
"openai/broadnet/glm-5.3",
base_url="https://inference.broadnet.ai/v1",
api_key=os.environ["BROADNET_API_KEY"],
)
invoice = pclient.create(response_model=Invoice, max_tokens=4000,
messages=[{"role": "user", "content": "Acme Trading, 1,250.00 SAR"}])
La parte openai/ elige el cliente. El resto, broadnet/glm-5.3, se envía como ID del modelo.
Qué modo elegir
| Mode | Qué envía | Uso con BroadNet |
|---|---|---|
Mode.TOOLS (predeterminado) |
Una llamada a herramienta forzada con su esquema | Sí, con GLM 5.3 o Qwen3.8 27B |
Mode.JSON_SCHEMA |
response_format de tipo json_schema |
Sí, con GLM 5.3 o Qwen3.8 27B |
Mode.MD_JSON |
Una solicitud normal; el JSON se extrae del texto | Alternativa para otros modelos; pruébela antes |
Mode.RESPONSES_TOOLS |
La Responses API | No: BroadNet sirve chat completions |
Imágenes
Qwen3.8 27B acepta imágenes además de herramientas, así que puede leer una foto o un escaneo directamente en su modelo:
import base64
img = base64.b64encode(open("invoice.jpg", "rb").read()).decode()
invoice = client.chat.completions.create(
model="broadnet/qwen3.8-27b",
response_model=Invoice,
max_tokens=4000,
messages=[{"role": "user", "content": [
{"type": "text", "text": "Extract the invoice fields."},
{"type": "image_url", "image_url": {"url": "data:image/jpeg;base64," + img}},
]}],
)
Con una clave de pago por uso, una imagen cuenta como tokens de entrada. Consulte leer facturas en árabe con visión.
Cómo lo probamos
El 2026-11-15 instalamos instructor 1.17.0 con openai 3.3.0 en un entorno virtual limpio y ejecutamos los ejemplos de arriba contra un servidor simulado (mock) local que habla el formato de chat completions de BroadNet. Revisamos las solicitudes registradas. Mode.TOOLS envió el esquema como herramienta con un tool_choice forzado, Mode.JSON_SCHEMA envió un formato de respuesta json_schema, y ambos devolvieron un Invoice válido. from_provider envió el ID del modelo sin cambios. Nuestro mock no escribe JSON en texto libre, así que no probamos Mode.MD_JSON, y tampoco enviamos el ejemplo de imagen. No teníamos una clave de BroadNet, así que no probamos la salida real de un modelo.
Solución de problemas
- Reintentos de validación que nunca tienen éxito. En GLM 5.3 y Qwen3.8 27B el razonamiento cuenta dentro de
max_tokens. Un límite bajo puede cortar los argumentos de la herramienta. Auméntelo. Por qué las respuestas llegan vacías. - 400 en la solicitud. Compruebe que usa GLM 5.3 o Qwen3.8 27B. Si se rechaza un
tool_choiceforzado, pruebeMode.JSON_SCHEMA. - 401. La clave es incorrecta, caducó o se quedó sin saldo.
- 404.
base_urldebe terminar en/v1. GLM 5.3 y Qwen3.8 27B requieren una recarga; el crédito de $5 no los cubre. - 429 en extracción por lotes. Una clave de pago por uso permite 30 solicitudes por minuto y 4 simultáneas. Cada reintento de validación es otra solicitud. Consulte errores y reintentos.
