Instructor là thư viện Python biến câu trả lời của LLM thành đối tượng Pydantic đã được kiểm tra hợp lệ, và có thể thử lại khi kiểm tra thất bại. Nó patch OpenAI client, và tài liệu của nó có hướng dẫn cho server tương thích OpenAI qua base_url. BroadNet Inference phục vụ chat completions tại https://inference.broadnet.ai/v1, và ghi hỗ trợ tool và đầu ra có cấu trúc cho GLM 5.3 và Qwen3.8 27B. BroadRouter là trang web của chính BroadNet; bài này làm theo tài liệu Instructor ở phiên bản 1.17.0.
Cài đặt
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
Trích xuất một đối tượng
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 biến Invoice thành schema của một tool, buộc model gọi tool đó bằng tool_choice, rồi kiểm tra các tham số. Truyền max_retries để quy định số lần nó hỏi lại, kèm lỗi kiểm tra, khi đối tượng không hợp lệ.
Hoặc dùng 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"}])
Phần openai/ chọn client. Phần còn lại, broadnet/glm-5.3, được gửi làm model ID.
Chọn mode nào
| Mode | Gửi gì | Dùng với BroadNet |
|---|---|---|
Mode.TOOLS (mặc định) |
Một lệnh gọi tool bắt buộc kèm schema của bạn | Có, trên GLM 5.3 hoặc Qwen3.8 27B |
Mode.JSON_SCHEMA |
response_format kiểu json_schema |
Có, trên GLM 5.3 hoặc Qwen3.8 27B |
Mode.MD_JSON |
Một request thường; JSON được parse từ văn bản | Phương án dự phòng cho model khác; thử trước |
Mode.RESPONSES_TOOLS |
Responses API | Không: BroadNet phục vụ chat completions |
Hình ảnh
Qwen3.8 27B nhận cả hình ảnh lẫn tool, nên có thể đọc thẳng ảnh chụp hoặc bản scan vào model Pydantic của bạn:
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}},
]}],
)
Với key trả theo mức dùng, hình ảnh được tính là token đầu vào. Xem đọc hóa đơn tiếng Ả Rập bằng vision.
Chúng tôi đã kiểm thử thế nào
Ngày 2026-11-15, chúng tôi cài instructor 1.17.0 cùng openai 3.3.0 trong một virtual environment sạch và chạy các ví dụ trên với một mock server cục bộ mô phỏng định dạng chat completions của BroadNet. Chúng tôi đọc các request đã ghi log. Mode.TOOLS gửi schema dưới dạng tool với tool_choice bắt buộc, Mode.JSON_SCHEMA gửi response format json_schema, và cả hai đều trả về một Invoice hợp lệ. from_provider gửi model ID nguyên văn. Mock server của chúng tôi không viết JSON dạng văn bản tự do, nên chúng tôi chưa thử Mode.MD_JSON, và cũng chưa gửi ví dụ hình ảnh. Chúng tôi không có key BroadNet nên chưa kiểm thử đầu ra thật của model.
Xử lý sự cố
- Thử lại kiểm tra mãi không thành công. Trên GLM 5.3 và Qwen3.8 27B, suy luận được tính vào
max_tokens. Giới hạn thấp có thể cắt cụt tham số của tool. Hãy tăng giá trị này. Vì sao câu trả lời trả về rỗng. - Request bị 400. Kiểm tra bạn đang dùng GLM 5.3 hoặc Qwen3.8 27B. Nếu
tool_choicebắt buộc bị từ chối, hãy thửMode.JSON_SCHEMA. - 401. Key sai, hết hạn hoặc hết hạn mức.
- 404.
base_urlphải kết thúc bằng/v1. GLM 5.3 và Qwen3.8 27B cần nạp tiền; $5 tín dụng ban đầu không dùng được cho hai model này. - 429 khi trích xuất hàng loạt. Một key trả theo mức dùng cho phép 30 request mỗi phút và 4 request đang xử lý cùng lúc. Mỗi lần thử lại do kiểm tra thất bại là một request nữa. Xem lỗi và thử lại.
