04LangChain SQL 问答系统知识点详解

LangChain SQL 问答系统知识点详解

本文档整理自 LangChain 中文网教程：

• 构建一个基于 SQL 数据的问答系统

本文面向初学者，只聚焦知识点和实现思路，不展开环境安装、API Key、Notebook 配置等准备内容。

一、SQL 问答系统是什么

1. 是什么

SQL 问答系统就是让用户用自然语言提问，系统自动查询 SQL 数据库，并返回自然语言答案。

例如用户问：

一共有多少员工？

系统内部会变成：

SELECT COUNT(*) FROM Employee;

然后执行 SQL，拿到结果，再回答：

一共有 8 名员工。

2. 解决什么问题

很多业务数据都存储在关系型数据库中，比如 MySQL、PostgreSQL、SQLite。普通用户不一定会写 SQL，但他们知道自己想问什么。

SQL 问答系统解决的是：

用户不会 SQL，但想查询数据库里的结构化数据

3. 为什么重要

企业内部很多数据都不是文档，而是表格数据：

• 用户表。
• 部门表。
• 合同表。
• 订单表。
• 发票表。
• 审批流表。

如果能让大模型把自然语言转换成 SQL，就可以让非技术人员直接查询数据库。

二、结构化数据和非结构化数据的区别

1. 是什么

非结构化数据通常是文档、网页、PDF、文本段落。RAG 常用向量检索来查这些内容。

结构化数据通常是数据库表，有明确的列、类型、主键、外键和表关系。

2. 解决什么问题

不同数据类型需要不同查询方式：

文档问答：通常先做向量检索，再让模型总结
SQL 问答：通常先生成 SQL，再执行数据库查询

3. 为什么不能都用向量检索

如果问题是：

哪个国家的客户消费最多？

这不是找一段相似文本，而是要计算：

GROUP BY country
SUM(total)
ORDER BY total DESC

这种统计、过滤、排序、连接表的任务更适合 SQL。

三、SQL 问答系统的基本架构

1. 是什么

教程把 SQL 问答系统拆成三步：

自然语言问题 -> SQL 查询 -> SQL 执行结果 -> 自然语言答案

更具体地说：

1. 将问题转换为 SQL
2. 执行 SQL
3. 根据 SQL 结果回答问题

2. 解决什么问题

把问题拆成三个步骤后，每一步职责清楚：

• LLM 负责理解问题并生成 SQL。
• 数据库负责执行 SQL。
• LLM 再负责把数据库结果组织成人话。

3. 为什么要分步骤

如果直接让模型回答，模型可能会编造数据库数据。把 SQL 执行结果放进流程后，答案会基于真实数据库返回值。

四、安全注意

1. 是什么

SQL 问答系统会执行模型生成的 SQL，这天然有风险。

2. 解决什么问题

模型可能生成错误 SQL，甚至生成危险 SQL，例如：

DELETE FROM users;
DROP TABLE contract;
UPDATE department SET name = 'test';

3. 为什么重要

数据库是真实业务资产。让模型自动执行 SQL 时，必须限制权限。

4. 初学者要记住的原则

实际项目里建议：

• 使用只读数据库账号。
• 限制只能访问必要表。
• 禁止 DML 和 DDL，例如 INSERT、UPDATE、DELETE、DROP。
• 对 SQL 做检查。
• 关键场景加人工审批。
• 不要把生产库直接暴露给模型实验。

五、SQLDatabase

1. 是什么

SQLDatabase 是 LangChain 对 SQL 数据库的统一封装。

示例：

from langchain_community.utilities import SQLDatabase

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

2. 解决什么问题

不同数据库连接方式不同。SQLDatabase 把数据库连接、表结构读取、SQL 执行等能力统一封装起来。

3. 为什么需要它

LangChain 的 SQL 链和 SQL Agent 需要知道：

• 数据库是什么方言。
• 有哪些表。
• 表结构是什么。
• 如何执行 SQL。

SQLDatabase 就是把这些信息提供给 LangChain 的入口。

4. 常用方法

print(db.dialect)
print(db.get_usable_table_names())
db.run("SELECT * FROM Artist LIMIT 10;")

含义：

