飞熊出品 · Vanna 调研：23K stars MIT Text-to-SQL 框架，2.0 让 AI Agent 真能查数据库

副标题 ：从 RAG Agentic Retrieval · 到任意 LLM + 任意数据库 · Text-to-SQL 事实标准
赛道 ：AI 原生 BI · 补足 316 WrenAI / 318 DB-GPT 之下的 ” 底层框架 ” 层
作者 ：yunying（增长运营官）
时间：2026-08-20

一、引子：316 / 318 没回答的那个问题

8/15 发的《WrenAI 调研》?p=316》和《DB-GPT 调研》?p=318》都是 平台层——给业务团队用的成品。

但如果客户问 ” 我们想 自己造 一个 ChatBI，用什么底层框架？” —— 316/318 答不上。

本文答：Vanna——MIT ✅ + 23K stars + 3 年沉淀 + 任意 LLM + 任意数据库，Text-to-SQL 事实标准。

二、它解决什么问题（30 秒版）

业务团队用数据库的 3 个老问题：

1. 业务方不会写 SQL——每次都要找数据团队
2. LLM 直接生成 SQL 不准——幻觉率高，复杂 Join 直接报错
3. 多轮对话状态丢失——第 2 轮就忘了第 1 轮的查询条件

Vanna = 解决这 3 个问题——RAG 训练（DDL + 文档 + 之前的 SQL）+ Agentic Retrieval + 多轮状态管理。

实时数据（2026-08-20 拉取）

关键判断 ：Vanna 是 Text-to-SQL 框架的 GitHub 最热门（23K stars 远超其他同类），但 ⚠️ 2026-02 后 6 个月没 push——介于 ” 主动维护 ” 和 ” 维护模式 ” 之间。 新项目可用，但要锁定 v2.0.x。

三、4 大核心特性

1. Agentic Retrieval（基于 RAG 的 SQL 生成）

# Vanna 训练：把 DDL / 文档 / 之前的 SQL 都进向量库
vn.train(ddl="""
CREATE TABLE customers (
    id INT PRIMARY KEY,
    region VARCHAR(10),
    signup_date DATE
);
""")

vn.train(documentation=" 订单表里的 is_repeat 标记是否复购 ")

vn.train(sql="SELECT region, COUNT(*) FROM customers GROUP BY region")

# 查询：自动从向量库检索 + LLM 生成
sql = vn.generate_sql(" 上个月华东区客户复购率 ")
vn.run_sql(sql)

核心创新：不像普通 Text-to-SQL 把 DDL 塞 prompt，Vanna 用 RAG Agentic Retrieval——基于相似度检索最相关的 DDL + 文档 + 历史 SQL，SQL 准确率比 Naive Prompt 高 30-50%。

2. Multi-Database（任意数据库）

Vanna 不绑死单一数据库，支持：

实战价值：客户用 Snowflake / 你用 Postgres / 同事用 BigQuery —— Vanna 一套代码搞定。

3. Multi-LLM（任意 LLM）

# 任意 LLM 都行
vn = VannaDefault(llm=OpenAI())         # OpenAI
vn = VannaDefault(llm=Anthropic())      # Claude
vn = VannaDefault(llm=Ollama(model="qwen2.5-coder:7b"))  # 本地
vn = VannaDefault(llm=HuggingFace())    # 开源 LLM

实战价值 ：用 GPT-4o 最准 / Claude 长文最强 / Ollama 本地省钱 —— 一个抽象切换。

4. Multi-Turn + Access Controlled（多轮 + 权限控制）

Vanna 2.0 新增的 SQL Agent 能力：
–
多轮对话——保留上下文（” 刚才那个查询按区域拆开 ”）
–
Access Control——基于 RBAC 限制查询的表 / 行 / 列
–
审计日志——所有 SQL 进审计 trail

四、对比 WrenAI / DB-GPT / Cube.js

选谁？

五、实战 3 步 · 35 分钟跑通 ”Vanna + Postgres + OpenAI”

Step 1 · Docker Compose 一键起（5 分钟）

version: '3.8'
services:
  postgres:
    image: postgres:16-alpine
    environment:
      POSTGRES_DB: ecom
      POSTGRES_USER: vanna
      POSTGRES_PASSWORD: ***
    ports:
      - "5432:5432"
    volumes:
      - ./init.sql:/docker-entrypoint-initdb.d/init.sql

  chromadb:
    image: chromadb/chroma:latest
    ports:
      - "8000:8000"
    volumes:
      - chroma-data:/chroma/.chroma

volumes:
  chroma-data:

Step 2 · 安装 Vanna + 训练 RAG（15 分钟）

pip install vanna[chromadb,openai]

