Instructor adalah library Python yang mengubah balasan LLM menjadi objek Pydantic yang tervalidasi dan bisa mencoba ulang saat validasi gagal. Library ini mem-patch klien OpenAI, dan dokumentasinya membahas server yang kompatibel dengan OpenAI lewat base_url. BroadNet Inference menyajikan chat completions di https://inference.broadnet.ai/v1, dan mencantumkan tools serta output terstruktur untuk GLM 5.3 dan Qwen3.8 27B. BroadRouter adalah situs milik BroadNet sendiri; panduan ini mengikuti dokumentasi Instructor per versi 1.17.0.
Instalasi
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
Mengekstrak objek
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 mengubah Invoice menjadi skema tool, memaksa model memanggilnya dengan tool_choice, lalu memvalidasi argumennya. Atur max_retries untuk menentukan berapa kali Instructor bertanya lagi, dengan menyertakan error validasinya, saat objek tidak lolos validasi.
Atau pakai 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"}])
Bagian openai/ memilih kliennya. Sisanya, broadnet/glm-5.3, dikirim sebagai ID model.
Mode mana
| Mode | Yang dikirim | Pakai dengan BroadNet |
|---|---|---|
Mode.TOOLS (default) |
Tool call wajib dengan skema Anda | Ya, di GLM 5.3 atau Qwen3.8 27B |
Mode.JSON_SCHEMA |
response_format bertipe json_schema |
Ya, di GLM 5.3 atau Qwen3.8 27B |
Mode.MD_JSON |
Permintaan biasa; JSON di-parse dari teks | Cadangan untuk model lain; uji dulu |
Mode.RESPONSES_TOOLS |
Responses API | Tidak: BroadNet menyajikan chat completions |
Gambar
Qwen3.8 27B menerima gambar sekaligus tools, jadi model ini bisa membaca foto atau hasil scan langsung ke model Pydantic Anda:
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}},
]}],
)
Pada kunci bayar sesuai pemakaian, gambar dihitung sebagai token input. Lihat membaca invoice berbahasa Arab dengan vision.
Cara kami mengujinya
Pada 2026-11-15 kami menginstal instructor 1.17.0 bersama openai 3.3.0 di virtual environment yang bersih dan menjalankan contoh-contoh di atas terhadap mock server lokal yang meniru format chat completions BroadNet. Kami membaca log permintaannya. Mode.TOOLS mengirim skema sebagai tool dengan tool_choice wajib, Mode.JSON_SCHEMA mengirim format respons json_schema, dan keduanya mengembalikan Invoice yang valid. from_provider mengirim ID model tanpa perubahan. Mock kami tidak menulis JSON dalam teks bebas, jadi Mode.MD_JSON tidak kami uji, dan contoh gambar tidak kami kirim. Kami tidak punya kunci BroadNet, jadi output model sungguhan tidak kami uji.
Pemecahan masalah
- Percobaan ulang validasi yang tidak pernah berhasil. Pada GLM 5.3 dan Qwen3.8 27B, penalaran ikut dihitung dalam
max_tokens. Batas yang rendah bisa memotong argumen tool. Naikkan nilainya. Kenapa jawaban kembali kosong. - 400 pada permintaan. Pastikan Anda memakai GLM 5.3 atau Qwen3.8 27B. Jika
tool_choicewajib ditolak, cobaMode.JSON_SCHEMA. - 401. Kuncinya salah, kedaluwarsa, atau jatahnya habis.
- 404.
base_urlharus diakhiri/v1. GLM 5.3 dan Qwen3.8 27B memerlukan top up; kredit $5 tidak mencakupnya. - 429 saat ekstraksi batch. Kunci bayar sesuai pemakaian mengizinkan 30 permintaan per menit dan 4 permintaan yang berjalan bersamaan. Setiap percobaan ulang validasi adalah satu permintaan lagi. Lihat panduan error dan percobaan ulang.
