Text-to-SQL Agent 🤖

基于 LangChain + LangGraph 构建的自然语言转 SQL 命令行智能助手，输入自然语言问题即可自动生成并执行 SQL 查询，返回结构化回答。

项目介绍

Text-to-SQL Agent 是一个将自然语言转换为 SQL 查询的 AI 智能助手。它基于以下技术栈构建：

• LangChain — 提供 LLM 编排与 SQL 数据库工具集
• LangGraph — 实现有状态的 Agent 对话管理与多轮记忆
• ChatOpenAI (兼容接口) — 支持任意 OpenAI API 兼容的大模型（如 GLM-4、DeepSeek 等）
• SQLDatabaseToolkit — 内置数据库操作工具集（列表、Schema 查看、SQL 执行、语法检查）

核心功能

• 🗣️ 自然语言查询：输入中文/英文问题，自动转换为 SQL 并执行
• 🔄 多轮对话：支持上下文连续对话，Agent 能记住历史问答
• 🛡️ 安全防护：禁止执行 DML 操作（INSERT/UPDATE/DELETE），保护数据安全
• 📊 流式输出：实时展示 Agent 思考过程、工具调用详情和最终回答
• 🔧 Unicode 安全：内置 SafeToolWrapper 自动清洗 surrogate 字符，防止编码错误

项目结构

text_to_sql_agent/
├── agent.py           # 核心代码：Agent 构建、工具包装、流式输出、REPL 入口
├── config.yaml        # 主配置文件（模型、数据库、System Prompt）
├── config.dev.yaml    # 开发环境配置文件
├── pyproject.toml     # Python 项目构建配置
├── .env               # 环境变量（API Key 等，不提交到 Git）
├── .env.example       # 环境变量模板
└── tutorial.ipynb     # Jupyter Notebook 教程

快速开始

1. 环境要求

• Python >= 3.10

2. 克隆项目

git clone <your-repo-url>
cd text_to_sql_agent

3. 创建虚拟环境并安装依赖

python -m venv .venv
source .venv/bin/activate  # macOS/Linux
# .venv\Scripts\activate   # Windows

pip install -e .

4. 配置环境变量

在项目根目录下创建 .env 文件：

cp .env.example .env

编辑 .env 文件，填入你的模型 API Key：

MODEL_API_KEY=your_api_key_here

5. 修改配置文件

编辑 config.yaml，填入你的数据库连接信息和模型配置（详见下方 配置说明）。

6. 启动 Agent

# 方式一：直接运行
python agent.py

# 方式二：通过 entry point 运行（需先 pip install -e .）
sql-agent

7. 开始对话

==================================================
  Text-to-SQL 智能助手
  输入自然语言，自动转换为 SQL 并执行
  输入 'exit' 或 'quit' 退出，输入 'new' 开启新会话
==================================================

🚀 正在启动，请稍候...

  ⏳ 加载配置文件...
  ⏳ 连接数据库...
  ⏳ 初始化 AI 模型...
  ⏳ 加载 SQL 工具集...
  ⏳ 构建 Agent...
  ✅ 初始化完成！

会话已启动（ID: a1b2c3d4...）

你: 数据库里有哪些表？

配置说明

项目通过 config.yaml 进行配置，包含三大部分：

模型配置 (model)

字段	说明	示例
name	模型名称	glm-4.7
base_url	OpenAI 兼容 API 的 Base URL	https://open.bigmodel.cn/api/paas/v4/
temperature	生成温度，越低越确定性	0.3

model:
  name: glm-4.7
  base_url: https://open.bigmodel.cn/api/paas/v4/
  temperature: 0.3

注意：模型的 API Key 不放在配置文件中，而是通过 .env 文件中的 MODEL_API_KEY 环境变量提供。

数据库配置 (db)

字段	说明	示例
type	数据库类型	mysql
url	SQLAlchemy 数据库连接 URI	mysql+pymysql://user:pass@host:port/db?charset=utf8mb4
sample_rows_in_table_info	展示表结构时的示例行数	5

db:
  type: mysql
  url: mysql+pymysql://username:password@ip:port/dbName?charset=utf8mb4
  sample_rows_in_table_info: 5

支持的数据库：理论上支持所有 SQLAlchemy 兼容的数据库（MySQL、PostgreSQL、SQLite、ClickHouse 等），只需修改 url 中的连接驱动即可。

System Prompt 配置 (system_prompt)

支持多版本 Prompt 管理，通过 active_version 切换当前生效的版本：

字段	说明
active_version	当前激活的 Prompt 版本名
versions	版本字典，key 为版本名，value 为 Prompt 内容

system_prompt:
  active_version: v1
  versions:
    v1: |
      您是一个旨在与 SQL 数据库进行交互的程序。
      ...
    v2: |
      自定义的另一个版本的 Prompt...

完整配置示例

model:
  name: glm-4.7
  base_url: https://open.bigmodel.cn/api/paas/v4/
  temperature: 0.3

db:
  type: mysql
  url: mysql+pymysql://username:password@ip:port/dbName?charset=utf8mb4
  sample_rows_in_table_info: 5

system_prompt:
  active_version: v1
  versions:
    v1: |
      您是一个旨在与 SQL 数据库进行交互的程序。
      对于输入的问题，创建一条语法正确的 MySQL 查询语句来执行，然后查看查询的结果并返回答案。
      除非用户指定了他们希望获取的具体示例数量，否则请始终将查询限制在最多 10 个结果以内。
      您可以按照相关列对结果进行排序，以获取数据库中最具代表性的示例。
      切勿从特定表中查询所有列，而应根据问题的要求仅请求相关列。
      在执行查询之前，您必须再次仔细检查您的查询内容。如果在执行查询时出现错误，请重新编写查询并再次尝试。
      切勿向数据库执行任何数据操作语言（DML）语句（如插入、更新、删除、删除表等）。
      首先，您应当始终查看数据库中的表，以了解可以进行哪些查询操作，切勿跳过此步骤。
      然后，您应当查询最相关的那些表的结构。
      你在回答的时候，首先给出对应的查询语句和查询结果，然后给出最终的答案。

环境变量 (.env)

变量名	说明	必填
MODEL_API_KEY	大模型 API Key	✅

交互命令

在命令行对话中支持以下命令：

命令	说明
任意自然语言	向 Agent 提问，自动转换为 SQL 并执行
new	开启一个新的对话会话（清除历史上下文）
exit / quit	退出程序

License

MIT