• db.dialect：数据库方言，例如 SQLite、MySQL。
• db.get_usable_table_names()：当前可用表名。
• db.run(sql)：执行 SQL 并返回结果。

六、数据库方言 dialect

1. 是什么

数据库方言指不同数据库的 SQL 语法差异。

例如：

• SQLite。
• MySQL。
• PostgreSQL。
• SQL Server。

2. 解决什么问题

同一个查询在不同数据库中写法可能不同。模型生成 SQL 时必须知道当前数据库方言。

3. 为什么重要

教程中提到 create_sql_query_chain 的提示词会根据数据库方言调整。例如 SQLite 会提醒使用 SQLite 语法。

如果数据库是 MySQL，却按 SQLite 写 SQL，可能会执行失败。

七、表结构信息 table_info

1. 是什么

表结构信息包括：

• 表名。
• 字段名。
• 字段类型。
• 主键。
• 外键。
• 示例数据。

2. 解决什么问题

模型不知道你的数据库里有哪些表和字段。必须把表结构放进提示词，模型才知道该查什么。

3. 为什么要包含示例行

教程指出，给模型看每张表的若干示例行可以提高效果。

因为模型不仅能看到字段名，还能看到字段值长什么样。例如：

Artist 表的 Name 字段里有 AC/DC、Alice In Chains

这能帮助模型理解字段含义。

八、链 Chain

1. 是什么

链是 LangChain 中多个 Runnable 组件的组合。SQL QA 中的链适合步骤固定的场景。

2. 解决什么问题

有些 SQL 问答流程是固定的：

问题 -> 生成 SQL -> 执行 SQL -> 回答

用链可以清晰地把这些步骤串起来。

3. 为什么适合简单问答

如果每个问题都可以用一次 SQL 查询解决，链就很合适。

例如：

一共有多少员工？
哪个部门用户最多？
合同类型有多少个？

九、create_sql_query_chain

1. 是什么

create_sql_query_chain 是 LangChain 内置的 SQL 生成链。

from langchain.chains import create_sql_query_chain

chain = create_sql_query_chain(llm, db)
response = chain.invoke({"question": "How many employees are there"})

2. 解决什么问题

它把用户的自然语言问题转换成 SQL 查询语句。

例如：

How many employees are there?

可能生成：

SELECT COUNT("EmployeeId") AS "TotalEmployees" FROM "Employee" LIMIT 1;

3. 为什么它能生成 SQL

它会把这些信息放进提示词：

• 数据库方言。
• 可用表结构。
• 每张表的示例行。
• 用户问题。
• SQL 输出格式要求。

模型根据这些信息生成 SQL。

4. 初学者理解

create_sql_query_chain = 自然语言转 SQL 的自动提示词链

注意：它只生成 SQL，不执行 SQL。

十、检查 SQL 生成链的 Prompt

1. 是什么

可以用下面代码查看 SQL 生成链内部提示词：

chain.get_prompts()[0].pretty_print()

2. 解决什么问题

初学者经常不知道模型为什么能生成 SQL。看 Prompt 可以理解 LangChain 在背后给模型提供了哪些信息。

3. 为什么重要

教程中展示的 Prompt 主要包含：

• 你是某种数据库专家。
• 根据问题生成正确 SQL。
• 默认最多返回 5 条。
• 不要查询所有列。
• 只使用给出的表。
• 输出格式是 Question / SQLQuery / SQLResult / Answer。
• 表结构会填入 {table_info}。
• 用户问题会填入 {input}。

看懂这个 Prompt 后，就能理解 SQL 链的底层逻辑。

十一、执行 SQL 查询

1. 是什么

生成 SQL 后，需要执行它：

db.run(response)

或者使用 LangChain 工具：

from langchain_community.tools.sql_database.tool import QuerySQLDataBaseTool

execute_query = QuerySQLDataBaseTool(db=db)

2. 解决什么问题

create_sql_query_chain 只会写 SQL。如果不执行 SQL，就拿不到真实数据库结果。

3. 为什么这是危险步骤

执行 SQL 是真正访问数据库。模型生成的 SQL 可能错误或危险。

所以这一步必须重视权限和校验。

