BroadRouter
Bắt đầu

Lấy đầu ra có cấu trúc bằng Instructor trên BroadNet Inference

Cập nhật

Bọc một OpenAI client có base_url https://inference.broadnet.ai/v1 và key BroadNet bằng instructor.from_openai, rồi gọi chat.completions.create với response_model là class Pydantic của bạn và model là broadnet/glm-5.3 hoặc broadnet/qwen3.8-27b. Đây là hai model BroadNet ghi hỗ trợ tool và đầu ra có cấu trúc. Mặc định là Mode.TOOLS; Mode.JSON_SCHEMA cũng hoạt động.

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_choice bắ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_url phả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.

Câu hỏi thường gặp

Nên dùng mode nào của Instructor với BroadNet?

Mode.TOOLS, chế độ mặc định, trên GLM 5.3 hoặc Qwen3.8 27B, hai model BroadNet ghi hỗ trợ tool và đầu ra có cấu trúc. Mode.JSON_SCHEMA thì gửi response_format kiểu json_schema. Cả hai đều tạo ra đối tượng hợp lệ trong thử nghiệm với mock server của chúng tôi.

Có dùng được Mode.RESPONSES_TOOLS không?

Không. Tài liệu Instructor khuyên không chọn mode này trừ khi server có triển khai Responses API. BroadNet chỉ phục vụ chat completions.

Instructor có chạy với DeepSeek V4.1 Flash hoặc Gemma trên BroadNet không?

BroadNet không ghi hỗ trợ tool hay đầu ra có cấu trúc cho các model đó. Mode.MD_JSON yêu cầu JSON dưới dạng văn bản thường rồi parse, có thể chạy được, nhưng hãy thử trên dữ liệu của bạn trước khi dựa vào nó.

Viết chuỗi model cho from_provider thế nào?

Dùng openai/broadnet/glm-5.3. Instructor tách phần đầu tiên làm provider, và trong thử nghiệm của chúng tôi nó gửi broadnet/glm-5.3 tới server nguyên văn.

Đọc dạng MarkdownHỏi ChatGPTHỏi ClaudeHỏi Perplexity