Text-to-SQLAI AgentsLLM API

Text-to-SQL Agent 2026: từ câu hỏi sang truy vấn an toàn

15 thg 8, 20261 phút đọc

Mọi nhà cung cấp BI đều phát hành NL-to-SQL trong năm nay. Cứ vài tuần lại có một hướng dẫn sản xuất mới được đăng. Cửa sổ để tự xây giải pháp của riêng bạn đang khép lại — và khoảng cách giữa demo và triển khai chưa bao giờ dễ đo lường đến vậy, đúng như những gì hướng dẫn này làm.

Hướng dẫn này bao quát bốn thứ tạo nên sự khác biệt giữa demo và triển khai: những gì các agent này thực sự làm được, cách đo độ chính xác trên schema của bạn, kiến trúc tạo và xác thực truy vấn, cùng các guardrail biến “an toàn” thành mặc định thay vì hy vọng.

Text-to-SQL agent hôm nay làm được gì

Điểm chính: text-to-SQL hiện đại được chấm theo kết quả thực thi, nhận biết schema, và ngày càng agentic — và khoảng cách giữa single-shot và agentic chính là nơi hầu hết đội ngũ thua.

Hai hình thái tồn tại trong năm 2026:

Tạo truy vấn single-shot — model nhìn schema và một câu hỏi, rồi phát ra một câu lệnh SQL. Nhanh, rẻ, và chính xác với các câu hỏi đơn giản.
Pipeline agentic — model lập kế hoạch, tạo truy vấn, thực thi, kiểm tra kết quả và retry: phân tích đa bước, câu hỏi làm rõ, truy vấn tiếp theo. Chậm hơn và đắt hơn, và là hình thái duy nhất sống sót được với câu hỏi mơ hồ và join nhiều bảng.

Sự phân chia thực tế: single-shot cho dashboard và báo cáo; agentic cho các phiên phân tích nơi người dùng lặp lại. Đội ngũ ép mọi thứ qua một hình thái sẽ phải trả giá cho hình thái sai.

Thực tế benchmark, nói thẳng: trên benchmark Spider chuẩn, các hệ thống hiện tại đạt độ chính xác thực thi ở mức khoảng 87-91% trên tập con không mơ hồ — một nghiên cứu IEEE về các hệ thống năm 2026 đưa ra khoảng 87-91%. Và lưu ý quan trọng không kém con số: một phân tích năm 2026 phát hiện các lỗi chú thích lan rộng ngay trong chính các benchmark công khai, đó là lý do “Spider nói X” chỉ là điểm khởi đầu cho bộ đánh giá của riêng bạn, không phải kết luận về cơ sở dữ liệu của bạn.

Vì sao SQL agent thất bại — và cửa sổ đang khép lại

Điểm chính: ba loại thất bại quyết định kết quả trong production — hiểu schema, cột bịa đặt và trôi dạt dialect — và thị trường đang hội tụ về giải pháp ngay lúc này.

Hiểu schema. Model không hiểu schema của bạn theo cách đội ngũ của bạn hiểu: tên cột khó đoán, mối quan hệ ẩn, và catalog lớn hơn cửa sổ ngữ cảnh. Schema linking — tiêm đúng bảng và mối quan hệ — là đòn bẩy độ chính xác lớn nhất, và cũng là thứ hay bị bỏ qua nhất.
Cột bịa đặt. Model phát ra một cột không tồn tại, hoặc join các bảng không có mối quan hệ nào. Không có xác thực tại thời điểm tạo truy vấn, câu query sẽ lỗi ầm ĩ (unknown column) hoặc — tệ hơn — thành công với một join sai tinh vi.
Trôi dạt dialect. Postgres, Snowflake và BigQuery khác nhau theo những cách thực tế: cách đặt dấu ngoặc kép, hàm, ngữ nghĩa LIMIT, xử lý ngày tháng. Một query chạy hoàn hảo trên Postgres dev của bạn sẽ hỏng — hoặc tệ hơn, âm thầm đổi nghĩa — trên warehouse của khách hàng.

Tính cấp bách là có thật: năm 2026 chứng kiến sự bùng nổ của công cụ text-to-SQL sản xuất — agent bản địa của cơ sở dữ liệu, framework guardrail và tích hợp nền tảng ra mắt hằng tháng. Mỗi tháng cửa sổ lại hẹp thêm, vì những mô hình mà hướng dẫn này mô tả đang trở thành điều kiện cơ bản.

Độ chính xác đo được: cùng schema, cùng câu hỏi, năm model

Điểm chính: hãy benchmark trên schema của bạn, chấm theo kết quả thực thi — không bao giờ so khớp văn bản, và không bao giờ dùng schema của người khác.

Bài kiểm tra trả lời câu hỏi của bạn, chỉ trong một buổi chiều:

