LangChain 1.0 实战： NL2SQL 数据分析 Agent

引言

在企业级数据分析场景中，"自然语言问数据" 已经成为新一代智能 BI 的主流趋势。

本文教你如何使用 LangChain 1.0 的 ReAct Agent 架构，实现 NL2SQL 数据分析，使业务人员能够以对话式交互高效获得数据洞察。

本文将带你完整了解：

什么是 NL2SQL ，他解决了什么问题？实际应用场景有哪些？
主流开源 AI NL2SQL 数据分析框架（Vanna、DB-GPT、PandasAI 等）
基于 LangChain 1.0 的 NL2SQL 数据分析 Agent 实现（找小助理免费领取项目完整源码）

演示视频：

nl2sql演示视频

一、 NL2SQL 详解

什么是 NL2SQL

NL2SQL 即自然语言到 SQL ，或称文本到 SQL，是指将用户用自然语言提出的问题自动翻译成可在关系数据库上执行的等效 SQL 查询。本质上，NL2SQL 系统充当了人与数据库之间的桥梁，使用户能够使用日常语言检索和分析数据，而无需具备专业的 SQL 技能。

NL2SQL 解决了什么问题

企业中大部分潜在用户（业务分析师、领域专家等）缺乏 SQL 技能。NL2SQL 降低数据库查询的门槛，并加速了数据驱动的决策过程。例如：商业智能或分析领域的非技术用户可以提出诸如"上个季度我们收入排名前五的产品是什么？"之类的问题，并获得结果，而无需手动编写复杂的 SQL。

NL2SQL 实际应用场景

NL2SQL核心应用场景对比

应用场景	场景描述	关键技术点	核心实现思路
数据自助分析	业务人员通过自然语言查询数据，无需懂SQL	• 自然语言理解与Schema映射 • NL2SQL生成与验证 • 数据库连接与结果呈现	LLM Agent作为"SQL助手"，通过链式思维(CoT)执行流程，利用Few-Shot示例库提高准确率，执行反馈循环逐步修正SQL
智能报表生成	自动生成统计报表和可视化图表	• 多步骤查询与分析 • 数据可视化生成 • 报告描述生成	Agent作为"自动化数据分析师"，规划分析流程，依次使用SQL工具、Python计算工具、可视化工具，形成图文并茂的报表
运营与客服分析	快速查询业务指标，支持对话追问	• 复杂业务指标计算 • 多表关联与大数据性能 • 上下文记忆和追问细化	配置业务语义层定义指标，提供优化视图避免复杂JOIN，使用LangChain会话记忆支持多轮对话，拆解复杂分析任务

二、热门开源 AI NL2SQL 数据分析产品对比

目前开源社区中最受关注的几个 NL2SQL 数据分析项目对比如下：

🔸 Vanna：轻量级 Text-to-SQL 框架

Github：https://github.com/vanna-ai/vanna

Vanna 是一个非常轻量的 Text-to-SQL Agent 框架，允许用户通过自然语言直接查询数据库。

它的架构包含 Search、Execution、Feedback 三个核心模块。

当用户输入自然语言时，系统会：

从向量数据库检索相关知识（DDL、Schema、历史 SQL）；
生成 SQL 并执行；
将结果通过可视化反馈，实现"生成-执行-校正"闭环。

🔸 DB-GPT：面向企业级的 AI 数据智能平台

Github：https://github.com/eosphoros-ai/DB-GPT

论文地址：Demonstration of DB-GPT (arXiv 2404.10209)

DB-GPT 由中国开源组织 eosphoros-ai 发起，是一个 AI-Native 数据应用开发框架，目标是让 LLM 能直接理解和操作数据库、数据仓库、Excel 等多源数据。

它支持：

Text2SQL 微调框架（Spider Benchmark 82.5%）；
多智能体协作 (Multi-Agents)；
RAG 检索增强生成；
AWEL 工作流引擎 (Agentic Workflow Expression Language)。

