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与向量存储的实现类

javascript 复制代码

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

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

ruby 复制代码

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密钥与模型名

makefile 复制代码

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

4. 创建Vanna实例

arduino 复制代码

vn = MyVanna(config=config)

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

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

ini 复制代码

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 业务文档训练，补充订单相关的业务定义

ini 复制代码

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

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

ini 复制代码

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：

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

项目地址

github.com/vanna-ai/va...