Instructor est une bibliothèque Python qui transforme les réponses d’un LLM en objets Pydantic validés et peut relancer la requête quand la validation échoue. Elle modifie le client OpenAI, et sa documentation couvre les serveurs compatibles OpenAI via base_url. BroadNet Inference sert les chat completions à https://inference.broadnet.ai/v1 et indique les outils et la sortie structurée pour GLM 5.3 et Qwen3.8 27B. BroadRouter est le site de BroadNet ; ce guide suit la documentation d’Instructor dans sa version 1.17.0.
Installation
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
Extraire un objet
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 transforme Invoice en schéma d’outil, oblige le modèle à l’appeler via tool_choice et valide les arguments. Passez max_retries pour fixer combien de fois il redemande, en joignant l’erreur de validation, quand l’objet n’est pas valide.
Ou utiliser 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 partie openai/ choisit le client. Le reste, broadnet/glm-5.3, est envoyé comme ID de modèle.
Quel mode ?
| Mode | Ce qu’il envoie | Avec BroadNet |
|---|---|---|
Mode.TOOLS (par défaut) |
Un appel d’outil forcé avec votre schéma | Oui, sur GLM 5.3 ou Qwen3.8 27B |
Mode.JSON_SCHEMA |
Un response_format de type json_schema |
Oui, sur GLM 5.3 ou Qwen3.8 27B |
Mode.MD_JSON |
Une requête simple ; JSON extrait du texte | Solution de repli pour les autres modèles ; à tester d’abord |
Mode.RESPONSES_TOOLS |
L’API Responses | Non : BroadNet sert chat completions |
Images
Qwen3.8 27B accepte les images en plus des outils et peut donc lire une photo ou un scan directement dans votre modèle :
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}},
]}],
)
Avec une clé à l’usage, une image compte comme des tokens d’entrée. Voir lire des factures arabes avec la vision.
Comment nous l’avons testé
Le 15 novembre 2026, nous avons installé instructor 1.17.0 avec openai 3.3.0 dans un environnement virtuel vierge et exécuté les exemples ci-dessus contre un serveur fictif local qui parle le format chat completions de BroadNet. Nous avons lu les requêtes journalisées. Mode.TOOLS a envoyé le schéma comme outil avec un tool_choice forcé, Mode.JSON_SCHEMA a envoyé un format de réponse json_schema, et les deux ont renvoyé un Invoice valide. from_provider a envoyé l’ID de modèle inchangé. Notre serveur fictif n’écrit pas de JSON en texte libre : nous n’avons donc pas testé Mode.MD_JSON, ni envoyé l’exemple d’image. Faute de clé BroadNet, nous n’avons pas testé de vraie sortie de modèle.
Dépannage
- Des relances de validation qui n’aboutissent jamais. Sur GLM 5.3 et Qwen3.8 27B, le raisonnement est décompté de
max_tokens. Une limite basse peut tronquer les arguments de l’outil. Augmentez-la. Pourquoi les réponses reviennent vides. - 400 sur la requête. Vérifiez que vous utilisez GLM 5.3 ou Qwen3.8 27B. Si un
tool_choiceforcé est refusé, essayezMode.JSON_SCHEMA. - 401. La clé est erronée, a expiré ou a épuisé son allocation.
- 404.
base_urldoit se terminer par/v1. GLM 5.3 et Qwen3.8 27B nécessitent une recharge ; le crédit de $5 ne les couvre pas. - 429 en extraction par lots. Une clé à l’usage autorise 30 requêtes par minute et 4 requêtes en cours. Chaque relance de validation est une requête de plus. Voir codes d’erreur et nouvelles tentatives.
