Instructor: khi LLM trả sai schema, gửi lỗi ngược lại và hỏi thêm lần nữa

Tài liệu Structured Outputs của OpenAI có một câu đáng dừng lại: cả JSON mode lẫn Structured Outputs đều đảm bảo sinh ra JSON hợp lệ, nhưng chỉ Structured Outputs mới đảm bảo bám đúng schema. Nghĩa là một chuỗi JSON parse ngon lành vẫn có thể thiếu trường, sai kiểu, hoặc nhét một ngày tháng vô nghĩa vào chỗ cần số tiền.

Với người làm demo, đó là chuyện nhỏ. Với FDE đang nối LLM vào hệ thống thật của khách hàng, đó là lỗi bật ra lúc hai giờ sáng, giữa một batch dài, trên một provider mà bạn không chọn.

Vì khách hàng hiếm khi để bạn chọn. Người dùng OpenAI, người dùng Anthropic, người chạy model mở qua Ollama trong mạng nội bộ vì dữ liệu không được rời khỏi công ty. Bạn cần một cách ép schema sống được trên nhiều stack như thế, và Instructor, với danh sách provider dài, giải đúng bài toán đó.

Pydantic là hợp đồng, Instructor là người đòi nợ

Pydantic, theo chính tài liệu của dự án, là thư viện validate dữ liệu được dùng rộng rãi nhất trong Python, với lõi validation viết bằng Rust. Quan trọng hơn cho câu chuyện này: một model Pydantic có thể xuất ra JSON Schema, tức là thứ bạn có thể đưa thẳng cho một LLM API để nói “trả về đúng hình này”.

Instructor, do Jason Liu viết, dựng trên nền đó. Trang chủ mô tả thư viện là công cụ trích xuất dữ liệu có cấu trúc từ bất kỳ LLM nào với type safety, validation và tự động retry. Cơ chế cốt lõi nằm ở một dòng trong README: validation thất bại sẽ được tự động thử lại kèm thông báo lỗi.

Mấu chốt nằm ở cụm “kèm thông báo lỗi”. Instructor không chỉ gọi lại cho đến khi may mắn; nó gửi ngược chính lỗi Pydantic sinh ra cho model, giống một reviewer trả PR với comment cụ thể thay vì chỉ bấm reject. Model được biết nó sai ở đâu thay vì phải đoán lại từ đầu.

Viết quy tắc của khách hàng thành code

Thử hình dung bạn đang ở một công ty logistics, nhiệm vụ là đọc email đặt hàng và đẩy vào hệ thống kho. Thay vì viết prompt dài dặn dò “nhớ trả JSON, nhớ số lượng là số nguyên”, bạn khai báo hợp đồng bằng Pydantic:

from pydantic import BaseModel, Field, field_validator

class OrderLine(BaseModel):
    sku: str = Field(description="Mã hàng theo danh mục của khách")
    quantity: int = Field(gt=0)
    unit: str

class Order(BaseModel):
    customer_code: str
    lines: list[OrderLine]
    requested_date: str

    @field_validator("customer_code")
    @classmethod
    def must_be_known(cls, v: str) -> str:
        if not v.startswith("KH-"):
            raise ValueError("customer_code phải bắt đầu bằng KH-")
        return v

Bạn đưa model Order này cho Instructor cùng nội dung email. Khi model trả về quantity là chuỗi “hai thùng” hoặc customer_code thiếu tiền tố, Pydantic bắt lỗi, Instructor đóng gói lỗi đó và hỏi lại. Thứ bạn nhận về cuối cùng là một object Order có kiểu rõ ràng, IDE autocomplete được, và không có đoạn json.loads kèm try/except nào trong code của bạn.

Phần thú vị là validator must_be_known. Đó là tri thức nghiệp vụ của khách hàng, không phải tri thức của model, và bạn đã nhét nó vào vòng lặp sửa lỗi mà không cần dạy lại model bất cứ điều gì.

Đây là lý do Instructor hợp với công việc FDE: mỗi khách hàng có một bộ quy tắc riêng, và Pydantic cho bạn chỗ để viết chúng ra bằng code thay vì bằng câu chữ trong prompt.

Retry là bảo hiểm, không phải phép màu

Mỗi lần hỏi lại là thêm một lần gọi API, tức thêm độ trễ và chi phí, và validator chỉ bắt được những gì bạn chịu viết ra. Một schema lỏng lẻo với toàn trường kiểu str sẽ đi qua Instructor mà không ai hỏi lại gì, dù dữ liệu bên trong vô nghĩa. Chất lượng output vẫn bắt đầu từ chất lượng schema.

Và nếu khách hàng chỉ dùng OpenAI, bạn nên thử Structured Outputs native trước, vì nó đảm bảo bám schema ngay ở tầng API thay vì sửa sau. Instructor thắng ở chỗ khác: nó chạy trên OpenAI, Anthropic, Google, Vertex AI, Mistral, Ollama, llama-cpp-python, Cohere và LiteLLM, nên một codebase có thể theo bạn qua nhiều khách hàng.

Học Pydantic trước, Instructor sau

Cài đặt chỉ là pip install instructor và dự án mang giấy phép MIT, nên rào cản không nằm ở công cụ. Rào cản nằm ở chỗ phần lớn developer dùng Pydantic như một cái khuôn dữ liệu, trong khi ở đây nó là một ngôn ngữ đặc tả: Field(description=...) là prompt, gt=0 là ràng buộc, field_validator là quy tắc nghiệp vụ.

Hãy tập viết model sao cho đọc JSON Schema sinh ra, một người lạ hiểu được bạn muốn gì.

Khi ứng tuyển, nếu job description nhắc tới việc trích xuất dữ liệu có cấu trúc từ LLM, bạn nên đưa kinh nghiệm này lên phần đầu CV. Hãy mô tả việc đã làm thật cụ thể, kiểu “đưa pipeline trích xuất từ prompt thuần sang schema Pydantic với validator nghiệp vụ, chạy qua Instructor trên hai provider khác nhau”.

Mô hình ngôn ngữ sẽ còn đoán sai. Việc của bạn không phải là cầu cho nó đoán đúng, mà là viết ra một hợp đồng đủ chặt để mỗi lần sai đều bị bắt, và được sửa, trước khi chạm vào dữ liệu của khách hàng.