Instructor, LLM yanıtlarını doğrulanmış Pydantic nesnelerine dönüştüren ve doğrulama başarısız olduğunda yeniden deneyebilen bir Python kütüphanesidir. OpenAI istemcisini yamalar ve belgeleri OpenAI uyumlu sunucuları base_url üzerinden ele alır. BroadNet Inference chat completions isteklerini https://inference.broadnet.ai/v1 adresinde sunar ve araçlarla yapılandırılmış çıktıyı GLM 5.3 ve Qwen3.8 27B için listeler. BroadRouter, BroadNet’in kendi sitesidir; bu rehber Instructor’ın 1.17.0 sürümü itibarıyla belgelerini izler.
Kurulum
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
Bir nesne çıkarın
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 Invoice sınıfını bir araç şemasına dönüştürür, tool_choice ile modeli bu aracı çağırmaya zorlar ve argümanları doğrular. Nesne doğrulanmadığında doğrulama hatasıyla kaç kez yeniden soracağını max_retries ile belirleyin.
Ya da from_provider kullanın
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"}])
openai/ kısmı istemciyi seçer. Geri kalanı, yani broadnet/glm-5.3, model kimliği olarak gönderilir.
Hangi mod
| Mod | Ne gönderir | BroadNet ile kullanım |
|---|---|---|
Mode.TOOLS (varsayılan) |
Şemanızla zorunlu bir araç çağrısı | Evet, GLM 5.3 veya Qwen3.8 27B üzerinde |
Mode.JSON_SCHEMA |
json_schema türünde response_format |
Evet, GLM 5.3 veya Qwen3.8 27B üzerinde |
Mode.MD_JSON |
Düz bir istek; JSON metinden ayrıştırılır | Diğer modeller için yedek yol; önce test edin |
Mode.RESPONSES_TOOLS |
Responses API | Hayır: BroadNet chat completions sunar |
Görseller
Qwen3.8 27B araçların yanında görsel de kabul eder; bu yüzden bir fotoğrafı veya taramayı doğrudan modelinize okuyabilir:
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}},
]}],
)
Kullandıkça öde anahtarında bir görsel girdi token’ı olarak sayılır. Arapça faturaları görüntü işlemeyle okuma rehberine bakın.
Bunu nasıl test ettik
2026-11-15’te instructor 1.17.0’ı openai 3.3.0 ile temiz bir sanal ortama kurduk ve yukarıdaki örnekleri BroadNet’in chat completions yapısını konuşan yerel bir mock sunucuya karşı çalıştırdık. Kaydedilen istekleri okuduk. Mode.TOOLS şemayı zorunlu bir tool_choice ile araç olarak gönderdi, Mode.JSON_SCHEMA ise json_schema türünde bir yanıt biçimi gönderdi; ikisi de geçerli bir Invoice döndürdü. from_provider model kimliğini değiştirmeden gönderdi. Mock sunucumuz serbest metin JSON yazmadığı için Mode.MD_JSON’u test etmedik; görsel örneğini de göndermedik. Elimizde bir BroadNet anahtarı yoktu; bu yüzden gerçek model çıktısını test etmedik.
Sorun giderme
- Hiç başarılı olmayan doğrulama denemeleri. GLM 5.3 ve Qwen3.8 27B’de akıl yürütme
max_tokenssınırına dahildir. Düşük bir sınır araç argümanlarını yarıda kesebilir. Değeri artırın. Yanıtlar neden boş geliyor. - İstekte 400. GLM 5.3 veya Qwen3.8 27B kullandığınızı kontrol edin. Zorunlu
tool_choicereddedilirseMode.JSON_SCHEMA’yı deneyin. - 401. Anahtar yanlış, süresi dolmuş veya kullanım hakkı tükenmiş.
- 404.
base_url/v1ile bitmelidir. GLM 5.3 ve Qwen3.8 27B bakiye yüklemesi gerektirir; $5 kredi bunları kapsamaz. - Toplu veri çıkarmada 429. Kullandıkça öde anahtarı dakikada 30 isteğe ve işlemde aynı anda 4 isteğe izin verir. Her doğrulama denemesi ayrı bir istektir. Hatalar ve yeniden denemeler rehberine bakın.
