用LLM API搭建自然语言数据库查询机器人：Text-to-SQL完整实践指南

如果你的Web应用里有一堆业务数据，但用户只能通过固定报表和后台列表查看，那这篇文章值得看完。这次我们聊的是怎么用LLM做一个数据库查询机器人（Database Query Bot），让用户直接用自然语言问“上个月哪个品类的销售额最高”，系统自动解析意图、生成SQL、查询数据库，再把结果返回给前端。整个流程可以压缩到一天内跑通，核心不是从零写一个Text-to-SQL引擎，而是把现成的LLM API、数据库Schema上下文和查询校验机制串起来。

这个方案最值得关注的点有三个：第一，不需要自己训练模型，直接用开放平台的大语言模型API即可，本地不需要高显存服务器；第二，SQL生成之后加一道校验和执行隔离，LLM只负责生成，不直接操作生产库；第三，前端接一个聊天框，后端暴露一个查询接口，支持多轮追问和查询结果格式化返回。本文会带你把架构设计、环境准备、后端实现、前端接入、接口调用、性能观察和排查方法完整过一遍，最后给出一套可以直接改的业务接入模板。

适合的读者有三类：一是Web应用开发者，想给后台管理系统加一个“数据问答”入口；二是做企业内部工具的产品技术同学，需要让非技术同事通过对话查数据；三是对LLM应用落地感兴趣，想看一个从提示词到SQL执行全链路的工程实现方案。

1. 核心能力速览

从材料看，这个主题的核心是工程集成，而不是算法研究。你需要把“LLM + 数据库 + Web App”三段串起来，每一段都有成熟组件可用，所以一天内完成一个可用原型是可行的。

2. 适用场景与使用边界

2.1 适合谁用

这个方案适合已经有一个相对稳定的业务数据库，并且数据库表结构、字段含义可以被明确描述的场景。典型的接入对象包括：

• 电商系统的订单、商品、库存查询。
• SaaS产品的用户行为分析。
• 企业内部运营数据看板补充入口。
• 内容平台的流量、转化、收益数据问答。

用户不需要懂SQL，只需要用自然语言描述需求，例如“查询最近7天每天的新增用户数，按天排序”。系统把这句话转成SQL，执行后返回结果。

2.2 不适合什么

不适合直接把生产库交给LLM去生成和执行任意SQL。原因很简单：LLM生成的SQL可能在语法上正确，但语义上越权，比如绕过行级权限；也可能因为提示词注入导致执行危险操作。因此生产落地的边界必须明确：

• 数据库账号必须只读。
• 只能查询配置好的表和视图。
• 不允许执行DDL、UPDATE、DELETE。
• 敏感字段要脱敏或直接排除在Schema上下文之外。

2.3 合规与安全提醒

涉及企业内部数据、用户隐私数据时，必须做好权限控制、审计日志和敏感信息过滤。LLM生成SQL的输入输出会经过外部API，如果数据敏感，需要评估是否使用私有化部署模型，或在请求前做脱敏处理。这个问题在架构设计阶段就要决定，不要等上线后再补。

3. 系统架构与设计思路

在写代码之前，先把架构理清楚。一个可用的LLM Database Query Bot不只是一个“SQL生成器”，而是一条完整的链路：

用户输入自然语言问题 ↓ 识别数据库类型与可用表 ↓ 组装Prompt（系统指令 + Schema定义 + 表样例 + 历史对话） ↓ 调用LLM API生成SQL ↓ SQL规则校验（只读、白名单、关键字过滤） ↓ 执行查询并捕获错误 ↓ 结果格式化，可选生成自然语言总结 ↓ 返回给前端Web页面

关键点在于：LLM负责“理解”和“生成SQL”，但不负责直接执行。执行之前必须有一层规则校验，把风险挡在数据库之外。

如果要做多轮对话，把前一轮的SQL和查询结果摘要作为上下文传入下一轮。这样用户说“那换成按分类统计”时，系统能理解“那”指代的是上一轮查询。

4. 环境准备与前置条件

没有真实的项目仓库时，建议先按以下通用清单准备环境。这些是LLM Web应用最常见的组合，先确认版本再开始写代码，避免后面出现依赖冲突。

4.1 运行环境

4.2 数据库准备

你需要一个可连接的测试数据库，并准备库表清单。例如：

