---
title: "JSON mode và JSON schema: đầu ra có cấu trúc, kèm code"
description: "JSON mode cho JSON hợp lệ; json_schema cho đúng cấu trúc. Cách yêu cầu từng loại trên model tương thích OpenAI, validate bằng Pydantic và sửa đầu ra lỗi."
url: https://broadrouter.com/vi/blog/structured-output-json-schema/
lang: vi
updated: 2026-11-14
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/blog/structured-output-json-schema/) (cập nhật ngày 2026-11-14).

# JSON mode và json\_schema: đầu ra có cấu trúc đáng tin cậy

Đội ngũ BroadNet Inference · 4 phút đọc · Đăng ngày 2026-11-14

JSON mode (response\_format json\_object) chỉ đảm bảo JSON hợp lệ. Đầu ra có cấu trúc (response\_format json\_schema) đảm bảo thêm cả trường và kiểu dữ liệu của bạn, nếu nhà cung cấp thực thi. Dù dùng cách nào, hãy kiểm tra finish\_reason, parse, rồi validate theo một schema như model Pydantic. Nếu validate thất bại, gửi lỗi lại và yêu cầu lần nữa, với giới hạn cứng về số lần thử.

## Ý chính

-   Theo hướng dẫn của OpenAI, cả hai chế độ đều tạo JSON hợp lệ, nhưng “only Structured Outputs ensure schema adherence” (bản dịch: chỉ Structured Outputs đảm bảo tuân thủ schema).
-   Mức hỗ trợ khác nhau giữa các nhà cung cấp tương thích OpenAI. Hãy test json\_schema trước, nếu không được thì lùi về json\_object, rồi tới cách chỉ dùng prompt.
-   Hãy validate mọi phản hồi. Một phản hồi bị cắt bởi max\_tokens là JSON hỏng, dù schema nói gì đi nữa.
-   Vòng lặp sửa lỗi hiệu quả khi bạn gửi lại chính xác lỗi validate. Giới hạn ở hai hoặc ba lần thử.
-   Trên BroadNet Inference, GLM 5.3 và Qwen3.8 27B có liệt kê đầu ra có cấu trúc.

**Trong trang này**

1.  JSON mode và json\_schema khác nhau thế nào?
2.  Yêu cầu json\_schema như thế nào?
3.  Nhà cung cấp của bạn hỗ trợ chế độ nào?
4.  Validate và sửa đầu ra lỗi như thế nào?
5.  Tính năng schema nào gây rắc rối?
6.  Giám sát đầu ra có cấu trúc trong production như thế nào?
7.  Khi nào nên dùng công cụ thay thế?
8.  BroadNet Inference phù hợp ở đâu?