整套系统可部署在 Kubernetes、Ray、AWS、阿里云环境中，支持私有化与可视化。

DB-GPT 的多层架构完整覆盖了从 数据交互 → 语义理解 → 模型生成 → 结果展示 → 反馈优化 的全过程，堪称企业级 AI 数据交互的标杆。

🔸 热门开源产品对比表

项目名称	GitHub Stars	核心定位	主要技术特点	适用场景	核心优势	局限性
PandasAI	22.3k	AI 辅助数据分析库	DataFrame NL 操作、可视化生成	临时分析、Notebook 场景	SQL + 本地数据	缺少权限体系
Vanna	20.9k	NL2SQL 组件库	Agentic Retrieval、轻量可嵌入	Chatbot/后端嵌入	灵活易集成	无语义层
Chat2DB	18.3k	AI 数据库客户端	SQL Copilot、自然语言问答	数据分析人员	本地安全、可视化强	工具型为主
DB-GPT	12.7k	数据智能框架	GBI、AWEL、多 Agent	企业数据平台	功能全面	学习曲线高
Wren AI	12.3k	生成式 BI 平台	Semantic-First 架构、Text-to-Chart	企业级 BI	语义层强	生态新
Dataherald	3.6k	NL2SQL 引擎	RAG + Fine-tuned Agent	生产环境 NL2SQL	生产就绪	商业版限制

三、基于 LangChain 1.0 的 NL2SQL 数据分析 Agent 实现

完整项目代码添加小助理免费领取，还有更多Agent、数据分析课程，等你来学

NL2SQL 数据分析系统的核心价值是可以让用户用自然语言查询和分析数据,而不需要学习SQL语法，即时返回查询结果、可视化图表和数据分析报告。

我们将使用LangChain 1.0的ReAct Agent架构,结合FastAPI后端和React前端,构建一个完整的智能SQL问答系统。该系统支持自然语言查询数据库表和CSV文件,并自动生成数据分析报告和可视化图表。

项目架构设计

本项目使用典型的三层架构设计:前端展示层、后端API层、业务逻辑层。

复制代码

        ┌─────────────────────────────────────────────────────────────────┐
        │                    前端 (React + TypeScript)                    │
        │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │
        │  │ 数据源面板    │  │ 智能问答区    │  │ 结果展示面板  │           │
        │  └──────────────┘  └──────────────┘  └──────────────┘           │
        └────────────────────────┬────────────────────────────────────────┘
                                 │ HTTP/REST API (Axios)
        ┌────────────────────────▼────────────────────────────────────────┐
        │                    后端 (FastAPI + Python)                      │
        │  ┌──────────────┐  ┌──────────────┐  ┌──────────────┐           │
        │  │ /upload      │  │ /query       │  │ /datasources │           │
        │  └──────────────┘  └──────────────┘  └──────────────┘           │
        └────────────────────────┬────────────────────────────────────────┘
                                 │
        ┌────────────────────────▼────────────────────────────────────────┐
        │               业务逻辑层 (LangChain SQL Agent)                   │
        │  ┌──────────────────────────────────────────────────────────┐   │
        │  │  LLM (GPT-4)  +  SQL Tools  +  ReAct Agent               │   │
        │  └──────────────────────────────────────────────────────────┘   │
        └────────────────────────┬────────────────────────────────────────┘
                                 │
        ┌────────────────────────▼────────────────────────────────────────┐
        │              数据存储层 (SQLite / CSV→SQLite)                    │
        └─────────────────────────────────────────────────────────────────┘

项目架构技术点

技术点	说明
`ReAct Agent`	思考-行动-观察循环,自动选择合适的工具
`SQLDatabaseToolkit`	LangChain的SQL工具包,提供4个核心工具
`CSV转SQLite`	将CSV文件动态转换为临时数据库
`FastAPI流式响应`	实时返回查询结果和分析报告
`自动可视化`	基于数据类型智能选择图表类型

