RAG2SQL实战：用Vanna AI把自然语言变成数据库查询，告别裸写SQL

不靠谱的糖饼·2026-09-03·阅读 21 GEO检测（免费）

RAG2SQL自然语言转SQLText2SQL

|难度：普通|阅读约 36 分钟

告别裸写SQL：我用Vanna AI把“查数据库”这件事变成了一句大白话，RAG2SQL到底强在哪

先交代一下背景：我平时做数据平台相关的工作，团队里一半是业务运营，一半是开发。运营同事想拉个“上周各渠道的注册转化率对比”，正常流程是提工单、排期、等开发写SQL、再等结果，一来一回半天就没了。他们自己也试过学SQL，但查得越多，条件越复杂——多表关联、时间窗口、去重口径、排除异常单——Joins还没搞明白就先放弃了。后来我接触到Vanna AI这个开源项目，思路是把“自然语言转SQL”这件事彻底换了个玩法，不靠硬编码规则，而是借助RAG（检索增强生成）让模型“现学现卖”你的数据库结构。这几个月我用它搭了一套内部查询工具，业务同学直接在聊天框里问“上个月华东区TOP10客户的复购率是多少”，几秒钟就能拿到SQL和结果。这篇就把我的完整实践过程、架构理解、踩过的坑一次说清。

如果你正在做数据分析工具、想给业务团队一个低门槛取数入口，或者纯粹对RAG和Text2SQL的结合感兴趣，这篇文章应该能帮你省掉不少试错时间。

1. 为什么“自然语言转SQL”这个概念喊了几年，直到RAG2SQL才算真落地

早些年Text2SQL并不是什么新词。你随便搜都能找到一堆论文和Demo，输入“查询所有用户的订单金额”，模型吐出来一段SQL，看着挺像回事。但一放到真实业务场景里，基本就崩了。

1.1 传统Text2SQL最大的坑：模型根本不认识你的库

问题出在哪？大模型训练时见过的是通用SQL语法，但你的数据库表结构是私有的。举个具体例子，你问“本月新用户的首单转化率”，模型需要知道：

用户表叫t_user_info还是users，还是member_profile
“新用户”的定义是注册时间在当月，还是首次下单时间在当月
“首单”对应哪张订单表，靠什么字段关联
佣金订单、测试订单、退款订单要不要排除，口径怎么定

这些信息，模型在训练阶段压根没见过。传统做法是把表结构（DDL）一股脑拼进Prompt里，告诉模型“这是你的数据库，请根据它写SQL”。刚开始数据表少还行，表一多就出问题：Prompt放不下，模型被大量无关字段干扰，生成出来的SQL经常捏造不存在的列名，或者选错关联条件。我见过最离谱的一次，模型把user_id写成了userID，还说“因为习惯性驼峰命名”——它完全是在靠猜。

1.2 RAG解决的核心问题：把“通用大模型”变成“懂你数据库的专家”

RAG的思路其实不复杂：不把整个数据库结构一股脑塞给模型，而是把建表语句、业务说明、参考SQL这些都切碎，存进一个向量数据库。每次收到自然语言问题，先做一次语义检索，从知识库里捞最相关的几段信息，再连同问题一起扔给大模型生成SQL。

这个机制解决了两件事：

上下文长度限制：数据库有几百张表也没关系，每次检索只取和当前问题最相关的几段，Prompt不会超长。
语义对齐：你问“转化率”，检索系统知识库里找到的是业务方写的说明文档——“转化率 = 下单用户数 / 注册用户数，下单用户以订单表首单时间为准”。模型基于这段说明去写SQL，自然就符合业务口径。

Vanna AI把这个流程封装得非常彻底。它不是把RAG当作一个辅助模块，而是把RAG这条链路作为整个系统的核心骨架。项目名字也很直白：Vanna = Vector + Anna，向量检索加上生成能力，就是它的全部。

1.3 为什么说这个思路比“微调模型”更聪明

有人可能会想：与其用RAG，不如直接把我的DDL和SQL拿去微调一个私有模型？这个问题我确实深入想过，结论是：在多数场景下，RAG的性价比远高于微调。