-- 示例：商品订单表 CREATE TABLE orders ( id BIGINT PRIMARY KEY, product_name VARCHAR(100), category VARCHAR(50), amount DECIMAL(10,2), order_date DATE );

查询机器人需要知道这些表结构，才能生成有效的SQL。你可以手动写死，也可以让程序读取数据库中的信息模式（information_schema）自动加载。

4.3 目录结构建议

llm-query-bot/ ├── app.py # FastAPI 服务入口 ├── config.py # 配置：数据库连接、LLM API配置 ├── models.py # 请求/响应数据结构 ├── db.py # 数据库连接与查询执行 ├── llm_client.py # LLM API调用封装 ├── sql_validator.py # SQL校验与过滤 ├── prompts.py # Prompt组装模板 ├── templates/ │ └── index.html # 前端聊天页面 └── requirements.txt

这种分离方式的好处是：后续换LLM供应商、换数据库类型、加权限逻辑时，不需要改全部代码。

5. 后端实现与启动方式

实际项目可能用FastAPI、Flask或Node.js，这里给出FastAPI的通用模板，路径和方法名需要按你的项目调整。

5.1 安装依赖

pip install fastapi uvicorn openai sqlalchemy pydantic python-dotenv

5.2 数据库连接

用SQLAlchemy创建只读引擎，重点设置连接池和超时参数，防止查询长时间占用连接。

# db.py from sqlalchemy import create_engine, text import os DATABASE_URL = os.getenv("DATABASE_URL", "postgresql://user:password@localhost:5432/mydb") engine = create_engine( DATABASE_URL, pool_size=5, max_overflow=10, connect_args={"connect_timeout": 10} ) def execute_query(sql: str): with engine.connect() as conn: result = conn.execute(text(sql)) rows = [dict(row._mapping) for row in result] return rows

5.3 LLM调用封装

# llm_client.py from openai import OpenAI client = OpenAI( api_key=os.getenv("LLM_API_KEY"), base_url=os.getenv("LLM_BASE_URL") # 兼容OpenAI格式的服务 ) def generate_sql(system_prompt: str, user_question: str) -> str: response = client.chat.completions.create( model=os.getenv("LLM_MODEL", "gpt-4o-mini"), messages=[ {"role": "system", "content": system_prompt}, {"role": "user", "content": user_question} ], temperature=0.1 ) return response.choices[0].message.content

5.4 提示词组装

提示词直接决定SQL生成质量。一个合格的Prompt至少包含四部分：角色指令、数据库Schema、字段口径说明、输出格式要求。

# prompts.py SYSTEM_PROMPT_TEMPLATE = """ 你是一个数据库查询助手。请根据用户的问题，生成一条SQL查询语句。 数据库类型：PostgreSQL 只允许SELECT查询，禁止任何UPDATE、DELETE、INSERT、DDL语句。 数据库表结构： {table_schema} 字段口径说明： {field_descriptions} 要求： 1. 只输出SQL，不要有多余解释。 2. 如果问题不明确，输出一个占位注释：-- NEED_MORE_INFO 3. SQL必须使用表结构中存在的字段名。 表结构如下： {table_ddl} """

这里最容易踩的坑是字段口径不写清楚。比如“成交额”到底统计的是支付成功订单还是所有订单，如果Prompt里不写，LLM每次生成的结果可能不一致。建议把口径说明写进Schema描述里，例如：

orders.amount：订单实付金额，已过滤退款订单

5.5 SQL校验器

执行之前做一次规则校验。这是生产环境必备的一层，不能省略。

# sql_validator.py import re BANNED_KEYWORDS = ["insert", "update", "delete", "drop", "alter", "truncate", "create", "grant", "into", "merge"] def validate_sql(sql: str) -> bool: sql_lower = sql.lower().strip() if not sql_lower.startswith("select"): return False for kw in BANNED_KEYWORDS: if re.search(r"\b" + kw + r"\b", sql_lower): return False return True

注意这只是基础过滤，不是绝对安全方案。真正的生产环境应该在数据库账号层面设置只读权限，双管齐下。

5.6 FastAPI服务入口

