Vanna-ai - 让自然语言对话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的使用流程分为两个步骤：
- 在你的数据上训练一个RAG模型
- 提出问题，系统会返回可配置为在你的数据库上运行的SQL语句
Vanna选择RAG而非传统LLM微调作为核心技术路径，原因如下：
部署与使用 - 从环境搭建到Text2SQL查询落地
Vanna的部署与使用门槛较低，基于Python生态，支持快速上手，核心流程分为环境准备 - 初始化配置 - 模型训练 - 查询交互四步，同时支持自定义扩展。
- 环境准备
通过PyPI安装Vanna核心包，命令如下：
pip install vanna
根据选择的LLM、向量数据库、目标数据库安装对应依赖。 - 初始化配置
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.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与关键业务文档，后续通过“自学习”逐步补充，避免一次性导入过多冗余数据影响检索精度。
- 查询与结果交互
训练完成后，即可通过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