微调的本质是修改模型参数，让模型“记住”你的业务规则。但数据库结构是会变的：加一个字段、改一个表名、调整一个业务口径，在微调模式下意味着要重新训练模型，成本极高。而RAG模式下的知识库是可插拔的：表结构变了，更新知识库里的文档就行，完全不用碰模型。Vanna AI甚至提供了train()接口，你可以随时追加新的训练数据，对应地，它的内部实现会在向量库里多存几段内容，整个过程秒级完成，不需要任何GPU资源。

微调还有另一个问题：它是黑盒。你不知道模型到底记住了什么、记错了什么。而RAG模式下，每次生成SQL你都能看到检索到了哪些文档、模型参考了什么上下文，整个生成链路完全可追溯。做数据这块的人都知道，可解释性在业务侧有多重要——至少出了问题你知道锅在哪。

需要模型API调用？免费领10W Token，多模型网关一键接入 Claude、DeepSeek 等主流模型。

2. Vanna AI的核心架构拆解：一条完整的“检索-生成-执行”流水线

Vanna AI的设计非常精巧。它把传统的Text2SQL流程拆成了几个可以独立替换的模块，每个模块都遵循一个统一的抽象接口。我自己在源码层面跟过一遍，这里把它的内部工作方式梳理清楚，对你理解它的行为边界和排查问题非常有帮助。

2.1 两大阶段：训练（学习）与查询（生成）

Vanna AI的运行分两个阶段，理解这两个阶段是关键。

训练阶段，你要把三类信息喂给它：

DDL（建表语句）：让系统知道数据库里有哪些表、每张表有哪些字段、字段类型是什么、主外键怎么关联。
业务注释文档：补充DDL之外的信息，比如“用户等级分为L1-L5，L5为最高等级”“订单状态包含待支付、已支付、已取消三种”。
参考SQL：历史沉淀下来的、经过验证的正确SQL，以及它对应的自然语言问题。这是最宝贵的训练数据。

查询阶段，当用户输入一个自然语言问题时，Vanna AI会走一遍完整的RAG链路：

把用户问题和知识库里的文档片段做向量相似度检索，找出最相关的若干条，作为生成SQL时的参考上下文。
把“参考上下文 + 用户问题”拼成Prompt，发送给配置好的LLM。
拿到模型生成的SQL后，Vanna AI还会做一次自检：尝试在数据库里执行这段SQL，如果报错，把错误信息反馈给模型让它修正，最多重试好几次。
最终把正确的SQL和查询结果一起返回给用户，同时在界面上展示SQL原文和对应的DataFrame。

这个“自执行自纠错”的环节是Vanna AI的一个亮点，也是它比裸调大模型靠谱的重要原因——它把SQL从“看着对”推进到“跑得通”。

2.2 模型、向量库、数据库：三个可替换的组件

Vanna AI的架构抽象层次做得很好，核心组件之间解耦得很干净：

组件	作用	我用的方案	其他可选方案
LLM	负责理解问题并生成SQL	OpenAI GPT-4o	Ollama本地模型、Anthropic Claude、通义千问等
向量存储	存放训练文档并支持语义检索	ChromaDB（本地文件型，零部署成本）	Qdrant、Pinecone、Milvus
数据库	执行SQL并返回结果	MySQL 8.0	PostgreSQL、SQLite、ClickHouse等

这套解耦设计带来的好处非常实际：如果你的公司不允许把业务数据传到外部API，你可以把LLM换成本地部署的Ollama，数据不出内网；如果查询量大了，向量库可以从ChromaDB平滑迁移到Milvus这类专业服务。所有组件都遵循同一个抽象接口，替换成本很低。

2.3 为什么要做一个官方的Web界面

Vanna AI自带一个基于Flask和React的Web UI，跑起来之后长得很像一个简化的ChatGPT界面，左侧是对话历史，右侧是聊天窗口，每条消息下面会展示SQL文本和查询结果表格。最开始我甚至觉得这个UI有点多余，毕竟我主要是想把它接入自己内部的数据平台。