# vanna_demo.py
from vanna.openai import OpenAI_Chat
from vanna.chromadb import ChromaDB_VectorStore

class MyVanna(ChromaDB_VectorStore, OpenAI_Chat):
    def __init__(self, config=None):
        ChromaDB_VectorStore.__init__(self, config=config)
        OpenAI_Chat.__init__(self, config=config)

vn = MyVanna(config={
    "api_key":": "sk-***",
    "model":": "gpt-4o",
    "chroma_db_path":": "./chroma"
})

# 连 Postgres
vn.connect_to_postgres(
    host="localhost",
    port=5432,
    dbname="ecom",
    user="vanna",
    password="***"
)

# 训练：DDL
vn.train(ddl="""
CREATE TABLE customers (
    id SERIAL PRIMARY KEY,
    region VARCHAR(10),
    signup_date DATE
);
CREATE TABLE orders (
    id SERIAL PRIMARY KEY,
    customer_id INT REFERENCES customers(id),
    amount DECIMAL(10,2),
    order_date DATE,
    is_repeat BOOLEAN
);
""")

# 训练：文档
vn.train(documentation=" 订单表里的 is_repeat=true 表示客户复购 ")

# 训练：示例 SQL（Few-shot）vn.train(sql="SELECT region, COUNT(*) FROM customers GROUP BY region")
vn.train(sql="SELECT AVG(amount) FROM orders WHERE is_repeat = true")

Step 3 · 自然语言查询 + 多轮（15 分钟）

# 第 1 轮：查复购率
sql1 = vn.generate_sql(" 上个月华东区客户复购率 ")
print(sql1)
# 输出: SELECT
#   COUNT(DISTINCT CASE WHEN o.is_repeat THEN o.customer_id END) /
#   COUNT(DISTINCT c.id) * 100 AS repeat_rate
# FROM customers c
# JOIN orders o ON c.id = o.customer_id
# WHERE c.region = '华东'
#   AND o.order_date >= DATE_TRUNC('month', CURRENT_DATE - INTERVAL '1 month')

df1 = vn.run_sql(sql1)
print(df1)
# 输出: repeat_rate
#        23.5

# 第 2 轮：多轮上下文（Vanna 2.0 自动保留）sql2 = vn.generate_sql(" 刚才那个查询按区域拆开 ")  # ← Vanna 知道 " 刚才 " 是哪个
df3 = vn.run_sql(sql2)

# 第 3 轮：可视化（Vanna 返回 Plotly）vn.ask(" 过去 6 个月每月 GMV 趋势图 ", visualize=True)

35 分钟跑通的成果：自然语言 → RAG 检索 → LLM 生成 SQL → 执行 → DataFrame + 图表。

六、风险与坑

七、总结

3 个最值得用的理由

1. MIT + 任意 LLM + 任意数据库——不被锁定，技术栈自由
2. 23K stars + 3 年沉淀——Text-to-SQL 框架 GitHub 最热门
3. RAG Agentic Retrieval——比 Naive Prompt SQL 准确率高 30-50%

1 句选型口诀

自己造 ChatBI → Vanna（MIT + 灵活）；业务团队用 → WrenAI / DB-GPT（平台）；嵌入式 BI → Cube.js（语义层）。

Vanna 是 Text-to-SQL 底层框架 ——316/318 是 成品平台 ，Cube.js 是 语义层引擎，三者定位完全不同。

飞熊 GenBI 完整赛道（补足后）

[底层框架]                  [语义层]                  [平台]                  [嵌入式]
Vanna (本篇)           Cube.js (375)            WrenAI (316)              React 组件
Text-to-SQL 库         Apache-2.0+MIT        GenBI 平台 AGPL-3.0        cubejs-client-react
MIT 任意 LLM/DB        任意查询 API           自然语言问数据               React 组件库
                                                                                │
                                                                                ▼
                                                                          AI Agent

参考

• Vanna 官网：vanna.ai
• GitHub 仓库：vanna-ai/vanna
• Vanna 2.0 Release Notes：GitHub Releases
• WrenAI 调研（316）：《WrenAI 调研》
• DB-GPT 调研（318）：《DB-GPT 调研》
• Cube.js 实战（375）：《Cube.js 实战》
• Apache Flink 调研（382）：《Apache Flink 调研》
• BI 栈全景图 v2 (338)：《2026 BI 栈全景图 v2》

📎 WordPress 链接

• 官方链接：《飞熊出品 · Vanna 调研：23K stars MIT Text-to-SQL 框架，2.0 让 AI Agent 真能查数据库》
• 短链：https://east196.cn/?p={WP_POST_ID}
• 状态：published · 2026-08-20