# app.py from fastapi import FastAPI, HTTPException from pydantic import BaseModel import db import prompts import llm_client import sql_validator app = FastAPI() class QueryRequest(BaseModel): question: str history: list = [] class QueryResponse(BaseModel): sql: str result: list error: str = "" @app.post("/api/query") def query(req: QueryRequest): system_prompt = prompts.SYSTEM_PROMPT_TEMPLATE.format( table_schema="...", field_descriptions="...", table_ddl="..." ) sql = llm_client.generate_sql(system_prompt, req.question) if not sql_validator.validate_sql(sql): raise HTTPException(status_code=400, detail="生成的SQL未通过安全校验") try: result = db.execute_query(sql) except Exception as e: return QueryResponse(sql=sql, result=[], error=str(e)) return QueryResponse(sql=sql, result=result) @app.get("/api/health") def health(): return {"status": "ok"}

启动方式：

uvicorn app:app --host 0.0.0.0 --port 8000

启动后访问http://127.0.0.1:8000/docs可以直接在Swagger UI里测试接口，这个对调试很友好。

6. 功能测试与效果验证

6.1 测试数据准备

准备几张表，插入少量测试数据。建议用和业务形态接近的数据，否则验证效果时没有说服力。例如：

INSERT INTO orders (id, product_name, category, amount, order_date) VALUES (1, 'iPhone 15', '手机', 6999.00, '2025-01-10'), (2, 'MacBook Air', '笔记本', 8999.00, '2025-01-12'), (3, 'AirPods Pro', '耳机', 1899.00, '2025-01-15');

6.2 基础查询测试

在Swagger UI或前端页面输入：

查询订单表中每个品类的总金额，按总金额降序排列

预期返回：

{ "sql": "SELECT category, SUM(amount) AS total_amount FROM orders GROUP BY category ORDER BY total_amount DESC", "result": [ {"category": "笔记本", "total_amount": 8999.00}, {"category": "手机", "total_amount": 6999.00}, {"category": "耳机", "total_amount": 1899.00} ] }

判断标准：SQL没有多余注释，分组和排序符合题意，返回结果与手写SQL一致。

6.3 多轮追问测试

第一轮先问“2025年1月订单总金额是多少”，拿到结果后追问“那各品类的占比呢”。多轮的关键是后端要把历史对话一并传给LLM，否则模型不知道“那”指什么。

6.4 错误SQL测试

输入一个明显越权的请求：“删除所有订单记录”。正常的系统应该返回400错误，SQL校验器拦截，而不是真的执行删除。这个用例必须测，而且要通过。

6.5 常见失败原因

7. 前端Web接入示例

后端接口跑通后，前端只需要一个聊天框就能接入。这里给一个最简单的原生HTML示例，适合快速验证。

<!DOCTYPE html> <html lang="zh"> <head> <meta charset="UTF-8"> <title>数据库查询机器人</title> </head> <body> <h2>数据库查询机器人</h2> <div id="history"></div> <input id="question" placeholder="输入你的问题" style="width: 400px;" /> <button onclick="sendQuestion()">发送</button> <script> async function sendQuestion() { const question = document.getElementById('question').value; const history = JSON.parse(localStorage.getItem('chat_history') || '[]'); const response = await fetch('http://127.0.0.1:8000/api/query', { method: 'POST', headers: {'Content-Type': 'application/json'}, body: JSON.stringify({ question: question, history: history }) }); const data = await response.json(); const historyDiv = document.getElementById('history'); historyDiv.innerHTML += `<p><b>问：</b>${question}</p>`; historyDiv.innerHTML += `<p><b>SQL：</b>${data.sql}</p>`; historyDiv.innerHTML += `<p><b>结果：</b>${JSON.stringify(data.result)}</p>`; history.push({ question: question, answer: data }); localStorage.setItem('chat_history', JSON.stringify(history)); } </script> </body> </html>

注意：这个示例仅用于本地验证，没有做跨域处理。实际接入时，如果你的Web应用和后端地址不同，需要在FastAPI端配置CORS（跨域资源共享）。

from fastapi.middleware.cors import CORSMiddleware app.add_middleware( CORSMiddleware, allow_origins=["*"], allow_methods=["*"], allow_headers=["*"], )

8. 接口 API 与批量任务

8.1 接口设计

对外暴露的接口建议分为三个：

8.2 批量任务设计

如果业务方要在凌晨跑一批固定问题，例如“每天查一次昨日转化数据”，不建议直接循环调用接口。更稳妥的做法是：

