LangChain SQL Agent构建指南（基于MySQL的大模型分析并STEM分发）

ggsshhgj

518人浏览 · 2026-04-04 11:21:27

ggsshhgj · 2026-04-04 11:21:27 发布

LangChain SQL Agent 使用指南

项目概述

LangChain SQL Agent 是基于 LangChain、OpenAI/DeepSeek（兼容 OpenAI 接口）和 SQLDatabase 的智能数据库助理。它可以接受自然语言（中文）输入，自动生成对应的 SQL 并在 MySQL 数据库上执行，返回结构化结果。项目还集成了周报生成的示例（task_agent.py），演示了如何把业务需求转换为 SQL 并输出报告。

环境准备

操作系统：Windows 10/11（亦可在 Linux/macOS 上运行）
Python：推荐 3.12（兼容 3.10+），建议使用 virtualenv 或 conda 创建独立环境
MySQL：8.0 以上，确保已有可以访问的数据库（示例中使用 weekly_tasks、sales_orders 表）
网络：能够访问 DeepSeek（或 OpenAI）API，需拥有相应的 API_KEY

项目结构

langChain_sql_Agent/
├─ .env                # 环境变量文件（API_KEY、DATABASE_URL）
├─ requirements.txt    # 依赖列表
├─ README.md           # 项目说明（本文件的源文档）
├─ task_agent.py       # 核心示例代码（演示自然语言生成 SQL）
├─ report_service.py   # 周报 PDF 生成（可选）
└─ Weekly_Report.pdf   # 示例输出文件

安装依赖

在项目根目录执行以下命令：

# 创建并激活虚拟环境（可选）
python -m venv venv
# Windows
venv\Scripts\activate
# Linux/macOS
source venv/bin/activate

# 安装项目依赖
pip install -r requirements.txt

requirements.txt 已包含 langchain, langchain-openai, langchain-community, python-dotenv, pymysql 等必要库。

配置环境变量

在根目录新建 .env（或直接编辑已有文件），示例内容如下：

# DeepSeek（或 OpenAI）API Key
DEEPSEEK_API_KEY=your_deepseek_api_key

# 数据库链接（MySQL）
# 格式: mysql+pymysql://username:password@host:port/database_name
DATABASE_URL=mysql+pymysql://root:your_password@127.0.0.1:3306/your_db

注意：确保 DATABASE_URL 能够在本机成功连接，否则在运行时会抛出 SQLAlchemy 连接错误。

运行示例代码

python task_agent.py

执行后，控制台会输出类似如下信息（示例）：

当前使用的 Python 解释器路径: C:\...\venv\Scripts\python.exe
当前使用的 Python 版本: 3.12.0 (main, Oct  2 2024, 12:00:00) [Clang 15.0.0]
🚀 Agent 正在思考中...

--- AI 生成的周报草稿 ---

[AI 返回的自然语言报告]

程序会自动：

读取 .env 中的 API Key 与数据库 URL
通过 SQLDatabase.from_uri 建立数据库连接
使用 ChatOpenAI（DeepSeek）模型生成 SQL
create_sql_agent 将自然语言转为可执行的 SQL 并返回结果
最终在控制台打印 AI 组合的周报文字稿

代码详解

下面把 task_agent.py 的关键代码块分段解释，帮助读者理解每一步的作用。

1️⃣ 导入与环境加载

import os
from dotenv import load_dotenv
from langchain_community.utilities import SQLDatabase
from langchain_openai import ChatOpenAI
from langchain_community.agent_toolkits import create_sql_agent
import sys

print(f"当前使用的 Python 解释器路径: {sys.executable}")
print(f"当前使用的 Python 版本: {sys.version}")

# 加载 .env 中的变量
load_dotenv()

load_dotenv() 会把 .env 内容注入到 os.getenv() 中。
打印解释器路径和版本，仅用于调试，确保使用的解释器是你创建的虚拟环境。

2️⃣ 数据库连接

# DATABASE_URL 形如 mysql+pymysql://user:pwd@host:port/db
db = SQLDatabase.from_uri(os.getenv("DATABASE_URL"))

SQLDatabase.from_uri 是 LangChain 对 SQLAlchemy 的包装，能自动读取表结构并提供 run 方法执行 SQL。

3️⃣ 大模型初始化（DeepSeek 示例）

llm = ChatOpenAI(
    model="deepseek-chat",
    openai_api_key=os.getenv("DEEPSEEK_API_KEY"),
    openai_api_base="https://api.deepseek.com/v1",
    temperature=0
)

temperature=0 让模型生成的 SQL 更确定，避免随机的无效语句。
若你使用 OpenAI，只需把 model 改为 gpt-4o 并使用对应的 OPENAI_API_KEY 即可。

4️⃣ 创建 SQL Agent

agent_executor = create_sql_agent(
    llm,
    db=db,
    agent_type="openai-tools",
    verbose=True,
    max_iterations=15,
    handle_parsing_errors=True
)

create_sql_agent 会构造一个 工具型 Agent，其中 SQLDatabase 被包装成工具，Agent 能在对话中自行调用该工具。
verbose=True 会把思考过程输出到控制台，帮助调试。
max_iterations 限制思考轮数，防止无限循环。
handle_parsing_errors=True 能把 SQL 语法错误返回给模型让它重写。

5️⃣ 输入自然语言 Prompt 并执行

prompt = """
你是公司的财务周报助手。请为员工'张三'生成本周（2026-03-30至今）的销售周报：
1. 统计销售总额和订单数量。
2. 列出金额最高的前三笔订单。
3. 结合 weekly_tasks 表，简述该员工本周的工作进展。
如果本周没有订单，请明确说明，但仍需汇总其工作任务进展。
"""

print("🚀 Agent 正在思考中...")
response = agent_executor.invoke({"input": prompt})
print("\n--- AI 生成的周报草稿 ---")
print(response["output"])

这里的 Prompt 给出了业务需求，Agent 会先分析表结构（SQLDatabase.get_table_info()），生成对应的 SELECT 语句，执行后再组织成自然语言答案。
invoke 返回一个字典，关键字段是 output，即最终的文字报告。

常见问题 & FAQ

问题	解决办法
无法连接 MySQL	检查 `DATABASE_URL` 中的用户名、密码、主机、端口是否正确；确认 MySQL 服务已启动并开放外部访问（防火墙）。
模型返回错误的 SQL	将 `temperature` 调整为 `0`，或在 Prompt 中明确要求 “请仅返回有效的 SQL”。开启 `verbose=True` 查看模型的思考过程以定位问题。
`DeepSeek API` 超时	确认网络能访问 `https://api.deepseek.com`，或在 `ChatOpenAI` 中添加 `request_timeout=30` 参数。
报错 `ImportError: cannot import name 'ChatOpenAI'`	检查 `langchain-openai` 版本是否 >= 0.1.0，或执行 `pip install --upgrade langchain-openai`。
想把报告导出为 PDF	参考项目中的 `report_service.py`，使用 `reportlab` 或 `fpdf` 将 `response["output"]` 写入 PDF。