让Agent用自然语言查数据库：Text-to-SQL从零到一实战教程

让Agent用自然语言查数据库Text-to-SQL实战企业里最多的数据在哪里。在数据库里。销售数据、用户数据、订单数据、库存数据全在数据库里。以前要查个数据得找数据分析师写SQL跑报表。等半天才能拿到结果。有了Agent以后这件事变简单了。业务人员直接用自然语言提问Agent自己写SQL自己查数据库自己把结果整理成答案。这个方向叫Text-to-SQL是Agent落地最快的场景之一。这一篇我们从零讲起。怎么让Agent连上数据库怎么让它写对SQL实际用的时候有哪些坑怎么提高准确率。先搭个实验环境我们用SQLite做演示。不用装数据库服务一个文件就是一个库方便上手。先准备一个示例数据库。我们造一张销售表几张产品表方便后面测试。importsqlite3# 创建数据库连接connsqlite3.connect(sales.db)cursorconn.cursor()# 创建产品表cursor.execute( CREATE TABLE IF NOT EXISTS products ( id INTEGER PRIMARY KEY, name TEXT NOT NULL, category TEXT, price REAL ) )# 创建销售表cursor.execute( CREATE TABLE IF NOT EXISTS sales ( id INTEGER PRIMARY KEY, product_id INTEGER, quantity INTEGER, amount REAL, sale_date TEXT, region TEXT, FOREIGN KEY (product_id) REFERENCES products(id) ) )# 插入示例产品数据products[(1,智能手机A,电子产品,2999),(2,笔记本电脑B,电子产品,5999),(3,无线耳机C,电子产品,399),(4,运动T恤D,服装,129),(5,跑鞋E,服装,459),]cursor.executemany(INSERT OR REPLACE INTO products VALUES (?,?,?,?),products)# 插入示例销售数据sales[(1,1,120,359880,2026-07-01,北京),(2,2,45,269955,2026-07-01,上海),(3,3,200,79800,2026-07-02,广州),(4,1,150,449850,2026-07-02,上海),(5,4,300,38700,2026-07-03,北京),(6,5,80,36720,2026-07-03,深圳),(7,2,60,359940,2026-07-04,广州),(8,3,250,99750,2026-07-04,上海),]cursor.executemany(INSERT OR REPLACE INTO sales VALUES (?,?,?,?,?,?),sales)conn.commit()conn.close()运行这段代码就会在当前目录生成一个sales.db文件里面有两张表和一些示例数据。最简单的Text-to-SQLLangChain有现成的SQL数据库工具。我们来搭一个最简单的版本。先装依赖。pipinstalllangchain langchain-openai python-dotenv然后写代码。fromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain_community.utilitiesimportSQLDatabasefromlangchain_community.tools.sql_database.toolimportQuerySQLDataBaseToolfromlangchain.chainsimportcreate_sql_query_chain load_dotenv()# 连接数据库dbSQLDatabase.from_uri(sqlite:///sales.db)# 初始化模型modelChatOpenAI(modelgpt-3.5-turbo,temperature0)# 创建SQL查询链chaincreate_sql_query_chain(model,db)# 提问responsechain.invoke({question:7月2号上海卖了多少部手机})print(response)运行一下你会看到它生成的SQL语句。create_sql_query_chain只负责生成SQL不会真的执行。要执行的话得自己调用数据库工具。我们把执行也加上。fromlangchain_community.tools.sql_database.toolimportQuerySQLDataBaseTool# 创建查询执行工具execute_queryQuerySQLDataBaseTool(dbdb)# 生成SQLsqlchain.invoke({question:7月2号上海卖了多少部手机})print(生成的SQL,sql)# 执行SQLresultexecute_query.invoke(sql)print(查询结果,result)这样就能拿到查询结果了。做成Agent上面的例子是用Chain的方式。我们把它做成Agent效果会更好。Agent可以多轮思考SQL写错了还能自己改。fromdotenvimportload_dotenvfromlangchain_openaiimportChatOpenAIfromlangchain_community.utilitiesimportSQLDatabasefromlangchain_community.tools.sql_database.toolimportQuerySQLDataBaseToolfromlangchainimporthubfromlangchain.agentsimportAgentExecutor,create_react_agent load_dotenv()# 连接数据库dbSQLDatabase.from_uri(sqlite:///sales.db)# 初始化模型modelChatOpenAI(modelgpt-3.5-turbo,temperature0)# 创建数据库查询工具query_toolQuerySQLDataBaseTool(dbdb)tools[query_tool]# 创建Agentprompthub.pull(hwchase17/react)agentcreate_react_agent(model,tools,prompt)agent_executorAgentExecutor(agentagent,toolstools,verboseTrue,handle_parsing_errorsTrue,)# 测试resultagent_executor.invoke({input:7月份上海的总销售额是多少})print(答案,result[output])Agent的好处是如果第一次写的SQL有问题查不到数据或者报错了它可以自己调整重新写SQL再查。简单的Chain做不到这一点。为什么有时候SQL写不对你可能会发现有时候Agent写的SQL不对。表名猜错了字段名用错了关联关系没搞对。原因很简单。大模型不知道你的数据库长什么样。它只能看到表名和字段名靠名字来猜是什么意思。猜得准不准全看命名规不规范。提高准确率有几个办法。第一个表和字段命名要规范。用有意义的英文名字别用拼音缩写别用单字母。sales_amount就比sa好懂多了。第二个给Agent更多的元数据。告诉它每张表是干什么的每个字段是什么意思有哪些枚举值。LangChain的SQLDatabase支持自定义表描述。# 自定义表描述table_descriptions{sales:销售记录表每一行代表一笔销售订单。包含产品ID、数量、金额、销售日期和销售地区。,products:产品表包含产品名称、分类和价格。product_id和sales表的product_id关联。}dbSQLDatabase.from_uri(sqlite:///sales.db,custom_table_infotable_descriptions,)加上描述以后Agent对表的理解更准确SQL写错的概率会降低。第三个用视图或者同义词。把复杂的表结构做成视图视图名和字段名起得直观一点。Agent查视图就好了不用理解复杂的表关系。第四个给few-shot例子。在Prompt里加几个问题-SQL的示例。大模型看到例子以后写出来的SQL会更准确。安全问题让Agent直接查数据库安全是绕不开的话题。SQL注入是第一个担心的。好在LangChain的SQL工具做了一些防护默认只允许SELECT语句不能执行INSERT、UPDATE、DELETE。数据不会被改。但还有别的风险。数据泄露。Agent可能查到不该看的数据。比如普通员工问了一句全公司工资最高的人是谁。Agent要是真去查了就麻烦了。性能问题。Agent写的SQL可能很慢全表扫描、笛卡尔积把数据库跑挂了。权限过大。Agent用什么账号连数据库。给高权限了不安全给低权限了查不到需要的数据。这些问题没有完美的解决方案只能层层设防。第一权限最小化。Agent用的数据库账号只给它需要的表的SELECT权限。其他表一概看不到。第二查询限制。设置超时时间设置返回行数上限。SQL跑太久自动杀掉返回太多行自动截断。第三内容审核。查询结果返回之前过一遍敏感信息检测。涉及隐私的数据做脱敏。第四人工审核。重要的查询或者可能有风险的查询让人确认一下再执行。做企业内部应用安全一定要放在心上。别等出事了再补。实际效果怎么样实话说现在的Text-to-SQL还做不到百分之百准确。简单查询单表查个总数、平均值基本没问题。准确率能到百分之八九十。中等复杂度两三张表关联加几个条件也还可以。七成左右的准确率吧。复杂查询多表嵌套、窗口函数、复杂统计就不行了。经常写不对。而且准确率跟数据模型的能力也有关系。GPT-4写SQL就比GPT-3.5好不少。国产模型里DeepSeek和通义的SQL能力也还可以。所以实际落地的时候通常是辅助角色。Agent生成SQL人来审核和修改。能省掉很多写SQL的时间但还不能完全替代人。对非技术人员来说能用自然语言查数据哪怕有时候需要人帮忙调一下也比学SQL容易多了。下一篇我们讲文件处理工具。PDF、Word、Excel这些文档Agent怎么读取、解析、生成。