Vanna：基于 RAG 的自然语言对话 SQL 数据库框架

项目概述 - Text-to-SQL 领域的开源 RAG 框架

Vanna 是一款基于 MIT 许可证的开源 Python 检索增强生成（RAG，Retrieval-Augmented Generation）框架，主要用于 SQL 生成及相关功能开发。核心定位是通过 RAG 与 LLM 实现高精度的 Text-to-SQL，最终让用户以自然语言与任意 SQL 数据库交互，无需手动编写 SQL 语句。

跨组件兼容性，支持 LLM + 向量数据库 + SQL 数据库的组合。

• 支持的大模型包括：OpenAI、Anthropic、Gemini、HuggingFace、AWS Bedrock、Ollama、Qianwen、Qianfan、Zhipu。
• 支持的向量存储包括：AzureSearch、Opensearch、PgVector、PineCone、ChromaDB、FAISS、Marqo、Milvus、Qdrant、Weaviate、Oracle。
• 支持的数据库包括：PostgreSQL、MySQL、PrestoDB、Apache Hive、ClickHouse、Snowflake、Oracle、Microsoft SQL Server、BigQuery、SQLite、DuckDB。
• 安全性与隐私保护。作为企业级工具的核心诉求，Vanna 确保数据库内容永不外传——训练阶段仅将表结构、业务文档、历史 SQL 转化为向量存储，不涉及原始数据；SQL 执行过程在用户本地环境完成，避免数据泄露风险。
• 自学习能力：通过反馈 - 迭代机制持续提升精度。如在 Jupyter Notebook 中可开启'自动训练'，将成功执行的 SQL 查询自动纳入训练数据；在 Web、Slack 等前端界面中，系统会主动提示用户反馈结果准确性；正确的问题 - SQL 对将被存储，为后续查询提供参考，实现'用得越多，精度越高'。
• 多前端适配性：支持从开发到落地的全流程前端需求。开发阶段可通过 Jupyter Notebook 快速调试；落地阶段可扩展为 Streamlit Web 应用、Flask 服务、Slack 机器人，或自定义前端，满足不同用户群体的交互习惯。

核心架构 - '训练 - 查询'双阶段驱动的技术链路

Vanna 的架构设计围绕 RAG 赋能 Text-to-SQL 展开，核心分为模型训练'与查询交互两大阶段，各阶段由 LLM 层、向量存储层、数据库连接层、前端层四大组件协同支撑，形成低耦合、高可扩展的技术架构。

Vanna 的使用流程分为两个步骤：

1. 在你的数据上训练一个 RAG 模型
2. 提出问题，系统会返回可配置为在你的数据库上运行的 SQL 语句

Vanna 选择 RAG 而非传统 LLM 微调作为核心技术路径，原因如下：

部署与使用 - 从环境搭建到 Text2SQL 查询落地

Vanna 的部署与使用门槛较低，基于 Python 生态，支持快速上手，核心流程分为环境准备 - 初始化配置 - 模型训练 - 查询交互四步，同时支持自定义扩展。

1. 环境准备 通过 PyPI 安装 Vanna 核心包，命令如下：

   pip install vanna
   

   根据选择的 LLM、向量数据库、目标数据库安装对应依赖。

2. 初始化配置 Vanna 的初始化需指定 LLM 实现与向量存储实现，通过继承对应类构建自定义 Vanna 实例。以 OpenAI GPT + ChromaDB 为例，核心代码如下。

   1. 导入对应 LLM 与向量存储的实现类

   from vanna.openai.openai_chat import OpenAI_Chat
   from vanna.chromadb.chromadb_vector import ChromaDB_VectorStore
   

   2. 自定义 Vanna 类，继承两个实现类

   class MyVanna(ChromaDB_VectorStore, OpenAI_Chat):
       def __init__(self, config=None):
           # 初始化向量存储（ChromaDB）
           ChromaDB_VectorStore.__init__(self, config=config)
           # 初始化 LLM（OpenAI）
           OpenAI_Chat.__init__(self, config=config)
   

   3. 配置参数，传入 OpenAI API 密钥与模型名

   config = {
       "api_key": "sk-你的 OpenAI API 密钥",  # 替换为实际密钥
       "model": "gpt-4",  # 可选 gpt-3.5-turbo、gpt-4-turbo 等
       "chroma_db_path": "./vanna_chromadb"  # ChromaDB 本地存储路径
   }
   

   4. 创建 Vanna 实例

   vn = MyVanna(config=config)
   

3. 模型训练 初始化完成后，需根据企业数据环境补充训练数据，核心训练命令如下：

   3.1 DDL 训练，导入数据库表结构，以电商场景的 order 表为例：

   vn.train(ddl=""" CREATE TABLE IF NOT EXISTS orders (
       order_id INT PRIMARY KEY,
       customer_id INT,
       order_date DATE,
       amount DECIMAL(10,2),
       status VARCHAR(20), -- 'paid'/'unpaid'/'cancelled'
       FOREIGN KEY (customer_id) REFERENCES customer(id)
   )""")
   

   3.2 业务文档训练，补充订单相关的业务定义

   vn.train(documentation="""
   4. 有效订单：status 为'paid'且未取消的订单，order_date 不为 NULL；
   5. 客单价：有效订单的 amount 平均值，按 customer_id 分组计算；
   6. 月度 GMV：当月所有有效订单的 amount 总和，不含退款金额。
   """)
   

   3.3 历史 SQL 训练，导入数据团队已有的 GMV 查询 SQL：

   vn.train(sql=""" SELECT DATE_TRUNC('month', order_date) AS month, SUM(amount) AS monthly_gmv FROM orders WHERE status = 'paid' GROUP BY month ORDER BY month DESC """)
   

   训练无固定次数要求，建议初期导入核心表的 DDL 与关键业务文档，后续通过'自学习'逐步补充，避免一次性导入过多冗余数据影响检索精度。

4. 查询与结果交互 训练完成后，即可通过 vn.ask() 方法实现自然语言查询，示例如下：

   result = vn.ask("2025 年第一季度各月 GMV 是多少")
   

   系统会先返回生成的 SQL：

   SELECT DATE_TRUNC('month', order_date) AS month, SUM(amount) AS monthly_gmv FROM orders WHERE status='paid' AND order_date BETWEEN '2025-01-01' AND '2025-03-31' GROUP BY month ORDER BY month
   

项目地址

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