技术栈

层级	技术选型	版本	核心作用
前端	React + TypeScript	18.3 + 5.2	用户交互界面
前端	TailwindCSS + Radix UI	3.4	现代化UI组件
前端	Recharts	2.15+	数据可视化
后端	FastAPI	0.115+	高性能异步API
后端	LangChain	1.0.3+	AI Agent框架
后端	SQLAlchemy + Pandas	2.0.30+	数据处理
数据	SQLite	-	轻量级数据库

项目实现

核心 Agen 实现

系统的核心是SQLAgentManager类,它封装了LangChain的SQL Agent逻辑。其核心设计思路是基于 ReAct (Reasoning + Acting) 架构:

Thought (思考): 分析用户问题,决定下一步操作
Action (行动): 调用工具(如查看表结构、执行SQL)
Observation (观察): 获取工具返回的结果
循环: 重复上述过程,直到得到最终答案

核心代码位置：

对于上传.CSV / .Excel 文件，需要进行动态转换为临时SQLite数据库，并创建SQLAgentManager对象。其转换过程为：CSV文件上传 → Pandas读取 → 清理列名 → 写入SQLite → 创建Agent → 执行查询，核心的关键点在于：

技术栈

问题	解决方案	原因
中文列名	保留原样,SQLite支持	用户友好
特殊字符列名	转为下划线	SQL标识符规范
UUID表名	预先清理连字符	避免表名不一致
临时数据库	使用内存或临时文件	提高性能

基于以上 Agent 实现即可做到

用户问题: "销售额最高的前5个产品"

json 复制代码

    Thought: 我需要查看数据库中有哪些表
    Action: sql_db_list_tables
    Action Input: ""
    Observation: sales_data

    Thought: 现在我需要查看 sales_data 表的结构
    Action: sql_db_schema
    Action Input: sales_data
    Observation: CREATE TABLE sales_data (电子产品名 TEXT, 价格_元_ REAL, 销量_件_ INTEGER, ...)

    Thought: 我需要计算销售额(价格×销量)并排序
    Action: sql_db_query
    Action Input: SELECT 电子产品名, 价格_元_, 销量_件_, 
                (价格_元_ * 销量_件_) as 销售额 
                FROM sales_data 
                ORDER BY 销售额 DESC 
                LIMIT 5
    Observation: [查询结果...]

    Thought: 我现在知道最终答案了
    Final Answer: [Markdown格式的分析报告]

Agent API 接口服务

有了核心的SQLAgentManager,我们需要用FastAPI封装成Web API,供前端调用。

核心代码如下：

技术栈

端点	方法	功能	请求参数
`/health`	GET	健康检查	-
`/datasources`	GET	获取数据源列表	-
`/upload`	POST	上传CSV文件	file (文件)
`/query`	POST	智能查询(核心)	query, file_id/table_name
`/files/{file_id}`	DELETE	删除文件	file_id (路径参数)

项目使用

添加小助理免费领取完整项目代码，按照以下步骤运行项目：

配置环境变量 (.env 文件)

复制代码

 OPENAI_API_KEY=sk-your-api-key
 OPENAI_BASE_URL=https://api.openai.com/v1
 DEFAULT_MODEL=gpt-4o-mini

启动后端服务

bash 复制代码

    # 1. 进入后端目录
    cd backend

    # 2. 创建并激活虚拟环境
    python -m venv venv
    source venv/bin/activate  # Linux/Mac
    # 或
    venv\Scripts\activate     # Windows

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

   

    # 4. 启动服务
    python api_with_db.py

启动前端服务

bash 复制代码

    # 1. 进入前端目录
    cd frontend

    # 2. 安装依赖
    npm install
  

    # 3. 启动开发服务器
    npm run dev

启动成功后，即可通过http://localhost:3000访问应用。