十二、QuerySQLDatabaseTool

1. 是什么

QuerySQLDatabaseTool 是 LangChain 提供的 SQL 执行工具。

execute_query = QuerySQLDataBaseTool(db=db)

2. 解决什么问题

它把"执行 SQL"包装成 Runnable/Tool，方便和链或 Agent 组合。

3. 为什么不用直接 db.run

直接 db.run(sql) 可以执行 SQL，但不容易和 LCEL 链组合。

QuerySQLDatabaseTool 可以这样串起来：

write_query = create_sql_query_chain(llm, db)
chain = write_query | execute_query

含义：

问题 -> 生成 SQL -> 执行 SQL -> 返回数据库结果

十三、用 LCEL 串起 SQL 执行链

1. 是什么

LCEL 的 | 可以把 SQL 生成链和 SQL 执行工具串起来。

write_query = create_sql_query_chain(llm, db)
chain = write_query | execute_query
result = chain.invoke({"question": "How many employees are there"})

2. 解决什么问题

不用手动写：

sql = write_query.invoke(...)
result = execute_query.invoke(sql)

而是把流程声明成一条链。

3. 为什么好用

它让数据流非常清楚：

用户问题 -> SQL 生成器 -> SQL 执行器 -> 数据库结果

十四、回答问题 Answer Prompt

1. 是什么

执行 SQL 后，数据库返回的通常是原始结果，例如：

[(8,)]

用户不一定能看懂，所以需要再让模型把它组织成自然语言。

教程使用：

answer_prompt = PromptTemplate.from_template(
    """Given the following user question, corresponding SQL query, and SQL result, answer the user question.

Question: {question}
SQL Query: {query}
SQL Result: {result}
Answer: """
)

2. 解决什么问题

把数据库原始结果变成人类友好的回答。

3. 为什么要同时给模型 question、query、result

模型需要知道：

• 用户原始问题是什么。
• SQL 查询是什么。
• SQL 执行结果是什么。

这样才能正确解释结果。

十五、RunnablePassthrough.assign

1. 是什么

RunnablePassthrough.assign 可以保留原始输入，并新增字段。

教程中：

chain = (
    RunnablePassthrough.assign(query=write_query).assign(
        result=itemgetter("query") | execute_query
    )
    | answer_prompt
    | llm
    | StrOutputParser()
)

2. 解决什么问题

最终回答阶段需要三个字段：

question
query
result

原始输入里只有：

{"question": "..."}

assign 可以一步步往字典里加字段。

3. 数据流解释

第一次 assign 后：

{
    "question": "How many employees are there",
    "query": "SELECT COUNT(...) ..."
}

第二次 assign 后：

{
    "question": "How many employees are there",
    "query": "SELECT COUNT(...) ...",
    "result": "[(8,)]"
}

然后把这三个字段填进 Prompt，再交给模型回答。

十六、itemgetter

1. 是什么

itemgetter("query") 用来从字典中取出 query 字段。

from operator import itemgetter

itemgetter("query") | execute_query

2. 解决什么问题

执行 SQL 时只需要 SQL 字符串，不需要整个输入字典。

所以要先从中间结果里取出 query。

3. 为什么在链里常见

LCEL 经常处理字典数据。itemgetter 是从字典中抽取某个字段的常用方法。

十七、StrOutputParser

1. 是什么

StrOutputParser 把模型返回的消息对象转成普通字符串。

2. 解决什么问题

模型返回的通常不是纯字符串，而是消息对象。用户最终需要看到的是文本答案。

3. 为什么放在链最后

因为前面模型已经生成自然语言回答，最后只需要提取文本内容。

完整流程：

question -> query -> result -> prompt -> llm -> string answer

十八、固定 SQL 链的局限

1. 是什么

固定链适合步骤稳定的问题，但不适合所有场景。

2. 解决什么问题

它能解决简单、直接、一次查询的问题。

3. 为什么有局限

教程指出：

• 它可能对任何输入都执行 SQL，即使用户只是说"你好"。
• 有些问题需要多次查询才能回答。
• 有些问题需要先检查有哪些表。
• 有些查询第一次可能写错，需要根据错误重试。