1. 用队列任务（如Celery）异步执行。
2. 查询任务写入任务表，记录状态。
3. 每批任务执行前先校验数据库连接和LLM额度。
4. 失败任务自动重试，最多3次。

# 批量任务伪代码 tasks = ["查询今日订单量", "查询今日成交额", "查询今日退款率"] for task in tasks: try: result = query_bot(task) save_result(task, result) except Exception as e: retry_count += 1 log_error(task, str(e))

9. 资源占用与性能观察

9.1 LLM API模式与本地部署模式

如果你用的是云端LLM API，本地不需要GPU，主要瓶颈在网络延迟和API并发限制。一个查询请求大约增加了2到10秒的额外延迟（需按实际模型服务测试），这部分用户体验可以通过前端loading提示来缓解。

如果选择本地部署开源模型，先评估硬件。按常规经验，7B级别模型量化版可能需要8G以上显存，13B级别需要更大显存，实际以指定模型和推理框架为准，这里不展开写死数字。

9.2 性能影响点

查询机器人的响应时间由四部分组成：

• LLM API调用时间：取决于模型尺寸和服务负载。
• 数据库查询时间：取决于SQL复杂度、数据量、索引情况。
• Prompt长度：表结构如果有几十张表，每次请求都传完整DDL会导致Token消耗增加。
• 结果格式化时间：结果集很大时，JSON序列化也会有开销。

9.3 优化手段

• 把常用的表结构放在模型上下文，不常用的表按需加载。
• 给数据库查询加LIMIT限制，默认返回前100行。
• 结果集过大时，不在对话中返回完整数据，而是生成下载链接。
• 对相同问题加缓存，短时间内的重复查询直接返回缓存结果。

10. 安全、权限与最佳实践

10.1 数据库权限隔离

生产环境必须使用只读账号。在数据库层面限制是最可靠的，不要依赖提示词约束。例如在PostgreSQL中：

CREATE ROLE query_bot_read WITH LOGIN PASSWORD 'safe_password'; GRANT CONNECT ON DATABASE mydb TO query_bot_read; GRANT USAGE ON SCHEMA public TO query_bot_read; GRANT SELECT ON ALL TABLES IN SCHEMA public TO query_bot_read; ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT ON TABLES TO query_bot_read;

这样即使LLM生成了恶意SQL，数据库本身也会拒绝执行。

10.2 敏感数据过滤

不要把用户手机号、身份证、明文密码等字段放在Schema上下文中。如果业务确实需要统计这类数据，用脱敏聚合结果而不是原始明细。例如“统计各省用户数”是安全的，“导出广东省所有用户手机号”就不应该允许。

10.3 建议清单

• 第一次运行时先用小参数测试：单用户、小表、简单问题。
• 保留一套最小可运行配置，方便快速恢复环境。
• 模型文件、输入请求、输出结果分目录管理。
• 批量任务要加日志和失败重试，避免任务中断后不知道跑到哪。
• 接口服务要限制访问来源，不要直接暴露在公网。
• 涉及人脸、声音、版权素材时要确认授权，本文场景主要是文本数据，也不可忽略合规。
• 上线前做一轮SQL正确性回归测试，把历史查询记录和人工标注结果对比。

11. 常见问题与排查方法

12. 总结与下一步

这个项目最值得尝试的点在于：它把LLM从“聊天玩具”变成了一个能查真实业务数据的生产力工具。一天内跑通的核心路径是“FastAPI + LLM API + SQLAlchemy + 前端聊天框”，关键在Prompt组装和SQL校验这两层。

最先应该验证的是基础查询能力。用一个小表，让机器人回答“总数是多少”“按分类统计”这类简单问题，确认SQL生成准、执行快、返回符合预期。最容易踩的坑有三个：一是Prompt里不写字段口径导致结果不稳定；二是忘了做SQL执行前校验；三是生产环境直接用了管理员账号连数据库。

后续可以扩展的方向包括：接入更多数据库类型、支持图表可视化返回、把常用查询沉淀为固定模板降低Token消耗、引入RAG方式管理超多表结构的Schema描述、增加用户级别的行级权限过滤，以及把查询历史作为人工反馈数据来优化Prompt。

如果你想把这个方案接到自己的Web应用里，建议先把接口返回结构和前端展示约定好，再让后端按生产标准补上日志、限流和审计。这样原型验证通过后，可以直接在这个骨架上填业务逻辑，不用推翻重来。