但实际用下来才发现，这个界面在业务推广阶段是刚需。业务同事对命令行和API完全没有概念，但你给他一个聊天框，他天然就会用。Vanna AI的Web UI还支持一个很实用的特性：允许用户对某条查询结果给反馈，这些反馈可以作为后续训练数据。这在冷启动阶段格外重要——业务方信任你的工具，前提是他能看得到你的整个工作过程。

3. 从零搭建一套“自然语言查库”服务：完整实操步骤与避坑记录

如果你看完了上面的原理，已经按捺不住想动手试试，这部分直接可以照抄。我会把完整流程走一遍，包括环境准备、最小实现、训练模型、启动Web UI，以及我实际遇到过的三个坑。

3.1 环境准备：版本和依赖，先避一批明显的坑

我的环境是Python 3.10，系统是Ubuntu 22.04。数据库是一台MySQL 8.0实例。安装Vanna AI本身非常简单：

bash复制pip install vanna
pip install vanna[mysql]  # 如果要连MySQL
pip install vanna[chromadb]  # 默认的向量库方案

这里有个容易踩的坑：Vanna AI在安装时依赖较多，如果你的环境里有旧版本的pydantic或者openai库，很可能会起冲突，表现通常是导入vanna时直接报ImportError。建议新建一个干净的虚拟环境，不要图省事往全局环境里装。

bash复制python -m venv vanna-env
source vanna-env/bin/activate
pip install --upgrade pip
pip install vanna[mysql,chromadb]

如果你用的数据库是SQLite，Vanna官方甚至内置了一个vanna[sqlite]选项，不需要额外起数据库服务，拿来练手非常方便。

3.2 最小实现：十行代码把Vanna跑起来

下面这段代码是Vanna AI最核心的用法。你需要有一个OpenAI API Key，也可以换成任何兼容OpenAI接口的服务。我最初用的是官方OpenAI，因为它的SQL生成能力目前还是最强的，后面会讲本地模型的替代方案。

python复制from vanna.openai.openai_chat import OpenAI_Chat
from vanna.chromadb.chroma_vector import Chroma_VectorStore
from vanna.mysql.mysql import MySQL_Database

class MyVanna(Chroma_VectorStore, OpenAI_Chat, MySQL_Database):
    def __init__(self, config):
        Chroma_VectorStore.__init__(self, config)
        OpenAI_Chat.__init__(self, config)
        MySQL_Database.__init__(self, config)

vn = MyVanna(config={
    "api_key": "YOUR_OPENAI_API_KEY",
    "model": "gpt-4o",
    "host": "127.0.0.1",
    "port": 3306,
    "database": "your_db",
    "user": "your_user",
    "password": "your_password",
})

核心逻辑在MyVanna这个多重继承类上。它把三类能力拼在一起：向量存储负责知识检索，LLM负责生成SQL，数据库连接负责执行查询。你甚至可以根据需要自由组合，比如不用MySQL用PostgreSQL，只需要把最后一个父类换成PostgreSQL_Database。

接下来是训练环节。先自动提取所有表的DDL：

python复制# 把库里所有表的结构存进知识库
df_ddl = vn.run_sql("SELECT table_name FROM information_schema.tables WHERE table_schema = 'your_db'")
for table_name in df_ddl['table_name'].tolist():
    ddl = vn.run_sql(f"SHOW CREATE TABLE `{table_name}`").iloc[0, 1]
    vn.train(ddl=ddl)

然后手动补充训练信息。Vanna官网推荐用这三类：

python复制# 1. 术语映射，告诉模型业务黑话和数据库字段的关系
vn.train(term="新用户", definition="注册时间为当月的用户，见 users.registered_at")

# 2. 问题-SQL对，给模型做参考范例
vn.train(
    question="按月统计每月的注册用户数",
    sql="SELECT DATE_FORMAT(registered_at, '%Y-%m') AS month, COUNT(*) FROM users GROUP BY month",
)

# 3. 业务逻辑说明
vn.train(documentation="订单金额 = 订单明细中商品单价 * 数量之和，不含运费和优惠券分摊")

训练完成后，就可以直接问了：

python复制response = vn.ask("上个月每天的新增用户数是多少？")