这些场景更适合 Agent。

十九、SQL Agent

1. 是什么

SQL Agent 是一个可以使用数据库工具的智能代理。

它不是固定执行一条链，而是可以循环：

思考 -> 调用工具 -> 观察结果 -> 再思考 -> 再调用工具 -> 最终回答

2. 解决什么问题

SQL Agent 适合更复杂的数据库问答：

• 不确定该查哪张表。
• 需要先查看表名。
• 需要查看表结构。
• SQL 执行报错后需要修正。
• 需要多次查询才能回答。
• 需要描述某张表。

3. 为什么比链更灵活

固定链的执行路径是写死的。

Agent 的执行路径由模型动态决定。

链：问题 -> SQL -> 执行 -> 回答
Agent：问题 -> 判断下一步 -> 调工具 -> 观察 -> 继续判断 -> 回答

二十、SQLDatabaseToolkit

1. 是什么

SQLDatabaseToolkit 可以根据数据库和模型创建一组 SQL 工具。

from langchain_community.agent_toolkits import SQLDatabaseToolkit

toolkit = SQLDatabaseToolkit(db=db, llm=llm)
tools = toolkit.get_tools()

2. 解决什么问题

Agent 不能直接操作数据库，它需要工具。Toolkit 会自动生成常用工具。

3. 常见工具

通常包括：

• sql_db_query：执行 SQL。
• sql_db_schema：查看表结构和示例行。
• sql_db_list_tables：列出可用表。
• sql_db_query_checker：检查 SQL 是否有常见错误。

4. 为什么要用 Toolkit

不用自己一个个手写工具，LangChain 已经帮你封装好了 SQL Agent 常用能力。

二十一、SystemMessage 系统提示

1. 是什么

系统提示是给 Agent 的行为规则。

from langchain_core.messages import SystemMessage

system_message = SystemMessage(content=SQL_PREFIX)

2. 解决什么问题

Agent 有了工具后，需要知道怎么安全、合理地使用工具。

系统提示可以规定：

• 不要查所有列。
• 默认限制查询结果数量。
• 执行前必须检查 SQL。
• 出错后要重写 SQL。
• 禁止 DML。
• 一开始先查看表。
• 再查看相关表结构。

3. 为什么重要

Agent 的自由度比链高，所以更需要规则约束。

二十二、create_react_agent

1. 是什么

create_react_agent 是 LangGraph 提供的预构建 ReAct Agent。

from langgraph.prebuilt import create_react_agent

agent_executor = create_react_agent(llm, tools, prompt=system_message)

2. 解决什么问题

它帮你创建一个可以调用工具、观察结果、继续推理的 Agent。

3. 为什么叫 ReAct

ReAct 可以理解为：

Reasoning + Acting
推理 + 行动

模型不只是一次性回答，而是可以边思考边调用工具。

4. 版本注意

教程中旧写法可能是：

create_react_agent(llm, tools, messages_modifier=system_message)

较新的 LangGraph 版本可能使用：

create_react_agent(llm, tools, prompt=system_message)

如果运行时报参数错误，要以当前安装版本为准。

二十三、Agent 的 stream

1. 是什么

agent_executor.stream(...) 可以流式输出 Agent 的每一步。

for s in agent_executor.stream(
    {"messages": [HumanMessage(content="Which country's customers spent the most?")]}
):
    print(s)
    print("----")

2. 解决什么问题

Agent 不是一步完成的。流式输出可以看到中间过程：

• 模型决定调用哪个工具。
• 工具返回什么结果。
• 模型是否修正 SQL。
• 最终答案是什么。

3. 为什么适合学习和调试

如果 Agent 答错了，流式输出能帮你看到错在哪里：

• 是选错表？
• 是字段名错？
• 是 SQL 写错？
• 是工具结果理解错？

二十四、Agent 自动纠错

1. 是什么

SQL Agent 可以在 SQL 执行报错后，根据错误信息重新尝试。

教程中的例子里，模型一开始用了错误表名 customers 和 invoices，数据库报错后，Agent 查看表名，发现正确表名是 Customer 和 Invoice，然后重写 SQL。

2. 解决什么问题

