---
title: "Instructor con base_url compatible con OpenAI (Pydantic)"
description: "Extraiga objetos Pydantic de BroadNet Inference con Instructor, mediante from_openai o from_provider con un base_url propio, y elija el Mode adecuado."
url: https://broadrouter.com/es/guides/instructor-structured-output/
lang: es
updated: 2026-11-16
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/guides/instructor-structured-output/) (actualizado el 2026-11-16).

# Salida estructurada con Instructor en BroadNet Inference

Actualizado 2026-11-16

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

```bash
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
```

## Extraer un objeto

```python
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

```python
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:

```python
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](https://broadrouter.com/es/guides/read-arabic-invoices-with-vision/).

## 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](https://broadrouter.com/es/guides/reasoning-tokens-empty-response/).
-   **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](https://broadrouter.com/es/guides/errors-and-retries/).

## Términos de esta guía

[Pago por uso (pay-as-you-go)](https://broadrouter.com/es/glossary/pay-as-you-go/)

El pago por uso es un modelo de precios en el que usted paga solo lo que usa, medido por unidades como tokens, solicitudes o minutos de audio, sin suscripción ni compromiso mínimo. La mayoría de las APIs de LLM cobran así, desde un saldo prepagado o con una factura periódica.

[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.

[Concurrencia (concurrency)](https://broadrouter.com/es/glossary/concurrency/)

La concurrencia es el número de solicitudes que un cliente tiene en curso al mismo tiempo. Las APIs de LLM suelen limitarla por clave o por plan, aparte de las solicitudes por minuto, porque cada solicitud abierta ocupa capacidad de GPU hasta que su respuesta termina.

[Límite de frecuencia (rate limit)](https://broadrouter.com/es/glossary/rate-limit/)

Un límite de frecuencia (rate limit) es un tope que una API impone a cuánto puede usarla un cliente en un periodo, como solicitudes por minuto o tokens por minuto. Las solicitudes que lo superan se rechazan, normalmente con HTTP 429 Too Many Requests, hasta que el uso vuelve a quedar por debajo.

[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.

[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.

[Crédito prepago (prepaid credit)](https://broadrouter.com/es/glossary/prepaid-credit/)

El crédito prepago es dinero que se añade a una cuenta de API antes de usarla. Cada solicitud descuenta su coste del saldo y, cuando el saldo se agota, las solicitudes medidas se detienen hasta que usted recargue. Limita el gasto a lo que ha pagado.

[Plantilla de chat (chat template)](https://broadrouter.com/es/glossary/chat-template/)

Una plantilla de chat es la regla de formato, normalmente escrita en Jinja e incluida con el tokenizador de un modelo, que convierte una lista de mensajes de chat con roles en la única secuencia de tokens que el modelo espera, incluidos sus tokens de control especiales. Usar la plantilla equivocada puede empeorar mucho las respuestas del modelo.

## 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.

## Guías relacionadas

-   [Usar el SDK de OpenAI para Python con BroadNet Inference](https://broadrouter.com/es/guides/openai-python-sdk/)
-   [Pydantic AI con BroadNet Inference (OpenAICompatibleProvider)](https://broadrouter.com/es/guides/pydantic-ai-openai-compatible/)
-   [Lea facturas y recibos en árabe con un modelo de visión](https://broadrouter.com/es/guides/read-arabic-invoices-with-vision/)
-   [¿Por qué un modelo de razonamiento devuelve una respuesta vacía?](https://broadrouter.com/es/guides/reasoning-tokens-empty-response/)
-   [Todas las herramientas que funcionan con BroadNet Inference (en inglés)](https://broadrouter.com/integrations/): SDK, agentes de programación, interfaces de chat y herramientas de automatización, con la configuración exacta de cada una

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-guides-instructor-structured-output&utm_content=page-cta) ·

**Fuentes**

-   [Documentación de Instructor, OpenAI y servidores compatibles con OpenAI (consultada el 2026-11-15)](https://python.useinstructor.com/integrations/openai/)
-   [PyPI, instructor 1.17.0 (consultado el 2026-11-15)](https://pypi.org/project/instructor/)
-   [Referencia de la API de BroadNet Inference (consultada el 2026-11-15) (en inglés)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=es-guides-instructor-structured-output&utm_content=sources)
