Structured Output là gì? Đó là tính năng API ép mô hình trả về JSON khớp đúng schema bạn đưa ra. Bạn không cần dặn bằng prompt rồi hy vọng nó nghe lời. Bài này trình bày 3 cách bật tính năng này. Bài cũng nêu những giới hạn cần nhớ trước khi đưa vào production.
JSON là một trong những định dạng trao đổi dữ liệu phổ biến nhất. Vấn đề là mô hình ngôn ngữ sinh chữ theo xác suất. Dù bạn dặn kỹ trong prompt, câu trả lời vẫn có thể thiếu trường. Nó cũng có thể sai kiểu dữ liệu hay thêm khóa lạ. Khi đó, code phía sau sẽ vỡ khi parse. Tài liệu của OpenAI mô tả Structured Outputs như sau. Tính năng này ràng buộc đầu ra phải khớp đúng JSON Schema bạn cung cấp. Quy tắc này áp cho đầu ra hoàn chỉnh, không bị từ chối. Ứng dụng vẫn phải tự xử lý ba trường hợp. Đó là mô hình từ chối, câu trả lời dở dang và lỗi API. Ứng dụng cũng phải kiểm tra các quy tắc nghiệp vụ mà schema không diễn đạt được.
OpenAI ra mắt tính năng này ngày 2024-08-06, cùng bản snapshot gpt-4o-2024-08-06. Tính năng này không thay thế JSON mode. Nó là bước tiến của JSON mode. Tài liệu khuyên luôn dùng Structured Outputs thay cho JSON mode khi có thể.
Đừng trả tiền thừa cho SaaS AI — Nhận lộ trình công cụ & chi phí tối ưu trong 10 giây
Mô tả bài toán của doanh nghiệp bạn (CSKH Zalo OA, Coding, RAG tài liệu nội bộ, Báo cáo P&L). Hệ thống cố vấn của 3A sẽ đề xuất bộ công cụ đã qua kiểm thử thực chiến.
Bảng đối chiếu: Structured Outputs và JSON mode
Hai chế độ đều cho ra JSON hợp lệ. Nhưng chỉ một chế độ bảo đảm JSON đó khớp schema của bạn. Bảng dưới đây theo đúng bảng so sánh trong tài liệu chính thức của OpenAI.
| Tiêu chí | Structured Outputs | JSON mode |
|---|---|---|
| Trả về JSON hợp lệ | Có | Có |
| Khớp đúng schema đã đưa | Có | Không |
| Cách bật | text.format với type json_schema và strict true, hoặc strict true trên function | text.format với type json_object |
| Model hỗ trợ | gpt-4o-mini, gpt-4o-2024-08-06 trở về sau | gpt-3.5-turbo, gpt-4-*, gpt-4o-*, and compatible GPT-5 models |
| API hỗ trợ | Responses, Chat Completions, Assistants, Fine-tuning, Batch | Responses, Chat Completions, Assistants, Fine-tuning, Batch |
Điểm khác biệt nằm ở cơ chế. JSON mode chỉ bảo đảm chuỗi trả về parse được thành JSON. Structured Outputs dùng constrained decoding. Hệ thống chuyển schema của bạn thành một văn phạm phi ngữ cảnh. Sau mỗi token, hệ thống chỉ cho phép những token vẫn khớp văn phạm đó. Nhờ vậy, trường bắt buộc không bị thiếu. Giá trị enum không bị bịa thêm. Kiểu dữ liệu không bị sai.
Cách 1: Đặt response_format json_schema với strict true
Cách trực tiếp nhất là đưa schema vào ngay trong yêu cầu, qua response_format. Trên Chat Completions API, bạn truyền response_format với type là json_schema. Bạn kèm tên schema, định nghĩa schema và strict true. Trên Responses API mới hơn, cùng schema đó nằm trong text.format. Nó không nằm trong response_format nữa. Tài liệu khuyên dùng dạng này cho một trường hợp. Đó là khi bạn muốn cấu trúc chính câu trả lời gửi cho người dùng. Ví dụ, một app gia sư toán muốn trả về từng bước giải. App cũng muốn trả về đáp án cuối theo đúng khung định sẵn.
Ví dụ trong tài liệu dùng schema math_reasoning. Schema này yêu cầu một mảng steps. Mỗi bước có explanation và output dạng chuỗi. Schema cũng yêu cầu một trường final_answer dạng chuỗi. Với schema đó, mô hình nhận đề bài "how can I solve 8x + 7 = -23". Nó trả về từng bước giải cùng đáp án cuối trong trường final_answer. Tất cả nằm đúng trong khung đã định. Bạn không cần viết prompt dài dặn dò định dạng. API đã khóa định dạng ở tầng sinh token.
Cách này chỉ hỗ trợ trên gpt-4o-mini, gpt-4o-2024-08-06 và các model mới hơn. Nếu dùng model cũ hơn như gpt-4-turbo, hệ thống sẽ rơi về JSON mode. Khi đổi schema giữa chừng trong một cuộc hội thoại, bạn gắn thêm một mục configuration_update. Bạn gắn mục này vào input trước tin nhắn tiếp theo. Bạn giữ nguyên text.format ở cấp cao nhất. Nhờ vậy, bạn vẫn được hưởng prompt caching.
Cách 2: Bật strict true trên function calling
Cách thứ hai dùng khi mô hình cần gọi công cụ của bạn. Bạn không cấu trúc câu trả lời. Bạn cấu trúc lời gọi hàm. Bạn thêm strict true vào từng định nghĩa function trong danh sách tools. Mô hình sẽ chỉ được gọi hàm với đúng tham số theo schema. Nó không thiếu trường. Nó không thêm trường lạ.
Cách này hỗ trợ rất rộng. Nó chạy trên mọi model có hỗ trợ function calling. Danh sách gồm gpt-4o, gpt-4o-mini, gpt-4-turbo, gpt-4 và gpt-3.5-turbo. Phạm vi này rộng hơn cách 1. Cách 1 đòi hỏi snapshot model mới. Tài liệu khuyên dùng function calling cho một trường hợp. Đó là khi bạn nối mô hình với công cụ, hàm hay dữ liệu trong hệ thống. Ví dụ, agent được quyền truy vấn đơn hàng. Agent trả về đúng các trường mã đơn, trạng thái và tổng tiền.
Một khác biệt thực tế cần nhớ. Function calling có thể trả về cả câu chữ lẫn lời gọi hàm trong cùng một lượt. Structured Outputs qua response_format chỉ trả về JSON. Vì vậy, nếu luồng của bạn cần mô hình vừa giải thích vừa gọi hàm, hãy chọn function calling. Nếu bạn chỉ cần một JSON sạch để code xử lý tiếp, hãy chọn response_format.

