BroadRouter
Bắt đầu

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

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

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 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?

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 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 và Qwen3.8 27B (so sánh song song), 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?

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

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

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

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 dạng MarkdownHỏi ChatGPTHỏi ClaudeHỏi Perplexity