JSON Toolkit

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

Trung cấpĐọc khoảng 8 phútXuất bản 2026-11-19Cập nhật 2026-11-19
Sơ đồ quy tắc viết lại JSON Schema cho chế độ strict của LLM

Đ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ố.

Tài liệu tham khảo

Bài viết liên quan

Kiểm thử hợp đồng JSON Schema: hàn quy tắc xác thực vào CI

Schema không kết thúc khi viết xong — đó là nơi thoái hóa bắt đầu. Một lỗi chính tả âm thầm nới lỏng xác thực, một lần refactor làm hỏng mọi fixture. Hướng dẫn này trình bày bộ khung kiểm thử hợp đồng khả thi: fixture dương, âm và snapshot, lint chính schema, biên dịch một lần tái sử dụng, và bốn cổng CI biến vỡ hợp đồng thành build đỏ.

Trung cấpĐọc khoảng 8 phútCập nhật 2026-11-05

JSON do LLM trả về bị cắt cụt: xem lý do dừng trước, rồi mới bàn đến sửa

Mô hình trả về JSON đứt giữa một giá trị và trình phân tích chỉ báo số cột. Đóng ngoặc lại thì phân tích được, nhưng mọi trường thiếu đều bị giấu vào trong dữ liệu. Bài viết vạch ranh giới giữa thứ mà việc sửa bản cắt cụt có thể phục hồi trung thực và thứ bắt buộc phải gọi lại.

Thực chiếnĐọc khoảng 5 phútCập nhật 2026-11-14

Không đóng additionalProperties thì xác thực Schema vô nghĩa

Xác thực thành công không đồng nghĩa dữ liệu sạch. Pydantic mặc định bỏ qua trường lạ, Zod gỡ bỏ chúng, Ajv cho qua — tham số bịa và khóa gõ sai lọt thẳng. Bài viết chỉ ra ba dạng chấp nhận im lặng và đưa ra cách làm đầy đủ: đóng đối tượng, kiểm soát ép kiểu, siết từng tầng lồng nhau.

IntermediateĐọc khoảng 8 phútCập nhật 2026-11-02