返回结果是一个字典，包含question、sql、df、plotly_code等信息。注意它可能会顺带生成一段用Plotly画图表的代码——因为Vanna AI默认连图表展示都替你想好了。

3.3 让我差点放弃的坑：为什么本地模型生成的SQL经常是“正确但愚蠢”的

我在前期测试时想省API费用，把LLM换成了本地Ollama跑的Llama 3 8B。结果发现，它生成的SQL语法完全正确，但逻辑上却非常“轴”——它不理解业务上的隐含条件。

举个例子，我让它查“已支付订单”，它生成的SQL是WHERE status = 'paid'，这没问题。但当我问“本月有效订单”，它也会生成WHERE status = 'valid'，而实际上业务上“有效订单”的定义是“状态为已支付且金额大于0且非测试订单”，这个条件在库表里根本没有valid这个值。它只是看到问题里有“有效”，就机械地把“有效”翻译成了SQL里的一个幻想的字段名。

问题出在哪？本地模型的语义理解能力和指令遵循能力确实比GPT-4这类商业模型弱不少。8B模型生成的SQL虽然语法正确，但业务规则的吸收和复用能力明显不行。而且它经常忽略我训练时提供的那段“有效订单定义”文档。

后来我做了几件事才把这个情况拉回来：

把训练文档拆分得更细。用vn.train(documentation=...)标记一条规则，不要在一个documentation字段里塞多句话。因为检索是按语义片段来的，一个太长的片段反而不容易被准确命中。
对每个常用业务口径，都配上至少3条问题-SQL对。模型可以从范例中学会“这个问题对应这种写法”。
换更强的模型。如果你要上生产，建议至少用一个顶级的商业模型API，本地小模型拿来搞PoC可以，生产会累死你。

3.4 启动Web UI：给业务同事一个他们能用的入口

命令行验证没问题后，我用Web UI把能力开放给了团队：

python复制from vanna.flask import VannaFlaskApp

app = VannaFlaskApp(vn, allow_llm_to_see_data=True)
app.run(host="0.0.0.0", port=8080, debug=False)

allow_llm_to_see_data=True这个参数很关键：开启后，执行完SQL会把查询结果也发给LLM，让它能根据真实结果做进一步的判断和修正，比如“这个数字看起来不对，可能是口径有问题”。当然，如果你们的数据敏感级别很高，不希望任何数据离开内网，这个参数一定要显式设为False。

启动之后，浏览器打开http://localhost:8080，就能看到聊天界面。业务同事在里面直接用中文提问就行，Vanna AI会自动做中文到SQL的翻译，因为我们底层LLM用的是GPT-4o，中文理解完全没问题。

4. 训练数据的“黄金配比”：为什么有人用了效果惊艳，有人用了效果拉胯

用Vanna AI的过程中，我最大的感悟是：这个工具的效果上限，不取决于模型，而是取决于知识库的质量。同样的LLM、同样的数据库，一个经过精心训练的知识库和一个随便导入的DDL，效果差距是断崖式的。

4.1 三类训练数据，缺一不可

我在2.1里提过Vanna需要三类训练数据。这里展开讲讲它们各自的作用和准备要点。

DDL建表语句是基础。Vanna官网的默认做法是直接从information_schema读取所有表的建表语句，一键训练。但这里有个隐患：如果库里有几百张表，全量导入DDL会产生很多噪音。比如一张历史的归档表，10年都没人查过，但它有50个字段，这些字段会干扰检索的精确度。

我的做法是：只导入核心业务表的DDL，通过查information_schema过滤掉不需要的表。一个小技巧是，如果你在表名或字段名上用了统一的命名规范（例如所有订单表都叫t_order_xxx），可以让Vanna先检索候选表，再决定是否导入。但这是进阶玩法，前期不建议折腾。

文档注释是把业务语义教给模型的关键。这一块质量和数量并重，核心是定义“口径”。什么是口径？就是业务侧的一句话，决定了SQL里WHERE和GROUP BY怎么写了。举几个我实际训练过的例子：

