今年每一家 BI 供應商都推出了 NL-to-SQL。每隔幾週就有一篇新的正式環境指南發表。自己打造一套的時間窗口正在關閉——而 demo 與正式部署之間的差距，從來沒有像現在這麼容易量測，這正是這份指南要做的事。
這份指南涵蓋拉開 demo 與正式部署差距的四件事：這些 agent 實際能做什麼、如何在你的 schema 上量測準確度、生成與驗證查詢的架構，以及讓「安全」成為預設而非期望的防護措施。
Text-to-SQL Agent 現在能做什麼
重點：現代的 text-to-SQL 是以執行結果評分、感知 schema、而且越來越 agentic——而單次生成（single-shot）與 agentic 之間的差距，正是大多數團隊輸掉的地方。
2026 年存在兩種形態：
- 單次生成（Single-shot generation）——模型看到 schema 與問題，產出一條 SQL 敘述。在直截了當的問題上，快速、便宜又正確。
- Agentic pipeline——模型會規劃、生成、執行、檢查結果並重試：多步驟分析、澄清問題、後續查詢。較慢也較貴，卻是唯一能撐過模糊問題與多表 JOIN 的形態。
實務上的切分：儀表板與報表用單次生成；使用者會反覆迭代的分析工作階段用 agentic。硬把所有工作塞進同一種形態的團隊，會為錯誤的那一種付費。
基準測試現況，說得誠實一點：在標準的 Spider benchmark 上，目前的系統在無歧義子集上的執行準確度落在八成後段到九成前段——一篇針對 2026 年系統的 IEEE 研究把範圍定在大約 87-91%。而這個警告與數字本身同樣重要：一份 2026 年的分析發現，公開 benchmark 本身普遍存在標註錯誤——這就是為什麼「Spider 說 X」只是你自己 eval 的起點，而不是關於你資料庫的結論。
SQL Agent 為什麼會失敗——而時間窗口正在關閉
重點：三類失敗決定正式環境的成敗——schema 理解、幻覺欄位與方言漂移——而市場現在正同時朝解決方案收斂。
- Schema 理解。 模型無法像你的團隊那樣理解你的 schema：欄位名稱晦澀、關聯是隱含的、目錄比上下文視窗還大。Schema 連結——注入正確的資料表與關聯——是單一最大的準確度槓桿，也是最常被跳過的一個。
- 幻覺欄位。 模型產出一個不存在的欄位，或 JOIN 了彼此沒有關聯的資料表。沒有生成時的驗證，查詢會大聲失敗（unknown column）——或者更糟——以一個細微錯誤的 JOIN 成功執行。
- 方言漂移。 Postgres、Snowflake 與 BigQuery 在實際層面就有差異：引號用法、函式、LIMIT 語義、日期處理。一條在你的開發環境 Postgres 上跑得好好的查詢，到了客戶的資料倉儲上就會壞掉——或者更糟，默默改變意義。
迫切性是真實的：2026 年正式環境 text-to-SQL 工具爆炸性成長——資料庫原生 agent、防護框架與平台整合每個月都在推出。時間窗口每個月都在縮小，因為這份指南描述的這些模式，正在變成基本門檻。
量測準確度：同一個 Schema、同一組問題、五個模型
重點：在你自己的 schema 上做基準測試，用執行評分——絕不用文字比對，也絕不用別人的 schema。
一個下午就能回答你問題的測試：
- 從真實使用者請求建一組 100 題的問題集，涵蓋簡單查詢、多表 JOIN 與模糊措辭。
- 把同一組問題丟進你的候選模型——GPT、Claude、Gemini、DeepSeek，以及 SQL 特化的開放模型——使用完全相同的 schema 注入。
- 以執行結果評分：查詢能不能跑？有沒有回傳預期結果？文字比對式評分會獎勵「相似的 SQL」、懲罰「正確但不同的 SQL」——這正是你想要的評分的鏡像。
- 同時追蹤每次查詢的成本與準確度。一台準確度高 3 個百分點、成本卻貴 10 倍的模型，是一個路由決策，不是贏家。
你要打造的結果表：在你自己的 schema、你自己的方言上，每個模型每次查詢的準確度與成本。這正是路由層消費的資料集——本系列套用在所有 LLM 輸出上的同一套執行評分方法論，特別應用在 SQL 上。
如何架構 Agent：Schema → 生成 → 驗證 → 執行
重點：四個階段，而驗證正是區分正式環境與 demo 的那一個。
核心迴圈，跑在統一 chat endpoint上：
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讓它達到正式環境等級的規則：
- Schema 連結，不是 schema 傾倒。 注入相關的資料表與關聯，而不是整個目錄——上下文預算是真實的，而無關的資料表正是幻覺的起點。工具介面部分適用function-calling 模式。
- 執行前先做靜態驗證。 欄位白名單、敘述型別檢查，正式環境版本再加一個真正的 SQL parser。驗證正是 demo 與正式部署之間的差別。
- 以唯讀方式執行。 連線在結構上就是唯讀——見下方防護措施一節，因為這一項沒有討價還價的空間。
- 只在需要時才用 agentic。 先從單次生成開始；當 eval set 顯示單次生成在真實問題上失敗時，再加入多步驟規劃（本系列的agent 架構）。
如何強制執行防護措施：預設唯讀
重點：四層各自獨立的防護，每一層單獨就足夠——因為失敗案例往往涉及你沒預料到的使用者。
| 防護層 | 阻擋什麼 | 位置 |
|---|---|---|
| 唯讀資料庫帳號 | 所有寫入，結構上就擋掉 | 資料庫設定 |
| 查詢攔截 | 非 SELECT 敘述，無論是哪個模型 | 應用程式中介層 |
| 列數／時間／成本限制 | 失控的查詢與 JOIN | 應用程式中介層 + rate limits |
| 權限範圍控管 | 跨租戶與權限提升查詢 | schema views + access guards |
第一層是團隊最常跳過、也最重要的一層：一個唯讀資料庫帳號，讓「模型生成了 DELETE」從一場事故變成一件不值一提的小事。2026 年的工具已經跟上——正式環境框架現在內建確定性的存取防護，會在生成的查詢上強制執行每位使用者的真實資料存取規則，補上了 prompt 層級指令補不了的跨租戶漏洞。按信任程度排序的模式：資料庫帳號 → 中介層 parser → 每使用者存取防護 → 模型指令。最後一層是禮貌，不是控制。
會上線危險 SQL 的常見錯誤
重點：四類失敗——三個關於安全、一個關於成本，全部可以避免。
- 沒有唯讀強制執行。 帳號不能寫，模型就寫不了。其他一切都是縱深防禦；而這一層就是縱深本身。
- 沒有欄位驗證。 幻覺欄位會大聲失敗——但幻覺JOIN會默默成功。用真正的 parser 做靜態驗證，兩者都能抓到。
- 單一方言部署。 在 Postgres 上測試、卻部署到 Snowflake：方言漂移會把能跑的查詢變成壞掉或細微錯誤的查詢。eval set 必須在你支援的每一種方言上執行。
- 每一條查詢都用前沿模型。 eval set 的成本欄存在有其原因：簡單查詢用預算級模型、只要零頭成本，前沿模型留給那模糊的 10%。自訂路由讓這件事變成機械化操作，模型目錄則列出目前有哪些模型可用。
常見問題
2026 年 text-to-SQL agent 的準確度如何？
在公開 benchmark 的無歧義子集上，執行準確度大約 87-91%——而這些 benchmark 本身有記錄在案的標註錯誤，所以只有你自己 schema 的 eval 數字才算數。複雜多表 schema 上的真實世界準確度更低，這正是 eval set 存在的目的。
如何阻止 agent 幻覺出欄位？
三層防護：只注入相關資料表的 schema、用真正的 parser 對欄位白名單做靜態驗證，以及把失敗回饋給重試的執行期錯誤處理。光靠 prompt 指令不是控制。
唯讀強制執行真的夠嗎？
作為主要控制，是的——唯讀資料庫帳號讓所有生成的寫入都不可能發生，無論模型做什麼。再以查詢攔截、列數／成本限制與每使用者存取防護，作為處理其餘情況的防護層。
單次生成還是 agentic——我該做哪一種？
先從單次生成開始，讓 eval set 來決定。如果真實問題在 JOIN 或模糊性上失敗，再逐步加入 agentic 規劃。一開始就做 agentic 的團隊，會為從來不需要規劃的查詢付規劃的錢。
如何支援多種 SQL 方言？
schema 注入包含方言專屬的指引，eval set 在每一種方言上執行，方言差異（引號用法、函式、LIMIT 語義）則記錄在 prompt 契約裡。在任何一種方言上線之前，先在所有方言上測試。
一條 text-to-SQL 查詢要多少錢？
從預算級模型處理簡單查詢的不到一分錢，到前沿模型處理 agentic 分析的數倍成本。在 eval set 中追蹤每次查詢的成本、依複雜度路由，平均值就能維持在低檔——快速上手展示了讓路由變成設定的統一 endpoint 模式。
總結
Text-to-SQL agent 在 2026 年已經具備正式環境等級，前提是內建這些注意事項：用執行評分在你自己的 schema 上做基準測試、連結 schema 而不是傾倒 schema、執行前先做靜態驗證、並在資料庫層強制唯讀。隨著工具逐漸成熟，時間窗口正在關閉——但現在就把 eval set 與防護措施建好的團隊，會是 agent 真正上線的那群人，而只停留在 demo 的版本，就繼續是 demo。
時間窗口正在關閉——你的 eval set 就是穿過它的方法。立即取得你的 TokSpan API Key，把 100 題問題集丟進幾個模型跑一輪——$5 免費額度足以支應第一輪 eval——然後讓「每美元的準確度」來挑選你的技術棧。