Structured Outputs

Đầu ra có cấu trúc

Nâng caoemerging

1Thử đoán1/6

Bạn yêu cầu LLM trả về danh sách sản phẩm JSON. 95% lần được JSON đúng, 5% lần LLM thêm 'Đây là danh sách...' trước JSON khiến code parse lỗi. Giải pháp?

2Khám phá2/6

Hình minh họa

Bộ thực thi JSON schema

Dán output thô của LLM và xem cách schema ràng buộc từng token.

Strict mode (constrained decoding)

Raw LLM output111 ký tự

Target JSON schema

{

"type": "object",

"additionalProperties": false,

"required": ["name", "price", "category", "in_stock"],

"properties": {

"name": { type: "string" }

"price": { type: "integer" }

"category": { type: "string" }

"in_stock": { type: "boolean" }

}

name — Tên sản phẩm, giữ nguyên chữ hoa/thường của input
price — Giá bán bằng VND, chỉ chấp nhận số nguyên
category — Danh mục (food | drink | other)
in_stock — Còn hàng hay hết, bắt buộc là true hoặc false

Các kiểu fail phổ biến

Lời mào đầu / kết

"Đây là JSON:\n{...}" hoặc "{...}\nChúc bạn thành công!"

Vì sao: LLM được huấn luyện để lịch sự. Nó thêm câu xã giao khiến JSON không còn bắt đầu bằng `{` hoặc `[`.

Fix: Bật JSON mode hoặc strict schema. Backup: dùng regex tìm `{.*}` cuối cùng nhưng chỉ là tạm.

Code fence ```json

```json\n{...}\n```

Vì sao: Copilot-style outputs hay bọc JSON trong code fence. Parser vanilla sẽ lỗi ngay ba backtick đầu.

Fix: Strict mode không bao giờ thêm fence. Nếu không có, strip ```json ... ``` trước khi parse.

Ép kiểu lệch (string vs number)

"price": "65.000đ" thay vì "price": 65000

Vì sao: LLM follow 'tự nhiên' → thêm dấu chấm, đơn vị. Downstream toán học (+, compare) sẽ vỡ.

Fix: Schema khai báo integer. Constrained decoding từ chối token non-digit tại vị trí này.

Thiếu field required

{ "name": "X", "price": 1 } → thiếu category, in_stock

Vì sao: Với temperature cao hoặc prompt dài, LLM bỏ sót field. Code mặc định null → UI broken.

Fix: Strict schema: grammar bắt buộc xuất hiện đủ keys trước khi đóng `}`.

Thêm field ngoài schema

{ ..., "confidence": 0.93, "notes": "best seller" }

Vì sao: LLM 'nhiệt tình' đề xuất thêm. DB insert có additional_columns strict sẽ reject.

Fix: Schema với additionalProperties: false. Constrained decoder loại token mở key ngoài schema.

Trailing comma / single quote

{ 'name': 'Phở', }

Vì sao: LLM học từ JS/Python — dấu phẩy cuối và nháy đơn là hợp lệ ở đó, không hợp lệ trong JSON.

Fix: Grammar JSON chuẩn loại trừ nháy đơn và trailing comma tự động.

Enum bị sáng tạo

"category": "food-and-drink" (schema chỉ có food | drink | other)

Vì sao: Khi enum không chặt, LLM có thể tổ hợp giá trị mới. Downstream switch/case không có case này → undefined.

Fix: Dùng enum strict. Constrained decoder chỉ cho phép token trong tập enum đã compile sẵn.

Nested object bị flatten

"address.city": "Hà Nội" thay vì "address": { "city": "Hà Nội" }

Vì sao: Với schema lồng nhiều lớp, LLM đôi khi flatten bằng dấu chấm — phá cấu trúc consumer expect.

Fix: Strict mode ép đúng structure. Nếu không dùng strict, validate với JSON schema validator trước khi consume.

Chú thích:OK — đúng schemaCoerced — ép kiểu được nhưng nguy hiểmMissing — field bắt buộc bị thiếuExtra — field không có trong schema

3Khoảnh khắc Aha3/6

Structured outputs giống điền form thay vì viết thư. Form chỉ chấp nhận đúng format (tên, email, số điện thoại). Thư tự do có thể viết bất kỳ gì. LLM với constrained decoding = form thông minh — luôn cho output đúng schema, 100% parseable! Đây cũng chính là cơ chế dưới function calling, và là cách đáng tin cậy hơn nhiều so với chỉ dựa vào prompt engineering để xin JSON.

4Thử thách4/6

Bạn cần LLM extract thông tin từ CV: tên, email, kinh nghiệm (list), kỹ năng (list). Schema có 4 trường required. Không có structured outputs, 1000 CVs có bao nhiêu sẽ parse lỗi?

Team bạn đang dùng 'parse → nếu lỗi thì retry' cho 1M requests/ngày, retry rate 7%. Chi phí thêm lớn nhất là gì?

5Giải thích5/6

Giải thích

Structured Outputs đảm bảo LLM sinh output theo schema cố định (JSON, XML) thay vì văn bản tự do — thiết yếu cho production systems.

3 cấp độ đảm bảo:

Prompt-based:"Trả về JSON" — khoảng 90-95% compliance. Không đủ cho production
JSON mode: Đảm bảo valid JSON nhưng không đảm bảo schema. Khoảng 98%
Schema-strict: Constrained decoding theo schema. 100% compliance

Constrained Decoding hoạt động thế nào

Tại mỗi step sinh token: context-free grammar (JSON schema → grammar) xác định set tokens hợp lệ. Mask tokens không hợp lệ trước softmax. Overhead: dưới 5% latency. Tools: Outlines, LM Format Enforcer, vLLM built-in, Anthropic tool_use, OpenAI response_format.

Bẫy: schema quá rộng

Nếu schema cho phép cả string và number cho cùng một field (union type), LLM sẽ tận dụng để output cái dễ hơn — và downstream code vẫn phải branch. Luôn chọn ONE type nhỏ nhất đủ dùng.

Khi nào KHÔNG cần strict mode

Free-form tốt hơn khi: (1) output cho người đọc (giải thích, chat), (2) độ sáng tạo quan trọng hơn format, (3) câu trả lời có thể dài tuỳ ý. Ép JSON ở đây sẽ giảm chất lượng văn phong.

Strict mode không thay được validation

Schema đảm bảo shape, không đảm bảo semantics. LLM vẫn có thể trả price = 1 (âm thầm sai) nếu model hallucinate. Luôn kèm rule business ở layer sau (price > 0, category ∈ enum).

P(\text{token}_t \mid \text{schema}, \text{prefix}) \propto \mathbb{1}[\text{token}_t \in \mathcal{V}_{\text{valid}}] \cdot \exp(z_t)

Ý nghĩa: với constrained decoding, xác suất token ngoài tập hợp lệ được đặt về 0 trước softmax. Những token hợp lệ được chuẩn hoá lại — phân phối vẫn "mượt" nhưng không bao giờ rời khỏi grammar.

Cấp 1 · Prompt

"Chỉ trả JSON, không giải thích"

~90-95% compliance

Rẻ, dễ thử. Không đủ cho production.

Cấp 2 · JSON mode

response_format: { type: "json_object" }

~98% (JSON valid, schema không)

Đảm bảo parse được, không đảm bảo field đúng.

Cấp 3 · Schema-strict

strict: true + JSON schema

100% match schema

Constrained decoding — chuẩn cho production.

structured_outputs.py

import anthropic
from pydantic import BaseModel, Field

client = anthropic.Anthropic()

class Product(BaseModel):
    name: str = Field(description="Tên sản phẩm")
    price: int = Field(description="Giá VND (integer)")
    category: str = Field(description="food | drink | other")
    in_stock: bool

class ProductList(BaseModel):
    products: list[Product]

response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{
        "role": "user",
        "content": (
            "Extract sản phẩm từ menu: "
            "Phở bò 65.000đ, Cơm tấm 55.000đ (hết hàng), Bún chả 50.000đ"
        ),
    }],
    tools=[{
        "name": "output_products",
        "description": "Output danh sách sản phẩm",
        "input_schema": ProductList.model_json_schema(),
    }],
    tool_choice={"type": "tool", "name": "output_products"},
)
# response.content[0].input là JSON đảm bảo match schema

Khi schema trở nên phức tạp:nested objects, arrays of objects, enum với hàng chục giá trị — tất cả đều hỗ trợ. Nhưng càng phức tạp, mask càng lớn, và model cũng khó "nhớ" thứ tự. Mẹo thực tế: flatten schema khi có thể, dùng enum thay vì free string cho category-like fields.

So sánh với function calling:cả hai cùng dùng một cơ chế schema-strict. Function calling chỉ là structured outputs với thêm ngữ cảnh "đây là một tool cần gọi". Nếu chỉ cần extract data, dùng structured outputs trực tiếp gọn hơn. Nếu cần LLM chọn giữa nhiều action, function calling với tool_choice = auto là lựa chọn đúng.

Đo lường compliance trong production:thêm metric "schema_parse_failures_total" vào observability stack. Với strict mode, con số này phải xấp xỉ 0 — nếu tăng đột biến là dấu hiệu API provider đang có vấn đề, không phải bug ở code bạn.

Checklist trước khi ship extract-pipeline có LLM

Schema định nghĩa bằng Pydantic/Zod, commit vào repo với version.
Bật strict mode / response_format schema ở layer client.
additionalProperties: false để chặn hallucinated keys.
Business validation layer sau LLM (price > 0, enum membership).
Metric schema_parse_failures_total = 0 là điều kiện deploy.
Sample 1% output lưu raw để debug khi regress.

6Tổng kết6/6

Tóm tắt

Structured outputs đảm bảo LLM sinh JSON/schema cố định — thiết yếu cho production (0% parse error)
3 cấp: Prompt (khoảng 95%), JSON mode (khoảng 98%), Schema-strict (100% constrained decoding)
Constrained decoding: mask invalid tokens tại mỗi step trước softmax, dưới 5% overhead
Dùng Pydantic BaseModel → model_json_schema() để tự generate schema từ class Python
additionalProperties: false để chặn LLM hallucinated extra keys — strict hơn nữa
Schema đảm bảo SHAPE, không đảm bảo SEMANTICS — vẫn cần business validation layer sau

Kiểm tra hiểu biết

Câu 1/8

Constrained decoding đảm bảo JSON hợp lệ bằng cách nào?

Chủ đề liên quan

Function Calling — Gọi hàm — Khi AI biết dùng công cụ Prompt Engineering — Kỹ thuật viết prompt AI Guardrails — Rào chắn an toàn cho AI