BroadRouter
Comenzar

Salida estructurada con Instructor en BroadNet Inference

Actualizado

Envuelva con instructor.from_openai un cliente de OpenAI con base_url https://inference.broadnet.ai/v1 y su clave de BroadNet, y llame a chat.completions.create con response_model igual a su clase Pydantic y model en broadnet/glm-5.3 o broadnet/qwen3.8-27b. Son los dos modelos para los que BroadNet indica herramientas y salida estructurada. Mode.TOOLS es el modo predeterminado; Mode.JSON_SCHEMA también funciona.

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_choice forzado, pruebe Mode.JSON_SCHEMA.
  • 401. La clave es incorrecta, caducó o se quedó sin saldo.
  • 404. base_url debe 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.

Preguntas frecuentes

¿Qué modo de Instructor debo usar con BroadNet?

Mode.TOOLS, el predeterminado, con GLM 5.3 o Qwen3.8 27B, para los que BroadNet indica herramientas y salida estructurada. Mode.JSON_SCHEMA envía en su lugar un response_format de tipo json_schema. Ambos produjeron objetos válidos en nuestra prueba con un servidor simulado (mock).

¿Puedo usar Mode.RESPONSES_TOOLS?

No. La documentación de Instructor indica no elegirlo salvo que el servidor implemente la Responses API. BroadNet solo sirve chat completions.

¿Instructor funciona con DeepSeek V4.1 Flash o Gemma en BroadNet?

BroadNet no indica herramientas ni salida estructurada para esos modelos. Mode.MD_JSON pide JSON en texto plano y lo interpreta, lo que puede funcionar, pero pruébelo con sus propios datos antes de depender de él.

¿Cómo escribo la cadena del modelo para from_provider?

Use openai/broadnet/glm-5.3. Instructor separa el primer segmento como proveedor y, en nuestra prueba, envió broadnet/glm-5.3 al servidor sin cambios.

Leer en MarkdownPreguntar a ChatGPTPreguntar a ClaudePreguntar a Perplexity