Xây bộ 100 câu hỏi từ các yêu cầu thực của người dùng, bao phủ tra cứu đơn giản, join nhiều bảng và cách diễn đạt mơ hồ.
Chạy cùng bộ câu hỏi qua các model ứng viên — GPT, Claude, Gemini, DeepSeek và các model mở chuyên SQL — với cùng cách tiêm schema.
Chấm theo thực thi: query có chạy không, và có trả về kết quả mong đợi không? Chấm theo so khớp văn bản khen “SQL tương tự” và phạt “SQL khác nhưng đúng” — chính xác là điều ngược lại với những gì bạn muốn.
Theo dõi chi phí mỗi query song song với độ chính xác. Một model chính xác hơn 3 điểm nhưng đắt gấp 10 lần là một quyết định định tuyến, không phải người thắng.

Bảng kết quả bạn đang hướng tới: độ chính xác và chi phí mỗi query theo từng model, trên schema của bạn, với dialect của bạn. Đó là tập dữ liệu mà lớp định tuyến tiêu thụ — cùng phương pháp luận chấm theo thực thi mà loạt bài này áp dụng cho mọi đầu ra LLM, giờ áp dụng riêng cho SQL.

Cách thiết kế kiến trúc cho agent: Schema → Generate → Validate → Execute

Điểm chính: bốn giai đoạn, và xác thực chính là thứ tách production khỏi demo.

Vòng lặp cốt lõi, trên endpoint hợp nhất:

import sqlite3
from openai import OpenAI

client = OpenAI()  # unified endpoint

def build_prompt(schema_snippet: str, question: str) -> list[dict]:
    return [
        {"role": "system", "content":
            "You write SQL for this schema. Use ONLY tables and columns shown. "
            "Never invent columns. Dialect: PostgreSQL.\n\n" + schema_snippet},
        {"role": "user", "content": question},
    ]

def validate_sql(sql: str, valid_columns: set[str]) -> str | None:
    # Static validation: reject unknown columns and non-SELECT statements
    if not sql.strip().upper().startswith("SELECT"):
        return None
    # Column whitelist check (simplified — production uses a real parser)
    return sql if any(c in sql for c in valid_columns) else None

def run(question: str, schema_snippet: str, valid_columns: set[str], conn: sqlite3.Connection):
    sql = client.chat.completions.create(
        model="gpt-4o-mini",
        messages=build_prompt(schema_snippet, question),
    ).choices[0].message.content
    sql = validate_sql(sql, valid_columns)
    if sql is None:
        return {"error": "query rejected by guard"}
    return conn.execute(sql).fetchall()  # read-only connection only

Những quy tắc đưa nó lên cấp production:

Schema linking, không phải schema dumping. Tiêm các bảng và mối quan hệ liên quan, không phải toàn bộ catalog — ngân sách ngữ cảnh là có thật, và các bảng không liên quan chính là nơi ảo giác bắt đầu. Các mô hình function calling áp dụng cho lớp API tool.
Xác thực tĩnh trước khi thực thi. Danh sách cột cho phép, kiểm tra loại câu lệnh, và một parser SQL thực thụ cho phiên bản production. Xác thực là khác biệt giữa demo và triển khai.
Thực thi read-only. Kết nối read-only ngay từ thiết kế — xem phần guardrail bên dưới, vì đây là điều không thể thương lượng.
Chỉ agentic khi cần. Bắt đầu với single-shot; thêm lập kế hoạch đa bước (kiến trúc agent trong loạt bài này) chỉ khi bộ đánh giá cho thấy single-shot thất bại trên các câu hỏi thực.

Cách thực thi guardrail: read-only theo mặc định

Điểm chính: bốn lớp độc lập, mỗi lớp tự nó đã đủ — vì kịch bản thất bại liên quan đến một người dùng mà bạn không lường trước.

Lớp	Chặn điều gì	Nằm ở đâu
Tài khoản database read-only	mọi thao tác ghi, về mặt cấu trúc	cấu hình database
Chặn truy vấn	câu lệnh không phải SELECT, bất kể model nào	application middleware
Giới hạn row/thời gian/chi phí	query và join vượt kiểm soát	application middleware + rate limits
Phân quyền truy cập	truy vấn xuyên tenant và leo thang đặc quyền	schema views + access guards

Lớp đầu tiên là lớp đội ngũ hay bỏ qua và cũng là lớp quan trọng nhất: một tài khoản database read-only biến “model tạo ra DELETE” thành chuyện thường thay vì một sự cố. Công cụ năm 2026 đã bắt kịp — các framework production giờ đây đi kèm access guard có tính tất định, thực thi đúng quy tắc truy cập dữ liệu thực của từng người dùng trên các truy vấn được tạo ra, qua đó bịt lỗ hổng xuyên tenant mà chỉ dẫn cấp prompt không thể. Mô hình, theo thứ tự tin cậy: tài khoản database → middleware parser → access guard theo người dùng → chỉ dẫn model. Lớp cuối cùng chỉ là phép lịch sự, không phải biện pháp kiểm soát.

