ChatSQL：用自然语言"翻译"你的数据库查询

想象这样一个场景：运营小张手里有一份 MySQL 数据库，里面躺着过去三年的销售订单记录。老板突然问：去年第四季度华南区销售额超过 50 万的单子有哪些？小张不是 DBA，面对十几张关联表，想写出一条准确的 SQL 要折腾半天。现在只需要把这句话扔给 ChatSQL，几秒钟后，一条精准的 SELECT 就出来了。

ChatSQL 正是为解决这个痛点而生的工具：由 GPT 驱动的 Text-to-SQL 引擎，将自然语言查询自动翻译为 MySQL 语句，可选直接执行并把原始结果再翻译成人类可读的自然语言返回。整个链路只需要配置文件和一个 Python 脚本，中小型数据库场景开箱即用。

图1：ChatSQL 项目 Logo

背景：Text-to-SQL 的技术挑战

Text-to-SQL 是自然语言处理领域的经典难题。2019 年以来，随着预训练语言模型的突破，基于 LLM 的 Text-to-SQL 方案逐渐成为主流。相比传统规则和 Seq2Seq 方法，LLM 能更好地理解复杂的表结构和多表 JOIN 逻辑。

ChatSQL 的作者在 README 中明确指出，项目更适合中小型数据库场景。当数据库规模增长、表结构复杂度提升时，直接把所有 schema 信息塞进 Prompt 的方式会变得昂贵且不稳定——作者计划未来通过向量数据库做 schema 检索来实现大规模数据库支持，但该项目最终未完成大规模版本，当前代码已停止维护（最后推送于 2023 年 5 月）。

核心架构：LangChain + gRPC 三步流水线

ChatSQL 的代码量不大，核心逻辑清晰，可分为三个功能模块：

第一步：Prompt 构建 - SQL 生成（chatsql.py）

ChatSql 类负责将自然语言 Prompt 转换为 SQL 语句。核心方法 prompt_to_query() 使用 LangChain 的 PromptTemplate 注入两个变量：用户查询 prompt 和数据库 schema 信息 info（来自 info.json）。LangChain 的 OpenAI LLM（底层调用 text-davinci-003）接收格式化后的 Prompt，输出一个 JSON 字符串，包含 query 键对应 SQL 语句。

template = '''Your mission is convert SQL query from given {prompt}. 
Use following database information (key=column name, value=explanation). {info}
Put your query in the JSON structure with key name is 'query'
'''
pr_ = PromptTemplate(input_variables=['prompt', 'info'], template=template)
gpt_query = json.loads(self.llm(final_prompt))

第二步：SQL 执行（sql_connector.py）

SqlConnector 类封装 MySQL 连接，根据配置（conf.json 中的 HOST/USER/PASSWD/DATABASE）建立连接，执行 LLM 生成的 SQL 语句，返回原始结果集（tuple 列表）。

第三步：结果自然语言化（chatsql.py）

raw_result_to_processed() 方法将数据库原始结果再次送入 LLM，生成自然语言描述。例如执行完查询后，返回的不再是冷冰冰的数据行，而是一段连贯的自然语言说明。

服务化：gRPC 架构（main.py + client.py）

除了直接命令行调用，ChatSQL 还提供了 gRPC 服务化部署。通过 chatsql.proto 定义 SqlPredictor RPC，客户端发送自然语言 Prompt，服务端返回三元组：{query, rawResult, processedResult}。服务端使用 ThreadPoolExecutor(max_workers=32) 支持多并发，端口默认 9001。

快速上手：本地部署实战

环境准备

项目要求 Python 3.8+，需提前准备好以下依赖：

• MySQL 8.0+：用于存储数据，可通过 Docker 快速启动：docker run -d -p 3306:3306 -e MYSQL_ROOT_PASSWORD=secret mysql:8
• OpenAI API Key：在 OpenAI 平台获取，用于调用 GPT 模型
• Docker（可选）：提供 Dockerfile，可一键构建镜像

步骤一：安装依赖

git clone https://github.com/ademakdogan/ChatSQL.git
cd ChatSQL
make install

requirements.txt 中锁定了旧版本 LangChain（0.0.135），实际使用时可能遇到依赖冲突。建议在虚拟环境中操作：

python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

步骤二：配置数据库和 API Key

编辑 conf.json，填入 OpenAI API Key、MySQL 连接信息和数据库名；编辑 info.json 描述数据库结构（列名 -> 含义的映射）。

步骤三：导入示例数据并查询

# 插入示例图书数据（data/books.csv）
python3 src/sample_data_creator.py

# 命令行查询
python3 src/chatsql.py --prompt "Show me all books whose genre is data_science"
# 输出: {query: SELECT * FROM bt WHERE Genre = 'data_science', ...}

Docker 部署（推荐生产使用）

make docker           # 构建镜像
make docker_run p=9001  # 启动容器，暴露端口 9001

部署分析总结

维度	评估
Web UI	无，纯 CLI/gRPC 调用
容器化	有 Dockerfile，基于 python:3.8-slim-buster
一键部署	无 docker-compose，需手动配置 MySQL 和 API Key
GPU 需求	无，需 OpenAI API Key（远程调用）
硬件难度	低（纯 CPU，无 GPU，内存仅需 512MB）
部署难度	中等（需理解 MySQL + gRPC 基础）

技术债务与局限性

尽管 ChatSQL 架构清晰、易于理解，但在 2026 年回看，存在若干明显局限：

1. LangChain 版本过旧：requirements.txt 锁定 langchain==0.0.135，该版本发布于 2023 年上半年，与当前 LangChain API 有显著差异。直接 pip install -r requirements.txt 很可能遇到 ImportError。

2. GPT 模型成本问题：项目将所有 schema 信息直接塞进 Prompt，数据库越大 token 消耗越高。README 中提到的向量数据库方案（用 Embedding 做 schema 检索再注入）未实现。

3. SQL 安全性：LLM 生成的 SQL 未经过白名单或语法校验就直接执行，存在注入风险。生产环境强烈建议增加 SQL 校验或限制 DDL/DML 操作。

4. 维护停滞：项目最后推送时间为 2023 年 5 月，已有近三年无更新，LangChain 生态已大幅演进，项目可能难以直接运行。

行业意义与数据隐私

ChatSQL 代表了 LLM 落地初期的一种典型模式：用 Prompt Engineering 解决结构化数据查询问题。其核心价值在于将 AI 能力以最小成本引入数据库查询场景，降低非技术人员的用数门槛。

在数据隐私方面，由于项目完全依赖 OpenAI API，用户的数据库 schema 信息会随 Prompt 发送至 OpenAI 服务器。如果处理敏感业务数据（如财务、医疗），需注意数据合规问题。

整体而言，ChatSQL 是一个优秀的 Text-to-SQL 入门级参考实现，适合学习 LangChain Prompt 模板编写和 gRPC 服务化部署；对于生产级应用，建议评估 LangChain 版本升级和 SQL 安全增强。