Chú thích ảnh: Đôi tay gõ phím trên laptop với mã nguồn trên màn hình. Ảnh minh họa việc viết schema rồi để SDK parse kết quả có kiểu. Ảnh: TREEDEO.ST, Pexels, giấy phép Pexels (link gốc xem mục Nguồn, phần Ảnh).
Cách 3: Viết schema bằng class trong SDK rồi parse có kiểu
Cách thứ ba không gọi API thô. Bạn viết schema bằng class trong SDK. Bạn để SDK parse kết quả thành object có kiểu. Với Python, bạn định nghĩa một lớp kế thừa pydantic.BaseModel. Ví dụ, lớp CalendarEvent có ba trường name, date và participants. Trường participants là danh sách chuỗi. Sau đó, bạn gọi client.responses.parse với text_format là lớp đó. Kết quả trả về nằm trong response.output_parsed. Kết quả này đã có kiểu, dưới dạng object. Bạn không cần json.loads rồi tự kiểm tra trường bằng tay.
from openai import OpenAI
from pydantic import BaseModel
client = OpenAI()
class Step(BaseModel):
explanation: str
output: str
class MathReasoning(BaseModel):
steps: list[Step]
final_answer: str
response = client.responses.parse(
model="gpt-6-astra",
input=[
{
"role": "system",
"content": "You are a helpful math tutor. Guide the user through the solution step by step.",
},
{"role": "user", "content": "how can I solve 8x + 7 = -23"},
],
text_format=MathReasoning,
)
math_reasoning = response.output_parsedVới JavaScript, cách làm tương đương là dùng z.object của thư viện Zod. Với Ruby, SDK hỗ trợ định nghĩa schema bằng Sorbet T::Struct. SDK trả về kết quả đã parse có kiểu. Điểm chung của cả ba SDK là một điều. Schema vẫn được gửi xuống API dưới dạng JSON Schema với strict true. Bảo đảm ở tầng sinh token vẫn giữ nguyên. Chỉ khác là bạn viết schema bằng code có kiểm tra kiểu ngay từ lúc viết.
Cách này phù hợp nhất cho đội đã dùng Pydantic hoặc Zod. Hai thư viện này mô tả dữ liệu trong codebase. Schema chỉ viết một lần trong code. Nó vừa làm tài liệu cho dữ liệu. Nó vừa làm hợp đồng ép mô hình tuân theo. Khi schema đổi, code báo lỗi biên dịch hoặc kiểm tra kiểu ngay. Bạn không phải đợi tới lúc chạy thật mới phát hiện JSON thiếu trường.
Giới hạn phải nhớ trước khi đưa vào production
Ba cách trên khóa được hình thức. Nhưng chúng không khóa được nội dung. Tài liệu cảnh báo rõ điều này. Cấu trúc được bảo đảm, còn giá trị bên trong JSON vẫn có thể sai. Một trường total dạng số vẫn có thể chứa con số sai. Vì vậy, sau khi parse xong, bạn vẫn phải kiểm tra quy tắc nghiệp vụ bằng code. Ví dụ, tổng tiền phải bằng tổng các dòng. Ngày tháng phải nằm trong khoảng hợp lệ.
Giới hạn thứ hai là chỉ một tập con của JSON Schema được hỗ trợ. Mọi object phải đặt additionalProperties là false. Mọi khóa đều phải liệt kê trong required. Không có khóa tùy chọn. Nếu một giá trị có thể vắng mặt, bạn vẫn phải khai báo khóa đó là bắt buộc. Nhưng bạn cho phép giá trị null. Schema lồng nhau quá sâu và một số từ khóa kết hợp cũng bị hạn chế. Schema càng phẳng càng dễ chạy.
Giới hạn thứ ba là hai trường hợp ngoại lệ. Bạn phải xử lý chúng như sự kiện bình thường. Thứ nhất, mô hình có thể từ chối yêu cầu vì lý do an toàn. Khi đó, câu trả lời mang trường refusal thay vì dữ liệu của bạn. Bạn phải kiểm tra refusal trước khi parse. Thứ hai, câu trả lời có thể dở dang khi chạm giới hạn token đầu ra. Khi đó, trạng thái là incomplete. Bạn phải báo lỗi thay vì cố parse đoạn JSON bị cắt.
Giới hạn cuối cùng là độ trễ. Lần gọi đầu tiên với một schema mới sẽ chậm hơn vì API phải xử lý schema đó. Tài liệu hiện hành ghi rõ: lần gọi đầu có thêm độ trễ, các lần gọi sau với cùng schema thì không còn phí này. Hãy tính phí trễ này vào thiết kế. Ví dụ, bạn làm ấm schema trước khi mở luồng cho người dùng thật.
Đọc thêm trên 3a.com.vn: LangChain là gì. Đọc thêm: AI agent là gì và prompt engineering là gì.
Nguồn
Nguồn
- OpenAI, "Structured model outputs", tài liệu API chính thức, ngày truy cập 2026-11-14. Link: https://developers.openai.com/api/docs/guides/structured-outputs
Ảnh
- Bìa: Markus Spiske, Pexels, giấy phép Pexels, ngày 2020-03-06. Link gốc: https://www.pexels.com/photo/multicolored-text-on-the-screen-3872166/
- Ảnh thân bài: TREEDEO.ST, Pexels, giấy phép Pexels, ngày 2020-09-18. Link gốc: https://www.pexels.com/photo/hands-typing-on-a-laptop-computer-5385526/