python复制vn.train(documentation="复购用户 = 在所选时间周期内，有过两次及以上成功支付订单的用户")
vn.train(documentation="GMV = 成功支付订单的金额总和，不含退款订单")
vn.train(documentation="新增用户 = 注册时间为所选时间范围内的用户，若用户既在范围内注册又在范围内下单，既算新增又算活跃")

这些规则看起来只是几行文字，但对生成SQL的影响是决定性的。我测试过同一个问题“每个月复购率变化”，在没有文档训练时，模型生成的SQL五花八门，有的甚至把“复购用户”理解成“关注了公众号的用户”。在加上那段文档之后，SQL里就会正确出现COUNT(DISTINCT CASE WHEN order_count >= 2 THEN user_id END)这种结构。

问题-SQL对是质量最高的训练数据，因为它直接示范了“用户的问题句式”到“正确SQL”的映射关系。Vanna官网建议每个知识域准备3-5对以上。我有一个很朴素的经验：从业务方真实问过的问题里收集。运营同事提过的问题，就是最优的训练素材，因为这些问题最贴近真实使用场景。

我准备了一个Excel表，让运营同事把日常需要查的数据用自然语言写下来，然后我逐条补上对应的SQL，统一用vn.train(question=..., sql=...)导入。这样训练出来的系统，比我自己臆想的问题高出一个数量级。

4.2 如何判断训练数据的质量：检索能不能命中

判断知识库质量有一个非常直观的方法：直接看Vanna在生成SQL时检索到了哪些文档。

python复制# 手动测试检索结果
from vanna.retriever import Retriever
retriever = Retriever(vn)
results = retriever.retrieve_documents("上个月的GMV环比变化", top_k=5)
for i, doc in enumerate(results):
    print(f"--- 检索结果 {i+1} ---")
    print(doc['document'])

如果你发现检索出来的文档和问题南辕北辙——比如问GMV却检索出一堆用户表的DDL——说明知识库的语义切分或向量索引有问题。这种情况通常是因为文档里有太多无关信息，或者术语表述和业务方习惯不一致。你需要调整训练数据，让文档内容和真实问法更贴近。

4.3 一个被我反复验证的经验：先小样本试跑，再全量铺开

刚开始我一股脑训练了50多张表的DDL、100多条业务规则和80对问题-SQL，结果模型的生成效果反而变差了。原因很可能是知识库里相似内容太多，互相干扰了检索结果。

后来我切成了按业务域拆分知识库的模式：核心交易域一个向量集合，用户画像域一个集合，内容运营域一个集合。每个域只训练和该域相关的表和SQL。这样查询命中率明显上升。

另外，Vanna AI内部有vn.remove_training_data()的方法，你可以随时删除某条错误训练数据，或者直接用vn.forget_the_last_thing()忘记最近的一条。不断迭代训练数据，比换模型更有效。

5. 生成SQL的可靠性：自纠错机制、复杂查询的边界与实用建议

当你真正把Vanna AI放到生产环境，会发现它有一个循环机制在持续提高查询准确率，同时也有很明显的边界，提前知道这些能让你少挨不少骂。

5.1 自纠错机制：一次次的“提交-反馈-重试”

Vanna AI内置的generate_sql方法并非一次成型，而是带着“验证-纠错”的循环。大致流程是：

LLM根据检索到的上下文生成候选SQL。
直接在配置的数据库连接上执行这条SQL。
如果SQL报错，Vanna会把错误信息（比如Unknown column 'regist_time'）拼进Prompt，请LLM根据错误修正。
修正后再执行，循环往复，直到成功或达到最大重试次数。

这个设计的意义在于：SQL这门语言非常严格，一个反引号、一个标点错了都执行不了。有自动纠错兜底，即使模型生成的SQL第一次有语法问题，也可能在第二轮自动修复。

不过需要注意，自纠错只能处理“能跑起来但不满足语义”的问题，无法处理“跑起来了但结果不对”的问题。比如LLM把“上月”理解成“最近30天”，SQL能执行，结果也对不上。这种语义偏差，只有靠更好的训练数据来根治。

5.2 什么时候它会非常吃力：别指望它处理所有查询

实事求是地讲，Vanna AI不是万能的。我总结了它最不擅长的几类问题：

