Đầu ra có cấu trúc của LLM bị hỏng: viết Schema thật cho chế độ strict như thế nào
Kết luận: Bật strict trên một JSON Schema tùy ý gần như luôn trả về 400: mọi trường required, additionalProperties:false trên mỗi object, $ref và allOf bị từ chối ngay lập tức. Hướng dẫn này cho thấy cách viết lại một schema nới lỏng thành phiên bản tương thích với strict — với union nullable, giới hạn cứng và checklist về refusal.

Điều cốt lõi: strict: true không phải là công tắc "hãy nghiêm túc hơn" — đó là một hợp đồng chỉ chấp nhận một tập con của JSON Schema. Mọi trường required, additionalProperties: false trên mọi object, $ref và allOf bị cấm ngay lập tức. Gửi schema ở chế độ strict mà không viết lại, câu trả lời là 400, không phải đầu ra đáng tin cậy.
Trong thực tế hằng ngày, cảnh này lặp lại y hệt: nhóm có một schema được thiết kế tốt, với các trường tùy chọn, $defs dùng lại được và additionalProperties mở ra để tương thích. Rồi ai đó thêm "strict": true vào lời gọi API, tin rằng giờ đây mô hình "sẽ tôn trọng" schema. Kết quả ngay lập tức là lỗi 400 với thông điệp dài, hoặc tệ hơn — schema được chấp nhận nhưng sản sinh đầu ra không như mong đợi. Chế độ strict không diễn giải schema với sự khoan dung: nó viết lại schema từ đầu thành một ngữ pháp mà bộ sinh có thể tuân theo từng chữ, và mọi thứ không vừa với ngữ pháp đó đều bị từ chối hoặc bị bỏ qua một cách lặng lẽ. Hiểu được những quy tắc nào thực sự có hiệu lực, trước khi gửi yêu cầu, là sự khác biệt giữa một pipeline ổn định và một tuần debug.
Chế độ strict = JSON Schema của bạn được biên dịch thành ngữ pháp mà mô hình phải tuân theo từng từ. Mọi thứ ngữ pháp không thể diễn đạt sẽ bị từ chối khi gửi hoặc bị bỏ qua lặng lẽ — và trong cả hai trường hợp, vấn đề xuất hiện sau khi người dùng đã nhìn thấy nó.
Cơ chế của strict mode thực sự hoạt động ra sao
Các mô hình không đọc JSON Schema của bạn như một validator thông thường. Khi strict: true được bật, schema được chuyển đổi thành một ngữ pháp ràng buộc — một automaton hữu hạn trạng thái, quyết định từng token xem những phần tiếp theo nào là hợp lệ. Mô hình chỉ sinh ra những chuyển tiếp được automaton cho phép; không có kiểm tra sau sinh nào sửa đầu ra — tính đúng đắn là mang tính cấu trúc.
Kiến trúc này giải thích mọi hành vi trông như bí ẩn. Nếu một trường không nằm trong required, automaton phải quyết định khi nào dừng lại: giải pháp an toàn duy nhất là cho mô hình tự do phát null, vì thế schema hiệu dụng mà bộ sinh nhận được sẽ luôn có trường đó hiện diện. Nếu một object cho phép thuộc tính bổ sung, automaton không thể dự đoán trước các key nào sẽ xuất hiện, nên mỗi object phải đóng cứng. Mỗi điều "cấm" trong tài liệu đều xuất phát từ một giới hạn cụ thể của automaton này, không phải từ một lựa chọn phong cách của OpenAI.
Hệ quả thứ hai còn khó lường hơn: một số từ khóa JSON Schema (như pattern, minLength, maximum) là hợp lệ đối với schema nhưng không được áp dụng bởi ngữ pháp. Schema được chấp nhận, phản hồi về sạch sẽ, nhưng ràng buộc chưa bao giờ được tuân thủ. Đó là cách âm thầm nhất để làm hỏng pipeline: xác thực sau đó thất bại trong sản xuất và không log nào hiển thị lỗi schema.
Ba quy tắc không thể thương lượng
Nếu chỉ có thời gian sửa một thứ, hãy sửa ba thứ này. Chúng giải quyết phần lớn các lỗi 400.
1. Mọi trường trong required, luôn luôn. Ở chế độ strict, mọi key khai báo trong properties phải xuất hiện trong required — kể cả tùy chọn. Mẹo chính thức để nói "tùy chọn" là union nullable:
{
"type": "object",
"properties": {
"couponCode": { "type": ["string", "null"] }
},
"required": ["couponCode"],
"additionalProperties": false
}
Như vậy automaton biết chính xác khi nào key hợp lệ, và mô hình diễn đạt "không có mã ưu đãi" bằng null thay vì bỏ qua key.
2. additionalProperties: false trên mọi object. Không chỉ trên object gốc: mọi object lồng nhau, không ngoại lệ. Chỉ một tầng mở là cả schema không tương thích.
3. $ref và allOf bị cấm. Không tham chiếu, không $defs, không kết hợp. Schema phải được mở rộng hoàn toàn — một cây duy nhất độc lập. if/then/else và oneOf ở gốc cũng chung số phận.
Bảng các thuật ngữ bị cấm và vô hiệu
| Từ khóa | Kết quả ở chế độ strict | Giải pháp thay thế đề xuất |
|---|---|---|
$ref, $defs |
Từ chối với 400 | Mở rộng hoàn toàn schema |
allOf |
Từ chối với 400 | Hợp nhất thuộc tính thủ công |
if/then/else |
Từ chối với 400 | enum + xử lý phía client |
oneOf ở gốc |
Vấn đề / phản hồi không tương thích | Chỉ một object gốc |
Trường ngoài required |
Đổi thành luôn bắt buộc | Union nullable ["string", "null"] |
pattern, minLength |
Schema được chấp nhận nhưng ràng buộc bị bỏ qua | Xác thực rõ ràng sau phản hồi |
maximum, format |
Schema được chấp nhận nhưng ràng buộc bị bỏ qua | Kiểm tra phía ứng dụng |
Dòng nguy hiểm nhất là cặp cuối: schema vượt qua xác thực nhưng ràng buộc không tồn tại. Nếu logic của bạn tin vào pattern, bạn đang xây trên cát.
Các giới hạn cứng mà không ai đọc
Trước khi viết schema, hãy chắc chắn bạn nằm trong các biên này — vượt qua chúng sinh ra lỗi chung khó chẩn đoán:
| Giới hạn | Tối đa |
|---|---|
| Tổng số thuộc tính mỗi schema | 5000 |
| Độ sâu lồng nhau | 10 tầng |
| Kích thước chuỗi schema | 120.000 ký tự |
| Tổng số giá trị enum | 1000 |
Các schema được sinh tự động từ framework hoặc định nghĩa OpenAPI thường vượt qua các giới hạn này mà không ai để ý: tổng cộng 6000 thuộc tính, 12 tầng lồng, 1500 giá trị enum rải rác. Thông điệp lỗi của API hiếm khi chỉ ra ngưỡng nào bị vượt, nên tốt nhất là tự kiểm tra trước khi gửi.
Viết lại tự động: script make_strict
Với schema lớn, viết lại thủ công là không khả thi. Script Python này duyệt cây và áp dụng đệ quy ba quy tắc:
import json
def make_strict(node):
if isinstance(node, dict):
if node.get("type") == "object":
props = node.get("properties", {})
# mọi thuộc tính trở thành required
node["required"] = list(props.keys())
node["additionalProperties"] = False
# các trường "tùy chọn" phải được đánh dấu nullable trước
# loại bỏ những gì strict không chấp nhận
for k in ("$ref", "$defs", "allOf", "if", "then", "else"):
node.pop(k, None)
return {k: make_strict(v) for k, v in node.items()}
if isinstance(node, list):
return [make_strict(v) for v in node]
return node
schema = json.load(open("schema.json"))
print(json.dumps(make_strict(schema), indent=2))
Hai lưu ý. Thứ nhất: script không đoán được những trường nào là tùy chọn — bạn phải tự đánh dấu các union nullable, tốt nhất là ở nguồn schema chứ không phải kết quả. Thứ hai: sau khi chuyển đổi, luôn chạy một yêu cầu thử: việc mở rộng có thể vượt qua giới hạn kích thước hoặc số thuộc tính mà trước đây bạn vẫn tuân thủ.
Con đường tương đương ở Anthropic
Anthropic không có cờ strict, nhưng đạt cùng kết quả bằng cơ chế tool: định nghĩa công cụ đóng vai trò schema, và mô hình bị ràng buộc theo hình dạng của nó. Cách tiếp cận thực tế giống hệt:
const tool = {
name: "extract_invoice",
description: "Trích xuất dữ liệu hóa đơn từ văn bản",
input_schema: {
type: "object",
properties: {
invoiceNumber: { type: "string" },
totalAmount: { type: ["number", "null"] },
lineItems: {
type: "array",
items: {
type: "object",
properties: {
description: { type: "string" },
quantity: { type: "number" }
},
required: ["description", "quantity"],
additionalProperties: false
}
}
},
required: ["invoiceNumber", "totalAmount", "lineItems"],
additionalProperties: false
}
};
// mô hình trả lời bằng lời gọi tool tương thích
const response = await anthropic.messages.create({
model: "claude-sonnet-4-5",
max_tokens: 1024,
tools: [tool],
tool_choice: { type: "tool", name: "extract_invoice" },
messages: [{ role: "user", content: invoiceText }]
});
Quy tắc thực hành là như nhau: ở Anthropic, mỗi object cũng cần required đầy đủ và additionalProperties: false. Khác biệt nằm ở kênh phản hồi — tool_use thay vì nội dung văn bản — và ở việc trường refusal là đặc thù của OpenAI.
Refusal, cắt ngắn và hình dạng gãy: ba lỗi, ba cách chữa
Ngay cả với schema hoàn hảo, đầu ra vẫn có thể thất bại vì ba lý do khác biệt, và nhầm lẫn giữa chúng là cách nhanh nhất để mất một ngày:
1. refusal không rỗng. OpenAI ở chế độ strict có thể trả về trường refusal kèm lý do từ chối yêu cầu. Đó không phải lỗi schema — mô hình từ chối công việc về mặt ngữ nghĩa. Cách chữa là xem lại prompt hoặc chính sách, không phải schema.
2. Cắt ngắn do max_tokens. Quá trình sinh bị ngắt giữa chuỗi và JSON không đóng. Ở chế độ strict, phản hồi nếu về là tương thích — nhưng nếu hết ngân sách token, nó về dạng bị cắt. Tăng max_tokens hoặc giảm kích thước đầu ra dự kiến. Với các kịch bản lặp lại, sửa tự động JSON bị cắt có sẵn các mẫu dùng ngay.
3. Hình dạng gãy không tương thích. Schema đã mở (cho phép thuộc tính bổ sung, trường ngoài required) và strict chưa bật: mô hình sinh JSON hợp lệ nhưng không tuân thủ hợp đồng. Cách chữa là viết lại schema như hướng dẫn này, không phải thêm kiểm tra sau sinh.
Chẩn đoán đúng luôn bắt đầu từ phân biệt ba trường hợp này: xem trường finish_reason, sự hiện diện của refusal, và đối chiếu phản hồi với schema đã thực sự gửi đi.
Checklist cuối cùng trước khi đưa vào sản xuất
| Điểm kiểm tra | Cần kiểm tra gì |
|---|---|
required đầy đủ |
Mọi thuộc tính khai báo đều nằm trong required |
| Nullable tường minh | Các trường tùy chọn là union ["...", "null"] |
additionalProperties: false |
Trên mọi object, không chỉ gốc |
Không có $ref / allOf / if-then-else |
Schema mở rộng hoàn toàn |
| Giới hạn được tuân thủ | ≤ 5000 thuộc tính, ≤ 10 tầng, ≤ 120k ký tự |
| Ràng buộc vô hiệu đã chuyển | pattern/format được kiểm tra phía ứng dụng |
Xử lý refusal |
Mã phân biệt từ chối với lỗi schema |
| Test bằng yêu cầu thật | Phản hồi thử đã được xác thực trước khi triển khai |
Nếu bạn muốn hiểu vì sao additionalProperties: false lại trung tâm đến vậy, bài phân tích sâu về từ khóa additionalProperties cho thấy mỗi object mở rộng làm nới không gian sinh. Để đưa schema vào pipeline CI với các kiểm tra hợp đồng tự động, quy trình mô tả trong JSON Schema contract testing chặn các hồi quy âm thầm. Và nếu bạn cần tạo schema từ các ví dụ JSON sẵn có, công cụ chuyển đổi sang JSON Schema của nền tảng giúp bạn bắt đầu từ dữ liệu thực — dù vậy, với chế độ strict bạn vẫn cần áp dụng cách viết lại trong bài này.
FAQ
Tại sao tài liệu yêu cầu mọi trường phải required, kể cả tùy chọn?
Vì automaton hữu hạn trạng thái phải quyết định trước khi nào mỗi key hợp lệ. "Tùy chọn" được diễn đạt bằng null, không phải bằng việc vắng key: union nullable là cách chính thức để nói điều đó.
Schema được chấp nhận nhưng pattern không có tác dụng. Đây là bug à?
Không. Ở chế độ strict, pattern, minLength, maximum và format không được ngữ pháp sinh áp dụng. Schema hợp lệ về cú pháp nhưng ràng buộc không tồn tại: kiểm tra phía ứng dụng.
Tôi có thể dùng $ref nếu cũng khai báo $defs không?
Không, cả hai đều bị cấm. Schema phải là một cây duy nhất, mở rộng hoàn toàn. Các script viết lại tự động lo phần mở rộng.
Sự khác biệt giữa refusal và lỗi schema là gì? Refusal là một phản hồi tương thích trong đó mô hình tuyên bố bằng ngữ nghĩa rằng nó không muốn thực hiện công việc. Lỗi schema là 400 khi gửi hoặc đầu ra không tương thích. Đây là hai vấn đề khác nhau với hai cách chữa khác nhau.
Tôi có thể lồng object sâu bao nhiêu? Tối đa 10 tầng lồng và 5000 thuộc tính tổng cộng mỗi schema. Các schema sinh tự động thường vượt qua các giới hạn này: kiểm tra trước khi gửi.
Kết luận
Chế độ strict không phải một tùy chọn trang trí: đó là bước chuyển từ "hy vọng mô hình tôn trọng schema" sang "ngữ pháp ngăn chặn vật lý đầu ra không tương thích". Cái giá là một tập con hà khắc của JSON Schema — required đầy đủ, object đóng kín, không tham chiếu — cùng vài ràng buộc lướt qua unnoticed nhưng không được áp dụng. Dành nửa giờ viết lại bằng script make_strict, đánh dấu union nullable một cách có chủ đích, và luôn test bằng yêu cầu thật trước khi triển khai: pipeline kết quả khác về chất so với pipeline xây trên retry và sửa chữa sau sự cố.