模型可能猜错表名或字段名。Agent 可以通过工具查询真实数据库结构并修正。

3. 为什么链不容易做到

固定链通常执行一次就结束，错误恢复能力弱。

Agent 可以循环多次：

执行 SQL -> 报错 -> 查表名 -> 重写 SQL -> 再执行

二十五、描述表结构类问题

1. 是什么

用户不一定只问统计问题，也可能问：

Describe the PlaylistTrack table

这类问题不是要算一个数，而是要解释表结构。

2. 解决什么问题

SQL Agent 可以调用 sql_db_schema 查看表结构和示例行，然后用自然语言总结。

3. 为什么 Agent 更适合

固定 SQL 链通常倾向于生成查询语句。Agent 可以判断这个问题更适合调用 schema 工具，而不是写统计 SQL。

二十六、高基数列

1. 是什么

高基数列是指不同取值很多的字段。

例如：

• 艺术家名称。
• 专辑标题。
• 用户姓名。
• 客户名称。
• 地址。
• 合同名称。

2. 解决什么问题

用户输入专有名词时，经常会拼错、缩写或大小写不一致。

例如：

alis in chain

数据库里的真实值可能是：

Alice In Chains

如果直接写：

WHERE Name = 'alis in chain'

就查不到结果。

3. 为什么需要特殊处理

SQL 的等值匹配很严格。用户输入和数据库真实值不完全一致时，查询就会失败。

二十七、query_as_list

1. 是什么

query_as_list 是教程中用来提取某列所有唯一值的辅助函数。

import ast
import re

def query_as_list(db, query):
    res = db.run(query)
    res = [el for sub in ast.literal_eval(res) for el in sub if el]
    res = [re.sub(r"\b\d+\b", "", string).strip() for string in res]
    return list(set(res))

2. 解决什么问题

把数据库查询结果整理成普通字符串列表。

例如：

artists = query_as_list(db, "SELECT Name FROM Artist")
albums = query_as_list(db, "SELECT Title FROM Album")

3. 每一步为什么这样写

db.run(query) 返回字符串形式的查询结果。

ast.literal_eval(res) 把字符串形式的列表/元组解析成 Python 对象。

列表推导式把多行结果拍平成单个列表。

re.sub(r"\b\d+\b", "", string).strip() 清理独立数字和空格。

set(res) 去重。

4. 初学者理解

query_as_list = 从数据库某一列里提取候选专有名词列表

二十八、FAISS 向量存储

1. 是什么

FAISS 是一个向量检索库，可以把文本转成向量并做相似度搜索。

教程中：

from langchain_community.vectorstores import FAISS
from langchain_openai import OpenAIEmbeddings

vector_db = FAISS.from_texts(artists + albums, OpenAIEmbeddings())

2. 解决什么问题

用户输入的专有名词可能不准确。向量检索可以按语义或相似度找最接近的数据库真实值。

3. 为什么不用 SQL LIKE

LIKE 可以做简单模糊匹配，但对拼写错误、缩写、近似表达不够智能。

向量检索更适合：

Alice Chains -> Alice In Chains

二十九、Retriever 检索器

1. 是什么

把 FAISS 向量库转成检索器：

retriever = vector_db.as_retriever(search_kwargs={"k": 5})

2. 解决什么问题

输入近似名称，返回最相似的几个候选值。

3. 为什么设置 k

k=5 表示返回前 5 个最相似结果。

这样 Agent 可以从候选中选择最合适的真实值。

三十、create_retriever_tool

1. 是什么

create_retriever_tool 可以把检索器包装成 Agent 工具。

from langchain.agents.agent_toolkits import create_retriever_tool

retriever_tool = create_retriever_tool(
    retriever,
    name="search_proper_nouns",
    description=description,
)

2. 解决什么问题

Agent 只能调用工具。检索器本身不是 SQL Agent 的默认工具，需要包装成工具后交给 Agent。

3. 为什么工具描述很重要

Agent 会根据工具名称和描述判断是否使用它。

教程给它的职责是：

输入专有名词的近似拼写，输出有效的专有名词

三十一、search_proper_nouns 工具

1. 是什么

search_proper_nouns 是自定义检索器工具，用来查找专有名词的正确写法。

