---
title: "Instructor với base_url tương thích OpenAI (Pydantic)"
description: "Trích xuất đối tượng Pydantic từ BroadNet Inference bằng Instructor, dùng from_openai hoặc from_provider với base_url tùy chỉnh, và chọn đúng Mode."
url: https://broadrouter.com/vi/guides/instructor-structured-output/
lang: vi
updated: 2026-11-16
publisher: BroadRouter (a BroadNet site); API by BroadNet Inference, https://inference.broadnet.ai
---

Được dịch từ tiếng Anh với sự hỗ trợ của AI. [Đọc bản gốc tiếng Anh](https://broadrouter.com/guides/instructor-structured-output/) (cập nhật ngày 2026-11-16).

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

Cập nhật 2026-11-16

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

```bash
pip install instructor
export BROADNET_API_KEY='your-broadnet-key'
```

## Trích xuất một đối tượng

```python
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

```python
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:

```python
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](https://broadrouter.com/vi/guides/read-arabic-invoices-with-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](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/).
-   **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](https://broadrouter.com/vi/guides/errors-and-retries/).

## Thuật ngữ trong hướng dẫn này

[Trả theo mức dùng (pay-as-you-go)](https://broadrouter.com/vi/glossary/pay-as-you-go/)

Trả theo mức dùng (pay-as-you-go) là mô hình giá mà bạn chỉ trả cho những gì đã dùng, đo theo đơn vị như token, request hoặc phút âm thanh, không có gói đăng ký hay cam kết tối thiểu. Hầu hết API LLM tính phí theo cách này, trừ vào số dư trả trước hoặc qua hóa đơn định kỳ.

[Chat Completions API](https://broadrouter.com/vi/glossary/chat-completions-api/)

Chat Completions API là endpoint HTTP của OpenAI, POST /v1/chat/completions, nhận tên model và danh sách message có gắn vai trò rồi trả về message tiếp theo của model. Cấu trúc request và response của nó đã trở thành định dạng chung mà các nhà cung cấp và SDK tương thích OpenAI dùng lại.

[Giới hạn tần suất (rate limit)](https://broadrouter.com/vi/glossary/rate-limit/)

Giới hạn tần suất (rate limit) là mức trần mà API đặt ra cho lượng sử dụng của một client trong một khoảng thời gian, như số request mỗi phút hoặc số token mỗi phút. Request vượt giới hạn bị từ chối, thường với HTTP 429 Too Many Requests, cho đến khi mức dùng giảm xuống dưới giới hạn.

[Tool calling (gọi tool, function calling)](https://broadrouter.com/vi/glossary/tool-calling/)

Tool calling, còn gọi là function calling, là tính năng của API LLM trong đó model trả về một yêu cầu có cấu trúc để chạy một hàm do nhà phát triển định nghĩa, kèm đối số JSON. Ứng dụng chạy hàm rồi gửi kết quả lại; model không bao giờ tự chạy code.

[API tương thích OpenAI (OpenAI-compatible API)](https://broadrouter.com/vi/glossary/openai-compatible-api/)

API tương thích OpenAI là một HTTP API nhận cùng định dạng request và phản hồi như OpenAI API, ví dụ POST /v1/chat/completions, nên SDK và công cụ của OpenAI dùng được nó chỉ bằng cách đổi base URL, API key và tên model.

[Concurrency (request đồng thời)](https://broadrouter.com/vi/glossary/concurrency/)

Concurrency (request đồng thời) là số request mà một client đang xử lý cùng lúc. Các API LLM thường giới hạn nó theo key hoặc theo gói, tách biệt với số request mỗi phút, vì mỗi request đang mở chiếm dụng năng lực GPU cho tới khi response kết thúc.

[Đầu ra có cấu trúc (structured output)](https://broadrouter.com/vi/glossary/structured-output/)

Đầu ra có cấu trúc (structured output) là tính năng của API LLM buộc câu trả lời của model theo định dạng do lập trình viên chỉ định, thường là JSON Schema, để code parse được tin cậy. Nó chặt hơn JSON mode, vốn chỉ đảm bảo JSON hợp lệ chứ không đảm bảo một cấu trúc cụ thể.

[Token](https://broadrouter.com/vi/glossary/token/)

Token là đơn vị văn bản mà model ngôn ngữ đọc và viết: một từ, một phần của từ, một dấu câu hoặc một chuỗi byte do tokenizer của model tạo ra. API LLM đếm, giới hạn và thường tính phí theo token.

## 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.

## Hướng dẫn liên quan

-   [Dùng OpenAI Python SDK với BroadNet Inference](https://broadrouter.com/vi/guides/openai-python-sdk/)
-   [Dùng Pydantic AI với BroadNet Inference (OpenAICompatibleProvider)](https://broadrouter.com/vi/guides/pydantic-ai-openai-compatible/)
-   [Đọc hóa đơn và biên lai tiếng Ả Rập bằng model thị giác](https://broadrouter.com/vi/guides/read-arabic-invoices-with-vision/)
-   [Vì sao model suy luận trả về câu trả lời rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/)
-   [Mọi công cụ dùng được với BroadNet Inference (tiếng Anh)](https://broadrouter.com/integrations/): SDK, agent lập trình, giao diện chat và công cụ tự động hóa, kèm cấu hình chính xác cho từng công cụ

Hãy thử với khối lượng công việc thực tế của bạn. Tài khoản mới được tặng US$5 tín dụng ban đầu cho Gemma và chuyển giọng nói thành văn bản. DeepSeek, GLM và Qwen3.8 cần nạp tiền.

[Bắt đầu](https://inference.broadnet.ai/account/?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-guides-instructor-structured-output&utm_content=page-cta) ·

**Nguồn**

-   [Tài liệu Instructor, OpenAI và server tương thích OpenAI (kiểm tra ngày 2026-11-15)](https://python.useinstructor.com/integrations/openai/)
-   [PyPI, instructor 1.17.0 (kiểm tra ngày 2026-11-15)](https://pypi.org/project/instructor/)
-   [Tài liệu tham chiếu API BroadNet Inference (kiểm tra ngày 2026-11-15) (tiếng Anh)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-guides-instructor-structured-output&utm_content=sources)
