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ó:
- Gửi
json_schemakèm một prompt rủ thêm trường thừa (“thêm cả một nhận xét ngắn”). - Nếu request báo lỗi, nhà cung cấp không nhận
json_schema. Hãy thửjson_object. - 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.
- Nếu
json_objectcũ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_reasontrước. Một phản hồi chạmmax_tokenslà 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:
- Phẳng tốt hơn lồng nhau. Hai cấp là đủ cho phần lớn việc trích xuất.
- Dùng enum thay vì chuỗi tự do cho các danh mục.
- Không dùng đối tượng mở. Các trường
dicttự do làm mất ý nghĩa của schema. - Tên trường ngắn kèm mô tả. Mô tả trong schema dẫn hướng cho model.
- 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á.