示例：

print(retriever_tool.invoke("Alice Chains"))

可能返回：

Alice In Chains
Alanis Morissette
Pearl Jam
Audioslave

2. 解决什么问题

在 SQL 查询前，先把用户输入的模糊名称映射到数据库真实名称。

3. 为什么必须先查再过滤

如果直接用用户输入过滤：

WHERE Name = 'alis in chain'

可能查不到。

先用工具找到：

Alice In Chains

再写：

WHERE Name = 'Alice In Chains'

结果就更可靠。

三十二、把检索器工具加入 SQL Agent

1. 是什么

把原来的 SQL 工具和新的专有名词检索工具组合：

tools.append(retriever_tool)
agent = create_react_agent(llm, tools, prompt=system_message)

2. 解决什么问题

原本 Agent 只能查数据库。加入检索工具后，它可以先纠正专有名词，再查询数据库。

3. 为什么要改系统提示词

只把工具加入列表还不够。还要在系统提示里明确告诉 Agent：

如果你需要对专有名词进行过滤，必须先使用 search_proper_nouns 工具。
不要猜测正确名称。

否则 Agent 可能不会主动使用这个工具。

三十三、完整 SQL QA 学习路径

这篇教程的学习顺序可以这样理解：

SQLDatabase
  -> create_sql_query_chain
  -> db.run / QuerySQLDatabaseTool
  -> LCEL SQL 链
  -> Answer Prompt
  -> SQL Agent
  -> SQLDatabaseToolkit
  -> Agent stream
  -> 高基数列处理
  -> Retriever Tool
  -> 更强的 SQL Agent

三十四、链 vs Agent

对比项	SQL 链	SQL Agent
执行路径	固定	动态
是否能多次查询	通常不行	可以
是否能查表结构	取决于链设计	可以主动调用工具
错误恢复	较弱	较强
可控性	更强	更灵活但更难控
适合场景	简单、稳定、单次查询	复杂、多步、不确定表结构

三十五、常见问题

1. SQL 链生成 SQL 后为什么还要执行

因为生成 SQL 只是写出查询语句，不代表拿到了数据库结果。必须执行 SQL 才能得到真实答案。

2. 为什么执行 SQL 前要检查

模型可能写错表名、字段名、连接条件或聚合逻辑。检查可以减少执行错误。

3. 为什么 SQL Agent 一开始要看表名

因为模型不应该猜数据库结构。先看表名可以知道有哪些表可用。

4. 为什么要看表结构

表结构告诉模型字段名、字段类型、主键外键和示例数据。没有表结构，SQL 很容易写错。

5. 为什么不查询所有列

查询所有列会浪费 token、暴露不必要数据，也可能影响性能。应该只查回答问题需要的列。

6. 为什么高基数列要用向量检索

因为用户输入专有名词时容易拼错，向量检索可以帮模型找到数据库里的正确值。

7. 为什么 Agent 有时比链慢

Agent 可能要多次调用工具，比如查表、查 schema、检查 SQL、执行 SQL，所以步骤更多。

8. SQL Agent 是否一定比 SQL 链好

不是。简单问题用链更直接、更可控；复杂问题用 Agent 更灵活。

三十六、核心心智模型

1. SQL QA 不是让模型凭记忆回答

模型负责生成 SQL 和解释结果，真实数据来自数据库。

2. SQL 链是固定流水线

问题 -> SQL -> 执行 -> 回答

3. SQL Agent 是动态工具调用

问题 -> 判断 -> 工具 -> 观察 -> 再判断 -> 最终回答

4. 表结构是模型写 SQL 的地图

没有表名和字段名，模型只能猜。

5. 高基数列需要先找标准值

用户输入的名称不一定等于数据库真实值，先检索再过滤更稳。

三十七、一句话总结

这篇教程教的是：

如何让大模型把自然语言问题变成 SQL，执行 SQL，再基于真实数据库结果回答用户。

它有两条实现路线：

SQL 链：适合固定、简单、可预测流程
SQL Agent：适合复杂、多步、需要查表结构和纠错的流程

再加上高基数列检索后，Agent 就能更好地处理用户输入不精确的专有名词。