Code của bạn cần dữ liệu, còn model thì viết văn bản. [Đầu ra có cấu trúc](https://broadrouter.com/vi/glossary/structured-output/) lấp khoảng trống đó, nhưng “model trả về JSON” có ba nghĩa khác nhau tùy cách bạn yêu cầu. Bài này so sánh các lựa chọn trên model mở tương thích OpenAI, chỉ cách yêu cầu từng loại, và đưa ra một vòng lặp validate và sửa lỗi bạn có thể đưa thẳng vào production.

## JSON mode và json\_schema khác nhau thế nào?

| Phương pháp | Request | Bạn được đảm bảo gì |
| --- | --- | --- |
| Chỉ dùng prompt | “Trả lời bằng JSON với các trường…” | Không gì cả; thường là JSON, đôi khi kèm văn bản thừa |
| JSON mode | `response_format: {"type": "json_object"}` | JSON hợp lệ, cấu trúc bất kỳ |
| Đầu ra có cấu trúc | `response_format: {"type": "json_schema", ...}` | JSON khớp schema của bạn, nếu được thực thi |

Hướng dẫn Structured Outputs của OpenAI nói thẳng: “While both ensure valid JSON is produced, only Structured Outputs ensure schema adherence.” (bản dịch: Dù cả hai đều đảm bảo tạo ra JSON hợp lệ, chỉ Structured Outputs đảm bảo tuân thủ schema.) Hướng dẫn khuyến nghị dùng đầu ra có cấu trúc thay cho JSON mode bất cứ khi nào có thể.

Với các nhà cung cấp model mở, mức đảm bảo phụ thuộc vào cách server cài đặt. Nhiều nơi dùng giải mã có ràng buộc (constrained decoding), chặn những token sẽ làm hỏng schema. Có nơi nhận trường này nhưng không thực thi. Vì vậy code bên dưới luôn validate dù thế nào.

## Yêu cầu json\_schema như thế nào?

```python
import os
from openai import OpenAI
from pydantic import BaseModel, Field

client = OpenAI(base_url="https://inference.broadnet.ai/v1", api_key=os.environ["BROADNET_API_KEY"])

class Invoice(BaseModel):
    vendor: str
    currency: str = Field(pattern="^[A-Z]{3}$")
    total: float
    line_items: list[float]

schema = Invoice.model_json_schema()
schema["additionalProperties"] = False

response_format = {"type": "json_schema",
                   "json_schema": {"name": "invoice", "strict": True, "schema": schema}}
```

Pydantic sinh JSON Schema từ class của bạn, nên schema và bộ validate không bao giờ lệch nhau. Nếu bạn không dùng Pydantic, [công cụ tạo JSON schema](https://broadrouter.com/tools/json-schema-generator/) dựng một schema strict mode từ một đối tượng mẫu. Với strict mode, OpenAI yêu cầu `additionalProperties: false` và mọi thuộc tính đều được liệt kê là required.

## Nhà cung cấp của bạn hỗ trợ chế độ nào?

Hãy chạy bài test này một lần cho mỗi model trước khi xây dựng trên nó:

1.  Gửi `json_schema` kèm một prompt rủ thêm trường thừa (“thêm cả một nhận xét ngắn”).
2.  Nếu request báo lỗi, nhà cung cấp không nhận `json_schema`. Hãy thử `json_object`.
3.  Nếu phản hồi chứa trường thừa, schema không được thực thi. Hãy coi nó như JSON mode.
4.  Nếu `json_object` cũng báo lỗi, hãy dùng cách chỉ dùng prompt kèm validate.

Trên BroadNet Inference, tài liệu liệt kê đầu ra có cấu trúc cho [GLM 5.3](https://broadrouter.com/vi/models/glm-5.3/) và [Qwen3.8 27B](https://broadrouter.com/vi/models/qwen3.8-27b/) ([so sánh song song](https://broadrouter.com/compare/glm-5.3-vs-qwen3.8-27b/)), nhưng không nêu tên tham số request. Hãy chạy bài test trên với model bạn đưa vào sản phẩm.

## Validate và sửa đầu ra lỗi như thế nào?

```python
import json
from pydantic import ValidationError

def extract(text: str, model="broadnet/glm-5.3", attempts=3) -> Invoice:
    messages = [
        {"role": "system", "content": "Extract the invoice. Reply with JSON only."},
        {"role": "user", "content": text},
    ]
    for attempt in range(attempts):
        r = client.chat.completions.create(model=model, messages=messages,
                                           response_format=response_format,
                                           max_tokens=4000)
        choice = r.choices[0]
        if choice.finish_reason == "length":
            raise RuntimeError("Cut off: raise max_tokens")  # retrying won't help
        if getattr(choice.message, "refusal", None):
            raise RuntimeError(f"Refused: {choice.message.refusal}")
        raw = choice.message.content or ""
        try:
            inv = Invoice.model_validate_json(raw)
            if abs(sum(inv.line_items) - inv.total) > 0.01:
                raise ValueError("total must equal the sum of line_items")
            return inv
        except (ValidationError, ValueError) as e:
            messages += [
                {"role": "assistant", "content": raw},
                {"role": "user", "content": f"That JSON is invalid: {e}. Return corrected JSON only."},
            ]
    raise RuntimeError(f"No valid JSON after {attempts} attempts")
```

Điều làm vòng lặp này hoạt động:

-   **Kiểm tra `finish_reason` trước.** Một phản hồi chạm [`max_tokens`](https://broadrouter.com/vi/glossary/max-tokens/) là JSON bị cắt cụt. Retry với cùng giới hạn sẽ thất bại y như cũ. Cả hai model trên đều suy luận trước khi trả lời, và [phần suy luận được tính vào giới hạn](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/), nên hãy chừa chỗ.
-   **Xử lý lời từ chối riêng.** Hướng dẫn của OpenAI lưu ý rằng một lời từ chối “does not necessarily follow the schema you have supplied” (bản dịch: không nhất thiết tuân theo schema bạn đã cung cấp).
-   **Gửi lại chính xác lỗi.** Retry mù quáng thường trả về đúng lỗi cũ. “line\_items: field required” cho model biết cần sửa gì.
-   **Kiểm tra quy tắc nghiệp vụ bằng code.** Schema không thể nói tổng tiền phải bằng tổng các dòng. Đoạn kiểm tra ở trên thì làm được.
-   **Giới hạn số lần thử.** Mỗi lần thử gửi lại toàn bộ prompt dưới dạng [token đầu vào](https://broadrouter.com/vi/glossary/input-and-output-tokens/).

## Tính năng schema nào gây rắc rối?

Hãy giữ schema thật đơn giản:

1.  **Phẳng tốt hơn lồng nhau.** Hai cấp là đủ cho phần lớn việc trích xuất.
2.  **Dùng enum thay vì chuỗi tự do** cho các danh mục.
3.  **Không dùng đối tượng mở.** Các trường `dict` tự do làm mất ý nghĩa của schema.
4.  **Tên trường ngắn kèm mô tả.** Mô tả trong schema dẫn hướng cho model.
5.  **Trường tùy chọn để nullable.** Trong strict mode, hãy liệt kê mọi trường là required và cho phép `null`.

Hướng dẫn của OpenAI lưu ý một số tính năng JSON Schema không được hỗ trợ trong strict mode. Server model mở cũng có giới hạn riêng. Nếu một schema bị từ chối, hãy đơn giản hóa nó trước khi đổi chế độ.

## Giám sát đầu ra có cấu trúc trong production như thế nào?

Một vòng lặp âm thầm sửa lỗi có thể che giấu một vấn đề ngày nào cũng ngốn token của bạn. Hãy ghi log ba con số cho mỗi điểm gọi:

| Chỉ số | Cho bạn biết điều gì |
| --- | --- |
| Tỷ lệ thành công ngay lần đầu | Model và schema khớp nhau tới đâu; tỷ lệ giảm thường xảy ra sau khi đổi prompt hoặc model |
| Số lần thử trung bình cho mỗi lần thành công | Chi phí token của việc sửa lỗi |
| Số lần thất bại cuối cùng | Những đầu vào pipeline không xử lý được; hãy xem xét thủ công |

Nếu tỷ lệ thành công lần đầu thấp hơn mức bạn quen thấy, hãy đơn giản hóa schema hoặc thử model khác trước khi thêm retry. Hãy giữ một mẫu các phản hồi thô bị lỗi, để có thể test cách sửa trên trường hợp thật.

## Khi nào nên dùng công cụ thay thế?

Dùng đầu ra có cấu trúc cho **câu trả lời cuối cùng**: một kết quả trích xuất, một phân loại, một kế hoạch. Dùng [gọi công cụ](https://broadrouter.com/vi/blog/tool-calling-open-models/) khi model cần code của bạn **làm** một việc gì đó rồi tiếp tục. Nhiều agent dùng cả hai: công cụ trong vòng lặp, schema cho bước cuối. Với ví dụ chuyển hình ảnh thành JSON, xem [đọc hóa đơn tiếng Ả Rập bằng model vision](https://broadrouter.com/vi/guides/read-arabic-invoices-with-vision/).

## BroadNet Inference phù hợp ở đâu?

BroadNet Inference liệt kê đầu ra có cấu trúc cho GLM 5.3 và Qwen3.8 27B, qua định dạng chat completions chuẩn, nên code ở trên chạy với [OpenAI Python SDK](https://broadrouter.com/vi/guides/openai-python-sdk/) mà không cần sửa. Qwen3.8 27B cũng nhận hình ảnh, phù hợp cho việc trích xuất tài liệu. Tài liệu của BroadNet không nêu đầu ra có cấu trúc cho DeepSeek V4.1 Flash hay Gemma 4 VL 26B, nên với hai model này hãy dùng cách chỉ dùng prompt kèm validate. So sánh giá theo token trên [trang giá](https://broadrouter.com/vi/pricing/).

Công cụ miễn phí cho chủ đề này (tiếng Anh)

-   [OpenAI to BroadNet migration helper](https://broadrouter.com/tools/openai-to-broadnet-migration/) Paste OpenAI SDK code; get base URL, key and model edits, a diff and the checks that remain.
-   [max\_tokens calculator for reasoning models](https://broadrouter.com/tools/reasoning-token-budget/) Answer length + reasoning budget + margin = a max\_tokens that does not cut the answer off.
-   [JSON schema generator for LLM structured output](https://broadrouter.com/tools/json-schema-generator/) Sample JSON to strict schema, Pydantic, Zod and a ready request.
-   [LLM JSON output validator](https://broadrouter.com/tools/llm-json-output-validator/) Parse errors by line and column, safe repairs, cut-off detection and JSON Schema checks for model output.

[Công cụ miễn phí (tiếng Anh)](https://broadrouter.com/tools/)

## Thuật ngữ trong bài này

[Đầ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ể.

[JSON Schema](https://broadrouter.com/vi/glossary/json-schema/)

JSON Schema là một bộ từ vựng viết bằng JSON để mô tả và kiểm tra cấu trúc dữ liệu JSON: kiểu, trường bắt buộc, giá trị cho phép và cách lồng nhau. Phiên bản hiện tại là 2020-12. Các API LLM dùng nó để định nghĩa tham số tool và cấu trúc chính xác mà structured output phải theo.

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

[JSON mode (chế độ JSON)](https://broadrouter.com/vi/glossary/json-mode/)

JSON mode là một thiết lập của API LLM, response\_format {"type": "json\_object"} trong các API kiểu OpenAI, khiến câu trả lời của model là JSON hợp lệ, parse được. Khác với structured output dùng JSON Schema, nó không đảm bảo object chứa những key, kiểu hay giá trị nào.

[Model trọng số mở (open-weight model)](https://broadrouter.com/vi/glossary/open-weight-model/)

Model trọng số mở (open-weight) là model học máy có trọng số đã huấn luyện được công bố để ai cũng tải về và chạy, thường kèm giấy phép có điều kiện. Nó khác AI mã nguồn mở hoàn toàn, vốn công bố thêm code huấn luyện và chi tiết dữ liệu huấn luyện để người khác tái tạo model.

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

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

[Token đầu vào và đầu ra (input and output tokens)](https://broadrouter.com/vi/glossary/input-and-output-tokens/)

Token đầu vào là token mà model ngôn ngữ đọc trong một request, gồm system prompt, lịch sử hội thoại, định nghĩa tool và hình ảnh. Token đầu ra là token nó sinh ra để trả lời, kể cả phần suy luận. API LLM thường tính giá riêng cho hai loại, và đầu ra thường đắt hơn.

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

### JSON mode và đầu ra có cấu trúc khác nhau thế nào?

JSON mode, tức response\_format type json\_object, chỉ đảm bảo phản hồi parse được thành JSON. Đầu ra có cấu trúc, type json\_schema, đảm bảo thêm các trường và kiểu dữ liệu bạn đã định nghĩa, nếu nhà cung cấp thực thi. OpenAI khuyến nghị dùng đầu ra có cấu trúc thay cho JSON mode khi có thể.

### Model mở có hỗ trợ response\_format json\_schema không?

Tùy nhà cung cấp. Có nơi nhận json\_schema, có nơi chỉ nhận json\_object, và có nơi bỏ qua trường này. Hãy gửi một request test kèm schema và một prompt dụ model thêm một trường thừa, rồi kiểm tra phản hồi.

### Có cần validate đầu ra có cấu trúc nữa không?

Có. Phản hồi có thể bị cắt bởi max\_tokens, có thể là lời từ chối, và có thể vi phạm quy tắc nghiệp vụ mà schema không diễn đạt được, chẳng hạn tổng tiền phải khớp.

### Nên retry JSON không hợp lệ bao nhiêu lần?

Hai hoặc ba lần thử kèm lỗi validate thường là đủ. Sau đó, hãy ghi log đầu vào và chuyển nó sang phương án dự phòng, một model mạnh hơn hoặc một người. Vòng lặp không giới hạn chỉ lãng phí token.

### Nên dùng đầu ra có cấu trúc hay gọi công cụ?

Dùng đầu ra có cấu trúc khi bạn muốn câu trả lời cuối cùng theo một cấu trúc cố định. Dùng gọi công cụ khi model cần code của bạn làm một việc gì đó rồi mới tiếp tục.

## Đọc tiếp

-   [Phân loại văn bản tiếng Ả Rập bằng LLM: cảm xúc, ý định, ticket](https://broadrouter.com/vi/blog/arabic-text-classification-llm/)
-   [Tool calling với model mở: schema, gọi song song, retry](https://broadrouter.com/vi/blog/tool-calling-open-models/)
-   [Chuyển sang API tương thích OpenAI: checklist khi chuyển đổi](https://broadrouter.com/vi/blog/openai-compatible-api-migration-checklist/)
-   [n8n AI Agent với LLM giá rẻ: cài đặt, model, chi phí mỗi lần chạy](https://broadrouter.com/vi/blog/n8n-ai-agent-cheap-llm/)
-   [Sửa JSON không hợp lệ từ LLM: nguyên nhân, sửa lỗi, thử lại](https://broadrouter.com/vi/blog/fix-invalid-json-from-llm/)
-   [Trích xuất thực thể tiếng Ả Rập bằng LLM: JSON, ngày tháng, kiểm tra](https://broadrouter.com/vi/blog/arabic-named-entity-extraction-llm/)
-   [Phần cứng GPU và cách phục vụ model của BroadNet, theo lời BroadNet](https://broadrouter.com/vi/blog/broadnet-gpu-fleet-and-serving/)
-   [Cache phản hồi API LLM để giảm chi phí: cache khớp chính xác (Python)](https://broadrouter.com/vi/blog/cache-llm-responses-cut-cost/)
-   [Hướng dẫn: Dùng OpenAI Python SDK với BroadNet Inference](https://broadrouter.com/vi/guides/openai-python-sdk/)
-   [Hướng dẫn: Đọ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/)
-   [Hướng dẫn: Vì sao model suy luận trả về câu trả lời rỗng](https://broadrouter.com/vi/guides/reasoning-tokens-empty-response/)

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-blog-structured-output-json-schema&utm_content=page-cta) ·

**Nguồn**

-   [OpenAI, hướng dẫn Structured Outputs (kiểm tra ngày 2026-11-14)](https://developers.openai.com/api/docs/guides/structured-outputs)
-   [Tài liệu tham chiếu API OpenAI, tạo chat completion (response\_format)](https://developers.openai.com/api/reference/resources/chat/subresources/completions/methods/create)
-   [Tài liệu Pydantic, JSON Schema và validation](https://docs.pydantic.dev/latest/concepts/json_schema/)
-   [Tài liệu tham chiếu API BroadNet Inference, các model (tiếng Anh)](https://inference.broadnet.ai/docs?utm_source=broadrouter&utm_medium=referral&utm_campaign=vi-blog-structured-output-json-schema&utm_content=sources#models)
