現(xiàn)輕量 Text2SQL：讓自然語(yǔ)言直接查詢(xún)數(shù)據(jù)庫(kù))
過(guò)去半年我一直在折騰一個(gè)很現(xiàn)實(shí)的問(wèn)題怎么讓不會(huì)寫(xiě) SQL 的人也能直接對(duì)著數(shù)據(jù)庫(kù)問(wèn)問(wèn)題。最終落地的是一個(gè)用 DeepSeek 做大模型推理、SQLite 做數(shù)據(jù)存儲(chǔ)的輕量 Text2SQL 查詢(xún)助手——輸入一句中文比如“上個(gè)月銷(xiāo)售額最高的三個(gè)商品”它自動(dòng)生成 SQL、在 SQLite 引擎里執(zhí)行再把結(jié)果用表格形式返回。整個(gè)過(guò)程不用寫(xiě)一行 SQL也不用部署重型數(shù)據(jù)庫(kù)服務(wù)。這個(gè)項(xiàng)目是典型的 LLM 落地形態(tài)不需要訓(xùn)練、不需要私有化部署大模型只需要把數(shù)據(jù)庫(kù)結(jié)構(gòu)和查詢(xún)約束交代給模型它就能輸出可執(zhí)行 SQL。整套代碼加起來(lái)不到 200 行特別適合第一次認(rèn)真做 Text2SQL 的人拿來(lái)當(dāng)模板也適合想驗(yàn)證大模型在生成式查詢(xún)場(chǎng)景里到底穩(wěn)不穩(wěn)的開(kāi)發(fā)者做一輪實(shí)測(cè)。下面我把從零搭建的完整過(guò)程講清楚包括提示詞設(shè)計(jì)、SQL 安全校驗(yàn)、錯(cuò)誤糾錯(cuò)循環(huán)以及我實(shí)際踩過(guò)的坑。1. 為什么選 Text2SQL 作為 LLM 落地項(xiàng)目整體思路是什么1.1 一句話(huà)描述項(xiàng)目形態(tài)這個(gè)查詢(xún)助手的核心鏈路可以概括為用戶(hù)輸入自然語(yǔ)言問(wèn)題 → 系統(tǒng)把 SQLite 的 schema 注入提示詞 → 調(diào)用 DeepSeek 生成 SQL → 程序提取并校驗(yàn) SQL → 在 SQLite 中執(zhí)行 → 返回查詢(xún)結(jié)果。如果生成的 SQL 報(bào)錯(cuò)程序會(huì)把錯(cuò)誤信息回傳給模型讓它基于錯(cuò)誤修正后重新生成。聽(tīng)起來(lái)很順但真正實(shí)施起來(lái)有幾個(gè)難點(diǎn)模型可能生成不存在的字段名可能寫(xiě)出 SQLite 不支持的語(yǔ)法甚至可能生成插入、刪除這類(lèi)危險(xiǎn)語(yǔ)句。所以這個(gè)項(xiàng)目表面上是在調(diào) API本質(zhì)上是在做三件事讓模型“看懂”庫(kù)結(jié)構(gòu)、讓輸出“規(guī)規(guī)矩矩”變成純 SQL、讓執(zhí)行過(guò)程“萬(wàn)無(wú)一失”不會(huì)破壞數(shù)據(jù)。1.2 為什么選 DeepSeek SQLite 這套組合先聊模型選型。Text2SQL 對(duì)模型的要求是中文理解能力強(qiáng)、SQL 語(yǔ)法知識(shí)扎實(shí)、輸出穩(wěn)定。DeepSeek 的開(kāi)放接口兼容 OpenAI 調(diào)用格式代碼上接入成本很低而且在實(shí)際測(cè)試中它對(duì)中文業(yè)務(wù)問(wèn)題的理解明顯比通用模型更貼近中文語(yǔ)境生成的 SQL 也習(xí)慣用注釋和 LIMIT 這類(lèi)安全寫(xiě)法。再聊數(shù)據(jù)庫(kù)選型。SQLite 是單文件數(shù)據(jù)庫(kù)不需要安裝服務(wù)端一個(gè).db文件就能承載一張完整的業(yè)務(wù)表結(jié)構(gòu)。對(duì)于個(gè)人工具、內(nèi)部小助手這類(lèi)場(chǎng)景它簡(jiǎn)直是絕配輕、免維護(hù)、隨時(shí)可以復(fù)制走。相比 MySQL、PostgreSQLSQLite 還能用只讀 URI 模式打開(kāi)天然適合給 LLM 生成的查詢(xún)語(yǔ)句做執(zhí)行沙箱。這套組合的另一個(gè)優(yōu)勢(shì)是成本極低。單次查詢(xún)請(qǐng)求通常只消耗幾千 token跑幾百次測(cè)試的成本也就在幾塊錢(qián)量級(jí)可以放心反復(fù)實(shí)驗(yàn)。相比接一個(gè)獨(dú)立的數(shù)據(jù)庫(kù)服務(wù)開(kāi)發(fā)階段省掉的不只是部署還有連接配置、賬號(hào)權(quán)限、網(wǎng)絡(luò)安全這一堆事。1.3 整體流程設(shè)計(jì)一次查詢(xún)請(qǐng)求是怎么走通的我把它拆成五個(gè)環(huán)節(jié)取 schema、拼提示詞、調(diào)模型、執(zhí)行 SQL、反饋糾錯(cuò)。前兩個(gè)環(huán)節(jié)是準(zhǔn)備中間一個(gè)是核心后兩個(gè)是保障。取 schema 這一步很多人會(huì)偷懶覺(jué)得寫(xiě)死幾張表名就行了。實(shí)際上模型能不能生成正確 SQL很大程度上取決于它能不能看到完整字段名和類(lèi)型。我選擇通過(guò)sqlite_master系統(tǒng)表自動(dòng)讀取建表語(yǔ)句這樣數(shù)據(jù)庫(kù)結(jié)構(gòu)一變提示詞也會(huì)自動(dòng)跟上。拼提示詞是最考功底的一步。要把數(shù)據(jù)庫(kù)結(jié)構(gòu)、業(yè)務(wù)字段說(shuō)明、輸出格式限制、安全約束全部塞進(jìn)一段上下文里。提示詞不是越長(zhǎng)越好而是要讓模型明確三件事回答范圍是什么、輸出格式是什么、禁區(qū)是什么。調(diào)模型和執(zhí)行 SQL 之間隔著一道安全檢查。LLM 生成的內(nèi)容本質(zhì)上不可信不能直接丟給數(shù)據(jù)庫(kù)執(zhí)行。我加了兩層防護(hù)關(guān)鍵字黑名單和只讀打開(kāi)連接。前者擋掉語(yǔ)義層面的危險(xiǎn)語(yǔ)句后者從數(shù)據(jù)庫(kù)層面保證即使漏網(wǎng)也改不了任何數(shù)據(jù)。整個(gè)設(shè)計(jì)里最讓我得意的是糾錯(cuò)循環(huán)。第一次生成的 SQL 很可能會(huì)因?yàn)樽侄蚊村e(cuò)、函數(shù)用錯(cuò)而執(zhí)行失敗。傳統(tǒng)的做法是讓用戶(hù)重新問(wèn)一遍但我在執(zhí)行出錯(cuò)時(shí)會(huì)把 SQLite 返回的錯(cuò)誤信息拼回對(duì)話(huà)上下文讓模型直接改寫(xiě)。這樣一次失敗的查詢(xún)往往能在第二次、第三次嘗試內(nèi)自我修復(fù)用戶(hù)體驗(yàn)好很多。2. 動(dòng)手前準(zhǔn)備示例庫(kù)、API 接入與 schema 注入2.1 建一個(gè)能說(shuō)明問(wèn)題的小型 SQLite 示例庫(kù)為了測(cè)試多表關(guān)聯(lián)和聚合查詢(xún)我建立了一個(gè)非常接近真實(shí)業(yè)務(wù)的三表結(jié)構(gòu)用戶(hù)表、商品表、訂單表。訂單表通過(guò)外鍵關(guān)聯(lián)用戶(hù)和商品這樣可以很方便地演示 JOIN、GROUP BY、子查詢(xún)這類(lèi)常見(jiàn)需求。建表 SQL 如下DROP TABLE IF EXISTS users; CREATE TABLE users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER, city TEXT, created_at TEXT NOT NULL ); DROP TABLE IF EXISTS products; CREATE TABLE products ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, category TEXT, price REAL, stock INTEGER ); DROP TABLE IF EXISTS orders; CREATE TABLE orders ( id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, product_id INTEGER NOT NULL, quantity INTEGER NOT NULL, order_time TEXT NOT NULL, FOREIGN KEY (user_id) REFERENCES users(id), FOREIGN KEY (product_id) REFERENCES products(id) );有一點(diǎn)需要注意SQLite 本身對(duì)字段類(lèi)型非常寬容所以時(shí)間字段我統(tǒng)一存成YYYY-MM-DD HH:MM:SS格式的字符串。這樣模型在做時(shí)間范圍查詢(xún)時(shí)可以用strftime或字符串比較不容易出錯(cuò)。插入數(shù)據(jù)也不必太復(fù)雜每個(gè)表放 20 條左右就夠測(cè)試了。記得讓訂單分布在不同的月份和城市因?yàn)椤吧蟼€(gè)月”這類(lèi)帶時(shí)間條件的查詢(xún)是 Text2SQL 測(cè)評(píng)的重災(zāi)區(qū)數(shù)據(jù)設(shè)計(jì)時(shí)就要故意制造可查詢(xún)的時(shí)間跨度。2.2 DeepSeek API 的接入方式DeepSeek 提供了 OpenAI 兼容的接口所以我直接用openaiPython 庫(kù)來(lái)調(diào)用避免另外封裝一套請(qǐng)求邏輯。所有需要登錄的密鑰都通過(guò)環(huán)境變量讀取絕不硬編碼在腳本里。import os from openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com ) def ask_deepseek(messages, temperature0.0): resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, temperaturetemperature, ) return resp.choices[0].message.content把溫度設(shè)置成 0 是我反復(fù)測(cè)試后確定的。Text2SQL 不是創(chuàng)意寫(xiě)作它需要確定性輸出。溫度一旦調(diào)高模型可能用不同的語(yǔ)法表達(dá)同一個(gè)查詢(xún)這會(huì)給后續(xù)糾錯(cuò)增加不必要的變量。如果你不想引入 openai 庫(kù)直接用requests調(diào)官方接口也是可行的但openai庫(kù)在消息構(gòu)造、超時(shí)處理、錯(cuò)誤信息這些方面已經(jīng)封裝得很好我建議直接用它。2.3 schema 自動(dòng)注入機(jī)制模型不知道你的庫(kù)長(zhǎng)什么樣所以每次查詢(xún)前都要把結(jié)構(gòu)信息喂給它。手動(dòng)寫(xiě)一段固定的 schema 描述很容易但數(shù)據(jù)庫(kù)一變就維護(hù)不過(guò)來(lái)了。我的做法是從 SQLite 系統(tǒng)表讀取真實(shí)建表語(yǔ)句再組裝成一段純文本。import sqlite3 def get_schema(db_path): conn sqlite3.connect(db_path) rows conn.execute( SELECT sql FROM sqlite_master WHERE typetable AND sql IS NOT NULL ).fetchall() conn.close() return \n\n.join(r[0] for r in rows)這樣返回的 schema 是原始的 CREATE TABLE 語(yǔ)句包含字段名、類(lèi)型、外鍵約束。模型對(duì)這種結(jié)構(gòu)化文本的吸收能力很強(qiáng)幾乎不需要再做格式化。唯一要補(bǔ)充的是業(yè)務(wù)說(shuō)明比如“price 單位是元”“order_time 是下單時(shí)間”。我會(huì)把這些注釋追加到 schema 末尾而不是直接改建表語(yǔ)句保持?jǐn)?shù)據(jù)庫(kù)文件干凈。實(shí)際測(cè)試下來(lái)schema 加上一句“請(qǐng)基于上面的表結(jié)構(gòu)生成 SQLite 方言的 SQL”就能明顯壓低模型使用錯(cuò)誤表名和字段名的概率。這一步做好后面所有環(huán)節(jié)都會(huì)省心很多。3. 核心代碼逐段拆解提示詞、安全校驗(yàn)與糾錯(cuò)循環(huán)3.1 提示詞模板是如何讓模型穩(wěn)定輸出 SQL 的提示詞設(shè)計(jì)是這個(gè)項(xiàng)目最核心的環(huán)節(jié)。一開(kāi)始我寫(xiě)得很簡(jiǎn)陋就一句“把下面的話(huà)轉(zhuǎn)成 SQL”結(jié)果模型輸出五花八門(mén)有的帶解釋有的用 MySQL 語(yǔ)法有的直接拒絕回答。后來(lái)我總結(jié)出一套有效的模板核心是四項(xiàng)約束。SYSTEM_PROMPT 你是一個(gè)精通 SQLite 的數(shù)據(jù)庫(kù)查詢(xún)助手。 請(qǐng)根據(jù)數(shù)據(jù)庫(kù) schema 和用戶(hù)問(wèn)題生成可直接執(zhí)行的 SQL 查詢(xún)。 要求 1. 只輸出 SQL 語(yǔ)句本身不要輸出任何解釋、代碼塊標(biāo)記。 2. 只允許 SELECT 查詢(xún)禁止 INSERT、UPDATE、DELETE、DROP 等語(yǔ)句。 3. 使用 SQLite 語(yǔ)法不要使用其他數(shù)據(jù)庫(kù)的專(zhuān)用函數(shù)。 4. 查詢(xún)結(jié)果默認(rèn)加上 LIMIT 50。 5. 如果問(wèn)題與數(shù)據(jù)庫(kù)無(wú)關(guān)或無(wú)法用提供的 schema 回答輸出 SQL_ERR: 無(wú)法回答。 def build_messages(user_question, schema, error_hintNone): user_content f數(shù)據(jù)庫(kù) schema:\n{schema}\n\n用戶(hù)問(wèn)題: {user_question} messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_content}, ] if error_hint: messages.append({ role: assistant, content: error_hint[sql] }) messages.append({ role: user, content: f你生成的 SQL 執(zhí)行報(bào)錯(cuò){error_hint[error]}\\n請(qǐng)修正后重寫(xiě)。 }) return messages第一條約束解決了“模型話(huà)多”的問(wèn)題。你可能會(huì)覺(jué)得讓模型輸出解釋更友好但對(duì)程序來(lái)說(shuō)解析一段可能有代碼標(biāo)記和廢話(huà)的文本遠(yuǎn)比解析純 SQL 麻煩。我寧可讓模型輸出裸 SQL再由程序負(fù)責(zé)展示結(jié)果。第二條約束是安全底線(xiàn)。模型本身沒(méi)有惡意但它可能因?yàn)橛脩?hù)問(wèn)題描述不當(dāng)而生成危險(xiǎn)語(yǔ)句。直接在提示詞里聲明禁區(qū)能從源頭過(guò)濾一大半風(fēng)險(xiǎn)。第三、四條約束屬于方言限定。SQLite 的日期函數(shù)、字符串處理方式和 MySQL、PostgreSQL 差別很大提前聲明可以避免模型想當(dāng)然地寫(xiě)出DATE_FORMAT這類(lèi)函數(shù)。3.2 SQL 安全校驗(yàn)為什么 LLM 的輸出不能直接執(zhí)行即使提示詞說(shuō)了“只允許 SELECT”我也在代碼里加了獨(dú)立校驗(yàn)。原因很簡(jiǎn)單提示詞是對(duì)模型的軟約束不是硬保證。模型可能因?yàn)樯舷挛奶L(zhǎng)而忽略限制也可能被一種叫“注入攻擊”的手段繞過(guò)。我的校驗(yàn)分為三層。第一層去掉首尾空白、將 SQL 轉(zhuǎn)成小寫(xiě)后檢查是否包含insert、update、delete、drop、alter、attach、pragma這些關(guān)鍵詞。第二層檢查第一個(gè)非空語(yǔ)句是否以select或with開(kāi)頭。第三層用只讀 URI 模式連接 SQLite從數(shù)據(jù)庫(kù)層保證任何寫(xiě)操作都會(huì)拋出錯(cuò)誤。import os import re BANNED_KEYWORDS [insert, update, delete, drop, alter, attach, pragma] def extract_sql(text): blocks re.findall(r(?:sql)?\\s*(.*?), text, re.S) if blocks: return blocks[0].strip() if text.startswith(SQL_ERR): return None return text.strip() def check_sql(sql): if not sql: return False, 空 SQL low sql.lower() for kw in BANNED_KEYWORDS: if re.search(r\\b kw r\\b, low): return False, f包含危險(xiǎn)關(guān)鍵詞 {kw} if not re.match(r^(select|with)\\b, low): return False, 必須以 SELECT 或 WITH 開(kāi)頭 return True, def execute_readonly(db_path, sql): uri ffile:{os.path.abspath(db_path)}?modero conn sqlite3.connect(uri, uriTrue, timeout10) try: cur conn.execute(sql) cols [d[0] for d in cur.description] if cur.description else [] rows cur.fetchall() return cols, rows finally: conn.close()我用了一個(gè)很實(shí)用的技巧如果 SQL 里包含注釋或者多余空白正則也能提取干凈。另外execute_readonly返回的不僅包含結(jié)果行還包含列名。這樣在命令行里展示時(shí)可以直接拿列名做表頭省得再查一次PRAGMA table_info。3.3 帶糾錯(cuò)的主流程一次查詢(xún)失敗怎么辦第一次生成的 SQL 執(zhí)行失敗太常見(jiàn)了。我的處理方法是把 SQL 和錯(cuò)誤信息一起回傳給模型讓它看到自己寫(xiě)的代碼和數(shù)據(jù)庫(kù)的真實(shí)反應(yīng)然后要求它修正。這相當(dāng)于給模型一個(gè)“現(xiàn)場(chǎng)調(diào)試”的機(jī)會(huì)。def text2sql(db_path, question, max_retries2): schema get_schema(db_path) messages build_messages(question, schema) for attempt in range(max_retries 1): raw ask_deepseek(messages) sql extract_sql(raw) if sql is None: return {error: 模型無(wú)法生成 SQL, raw: raw} ok, msg check_sql(sql) if not ok: messages build_messages(question, schema, {sql: sql, error: msg}) continue try: cols, rows execute_readonly(db_path, sql) return {sql: sql, columns: cols, rows: rows} except sqlite3.Error as e: messages build_messages(question, schema, {sql: sql, error: str(e)}) return {error: 重試次數(shù)用盡, sql: sql}這里有個(gè)細(xì)節(jié)值得多說(shuō)兩句重試時(shí)不是簡(jiǎn)單地把錯(cuò)誤信息追加到原消息尾部而是完整重建 message 列表并在其中模擬一段“助手生成了 SQL用戶(hù)反饋了報(bào)錯(cuò)”的對(duì)話(huà)。這樣做的好處是模型能明確看到自己的上一次輸出而不是在越來(lái)越長(zhǎng)的上下文里迷失。實(shí)測(cè)中絕大多數(shù)語(yǔ)法錯(cuò)誤和字段名錯(cuò)誤都能在第一次糾錯(cuò)內(nèi)解決。3.4 一個(gè)可以直接跑的命令行主循環(huán)把上面的函數(shù)組合起來(lái)就是一個(gè)完整的命令行查詢(xún)助手。它支持exit退出每次輸入問(wèn)題都會(huì)打印 SQL 和查詢(xún)結(jié)果。def main(): db_path shop.db print(Text2SQL 查詢(xún)助手已啟動(dòng)輸入 exit 退出。) while True: question input(\\n問(wèn)題: ).strip() if question.lower() in (exit, quit): break if not question: continue result text2sql(db_path, question) if error in result: print(錯(cuò)誤:, result[error]) continue print(\\nSQL:, result[sql]) if result[columns]: print(\\t.join(result[columns])) for row in result[rows]: print(\\t.join(str(c) for c in row)) if __name__ __main__: main()整個(gè)腳本文件大概 150 行。你如果只想快速驗(yàn)證效果把這段代碼存成text2sql_assistant.py再設(shè)置好環(huán)境變量就能啟動(dòng)。別急著加界面、加日志、加權(quán)限控制輕量才是這個(gè)項(xiàng)目的定位。等驗(yàn)證完模型效果再去擴(kuò)展 UI 和配套能力也不遲。4. 實(shí)測(cè)效果與幾個(gè)值得注意的點(diǎn)4.1 一組典型查詢(xún)的輸入與輸出對(duì)比我把腳本跑起來(lái)后連續(xù)問(wèn)了十多個(gè)問(wèn)題包括單表過(guò)濾、聚合、多表關(guān)聯(lián)、時(shí)間范圍、排序取前幾。下面是幾組有代表性的結(jié)果自然語(yǔ)言問(wèn)題生成的 SQL節(jié)選執(zhí)行結(jié)果每個(gè)城市的用戶(hù)數(shù)量是多少SELECT city, COUNT(*) AS cnt FROM users GROUP BY city ORDER BY cnt DESC正常返回上個(gè)月銷(xiāo)量最高的三個(gè)商品SELECT p.name, SUM(o.quantity) AS total FROM orders o JOIN products p ON o.product_id p.id WHERE strftime(%Y-%m, o.order_time) strftime(%Y-%m, now, -1 month) GROUP BY p.name ORDER BY total DESC LIMIT 3正常返回哪些商品價(jià)格超過(guò)100元但庫(kù)存不足20件SELECT name, price, stock FROM products WHERE price 100 AND stock 20正常返回找出購(gòu)買(mǎi)了商品最多的前5個(gè)用戶(hù)子查詢(xún) JOIN自動(dòng)處理聚合和排序正常返回昨天每個(gè)類(lèi)別的銷(xiāo)售額strftime(%Y-%m-%d, o.order_time) strftime(%Y-%m-%d, now, -1 day)結(jié)合 JOIN正常返回讓我意外的是模型對(duì)“上個(gè)月”“昨天”這類(lèi)相對(duì)時(shí)間理解得相當(dāng)準(zhǔn)直接用了strftime(%Y-%m, now, -1 month)這種寫(xiě)法而不是我預(yù)想中的死日期。這說(shuō)明只要 schema 里字段命名清晰模型完全可以把自然語(yǔ)言的時(shí)間表達(dá)映射成 SQLite 方言。4.2 實(shí)測(cè)中的效果邊界模型不是萬(wàn)能的。我試過(guò)一個(gè)問(wèn)題“誰(shuí)的訂單金額最高”。這個(gè)描述有歧義可以指單個(gè)訂單金額最高也可以指累計(jì)消費(fèi)金額最高。模型默認(rèn)選擇了累計(jì)求和但這未必是提問(wèn)者想要的。這類(lèi)模糊查詢(xún)沒(méi)有標(biāo)準(zhǔn)答案需要在提示詞里追加“如果問(wèn)題不明確請(qǐng)列出多種解釋”的規(guī)則或者讓用戶(hù)補(bǔ)充條件。另一個(gè)邊界是復(fù)雜嵌套查詢(xún)。比如“找出購(gòu)買(mǎi)過(guò)所有超過(guò)100元商品的用戶(hù)”這種帶全稱(chēng)量詞的語(yǔ)義模型偶爾會(huì)生成錯(cuò)誤的邏輯結(jié)構(gòu)。我建議遇到這種問(wèn)題時(shí)把問(wèn)題拆成多個(gè)步驟查詢(xún)而不是期望模型一步到位。4.3 成本與性能控制成本方面單次查詢(xún)包含 schema 和 SQL 結(jié)果大約消耗 1000 到 2000 token。一次完整的糾錯(cuò)循環(huán)可能到 4000 token。就算連續(xù)測(cè)試 500 個(gè)問(wèn)題成本也很低完全可以接受。性能方面真正的瓶頸不在模型調(diào)用而在每次請(qǐng)求都要重新獲取 schema。雖然這條語(yǔ)句執(zhí)行很快但反復(fù)讀取也不優(yōu)雅。我后來(lái)加了一個(gè)簡(jiǎn)單的模塊級(jí)緩存_schema_cache {} def get_schema_cached(db_path): if db_path not in _schema_cache: _schema_cache[db_path] get_schema(db_path) return _schema_cache[db_path]如果你的數(shù)據(jù)庫(kù)結(jié)構(gòu)很少變動(dòng)這個(gè)緩存非常管用能省掉每次讀取和拼接的開(kāi)銷(xiāo)。同時(shí)建議給 OpenAI 客戶(hù)端設(shè)置一個(gè)合理的timeout和max_retries避免網(wǎng)絡(luò)抖動(dòng)時(shí)整個(gè)命令行卡死。5. 常見(jiàn)問(wèn)題排查與避坑記錄5.1 問(wèn)題速查表癥狀原因分析解決方案模型輸出帶解釋文字SQL 提取失敗提示詞約束不足在提示詞里強(qiáng)調(diào)“只輸出 SQL 本身”并用正則提取代碼塊生成的 SQL 在 SQLite 中報(bào)語(yǔ)法錯(cuò)誤模型慣性寫(xiě)了 MySQL/PostgreSQL 語(yǔ)法提示詞里明確“使用 SQLite 語(yǔ)法”利用糾錯(cuò)循環(huán)回傳錯(cuò)誤查詢(xún)結(jié)果明顯錯(cuò)誤但不是 SQL 報(bào)錯(cuò)字段語(yǔ)義理解偏差在 schema 后補(bǔ)充業(yè)務(wù)注釋或把問(wèn)題改得更具體查出來(lái)的數(shù)據(jù)為空時(shí)間格式或過(guò)濾條件不匹配檢查數(shù)據(jù)里的時(shí)間字段是否與strftime格式化結(jié)果一致模型把“價(jià)格超過(guò)100元”理解成“價(jià)格低于100”否定詞或多條件組合理解偏差換一種更直接的說(shuō)法或拆成兩個(gè)查詢(xún)對(duì)比5.2 我實(shí)際踩過(guò)的幾個(gè)坑第一個(gè)坑是時(shí)間字段的格式。我最初插入數(shù)據(jù)時(shí)用的是2024-3-5這樣不補(bǔ)零的格式導(dǎo)致strftime(%Y-%m, order_time)匹配不到數(shù)據(jù)。排查了很久才發(fā)現(xiàn)是數(shù)據(jù)格式問(wèn)題。建議統(tǒng)一用YYYY-MM-DD HH:MM:SS否則模型生成的時(shí)間條件經(jīng)常對(duì)不上。第二個(gè)坑是模型把ORDER BY和LIMIT的先后順序?qū)懛?。這不是大問(wèn)題SQLite 會(huì)直接報(bào)語(yǔ)法錯(cuò)誤糾錯(cuò)循環(huán)能自動(dòng)修復(fù)。但如果你的場(chǎng)景對(duì)延遲敏感可以在提示詞里加一個(gè) few-shot 示例讓模型看一眼正確寫(xiě)法。第三個(gè)坑是字段名大小寫(xiě)不一致。SQLite 對(duì)字段名大小寫(xiě)不敏感但模型在生成 SQL 時(shí)可能一會(huì)兒用OrderTime一會(huì)兒用order_time。最好的做法是建表時(shí)統(tǒng)一使用小寫(xiě)蛇形命名并在 schema 里保持完全一致減少模型的猜測(cè)空間。第四個(gè)坑和安全性有關(guān)。我在做校驗(yàn)時(shí)只檢查了首個(gè)非空關(guān)鍵詞結(jié)果有一次模型生成了WITH x AS (...) DELETE FROM users這種以 WITH 開(kāi)頭的危險(xiǎn)語(yǔ)句第一層校驗(yàn)沒(méi)能攔下來(lái)。幸好只讀連接兜了底。后來(lái)我把關(guān)鍵詞檢查從“是否包含 DELETE”改成了“是否包含以 DELETE 開(kāi)頭的任何語(yǔ)法結(jié)構(gòu)”并額外檢查了with語(yǔ)句內(nèi)部是否出現(xiàn)寫(xiě)操作關(guān)鍵詞。5.3 幾個(gè)讓效果更穩(wěn)的進(jìn)階小技巧給模型喂 few-shot 樣例是我認(rèn)為性?xún)r(jià)比最高的優(yōu)化手段。在系統(tǒng)提示詞里加兩組“問(wèn)題 → SQL”的示例一組是簡(jiǎn)單條件查詢(xún)一組是 JOIN GROUP BY 聚合查詢(xún)。模型只需多讀幾十個(gè) token 的上下文就能少犯很多類(lèi)型錯(cuò)誤。第二個(gè)技巧是給 schema 加“使用說(shuō)明”。比如字段里有個(gè)price我是在 schema 后面追加一行“price單位是元查詢(xún)價(jià)格時(shí)直接比較數(shù)值即可”。這類(lèi)業(yè)務(wù)說(shuō)明模型是從建表語(yǔ)句里猜不出來(lái)的但它對(duì)查詢(xún)語(yǔ)義的準(zhǔn)確度影響極大。第三個(gè)技巧是限制最大行數(shù)。除了讓模型默認(rèn)加 LIMIT 50我在執(zhí)行層也會(huì)強(qiáng)行限制返回行數(shù)。比如在fetchall后再截?cái)嗟?200 行防止因?yàn)槟Ｐ蜕蒘ELECT *導(dǎo)致終端被大量數(shù)據(jù)淹沒(méi)。第四個(gè)技巧是記錄失敗案例并形成小型回歸測(cè)試集。每次模型生成錯(cuò)誤我就把那條自然語(yǔ)言問(wèn)題、錯(cuò)誤 SQL、糾正后的 SQL 存到一個(gè) JSON 文件里。后續(xù)修改提示詞時(shí)直接用這套測(cè)試集重放一看就知道改動(dòng)是變好還是變差。這個(gè)方法讓整個(gè)項(xiàng)目從“試出來(lái)能用”變成了“可持續(xù)迭代”。結(jié)尾一點(diǎn)個(gè)人體會(huì)這套查詢(xún)助手做到現(xiàn)在最大的收獲不是“能跑”而是我真正理解了 LLM 應(yīng)用里“約束”的價(jià)值。模型的能力邊界固然重要但提示詞的結(jié)構(gòu)化、SQL 的校驗(yàn)層、錯(cuò)誤反饋的閉環(huán)這些工程細(xì)節(jié)才是決定一個(gè)工具能不能被真實(shí)使用的關(guān)鍵。我個(gè)人的建議是不要一上來(lái)就追求復(fù)雜架構(gòu)。先用 SQLite 做底層、用一個(gè)模型接口做推理把一條最核心的查詢(xún)鏈路跑通再逐步加入緩存、界面、多輪對(duì)話(huà)。很多看似“簡(jiǎn)陋”的原型反而能幫你最清楚地看到模型在哪里犯傻、工程在哪里彌補(bǔ)、產(chǎn)品在哪里加分。后續(xù)如果把這個(gè)助手接上 Grafana 或者做成 Web 服務(wù)也只是在這套骨架上加肉而已。最后分享一個(gè)使用習(xí)慣我把這個(gè)腳本掛在了本地終端別名里平時(shí)查任何開(kāi)發(fā)庫(kù)的數(shù)據(jù)都先打一句自然語(yǔ)言試試。查成功了就省一段自己手寫(xiě) SQL 的時(shí)間查失敗了模型的錯(cuò)誤往往比搜索引擎的答案更接近問(wèn)題本身。這套“讓 AI 替你寫(xiě)第一版 SQL你只做校驗(yàn)和修改”的工作流我已經(jīng)離不開(kāi)了。 DeepSeek + SQLite 實(shí)現(xiàn)輕量 Text2SQL：讓自然語(yǔ)言直接查詢(xún)數(shù)據(jù)庫(kù)
過(guò)去半年我一直在折騰一個(gè)很現(xiàn)實(shí)的問(wèn)題怎么讓不會(huì)寫(xiě) SQL 的人也能直接對(duì)著數(shù)據(jù)庫(kù)問(wèn)問(wèn)題。最終落地的是一個(gè)用 DeepSeek 做大模型推理、SQLite 做數(shù)據(jù)存儲(chǔ)的輕量 Text2SQL 查詢(xún)助手——輸入一句中文比如“上個(gè)月銷(xiāo)售額最高的三個(gè)商品”它自動(dòng)生成 SQL、在 SQLite 引擎里執(zhí)行再把結(jié)果用表格形式返回。整個(gè)過(guò)程不用寫(xiě)一行 SQL也不用部署重型數(shù)據(jù)庫(kù)服務(wù)。這個(gè)項(xiàng)目是典型的 LLM 落地形態(tài)不需要訓(xùn)練、不需要私有化部署大模型只需要把數(shù)據(jù)庫(kù)結(jié)構(gòu)和查詢(xún)約束交代給模型它就能輸出可執(zhí)行 SQL。整套代碼加起來(lái)不到 200 行特別適合第一次認(rèn)真做 Text2SQL 的人拿來(lái)當(dāng)模板也適合想驗(yàn)證大模型在生成式查詢(xún)場(chǎng)景里到底穩(wěn)不穩(wěn)的開(kāi)發(fā)者做一輪實(shí)測(cè)。下面我把從零搭建的完整過(guò)程講清楚包括提示詞設(shè)計(jì)、SQL 安全校驗(yàn)、錯(cuò)誤糾錯(cuò)循環(huán)以及我實(shí)際踩過(guò)的坑。1. 為什么選 Text2SQL 作為 LLM 落地項(xiàng)目整體思路是什么1.1 一句話(huà)描述項(xiàng)目形態(tài)這個(gè)查詢(xún)助手的核心鏈路可以概括為用戶(hù)輸入自然語(yǔ)言問(wèn)題 → 系統(tǒng)把 SQLite 的 schema 注入提示詞 → 調(diào)用 DeepSeek 生成 SQL → 程序提取并校驗(yàn) SQL → 在 SQLite 中執(zhí)行 → 返回查詢(xún)結(jié)果。如果生成的 SQL 報(bào)錯(cuò)程序會(huì)把錯(cuò)誤信息回傳給模型讓它基于錯(cuò)誤修正后重新生成。聽(tīng)起來(lái)很順但真正實(shí)施起來(lái)有幾個(gè)難點(diǎn)模型可能生成不存在的字段名可能寫(xiě)出 SQLite 不支持的語(yǔ)法甚至可能生成插入、刪除這類(lèi)危險(xiǎn)語(yǔ)句。所以這個(gè)項(xiàng)目表面上是在調(diào) API本質(zhì)上是在做三件事讓模型“看懂”庫(kù)結(jié)構(gòu)、讓輸出“規(guī)規(guī)矩矩”變成純 SQL、讓執(zhí)行過(guò)程“萬(wàn)無(wú)一失”不會(huì)破壞數(shù)據(jù)。1.2 為什么選 DeepSeek SQLite 這套組合先聊模型選型。Text2SQL 對(duì)模型的要求是中文理解能力強(qiáng)、SQL 語(yǔ)法知識(shí)扎實(shí)、輸出穩(wěn)定。DeepSeek 的開(kāi)放接口兼容 OpenAI 調(diào)用格式代碼上接入成本很低而且在實(shí)際測(cè)試中它對(duì)中文業(yè)務(wù)問(wèn)題的理解明顯比通用模型更貼近中文語(yǔ)境生成的 SQL 也習(xí)慣用注釋和 LIMIT 這類(lèi)安全寫(xiě)法。再聊數(shù)據(jù)庫(kù)選型。SQLite 是單文件數(shù)據(jù)庫(kù)不需要安裝服務(wù)端一個(gè).db文件就能承載一張完整的業(yè)務(wù)表結(jié)構(gòu)。對(duì)于個(gè)人工具、內(nèi)部小助手這類(lèi)場(chǎng)景它簡(jiǎn)直是絕配輕、免維護(hù)、隨時(shí)可以復(fù)制走。相比 MySQL、PostgreSQLSQLite 還能用只讀 URI 模式打開(kāi)天然適合給 LLM 生成的查詢(xún)語(yǔ)句做執(zhí)行沙箱。這套組合的另一個(gè)優(yōu)勢(shì)是成本極低。單次查詢(xún)請(qǐng)求通常只消耗幾千 token跑幾百次測(cè)試的成本也就在幾塊錢(qián)量級(jí)可以放心反復(fù)實(shí)驗(yàn)。相比接一個(gè)獨(dú)立的數(shù)據(jù)庫(kù)服務(wù)開(kāi)發(fā)階段省掉的不只是部署還有連接配置、賬號(hào)權(quán)限、網(wǎng)絡(luò)安全這一堆事。1.3 整體流程設(shè)計(jì)一次查詢(xún)請(qǐng)求是怎么走通的我把它拆成五個(gè)環(huán)節(jié)取 schema、拼提示詞、調(diào)模型、執(zhí)行 SQL、反饋糾錯(cuò)。前兩個(gè)環(huán)節(jié)是準(zhǔn)備中間一個(gè)是核心后兩個(gè)是保障。取 schema 這一步很多人會(huì)偷懶覺(jué)得寫(xiě)死幾張表名就行了。實(shí)際上模型能不能生成正確 SQL很大程度上取決于它能不能看到完整字段名和類(lèi)型。我選擇通過(guò)sqlite_master系統(tǒng)表自動(dòng)讀取建表語(yǔ)句這樣數(shù)據(jù)庫(kù)結(jié)構(gòu)一變提示詞也會(huì)自動(dòng)跟上。拼提示詞是最考功底的一步。要把數(shù)據(jù)庫(kù)結(jié)構(gòu)、業(yè)務(wù)字段說(shuō)明、輸出格式限制、安全約束全部塞進(jìn)一段上下文里。提示詞不是越長(zhǎng)越好而是要讓模型明確三件事回答范圍是什么、輸出格式是什么、禁區(qū)是什么。調(diào)模型和執(zhí)行 SQL 之間隔著一道安全檢查。LLM 生成的內(nèi)容本質(zhì)上不可信不能直接丟給數(shù)據(jù)庫(kù)執(zhí)行。我加了兩層防護(hù)關(guān)鍵字黑名單和只讀打開(kāi)連接。前者擋掉語(yǔ)義層面的危險(xiǎn)語(yǔ)句后者從數(shù)據(jù)庫(kù)層面保證即使漏網(wǎng)也改不了任何數(shù)據(jù)。整個(gè)設(shè)計(jì)里最讓我得意的是糾錯(cuò)循環(huán)。第一次生成的 SQL 很可能會(huì)因?yàn)樽侄蚊村e(cuò)、函數(shù)用錯(cuò)而執(zhí)行失敗。傳統(tǒng)的做法是讓用戶(hù)重新問(wèn)一遍但我在執(zhí)行出錯(cuò)時(shí)會(huì)把 SQLite 返回的錯(cuò)誤信息拼回對(duì)話(huà)上下文讓模型直接改寫(xiě)。這樣一次失敗的查詢(xún)往往能在第二次、第三次嘗試內(nèi)自我修復(fù)用戶(hù)體驗(yàn)好很多。2. 動(dòng)手前準(zhǔn)備示例庫(kù)、API 接入與 schema 注入2.1 建一個(gè)能說(shuō)明問(wèn)題的小型 SQLite 示例庫(kù)為了測(cè)試多表關(guān)聯(lián)和聚合查詢(xún)我建立了一個(gè)非常接近真實(shí)業(yè)務(wù)的三表結(jié)構(gòu)用戶(hù)表、商品表、訂單表。訂單表通過(guò)外鍵關(guān)聯(lián)用戶(hù)和商品這樣可以很方便地演示 JOIN、GROUP BY、子查詢(xún)這類(lèi)常見(jiàn)需求。建表 SQL 如下DROP TABLE IF EXISTS users; CREATE TABLE users ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, age INTEGER, city TEXT, created_at TEXT NOT NULL ); DROP TABLE IF EXISTS products; CREATE TABLE products ( id INTEGER PRIMARY KEY AUTOINCREMENT, name TEXT NOT NULL, category TEXT, price REAL, stock INTEGER ); DROP TABLE IF EXISTS orders; CREATE TABLE orders ( id INTEGER PRIMARY KEY AUTOINCREMENT, user_id INTEGER NOT NULL, product_id INTEGER NOT NULL, quantity INTEGER NOT NULL, order_time TEXT NOT NULL, FOREIGN KEY (user_id) REFERENCES users(id), FOREIGN KEY (product_id) REFERENCES products(id) );有一點(diǎn)需要注意SQLite 本身對(duì)字段類(lèi)型非常寬容所以時(shí)間字段我統(tǒng)一存成YYYY-MM-DD HH:MM:SS格式的字符串。這樣模型在做時(shí)間范圍查詢(xún)時(shí)可以用strftime或字符串比較不容易出錯(cuò)。插入數(shù)據(jù)也不必太復(fù)雜每個(gè)表放 20 條左右就夠測(cè)試了。記得讓訂單分布在不同的月份和城市因?yàn)椤吧蟼€(gè)月”這類(lèi)帶時(shí)間條件的查詢(xún)是 Text2SQL 測(cè)評(píng)的重災(zāi)區(qū)數(shù)據(jù)設(shè)計(jì)時(shí)就要故意制造可查詢(xún)的時(shí)間跨度。2.2 DeepSeek API 的接入方式DeepSeek 提供了 OpenAI 兼容的接口所以我直接用openaiPython 庫(kù)來(lái)調(diào)用避免另外封裝一套請(qǐng)求邏輯。所有需要登錄的密鑰都通過(guò)環(huán)境變量讀取絕不硬編碼在腳本里。import os from openai import OpenAI client OpenAI( api_keyos.getenv(DEEPSEEK_API_KEY), base_urlhttps://api.deepseek.com ) def ask_deepseek(messages, temperature0.0): resp client.chat.completions.create( modeldeepseek-chat, messagesmessages, temperaturetemperature, ) return resp.choices[0].message.content把溫度設(shè)置成 0 是我反復(fù)測(cè)試后確定的。Text2SQL 不是創(chuàng)意寫(xiě)作它需要確定性輸出。溫度一旦調(diào)高模型可能用不同的語(yǔ)法表達(dá)同一個(gè)查詢(xún)這會(huì)給后續(xù)糾錯(cuò)增加不必要的變量。如果你不想引入 openai 庫(kù)直接用requests調(diào)官方接口也是可行的但openai庫(kù)在消息構(gòu)造、超時(shí)處理、錯(cuò)誤信息這些方面已經(jīng)封裝得很好我建議直接用它。2.3 schema 自動(dòng)注入機(jī)制模型不知道你的庫(kù)長(zhǎng)什么樣所以每次查詢(xún)前都要把結(jié)構(gòu)信息喂給它。手動(dòng)寫(xiě)一段固定的 schema 描述很容易但數(shù)據(jù)庫(kù)一變就維護(hù)不過(guò)來(lái)了。我的做法是從 SQLite 系統(tǒng)表讀取真實(shí)建表語(yǔ)句再組裝成一段純文本。import sqlite3 def get_schema(db_path): conn sqlite3.connect(db_path) rows conn.execute( SELECT sql FROM sqlite_master WHERE typetable AND sql IS NOT NULL ).fetchall() conn.close() return \n\n.join(r[0] for r in rows)這樣返回的 schema 是原始的 CREATE TABLE 語(yǔ)句包含字段名、類(lèi)型、外鍵約束。模型對(duì)這種結(jié)構(gòu)化文本的吸收能力很強(qiáng)幾乎不需要再做格式化。唯一要補(bǔ)充的是業(yè)務(wù)說(shuō)明比如“price 單位是元”“order_time 是下單時(shí)間”。我會(huì)把這些注釋追加到 schema 末尾而不是直接改建表語(yǔ)句保持?jǐn)?shù)據(jù)庫(kù)文件干凈。實(shí)際測(cè)試下來(lái)schema 加上一句“請(qǐng)基于上面的表結(jié)構(gòu)生成 SQLite 方言的 SQL”就能明顯壓低模型使用錯(cuò)誤表名和字段名的概率。這一步做好后面所有環(huán)節(jié)都會(huì)省心很多。3. 核心代碼逐段拆解提示詞、安全校驗(yàn)與糾錯(cuò)循環(huán)3.1 提示詞模板是如何讓模型穩(wěn)定輸出 SQL 的提示詞設(shè)計(jì)是這個(gè)項(xiàng)目最核心的環(huán)節(jié)。一開(kāi)始我寫(xiě)得很簡(jiǎn)陋就一句“把下面的話(huà)轉(zhuǎn)成 SQL”結(jié)果模型輸出五花八門(mén)有的帶解釋有的用 MySQL 語(yǔ)法有的直接拒絕回答。后來(lái)我總結(jié)出一套有效的模板核心是四項(xiàng)約束。SYSTEM_PROMPT 你是一個(gè)精通 SQLite 的數(shù)據(jù)庫(kù)查詢(xún)助手。 請(qǐng)根據(jù)數(shù)據(jù)庫(kù) schema 和用戶(hù)問(wèn)題生成可直接執(zhí)行的 SQL 查詢(xún)。 要求 1. 只輸出 SQL 語(yǔ)句本身不要輸出任何解釋、代碼塊標(biāo)記。 2. 只允許 SELECT 查詢(xún)禁止 INSERT、UPDATE、DELETE、DROP 等語(yǔ)句。 3. 使用 SQLite 語(yǔ)法不要使用其他數(shù)據(jù)庫(kù)的專(zhuān)用函數(shù)。 4. 查詢(xún)結(jié)果默認(rèn)加上 LIMIT 50。 5. 如果問(wèn)題與數(shù)據(jù)庫(kù)無(wú)關(guān)或無(wú)法用提供的 schema 回答輸出 SQL_ERR: 無(wú)法回答。 def build_messages(user_question, schema, error_hintNone): user_content f數(shù)據(jù)庫(kù) schema:\n{schema}\n\n用戶(hù)問(wèn)題: {user_question} messages [ {role: system, content: SYSTEM_PROMPT}, {role: user, content: user_content}, ] if error_hint: messages.append({ role: assistant, content: error_hint[sql] }) messages.append({ role: user, content: f你生成的 SQL 執(zhí)行報(bào)錯(cuò){error_hint[error]}\\n請(qǐng)修正后重寫(xiě)。 }) return messages第一條約束解決了“模型話(huà)多”的問(wèn)題。你可能會(huì)覺(jué)得讓模型輸出解釋更友好但對(duì)程序來(lái)說(shuō)解析一段可能有代碼標(biāo)記和廢話(huà)的文本遠(yuǎn)比解析純 SQL 麻煩。我寧可讓模型輸出裸 SQL再由程序負(fù)責(zé)展示結(jié)果。第二條約束是安全底線(xiàn)。模型本身沒(méi)有惡意但它可能因?yàn)橛脩?hù)問(wèn)題描述不當(dāng)而生成危險(xiǎn)語(yǔ)句。直接在提示詞里聲明禁區(qū)能從源頭過(guò)濾一大半風(fēng)險(xiǎn)。第三、四條約束屬于方言限定。SQLite 的日期函數(shù)、字符串處理方式和 MySQL、PostgreSQL 差別很大提前聲明可以避免模型想當(dāng)然地寫(xiě)出DATE_FORMAT這類(lèi)函數(shù)。3.2 SQL 安全校驗(yàn)為什么 LLM 的輸出不能直接執(zhí)行即使提示詞說(shuō)了“只允許 SELECT”我也在代碼里加了獨(dú)立校驗(yàn)。原因很簡(jiǎn)單提示詞是對(duì)模型的軟約束不是硬保證。模型可能因?yàn)樯舷挛奶L(zhǎng)而忽略限制也可能被一種叫“注入攻擊”的手段繞過(guò)。我的校驗(yàn)分為三層。第一層去掉首尾空白、將 SQL 轉(zhuǎn)成小寫(xiě)后檢查是否包含insert、update、delete、drop、alter、attach、pragma這些關(guān)鍵詞。第二層檢查第一個(gè)非空語(yǔ)句是否以select或with開(kāi)頭。第三層用只讀 URI 模式連接 SQLite從數(shù)據(jù)庫(kù)層保證任何寫(xiě)操作都會(huì)拋出錯(cuò)誤。import os import re BANNED_KEYWORDS [insert, update, delete, drop, alter, attach, pragma] def extract_sql(text): blocks re.findall(r(?:sql)?\\s*(.*?), text, re.S) if blocks: return blocks[0].strip() if text.startswith(SQL_ERR): return None return text.strip() def check_sql(sql): if not sql: return False, 空 SQL low sql.lower() for kw in BANNED_KEYWORDS: if re.search(r\\b kw r\\b, low): return False, f包含危險(xiǎn)關(guān)鍵詞 {kw} if not re.match(r^(select|with)\\b, low): return False, 必須以 SELECT 或 WITH 開(kāi)頭 return True, def execute_readonly(db_path, sql): uri ffile:{os.path.abspath(db_path)}?modero conn sqlite3.connect(uri, uriTrue, timeout10) try: cur conn.execute(sql) cols [d[0] for d in cur.description] if cur.description else [] rows cur.fetchall() return cols, rows finally: conn.close()我用了一個(gè)很實(shí)用的技巧如果 SQL 里包含注釋或者多余空白正則也能提取干凈。另外execute_readonly返回的不僅包含結(jié)果行還包含列名。這樣在命令行里展示時(shí)可以直接拿列名做表頭省得再查一次PRAGMA table_info。3.3 帶糾錯(cuò)的主流程一次查詢(xún)失敗怎么辦第一次生成的 SQL 執(zhí)行失敗太常見(jiàn)了。我的處理方法是把 SQL 和錯(cuò)誤信息一起回傳給模型讓它看到自己寫(xiě)的代碼和數(shù)據(jù)庫(kù)的真實(shí)反應(yīng)然后要求它修正。這相當(dāng)于給模型一個(gè)“現(xiàn)場(chǎng)調(diào)試”的機(jī)會(huì)。def text2sql(db_path, question, max_retries2): schema get_schema(db_path) messages build_messages(question, schema) for attempt in range(max_retries 1): raw ask_deepseek(messages) sql extract_sql(raw) if sql is None: return {error: 模型無(wú)法生成 SQL, raw: raw} ok, msg check_sql(sql) if not ok: messages build_messages(question, schema, {sql: sql, error: msg}) continue try: cols, rows execute_readonly(db_path, sql) return {sql: sql, columns: cols, rows: rows} except sqlite3.Error as e: messages build_messages(question, schema, {sql: sql, error: str(e)}) return {error: 重試次數(shù)用盡, sql: sql}這里有個(gè)細(xì)節(jié)值得多說(shuō)兩句重試時(shí)不是簡(jiǎn)單地把錯(cuò)誤信息追加到原消息尾部而是完整重建 message 列表并在其中模擬一段“助手生成了 SQL用戶(hù)反饋了報(bào)錯(cuò)”的對(duì)話(huà)。這樣做的好處是模型能明確看到自己的上一次輸出而不是在越來(lái)越長(zhǎng)的上下文里迷失。實(shí)測(cè)中絕大多數(shù)語(yǔ)法錯(cuò)誤和字段名錯(cuò)誤都能在第一次糾錯(cuò)內(nèi)解決。3.4 一個(gè)可以直接跑的命令行主循環(huán)把上面的函數(shù)組合起來(lái)就是一個(gè)完整的命令行查詢(xún)助手。它支持exit退出每次輸入問(wèn)題都會(huì)打印 SQL 和查詢(xún)結(jié)果。def main(): db_path shop.db print(Text2SQL 查詢(xún)助手已啟動(dòng)輸入 exit 退出。) while True: question input(\\n問(wèn)題: ).strip() if question.lower() in (exit, quit): break if not question: continue result text2sql(db_path, question) if error in result: print(錯(cuò)誤:, result[error]) continue print(\\nSQL:, result[sql]) if result[columns]: print(\\t.join(result[columns])) for row in result[rows]: print(\\t.join(str(c) for c in row)) if __name__ __main__: main()整個(gè)腳本文件大概 150 行。你如果只想快速驗(yàn)證效果把這段代碼存成text2sql_assistant.py再設(shè)置好環(huán)境變量就能啟動(dòng)。別急著加界面、加日志、加權(quán)限控制輕量才是這個(gè)項(xiàng)目的定位。等驗(yàn)證完模型效果再去擴(kuò)展 UI 和配套能力也不遲。4. 實(shí)測(cè)效果與幾個(gè)值得注意的點(diǎn)4.1 一組典型查詢(xún)的輸入與輸出對(duì)比我把腳本跑起來(lái)后連續(xù)問(wèn)了十多個(gè)問(wèn)題包括單表過(guò)濾、聚合、多表關(guān)聯(lián)、時(shí)間范圍、排序取前幾。下面是幾組有代表性的結(jié)果自然語(yǔ)言問(wèn)題生成的 SQL節(jié)選執(zhí)行結(jié)果每個(gè)城市的用戶(hù)數(shù)量是多少SELECT city, COUNT(*) AS cnt FROM users GROUP BY city ORDER BY cnt DESC正常返回上個(gè)月銷(xiāo)量最高的三個(gè)商品SELECT p.name, SUM(o.quantity) AS total FROM orders o JOIN products p ON o.product_id p.id WHERE strftime(%Y-%m, o.order_time) strftime(%Y-%m, now, -1 month) GROUP BY p.name ORDER BY total DESC LIMIT 3正常返回哪些商品價(jià)格超過(guò)100元但庫(kù)存不足20件SELECT name, price, stock FROM products WHERE price 100 AND stock 20正常返回找出購(gòu)買(mǎi)了商品最多的前5個(gè)用戶(hù)子查詢(xún) JOIN自動(dòng)處理聚合和排序正常返回昨天每個(gè)類(lèi)別的銷(xiāo)售額strftime(%Y-%m-%d, o.order_time) strftime(%Y-%m-%d, now, -1 day)結(jié)合 JOIN正常返回讓我意外的是模型對(duì)“上個(gè)月”“昨天”這類(lèi)相對(duì)時(shí)間理解得相當(dāng)準(zhǔn)直接用了strftime(%Y-%m, now, -1 month)這種寫(xiě)法而不是我預(yù)想中的死日期。這說(shuō)明只要 schema 里字段命名清晰模型完全可以把自然語(yǔ)言的時(shí)間表達(dá)映射成 SQLite 方言。4.2 實(shí)測(cè)中的效果邊界模型不是萬(wàn)能的。我試過(guò)一個(gè)問(wèn)題“誰(shuí)的訂單金額最高”。這個(gè)描述有歧義可以指單個(gè)訂單金額最高也可以指累計(jì)消費(fèi)金額最高。模型默認(rèn)選擇了累計(jì)求和但這未必是提問(wèn)者想要的。這類(lèi)模糊查詢(xún)沒(méi)有標(biāo)準(zhǔn)答案需要在提示詞里追加“如果問(wèn)題不明確請(qǐng)列出多種解釋”的規(guī)則或者讓用戶(hù)補(bǔ)充條件。另一個(gè)邊界是復(fù)雜嵌套查詢(xún)。比如“找出購(gòu)買(mǎi)過(guò)所有超過(guò)100元商品的用戶(hù)”這種帶全稱(chēng)量詞的語(yǔ)義模型偶爾會(huì)生成錯(cuò)誤的邏輯結(jié)構(gòu)。我建議遇到這種問(wèn)題時(shí)把問(wèn)題拆成多個(gè)步驟查詢(xún)而不是期望模型一步到位。4.3 成本與性能控制成本方面單次查詢(xún)包含 schema 和 SQL 結(jié)果大約消耗 1000 到 2000 token。一次完整的糾錯(cuò)循環(huán)可能到 4000 token。就算連續(xù)測(cè)試 500 個(gè)問(wèn)題成本也很低完全可以接受。性能方面真正的瓶頸不在模型調(diào)用而在每次請(qǐng)求都要重新獲取 schema。雖然這條語(yǔ)句執(zhí)行很快但反復(fù)讀取也不優(yōu)雅。我后來(lái)加了一個(gè)簡(jiǎn)單的模塊級(jí)緩存_schema_cache {} def get_schema_cached(db_path): if db_path not in _schema_cache: _schema_cache[db_path] get_schema(db_path) return _schema_cache[db_path]如果你的數(shù)據(jù)庫(kù)結(jié)構(gòu)很少變動(dòng)這個(gè)緩存非常管用能省掉每次讀取和拼接的開(kāi)銷(xiāo)。同時(shí)建議給 OpenAI 客戶(hù)端設(shè)置一個(gè)合理的timeout和max_retries避免網(wǎng)絡(luò)抖動(dòng)時(shí)整個(gè)命令行卡死。5. 常見(jiàn)問(wèn)題排查與避坑記錄5.1 問(wèn)題速查表癥狀原因分析解決方案模型輸出帶解釋文字SQL 提取失敗提示詞約束不足在提示詞里強(qiáng)調(diào)“只輸出 SQL 本身”并用正則提取代碼塊生成的 SQL 在 SQLite 中報(bào)語(yǔ)法錯(cuò)誤模型慣性寫(xiě)了 MySQL/PostgreSQL 語(yǔ)法提示詞里明確“使用 SQLite 語(yǔ)法”利用糾錯(cuò)循環(huán)回傳錯(cuò)誤查詢(xún)結(jié)果明顯錯(cuò)誤但不是 SQL 報(bào)錯(cuò)字段語(yǔ)義理解偏差在 schema 后補(bǔ)充業(yè)務(wù)注釋或把問(wèn)題改得更具體查出來(lái)的數(shù)據(jù)為空時(shí)間格式或過(guò)濾條件不匹配檢查數(shù)據(jù)里的時(shí)間字段是否與strftime格式化結(jié)果一致模型把“價(jià)格超過(guò)100元”理解成“價(jià)格低于100”否定詞或多條件組合理解偏差換一種更直接的說(shuō)法或拆成兩個(gè)查詢(xún)對(duì)比5.2 我實(shí)際踩過(guò)的幾個(gè)坑第一個(gè)坑是時(shí)間字段的格式。我最初插入數(shù)據(jù)時(shí)用的是2024-3-5這樣不補(bǔ)零的格式導(dǎo)致strftime(%Y-%m, order_time)匹配不到數(shù)據(jù)。排查了很久才發(fā)現(xiàn)是數(shù)據(jù)格式問(wèn)題。建議統(tǒng)一用YYYY-MM-DD HH:MM:SS否則模型生成的時(shí)間條件經(jīng)常對(duì)不上。第二個(gè)坑是模型把ORDER BY和LIMIT的先后順序?qū)懛?。這不是大問(wèn)題SQLite 會(huì)直接報(bào)語(yǔ)法錯(cuò)誤糾錯(cuò)循環(huán)能自動(dòng)修復(fù)。但如果你的場(chǎng)景對(duì)延遲敏感可以在提示詞里加一個(gè) few-shot 示例讓模型看一眼正確寫(xiě)法。第三個(gè)坑是字段名大小寫(xiě)不一致。SQLite 對(duì)字段名大小寫(xiě)不敏感但模型在生成 SQL 時(shí)可能一會(huì)兒用OrderTime一會(huì)兒用order_time。最好的做法是建表時(shí)統(tǒng)一使用小寫(xiě)蛇形命名并在 schema 里保持完全一致減少模型的猜測(cè)空間。第四個(gè)坑和安全性有關(guān)。我在做校驗(yàn)時(shí)只檢查了首個(gè)非空關(guān)鍵詞結(jié)果有一次模型生成了WITH x AS (...) DELETE FROM users這種以 WITH 開(kāi)頭的危險(xiǎn)語(yǔ)句第一層校驗(yàn)沒(méi)能攔下來(lái)。幸好只讀連接兜了底。后來(lái)我把關(guān)鍵詞檢查從“是否包含 DELETE”改成了“是否包含以 DELETE 開(kāi)頭的任何語(yǔ)法結(jié)構(gòu)”并額外檢查了with語(yǔ)句內(nèi)部是否出現(xiàn)寫(xiě)操作關(guān)鍵詞。5.3 幾個(gè)讓效果更穩(wěn)的進(jìn)階小技巧給模型喂 few-shot 樣例是我認(rèn)為性?xún)r(jià)比最高的優(yōu)化手段。在系統(tǒng)提示詞里加兩組“問(wèn)題 → SQL”的示例一組是簡(jiǎn)單條件查詢(xún)一組是 JOIN GROUP BY 聚合查詢(xún)。模型只需多讀幾十個(gè) token 的上下文就能少犯很多類(lèi)型錯(cuò)誤。第二個(gè)技巧是給 schema 加“使用說(shuō)明”。比如字段里有個(gè)price我是在 schema 后面追加一行“price單位是元查詢(xún)價(jià)格時(shí)直接比較數(shù)值即可”。這類(lèi)業(yè)務(wù)說(shuō)明模型是從建表語(yǔ)句里猜不出來(lái)的但它對(duì)查詢(xún)語(yǔ)義的準(zhǔn)確度影響極大。第三個(gè)技巧是限制最大行數(shù)。除了讓模型默認(rèn)加 LIMIT 50我在執(zhí)行層也會(huì)強(qiáng)行限制返回行數(shù)。比如在fetchall后再截?cái)嗟?200 行防止因?yàn)槟Ｐ蜕蒘ELECT *導(dǎo)致終端被大量數(shù)據(jù)淹沒(méi)。第四個(gè)技巧是記錄失敗案例并形成小型回歸測(cè)試集。每次模型生成錯(cuò)誤我就把那條自然語(yǔ)言問(wèn)題、錯(cuò)誤 SQL、糾正后的 SQL 存到一個(gè) JSON 文件里。后續(xù)修改提示詞時(shí)直接用這套測(cè)試集重放一看就知道改動(dòng)是變好還是變差。這個(gè)方法讓整個(gè)項(xiàng)目從“試出來(lái)能用”變成了“可持續(xù)迭代”。結(jié)尾一點(diǎn)個(gè)人體會(huì)這套查詢(xún)助手做到現(xiàn)在最大的收獲不是“能跑”而是我真正理解了 LLM 應(yīng)用里“約束”的價(jià)值。模型的能力邊界固然重要但提示詞的結(jié)構(gòu)化、SQL 的校驗(yàn)層、錯(cuò)誤反饋的閉環(huán)這些工程細(xì)節(jié)才是決定一個(gè)工具能不能被真實(shí)使用的關(guān)鍵。我個(gè)人的建議是不要一上來(lái)就追求復(fù)雜架構(gòu)。先用 SQLite 做底層、用一個(gè)模型接口做推理把一條最核心的查詢(xún)鏈路跑通再逐步加入緩存、界面、多輪對(duì)話(huà)。很多看似“簡(jiǎn)陋”的原型反而能幫你最清楚地看到模型在哪里犯傻、工程在哪里彌補(bǔ)、產(chǎn)品在哪里加分。后續(xù)如果把這個(gè)助手接上 Grafana 或者做成 Web 服務(wù)也只是在這套骨架上加肉而已。最后分享一個(gè)使用習(xí)慣我把這個(gè)腳本掛在了本地終端別名里平時(shí)查任何開(kāi)發(fā)庫(kù)的數(shù)據(jù)都先打一句自然語(yǔ)言試試。查成功了就省一段自己手寫(xiě) SQL 的時(shí)間查失敗了模型的錯(cuò)誤往往比搜索引擎的答案更接近問(wèn)題本身。這套“讓 AI 替你寫(xiě)第一版 SQL你只做校驗(yàn)和修改”的工作流我已經(jīng)離不開(kāi)了。