让智能体直接查询数据库:lca-lc-foundations 附赠 SQL 查询 Agent 完整教程

原创2026-11-01 14:13:451,870 阅读

让智能体直接查询数据库:lca-lc-foundations 附赠 SQL 查询 Agent 完整教程

在 lca-lc-foundations(LangChain Academy 官方基础课程仓库)的 Module 2 中,隐藏着一个实用的 SQL 查询 Agent 教程——bonus_sql.ipynb。它教你用不到 50 行代码,让大语言模型通过自然语言直接查询 SQLite 数据库,无需手写复杂的提示词工程。这篇完整教程带你从零搭建这个数据库查询智能体,掌握 LangChain 工具调用的核心模式。

为什么需要 SQL 查询 Agent? 🤔

传统方式下,用户要查询数据库必须会写 SQL。而通过 LangChain 的 工具调用(Tool Calling) 机制,你可以把 sql_query 函数注册为 Agent 的工具,Agent 会自动把用户的自然语言问题翻译成 SQL 语句,执行查询后把结果返回给用户。

这正是 lca-lc-foundations 附赠教程的核心思路:

用户提问 → Agent 生成 SQL → 执行查询 → 返回结果

整个流程由 LangChain 的 create_agent 函数自动编排,开发者只需定义"工具"和"模型"即可。

项目结构与环境配置

快速克隆与安装

如果你还没有这个仓库,可以通过以下命令获取:

git clone --depth 1 https://gitcode.com/gh_mirrors/lc/lca-lc-foundations
cd lca-lc-foundations

项目要求 Python >= 3.12, < 3.14,推荐使用 uv 管理依赖:

cp example.env .env   # 创建环境配置文件
uv sync              # 安装所有依赖
uv run env_utils.py  # 验证环境
uv run jupyter lab   # 启动 Jupyter

⚠️ 你需要在 .env 文件中配置 OPENAI_API_KEY,因为教程默认使用 gpt-5-nano 模型。模板文件为 example.env。

关键依赖说明

SQL 查询 Agent 用到两个核心库(已包含在 requirements.txt 中):

依赖包 作用
langchain-community 提供 SQLDatabase 数据库连接工具
langchain 提供 create_agent、@tool、HumanMessage 等核心 API

三步搭建 SQL 查询工具 🔧

整个 Agent 的构建只有 三步,对应 notebooks/module-2/bonus_sql.ipynb 中的前四个代码单元。

第一步:连接数据库

LangChain 通过 SQLDatabase 类来连接数据库。教程使用的是内置的 Chinook 示例数据库(一个经典的音乐商店 SQLite 数据库,包含歌手、专辑、歌曲、客户等表):

from langchain_community.utilities import SQLDatabase

db = SQLDatabase.from_uri("sqlite:///resources/Chinook.db")

这里用 from_uri 一行代码完成连接,支持 SQLite、PostgreSQL、MySQL 等多种数据库,只需替换连接字符串即可。

第二步:定义查询工具

用 @tool 装饰器把一个普通函数变成 Agent 可以调用的工具:

from langchain.tools import tool

@tool
def sql_query(query: str) -> str:
    """Obtain information from the database using SQL queries"""
    try:
        return db.run(query)
    except Exception as e:
        return f"Error: {e}"

这里有 两个关键细节:

  1. docstring 很重要——它是 Agent 理解"这个工具能做什么"的依据,写清楚"用什么、做什么"
  2. 异常捕获——数据库查询可能出错(语法错误、表不存在),捕获后返回错误信息让 Agent 有机会自我修正

第三步:创建 Agent

from langchain.agents import create_agent

agent = create_agent(
    model="gpt-5-nano",
    tools=[sql_query]
)

create_agent 是 LangChain 提供的高层 API,传入 模型名称 和 工具列表,Agent 就自动具备了"思考 → 调用工具 → 观察结果 → 回答"的完整循环能力。

用自然语言对话数据库 🗣️

搭建完成后,只需发送一条自然语言消息:

from langchain.messages import HumanMessage
from pprint import pprint

question = HumanMessage(
    content="Who is the most popular artist beginning with 'S' in this database?"
)

response = agent.invoke({"messages": [question]})
pprint(response["messages"])

Agent 收到问题后,会经历以下过程:

  1. 推理阶段:模型分析问题,决定调用 sql_query 工具
  2. SQL 生成:自动编写一条类似 SELECT ... FROM Artist WHERE Name LIKE 'S%' ORDER BY ... 的 SQL
  3. 执行查询:sql_query 工具执行 SQL,返回查询结果
  4. 总结回答:模型把查询结果整理成自然语言回复给用户

你可以在 notebooks/module-2/bonus_sql.ipynb 的最后一个代码单元中查看 Agent 实际生成的 SQL 语句:

print(response["messages"][-3].tool_calls[0]['args']['query'])

这会打印出 Agent 推理过程中生成的原始 SQL,帮助你理解它的"思考过程"。

从 SQLite 扩展到更多场景 🚀

SQLDatabase.from_uri 支持多种数据库,只需修改连接字符串:

数据库类型 连接示例
SQLite sqlite:///path/to/db.db
PostgreSQL postgresql://user:pass@host/dbname
MySQL mysql://user:pass@host/dbname
SQL Server mssql://user:pass@host/dbname

安全提示

在实际生产环境中,建议给工具函数加上 只读限制,防止 Agent 执行 DROP TABLE、DELETE 等危险操作。可以在 sql_query 函数内对 SQL 语句做关键词过滤,或让数据库账号只具备 SELECT 权限。

更多学习资源 📚

lca-lc-foundations 仓库包含三个递进模块,SQL 查询 Agent 位于 Module 2 的附赠课程中。以下是与本文相关的扩展学习路径:

模块 文件 学习重点
Module 1 - 工具基础 notebooks/module-1/1.2_tools.ipynb @tool 装饰器用法、工具调用原理
Module 2 - 多 Agent notebooks/module-2/2.4_wedding_planners.ipynb 多 Agent 协作,其中也使用了 Chinook 数据库
Module 2 - RAG notebooks/module-2/bonus_rag.ipynb 另一个附赠课程,用文档问答代替数据库查询
Module 3 - 动态工具 notebooks/module-3/3.4_dynamic_tools.ipynb 运行时动态加载 SQL 工具

项目完整说明与安装步骤见 README.md,环境验证脚本为 env_utils.py。

总结

bonus_sql.ipynb 用最简洁的方式展示了 LangChain 智能体与数据库交互 的完整模式:SQLDatabase 连接 → @tool 包装 → create_agent 组装 → 自然语言查询。掌握这个模式后,你可以快速将其迁移到 PostgreSQL、MySQL 等任意数据库,构建属于自己的"对话式数据分析"应用。

登录后查看全文
lca-lc-foundations