ONE is preparing: 01 / INITIALIZING MODEL ROUTER. Evaluating routing across providers.
Current state
01 / INITIALIZING MODEL ROUTER.

Evaluating routing across providers.

Start learning
← RAG & Agents

AI Builder

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

Vietnamese onlyThe learning content is available in Vietnamese only. The surrounding interface follows your language.

Kỹ thuật đảm bảo LLM sinh ra JSON, XML hoặc schema cố định thay vì văn bản tự do.

lesson94 minRAG & AgentsAI Engineer

Thử đoán

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?

Prompt engineering chỉ giảm lỗi, không triệt để. Structured outputs dùng constrained decoding: tại mỗi bước sinh token, chỉ cho phép tokens tạo JSON hợp lệ. 100% guarantee — giống điền form (chỉ chấp nhận format đúng) thay vì viết thư tự do.

Các kiểu lỗi và cách khắc phục

Kiểu lỗiVí dụVì saoCách khắc phục
Lời mào đầu / kết"Đây là JSON:\n{ … }" hoặc "{ … }\nChúc bạn thành công!"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 [.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 `jsonjson\\n{ … }\\nCopilot-style outputs hay bọc JSON trong code fence. Parser vanilla sẽ lỗi ngay ba backtick đầu.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": 65000LLM follow 'tự nhiên' → thêm dấu chấm, đơn vị. Downstream toán học (+, compare) sẽ vỡ.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_stockVới temperature cao hoặc prompt dài, LLM bỏ sót field. Code mặc định null → UI broken.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" }LLM 'nhiệt tình' đề xuất thêm. DB insert có additional_columns strict sẽ reject.Schema với additionalProperties: false. Constrained decoder loại token mở key ngoài schema.
Trailing comma / single quote{ 'name': 'Phở', }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.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)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.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ớ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.Strict mode ép đúng structure. Nếu không dùng strict, validate với JSON schema validator trước khi consume.
Client yêu cầu JSON, nhưng response bắt đầu bằng 'Đây là JSON:'. Cách sửa gốc nhất?

Khoảnh khắc Aha

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.

Thử thách 1

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?

Không có structured outputs: 3-10% failure rate là bình thường. Với 4 trường x 1000 CVs, có thể 50-100 records lỗi. Trong production: 5% failure = 50 customers nhận lỗi/ngày. Structured outputs: 0% failure.

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ì?

Retry loop: mỗi request fail phải sinh lại toàn bộ output → 2x output tokens cho 7% requests = 7% × 2 = 14% cost tăng. Latency p95 xấu hẳn vì p95 users luôn rơi vào nhóm retry. Strict schema giải quyết gốc rễ.

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
P(tokent∣schema,prefix)∝1[tokent∈Vvalid]⋅exp⁡(zt)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.

Ba cấp độ đảm bảo

CấpCách làmTỷ lệ tuân thủ (theo nguồn bài, chưa kiểm chứng)Nhận xét
Cấp 1 · Prompt"Chỉ trả JSON, không giải thích"~90-95% complianceRẻ, dễ thử. Không đủ cho production.
Cấp 2 · JSON moderesponse_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-strictstrict: true + JSON schema100% match schemaConstrained decoding — chuẩn cho production.

Code theo thư viện

Pydantic + Anthropic

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

OpenAI strict

openai_strict.py

from openai import OpenAI
from pydantic import BaseModel

client = OpenAI()

class Product(BaseModel):
    name: str
    price: int
    category: str
    in_stock: bool

response = client.responses.parse(
    model="gpt-5",
    input="Extract: Phở bò 65.000đ, Cơm tấm (hết)",
    text_format=Product,  # SDK tự convert sang JSON schema strict
)

# response.output_parsed là Product object đã validate

Outlines (OSS)

outlines_local.py

import outlines
from pydantic import BaseModel

class Product(BaseModel):
    name: str
    price: int
    category: str
    in_stock: bool

model = outlines.models.transformers("mistralai/Mistral-7B-v0.3")
generator = outlines.generate.json(model, Product)

result = generator("Phở bò 65.000đ còn hàng")
# Local model, 100% schema-valid, không cần API

Deep dive: grammar → finite state machine

Một JSON schema được compile thành context-free grammar, sau đó lazily chuyển sang pushdown automaton. Mỗi bước decode, engine biết state hiện tại (ví dụ: đang trong string value của key "price", chờ integer đóng bằng dấu phẩy hoặc }). Từ state này sinh ra một mask boolean có độ dài = vocab size. Mask được AND với logits trước softmax.

Chi phí build mask cho mỗi state được cache. Với vocab 128K và grammar cỡ vài chục states, bộ nhớ cache không đáng kể so với KV-cache của transformer.

Điểm quan trọng: mask được áp sau khi logits được tính — tức là model vẫn "nghĩ" tự nhiên, nhưng chỉ được chọn trong tập hợp lệ. Đây là vì sao chất lượng semantic gần như không đổi.

Schema versioning trong production

Schema không phải bất biến: thêm field, bỏ field, thay type đều xảy ra. Nguyên tắc:

  • Thêm field optional: backward-compatible. Bump minor version.
  • Bỏ field: bump major. Giữ 2 version song song cho đến khi consumer migrate xong.
  • Đổi type: luôn major. Coi như bỏ + thêm.
  • Thêm enum value: có thể coerce ngược nếu consumer có default branch.

Thực tế nhiều team lưu schema trong repo Git và pin version vào prompt: "use schema v3.1". Dễ rollback khi cần.

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.

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

Continue the module

Lesson 15 of 16