需要多轮业务推理的。比如“找出那些在A渠道注册、但在B渠道完成首单的用户，分析他们的特征”。这需要模型对业务背景有整体理解，单靠检索几段文档很难做好。
依赖隐含知识或默认行为的。比如“要显示TOP10用户，但用户数不足10时全显示”。这类情况模型不会自动想到，需要你在训练数据里明确标注这种边界条件。
复杂的分层聚合或窗口函数。比如跨多级维度的CUBE汇总、基于事件间隔的漏斗分析。模型能生成这类SQL，但极难保证效率，生成出来可能会是一段逻辑相同但性能很差的写法。

所以我的建议是：Vanna AI最适合处理的场景是80%的日常数据查询需求——指标看板、趋势分析、简单的多表关联、按维度切分汇总。这类需求占据业务方查询的大部分，恰好是之前最消耗开发精力的部分。至于那些特别复杂的深度分析，它做不了，也不应该让它硬做。

5.3 权限与安全：必须从第一天就想清楚的问题

最后强调一个最容易出事的点：权限。Vanna AI执行SQL用的是你配置的那个数据库账号，如果你给的是一个高权限账号，那么任何能访问Web UI的人，理论上都能查到库里所有数据。这显然不行。

我在内测阶段就碰到过一次：一个运营同学在聊天框里问“所有员工的薪资明细”，Vanna AI真的就把整张工资表拉了出来。虽然她马上意识到不对且立刻询问，但也给我敲响了警钟。

建议的做法是：单独为Vanna AI创建一个只读账号，只授予查询所需表的SELECT权限，最好再限制只能访问特定库。MySQL里可以这样：

sql复制CREATE USER 'vanna_readonly'@'%' IDENTIFIED BY 'strong_password';
GRANT SELECT ON your_db.* TO 'vanna_readonly'@'%';
FLUSH PRIVILEGES;

更进一步，如果你的数据库字段级权限要求很细，比如某些敏感列不能开放给业务查询，那需要在数据访问层做一层视图，只暴露允许查询的列。Vanna AI执行的SQL仍然可能尝试查询原始表，但数据库权限会直接拒绝。这样Vanna的自纠错会一直失败，最终返回一条错误信息，但至少数据不会被泄露。

5.4 我踩过的最后一个坑：LLM返回结果里的“虚构代码”

Vanna AI的ask方法不但返回SQL和分析结果，有时还会返回一段plotly_code，目的是直接画出可视化图表。但我发现，这段图表代码有时候会引用一些不存在的变量，或者与执行结果不匹配——尤其是当数据库返回的列名是中文时，生成代码很容易出错。

所以，如果只是想把原始查询结果展示给业务，最简单的方案是直接渲染df，不要依赖plotly_code。只有当你确认模型的图表生成能力足够稳定时，才把可视化代码放给用户。

安全性上还有一个点：Vanna虽然执行了SQL，但它默认不会把业务数据直接作为上下文灌给LLM（除非你显式设置allow_llm_to_see_data=True）。这很重要，因为如果问“列出所有用户手机号”，Vanna执行完SQL后，除非你打开上述开关，否则它不会把手机号这些明细数据发送给OpenAI。我在文档里明确建议：生产环境务必保持这个开关为关闭状态，否则存在数据泄露风险。

最后分享一个我在实际使用中觉得很“值回票价”的小技巧

Vanna AI默认生成的SQL是从零生成的，即使知识库里已经有完全等价的、经过优化的历史SQL，它也会重新写一遍。但Vanna其实支持一个叫做“缓存”的机制——在启动代码里设定好：

python复制vn.config["cache"] = True

开启后，系统会把已经生成过且执行成功的“问题-SQL对”自动缓存。下次遇到一模一样的问题，直接返回缓存结果，不再调用LLM，速度和成本都有明显优化。

在实际运维知识库时，我会周期性地把近期成功的问题-SQL对再重新train一次。这样相当于把生产环境里跑通的高质量SQL沉淀进了知识库，让系统越用越“懂”业务。这比任何调参都有效。如果你已经跑到这一步，恭喜你，你现在手里的Vanna AI已经不只是一件工具，而是一套会随着业务积累不断生长的查询系统。