說實(shí)話直到今天仍然有大量團(tuán)隊(duì)在“讓大模型直接寫SQL”這件事上反復(fù)踩坑。裸調(diào)大模型接口讓它根據(jù)一句“幫我查一下上個(gè)月華東區(qū)哪些客戶的回款逾期了”生成SQL然后把結(jié)果丟給用戶——你很快會(huì)發(fā)現(xiàn)幾類問題生成的SQL對(duì)不上真實(shí)庫(kù)表結(jié)構(gòu)、日期口徑五花八門、查出來的結(jié)果沒人敢信更別提權(quán)限控制和查詢超時(shí)這些企業(yè)級(jí)基礎(chǔ)需求。LangChain SQL Agent的出現(xiàn)本質(zhì)上就是把這些散落的痛點(diǎn)收攏成一個(gè)完整工程方案。它不止是“大模型 數(shù)據(jù)庫(kù)”而是一個(gè)有工具、有記憶、有決策鏈路的智能體模型先生成計(jì)劃再調(diào)用查表工具拿元數(shù)據(jù)根據(jù)元數(shù)據(jù)修正SQL執(zhí)行完還能把報(bào)錯(cuò)反饋給自己自我糾錯(cuò)。1.28這個(gè)版本在工具鏈編排、Schema上下文裁剪、記憶管理上都做了很多收斂特別適合拿來搭建面向企業(yè)內(nèi)部的自助查詢助手。這篇內(nèi)容適合正在做數(shù)據(jù)平臺(tái)、內(nèi)部BI系統(tǒng)、或者想給業(yè)務(wù)團(tuán)隊(duì)提供“自然語言查數(shù)”能力的開發(fā)者。我會(huì)從設(shè)計(jì)思路講起拆解核心組件給出可直接落地的完整代碼最后把我在真實(shí)項(xiàng)目中踩過的坑一并列出來。全部是基于LangChain SQL Agent在1.28版本下的實(shí)踐總結(jié)。1. 為什么需要一套SQL Agent而不是讓大模型“裸寫SQL”1.1 大模型直接寫SQL的四個(gè)致命問題先說說裸調(diào)模型會(huì)遇到什么。第一模型對(duì)庫(kù)表結(jié)構(gòu)一無所知。你給它一個(gè)提問它只能憑預(yù)訓(xùn)練時(shí)見過的“通用表結(jié)構(gòu)”猜測(cè)字段名比如把customer_name猜成client_name把order_paid_time猜成pay_time結(jié)果生成的SQL一執(zhí)行就是Column not found。第二上下文窗口裝不下整庫(kù)Schema。企業(yè)庫(kù)動(dòng)輒幾百?gòu)埍砻總€(gè)表幾十個(gè)字段全塞進(jìn)Prompt費(fèi)用和延遲都不可接受。第三模型不會(huì)自己糾錯(cuò)。SQL執(zhí)行報(bào)錯(cuò)之后裸調(diào)接口的流程就斷了你得人工把報(bào)錯(cuò)信息再拼回Prompt再調(diào)一次循環(huán)往復(fù)。第四也是最容易被忽視的——安全性完全失控一個(gè)DROP TABLE可能就把生產(chǎn)環(huán)境帶走了。1.2 LangChain SQL Agent的核心價(jià)值把“執(zhí)行-反饋-糾錯(cuò)”閉環(huán)交給Agent自己SQL Agent解決這些問題的思路本質(zhì)上是把數(shù)據(jù)庫(kù)操作封裝成Agent的工具集。Agent拿到用戶問題后不是直接生成SQL而是先進(jìn)入一個(gè)決策循環(huán)觀察當(dāng)前可用的工具和上下文決定下一步動(dòng)作執(zhí)行動(dòng)作并接收結(jié)果再根據(jù)結(jié)果決定是繼續(xù)還是輸出最終答案。在這個(gè)循環(huán)里模型可以自主調(diào)用list_tables看有哪些表調(diào)用get_schema獲取某張表的字段定義再由query_sql執(zhí)行SQL并返回結(jié)果或報(bào)錯(cuò)信息。報(bào)錯(cuò)信息會(huì)回傳給模型模型會(huì)根據(jù)報(bào)錯(cuò)內(nèi)容重寫SQL。這就是1.28版本中SQL Agent最值錢的地方——把“人肉多輪調(diào)試”轉(zhuǎn)交給了Agent自己。1.3 什么樣才算“企業(yè)級(jí)SQL助手”我對(duì)企業(yè)級(jí)這個(gè)詞的判斷標(biāo)準(zhǔn)其實(shí)就四條權(quán)限與安全可控、查詢性能有保障、口徑能對(duì)齊業(yè)務(wù)語義、以及對(duì)話體驗(yàn)穩(wěn)定。第一條靠工具層攔截和角色權(quán)限第二條靠行數(shù)限制、超時(shí)設(shè)置和只讀封裝第三條靠自定義表注釋、字段描述和業(yè)務(wù)詞匯表注入到Prompt里第四條靠Memory設(shè)計(jì)。這四條全做到才配叫企業(yè)級(jí)。只做到“能跑通一個(gè)Demo”那叫玩具級(jí)。2. LangChain SQL Agent的核心組件拆解2.1 模型層LangChain模型接口與SQL Agent的適配模型是Agent的“大腦”LangChain通過標(biāo)準(zhǔn)化的接口封裝了OpenAI、Anthropic、國(guó)產(chǎn)模型等各家通道。1.28版本的SQL Agent對(duì)工具的調(diào)用格式做了統(tǒng)一處理模型只要支持Function Calling或Tool Calling就能無縫接入。我實(shí)測(cè)下來在1.28版本里選用支持Tool Calling的模型比純文本補(bǔ)全格式穩(wěn)定得多。因?yàn)門ool Calling在模型輸出層就有“這個(gè)輸出是一個(gè)工具調(diào)用”的結(jié)構(gòu)化標(biāo)記不需要從文本里硬解析Action:和Action Input:字段解析出錯(cuò)的概率大幅下降。如果你用的是DeepSeek、Qwen這類兼容OpenAI協(xié)議的工具調(diào)用模型也可以直接對(duì)接只要在模型初始化時(shí)把base_url指過去就行。from langchain_openai import ChatOpenAI llm ChatOpenAI( modelqwen2.5:72b, api_keyyour_api_key, base_urlhttp://your-llm-gateway:8000/v1, temperature0, )這里必須強(qiáng)調(diào)溫度設(shè)為0。SQL生成的確定性要求遠(yuǎn)高于創(chuàng)意寫作任何隨機(jī)性都會(huì)導(dǎo)致同樣的語義問題生成不同的SQL這對(duì)企業(yè)級(jí)查詢是不可接受的。2.2 Schema上下文SQLDatabase與TableInfo的作用要讓模型寫出“對(duì)得上真實(shí)庫(kù)表”的SQL必須先讓它“看見”表結(jié)構(gòu)。LangChain的SQLDatabase類在這里扮演了數(shù)據(jù)庫(kù)連接器和元數(shù)據(jù)管理器兩個(gè)角色。from langchain_community.utilities import SQLDatabase db SQLDatabase.from_uri( mysqlpymysql://user:passwordhost:3306/warehouse, sample_rows_in_table_info2, max_string_length300, )關(guān)鍵參數(shù)是sample_rows_in_table_info。它的作用是在每個(gè)表的元數(shù)據(jù)后面附帶兩行示例數(shù)據(jù)。別小看這個(gè)參數(shù)模型在看了status字段的示例值是paid、pending、overdue之后生成的查詢條件會(huì)精準(zhǔn)得多不會(huì)憑空猜一個(gè)finished出來。max_string_length用來截?cái)喑L(zhǎng)字段值防止枚舉類型字段的值列表爆掉上下文。對(duì)于幾百?gòu)埍淼拇髱?kù)全量注入Schema必然爆Token。SQL Agent內(nèi)置的get_table_info工具會(huì)在運(yùn)行時(shí)按需獲取單個(gè)表的結(jié)構(gòu)而不是一次性全倒給模型這是能落地大庫(kù)的關(guān)鍵。2.3 工具集query_sql與schema工具的邊界劃分Agent手動(dòng)操縱的“手”就是工具。SQL Agent在1.28版本里通常注冊(cè)三個(gè)工具sql_db_list_tables列出所有可用的表名適合模型在不確定表名時(shí)調(diào)用sql_db_schema獲取指定表的DDL和示例行注入上下文sql_db_query執(zhí)行SQL并返回查詢結(jié)果或報(bào)錯(cuò)信息這三個(gè)工具的邊界劃分非常講究。schema相關(guān)的工具是“只讀元數(shù)據(jù)”的不會(huì)產(chǎn)生副作用而query工具是真正碰數(shù)據(jù)的。邊界清晰的好處是模型在探索階段不會(huì)誤觸數(shù)據(jù)只有它確認(rèn)了表結(jié)構(gòu)、生成了SQL之后才走到執(zhí)行步。執(zhí)行工具還可以進(jìn)一步做封裝比如強(qiáng)制限制返回行數(shù)from langchain_community.tools.sql_database.tool import QuerySQLDataBaseTool query_tool QuerySQLDataBaseTool(dbdb)默認(rèn)工具會(huì)自動(dòng)包一層LIMIT限制但基于我對(duì)真實(shí)項(xiàng)目的觀察建議在工具內(nèi)部再套一層只讀保護(hù)和行數(shù)上限后文會(huì)詳細(xì)說。2.4 Memory讓對(duì)話上下文成為SQL生成的輔助約束企業(yè)用戶查數(shù)極少是單輪完成的更多是“上個(gè)月華東區(qū)回款逾期客戶有哪些”——“改成全國(guó)”——“再按逾期天數(shù)排序”這種連續(xù)追問。沒有Memory第二條追問就會(huì)丟失“回款逾期客戶”這個(gè)前提模型完全不知道在說什么。1.28版本里Memory的接入有兩種常用方式。一種是直接給create_sql_agent傳memory參數(shù)Agent會(huì)把聊天歷史作為上下文拼進(jìn)每一輪推理另一種是自己維護(hù)消息列表在調(diào)用傳遞給Agent時(shí)手動(dòng)把歷史追加進(jìn)來。我建議用后者可控性更強(qiáng)也方便在體積過大時(shí)做裁剪或摘要。但在SQL Agent里Memory不能“全量照搬”。時(shí)間久了聊天記錄會(huì)非常長(zhǎng)擠占上下文空間。我的做法是只保留最近3到5輪原始對(duì)話更早的對(duì)話在進(jìn)入Agent前用單獨(dú)的LLM請(qǐng)求壓縮成一段摘要再拼入歷史。2.5 完整執(zhí)行鏈路ReAct循環(huán)在SQL場(chǎng)景下的真實(shí)走法把上面的組件串起來SQL Agent一輪查詢的執(zhí)行鏈路是這樣的第1步用戶提問Agent把“問題 Memory 工具描述 已獲取的schema”拼進(jìn)上下文。第2步模型決策。如果是“有哪些表和客戶相關(guān)”選sql_db_list_tables如果已知表名但不確定字段選sql_db_schema如果結(jié)構(gòu)和口徑都清楚了選sql_db_query。第3步工具執(zhí)行結(jié)果回到模型。如果是報(bào)錯(cuò)模型讀報(bào)錯(cuò)重寫SQL如果是空結(jié)果模型可能回頭確認(rèn)是不是條件錯(cuò)了。第4步循環(huán)直到模型輸出最終答案Agent把SQL執(zhí)行結(jié)果用自然語言組織成回答?！岸嘧邘撞健睅淼氖找媸亲罱KSQL的準(zhǔn)確度顯著上升。代價(jià)是推理次數(shù)變多延遲會(huì)增加到5到15秒。這是必須接受的設(shè)計(jì)取舍企業(yè)場(chǎng)景里看著思考過程總比看著錯(cuò)誤答案強(qiáng)。3. 完整實(shí)現(xiàn)從零搭建一套可落地的LangChain SQL Agent3.1 環(huán)境準(zhǔn)備與依賴安裝先準(zhǔn)備好基礎(chǔ)環(huán)境。Python版本建議3.10及以上1.28版本對(duì)Python 3.9的兼容略差容易在pydantic依賴上出問題。pip install langchain1.28.0 pip install langchain-openai langchain-community pip install sqlalchemy pymysql cryptography確認(rèn)版本正常import langchain print(langchain.__version__) # 1.28.0同時(shí)準(zhǔn)備好一個(gè)庫(kù)的連接串。為了安全演示我這里用一個(gè)測(cè)試庫(kù)別在生產(chǎn)庫(kù)上直接跑。3.2 創(chuàng)建數(shù)據(jù)庫(kù)連接并裁剪Schemafrom langchain_community.utilities import SQLDatabase from sqlalchemy import create_engine from sqlalchemy.pool import QueuePool engine create_engine( mysqlpymysql://analyst:passwordyour-host:3306/analytics_db, poolclassQueuePool, pool_size5, max_overflow10, ) db SQLDatabase(engine, sample_rows_in_table_info2)用連接池而不是每次新建連接是避免Agent多輪循環(huán)時(shí)把數(shù)據(jù)庫(kù)連接打滿的關(guān)鍵。Agent一輪查詢可能要開3到5次工具調(diào)用每次都新建連接高并發(fā)下連接數(shù)很快就堆到上限。如果你的庫(kù)有幾百?gòu)埍斫ㄗh先做Schema裁剪只把業(yè)務(wù)常用的表注冊(cè)給Agent不相關(guān)的表不暴露。SQLDatabase有一個(gè)include_tables參數(shù)可以做到db SQLDatabase(engine, include_tables[orders, customers, payments], sample_rows_in_table_info2)這不僅是性能考慮也是數(shù)據(jù)權(quán)限的粗粒度控制——用戶不該見的表壓根就不該出現(xiàn)在工具的“視野”里。3.3 提示詞模板與業(yè)務(wù)口徑注入直接使用默認(rèn)Prompt模型往往不理解你業(yè)務(wù)里的黑話。比如“回款逾期”在庫(kù)里的判定條件是payments.due_date CURDATE() AND payments.status pending你不告訴模型它只能猜。在1.28版本中create_sql_agent有一個(gè)extra_prompt或agent_executor_kwargs機(jī)制可以把業(yè)務(wù)口徑注入System Message。我的做法是單獨(dú)定義一個(gè)口徑字典business_rules 業(yè)務(wù)口徑定義 1. 回款逾期payments.statuspending 且 payments.due_date CURDATE() 2. 活躍客戶customers.statusactive 且最近12個(gè)月內(nèi)有訂單 3. 華東區(qū)region字段值為 上海/江蘇/浙江/安徽/福建/江西/山東 4. 訂單金額單位默認(rèn)為CNY統(tǒng)計(jì)時(shí)無需轉(zhuǎn)換 5. 日期字段統(tǒng)一使用 DATE() 函數(shù)進(jìn)行比較 并且把表注釋和關(guān)鍵字段注釋也帶上table_comments 表說明 - orders訂單主表每行一個(gè)訂單created_at為下單時(shí)間 - customers客戶主表status表示客戶狀態(tài)region為所屬大區(qū) - payments回款表amount為回款金額due_date為應(yīng)回款日期status為回款狀態(tài) 這里的價(jià)值非常直接模型寫出來的SQL天然就優(yōu)先匹配你給的定義而不是它腦補(bǔ)的通用口徑。3.4 構(gòu)建Agent并綁定安全控件核心構(gòu)建代碼from langchain.agents import create_sql_agent from langchain.agents.agent_types import AgentType from langchain.agents.agent_toolkits import SQLDatabaseToolkit toolkit SQLDatabaseToolkit(dbdb, llmllm) agent_executor create_sql_agent( llmllm, toolkittoolkit, agent_typeAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue, handle_parsing_errorsTrue, max_iterations5, max_execution_time30, extra_promptbusiness_rules table_comments, )max_iterations5決定了Agent最多自我糾錯(cuò)5輪超過后自動(dòng)放棄避免無休止地循環(huán)調(diào)用工具燒錢。handle_parsing_errorsTrue保證模型輸出不是標(biāo)準(zhǔn)格式時(shí)把解析錯(cuò)誤回傳給模型讓它自行修正而不是整個(gè)流程崩潰。這里要說清楚一個(gè)版本細(xì)節(jié)1.28版本中AgentType.ZERO_SHOT_REACT_DESCRIPTION與OPENAI_FUNCTIONS都可用。如果你的模型支持Tool Calling優(yōu)先用OPENAI_FUNCTIONS如果用的是傳統(tǒng)重構(gòu)模型才回退到React的文本約定格式。我兩種都測(cè)過對(duì)于同一個(gè)模型Tool Calling的穩(wěn)定性要好不少。3.5 調(diào)用Agent并輸出結(jié)果response agent_executor.invoke({input: 上個(gè)月華東區(qū)哪些客戶的回款逾期了按逾期金額從大到小列前10個(gè)}) print(response[output])注意invoke入?yún)⒈仨殠nput鍵這是SQL Agent的固定接口。返回值里的output是模型組織的自然語言答案intermediate_steps則能看到模型調(diào)用過的工具和對(duì)應(yīng)輸入輸出。調(diào)試階段建議開著verboseTrue你會(huì)直觀看到模型這樣思考 Entering new SQL Agent Executor chain... Thought: 需要先確認(rèn)有哪些表和客戶、回款相關(guān) Action: sql_db_list_tables Action Input: Observation: orders, customers, payments, products Thought: 客戶和回款分別涉及customers和payments需要查看表結(jié)構(gòu) Action: sql_db_schema Action Input: customers, payments Observation: ... Thought: 現(xiàn)在生成SQL查詢逾期客戶并關(guān)聯(lián)按金額排序 Action: sql_db_query Action Input: SELECT ... ORDER BY amount DESC LIMIT 10 Observation: [(250, 客戶A, 30000.0), ...] Thought: 我現(xiàn)在知道最終答案了 Final Answer: 上個(gè)月華東區(qū)逾期回款客戶共250個(gè)金額最高的前10個(gè)是...這個(gè)思考鏈路不只是在做“技術(shù)展示”它同時(shí)也是排查問題的最有力工具——任何一步不符合預(yù)期你都能在intermediate_steps里找到原因。3.6 一個(gè)完整可運(yùn)行的業(yè)務(wù)示例把上面的代碼串成一個(gè)實(shí)際問題案例假設(shè)你現(xiàn)在接到需求“讓業(yè)務(wù)運(yùn)營(yíng)能在對(duì)話框里問‘這個(gè)月各區(qū)域的新增客戶數(shù)和訂單總額’”完整的Agent構(gòu)建如下from langchain_openai import ChatOpenAI from langchain_community.utilities import SQLDatabase from langchain.agents import create_sql_agent from langchain.agents.agent_types import AgentType from langchain.agents.agent_toolkits import SQLDatabaseToolkit llm ChatOpenAI(modelqwen2.5:72b, temperature0, api_key..., base_url...) db SQLDatabase.from_uri(mysqlpymysql://analyst:...host:3306/analytics_db, sample_rows_in_table_info2) toolkit SQLDatabaseToolkit(dbdb, llmllm) business 業(yè)務(wù)口徑定義 - 新增客戶customers.created_at在本月 - 訂單總額orders.total_amount求和 - 區(qū)域customers.region agent create_sql_agent( llmllm, toolkittoolkit, agent_typeAgentType.ZERO_SHOT_REACT_DESCRIPTION, verboseTrue, handle_parsing_errorsTrue, max_iterations5, extra_promptbusiness, ) result agent.invoke({input: 這個(gè)月各區(qū)域的新增客戶數(shù)和訂單總額各是多少}) print(result[output])運(yùn)營(yíng)人員看到的是本月2025年1月各區(qū)域數(shù)據(jù)如下華東區(qū)新增客戶132家訂單總額5800萬華南區(qū)新增客戶98家訂單總額4200萬。Agent內(nèi)部生成的SQL和直接“裸寫”的區(qū)別就在于表名、字段、口徑、排序都經(jīng)過了schema校驗(yàn)和業(yè)務(wù)規(guī)則約束結(jié)果才是可信的。4. 企業(yè)級(jí)落地的工程化改造安全、性能與治理4.1 SQL執(zhí)行安全只讀事務(wù)與危險(xiǎn)操作攔截這是所有企業(yè)上線前必須過的第一關(guān)。LangChain自帶工具不會(huì)自動(dòng)攔截DELETE、UPDATE、DROP所以必須在數(shù)據(jù)庫(kù)賬號(hào)層面解決而不是依賴模型的自覺。我的方案分兩層。第一層給Agent用的數(shù)據(jù)庫(kù)賬號(hào)只授予SELECT權(quán)限從根源上杜絕Agent連接執(zhí)行任何寫操作。第二層在SQL執(zhí)行前加一道正則或AST癥狀檢查一旦捕獲到疑似高危操作DROP、TRUNCATE、ALTER、CREATE、DELETE、UPDATE、INTO OUTFILE等就直接拒絕執(zhí)行并返回錯(cuò)誤信息讓模型改寫。import re BLOCKLIST re.compile( r\b(DROP|TRUNCATE|ALTER|CREATE|DELETE|UPDATE|INSERT|REPLACE|GRANT|REVOKE|INTO OUTFILE)\b, re.IGNORECASE, ) def safe_query(sql: str) - str: if BLOCKLIST.search(sql): return Error: 不允許執(zhí)行非查詢類SQL語句。只能執(zhí)行SELECT。 return str(db.run(sql))這里要提醒的是正則攔截只是兜底絕不能當(dāng)作唯一防線。真正的防線是數(shù)據(jù)庫(kù)賬號(hào)權(quán)限生產(chǎn)環(huán)境必須確保Agent賬號(hào)連DELETE權(quán)限都不存在。4.2 查詢治理行數(shù)限制與超時(shí)控制一個(gè)運(yùn)營(yíng)隨口問“所有歷史訂單”不加限制的SQL會(huì)直接拖垮數(shù)據(jù)庫(kù)。我通常做三件事第一所有Agent產(chǎn)生的SQL默認(rèn)強(qiáng)制追加LIMIT 100除非極端情況下明確要求全量分析。QuerySQLDataBaseTool本身就帶這個(gè)行為但建議自定義工具再?gòu)?qiáng)調(diào)一次。第二給數(shù)據(jù)庫(kù)查詢?cè)O(shè)置超時(shí)。通過SQLAlchemy連接串傳connect_args里的connect_timeout和read_timeout或者干脆包裝工具調(diào)用執(zhí)行超過15秒直接拋錯(cuò)。Agent收到超時(shí)錯(cuò)誤后會(huì)意識(shí)到“這SQL太重了”你就把這條語義加在System Message里告訴它遇到超時(shí)應(yīng)該自動(dòng)改寫查詢條件聚合。import sqlalchemy engine create_engine( mysqlpymysql://analyst:pwdhost:3306/analytics_db, connect_args{connect_timeout: 10, read_timeout: 15, charset: utf8mb4}, )第三大數(shù)據(jù)量聚合優(yōu)先提示模型使用DATE_FORMAT、COUNT、SUM等預(yù)聚合語法避免把全表30萬行拉進(jìn)上下文里讓模型數(shù)數(shù)。4.3 結(jié)果緩存讓重復(fù)問題秒回企業(yè)里“本月銷售額是多少”這類問題隔幾分鐘就有人問一次。每次都跑全量聚合數(shù)據(jù)庫(kù)壓力大、響應(yīng)也慢。緩存老話但放在Agent場(chǎng)景里格外有效。我按“SQL文本Hash”做緩存命中就直接返回歷史結(jié)果不再調(diào)用模型推理也不碰數(shù)據(jù)庫(kù)。這里有一個(gè)細(xì)節(jié)值得注意不能直接用用戶的問題文本作為Key因?yàn)閱栴}一樣、時(shí)間區(qū)間可能不一樣用“生成的SQL 庫(kù)名”作為Key才準(zhǔn)確。另外緩存過期時(shí)間按查詢類型區(qū)分寫死在Prompt里的固定指標(biāo)15分鐘過期日期類動(dòng)態(tài)條件一律不緩存。實(shí)現(xiàn)最輕量的方式是在工具層包一層from functools import lru_cache import hashlib def cached_query(sql: str) - str: key hashlib.md5(sql.encode()).hexdigest() result cache.get(key) if result: return result result safe_query(sql) cache.set(key, result, ex600) return result4.4 日志審計(jì)每一條SQL都要可追溯企業(yè)場(chǎng)景里業(yè)務(wù)人員不是開發(fā)人員他可能自己都不知道自己在問什么敏感數(shù)據(jù)。所以Agent每執(zhí)行的SQL、輸入的問題、經(jīng)過的工具鏈全部要落審計(jì)日志。LangChain在intermediate_steps里已經(jīng)記錄了工具調(diào)用對(duì)但那是Python對(duì)象不適合直接存庫(kù)。你的輸出層需要用一個(gè)封裝函數(shù)統(tǒng)一落日志def run_agent_with_audit(question: str, user_id: str): response agent_executor.invoke({input: question}) for step in response[intermediate_steps]: audit_logs.insert({ user_id: user_id, question: question, tool: step[0].tool, tool_input: step[0].tool_input, observation: str(step[1])[:2000], time: datetime.now(), }) return response[output]審計(jì)日志的價(jià)值在出問題時(shí)能被放大十倍。某天業(yè)務(wù)說“這個(gè)數(shù)怎么不對(duì)”你能翻出當(dāng)時(shí)Agent到底跑了一條什么SQL用的是什么條件馬上定位是口徑錯(cuò)還是數(shù)據(jù)錯(cuò)。5. 常見問題與排查技巧實(shí)錄5.1 模型反復(fù)執(zhí)行同一個(gè)工具不輸出最終答案癥狀日志里schema工具被調(diào)了五六次Agent就是不往下一步走。原因多數(shù)情況下是模型的上下文里已經(jīng)拿到了schema但它不確定是否完整反復(fù)確認(rèn)。深層原因則可能是System Message里的表注釋寫得太復(fù)雜或者字段名有歧義模型還在猜哪個(gè)是“正確的”。排查先把max_iterations調(diào)低讓它快速失敗倒逼你檢查Prompt設(shè)計(jì)。更有效的做法是把表注釋寫得更明確——如果payments.status注釋里寫了“回款狀態(tài):paid-已回款, pending-待回款, overdue-逾期”模型大概率一次就選對(duì)工具不會(huì)反復(fù)試探。5.2 Schema過大導(dǎo)致Token溢出癥狀A(yù)gent在調(diào)用schema工具后上下文瞬間爆炸報(bào)錯(cuò)信息是“Exceeded token limit”。原因某個(gè)表有上百個(gè)字段且sample_rows_in_table_info設(shè)置過大把示例數(shù)據(jù)里的長(zhǎng)文本值都帶進(jìn)來了。解法用include_tables只暴露核心表max_string_length調(diào)小只保留字段值前50個(gè)字符還有就是把sample_rows_in_table_info從2降到1。實(shí)測(cè)大部分場(chǎng)景1行示例就夠模型理解字段語義了。5.3 方言問題日期函數(shù)、分頁(yè)語法不兼容癥狀A(yù)gent生成的SQL在MySQL沒問題換到SQLite或PG庫(kù)就語法報(bào)錯(cuò)。原因模型默認(rèn)傾向生成MySQL語法而某些數(shù)據(jù)庫(kù)方言差異很大。解法在System Message里顯式標(biāo)注“當(dāng)前數(shù)據(jù)庫(kù)類型是PostgreSQL日期函數(shù)請(qǐng)使用DATE_TRUNC分頁(yè)使用LIMIT/OFFSET”最好的方案是注入真實(shí)DB的方言描述到extra_prompt里。1.28版本的SQLDatabase底層會(huì)帶上方言信息但模型不一定主動(dòng)遵守強(qiáng)調(diào)一遍效果明顯更穩(wěn)。5.4 上下文太大Memory被聊天記錄占據(jù)癥狀對(duì)話進(jìn)行到第8輪Agent突然“忘記”庫(kù)表結(jié)構(gòu)開始瞎編SQL。原因歷史對(duì)話沒有被合理壓縮模型在長(zhǎng)上下文中注意力分散。解法在每次進(jìn)入Agent之前保留最近3輪原始對(duì)話作為Memory更早的歷史用單獨(dú)的LLM拆成一條摘要拼到System Message里。這樣既保留對(duì)話背景又不擠壓schema空間。5.5 工具注入被繞過有些同事會(huì)問“Agent要是有6個(gè)工具模型會(huì)不會(huì)在最終回答里拿工具結(jié)果還不夠還要瞎編一點(diǎn)”會(huì)。模型偶爾會(huì)在拿到查詢結(jié)果后為了“回答完整一點(diǎn)”加一些自己腦補(bǔ)的上下文信息這在企業(yè)口徑里是不能接受的。解法分兩步一是System Message里強(qiáng)約束“所有數(shù)據(jù)必須來自工具結(jié)果禁止在最終答案中添加未在工具結(jié)果中出現(xiàn)的數(shù)據(jù)”二是在輸出層做校驗(yàn)如果發(fā)現(xiàn)最終答案里出現(xiàn)了不屬于工具結(jié)果的精確數(shù)字就強(qiáng)制Agent重新回答。這個(gè)校驗(yàn)不能太硬因?yàn)橥ㄓ勉暯诱Z“根據(jù)查詢結(jié)果”這類是正常的主要是緊盯數(shù)字。結(jié)語與個(gè)人體會(huì)LangChain SQL Agent在1.28版本下已經(jīng)具備了不少可直接用于生產(chǎn)的組件但真正決定它能跑多遠(yuǎn)往往不在LangChain本身而在于你為它做了多少工程化防護(hù)和口徑治理。我在這類項(xiàng)目里最深的體會(huì)是Agent的推理能力只是上限而Schema裁剪、業(yè)務(wù)口徑注入、權(quán)限與審計(jì)才是下限。下限不穩(wěn)上限再高也不敢讓業(yè)務(wù)人員點(diǎn)開頁(yè)面。如果后續(xù)要再擴(kuò)展比較值得做的方向是將“口徑管理”從一個(gè)硬編碼字典升級(jí)為動(dòng)態(tài)拋出的知識(shí)庫(kù)配合Agent的Retrieval能力實(shí)現(xiàn)口徑的自助查找與引用。如果你的團(tuán)隊(duì)正準(zhǔn)備做企業(yè)級(jí)自然語言查數(shù)先把這五個(gè)問題在測(cè)試環(huán)境逐一壓一遍再考慮上線能少走很多彎路。