Những sai lầm phổ biến đưa SQL nguy hiểm vào sản xuất

Điểm chính: bốn loại thất bại — ba về an toàn, một về chi phí, tất cả đều tránh được.

Không thực thi read-only. Model không thể ghi nếu tài khoản không thể ghi. Mọi thứ khác là phòng thủ nhiều lớp; đây chính là lớp sâu nhất.
Không xác thực cột. Cột bịa đặt lỗi ầm ĩ — nhưng join bịa đặt lại thành công âm thầm. Xác thực tĩnh với một parser thực thụ bắt được cả hai.
Triển khai chỉ một dialect. Kiểm thử trên Postgres, triển khai lên Snowflake: trôi dạt dialect biến các query đang chạy tốt thành hỏng hoặc sai tinh vi. Bộ đánh giá phải chạy trên mọi dialect bạn hỗ trợ.
Dùng model hàng đầu cho mọi query. Cột chi phí trong bộ đánh giá tồn tại có lý do: tra cứu đơn giản trên model giá rẻ với chi phí chỉ bằng một phần nhỏ, model hàng đầu dành riêng cho 10% câu hỏi mơ hồ. Custom routing tự động hóa việc này, và danh mục model cho thấy những gì khả dụng.

Câu hỏi thường gặp

Text-to-SQL agent trong năm 2026 chính xác đến mức nào?

Trên tập con không mơ hồ của các benchmark công khai, khoảng 87-91% độ chính xác thực thi — và bản thân các benchmark có lỗi chú thích đã được ghi nhận, nên bộ đánh giá trên schema của bạn mới là con số duy nhất đáng quan tâm. Độ chính xác thực tế trên các schema nhiều bảng phức tạp thấp hơn, và đó chính là mục đích của bộ đánh giá.

Làm sao ngăn agent bịa cột?

Ba lớp: tiêm schema chỉ với các bảng liên quan, xác thực tĩnh đối chiếu danh sách cột cho phép bằng một parser thực thụ, và xử lý lỗi tại thời điểm thực thi đưa lỗi quay lại để retry. Chỉ dẫn trong prompt một mình không phải là biện pháp kiểm soát.

Thực thi read-only có thực sự đủ không?

Là biện pháp kiểm soát chính, có — một tài khoản database read-only khiến mọi thao tác ghi được tạo ra trở nên bất khả thi, bất kể model làm gì. Thêm chặn truy vấn, giới hạn row/chi phí và access guard theo người dùng làm các lớp xử lý phần còn lại.

Single-shot hay agentic — tôi nên xây cái nào?

Bắt đầu với single-shot và để bộ đánh giá quyết định. Nếu các câu hỏi thực thất bại ở join hoặc độ mơ hồ, hãy thêm lập kế hoạch agentic từng bước. Đội ngũ bắt đầu với agentic sẽ trả tiền cho việc lập kế hoạch trên những query chưa bao giờ cần nó.

Làm sao hỗ trợ nhiều dialect SQL?

Việc tiêm schema bao gồm chỉ dẫn riêng theo dialect, bộ đánh giá chạy trên mọi dialect, và các khác biệt dialect (dấu ngoặc kép, hàm, ngữ nghĩa LIMIT) được ghi trong hợp đồng prompt. Hãy kiểm thử trên mọi dialect trước khi bất kỳ dialect nào được đưa vào sản xuất.

Một query text-to-SQL tốn bao nhiêu?

Từ vài phần của một xu trên model giá rẻ cho tra cứu đơn giản đến nhiều lần mức đó trên model hàng đầu cho phân tích agentic. Theo dõi chi phí mỗi query trong bộ đánh giá, định tuyến theo độ phức tạp, và mức trung bình sẽ luôn thấp — quickstart cho thấy mô hình endpoint hợp nhất giúp định tuyến trở thành cấu hình.

Tóm tắt

Text-to-SQL agent đã sẵn sàng cho production trong năm 2026, kèm theo những lưu ý đã được tính sẵn: benchmark trên schema của bạn với cách chấm theo thực thi, link schema thay vì dump toàn bộ, xác thực tĩnh trước khi thực thi, và thực thi read-only ngay ở lớp database. Cửa sổ đang khép lại khi công cụ trưởng thành — nhưng những đội ngũ xây bộ đánh giá và guardrail ngay bây giờ sẽ là những người đưa agent của mình lên sản xuất, trong khi các phiên bản chỉ-demo vẫn mãi là demo.

Cửa sổ đang khép lại — bộ đánh giá của bạn là con đường xuyên qua nó. Lấy API key TokSpan của bạn, chạy bộ 100 câu hỏi qua vài model — $5 tín dụng miễn phí đủ cho lần đánh giá đầu tiên — và để độ chính xác-trên-mỗi-đô-la chọn stack cho bạn.