vanna-ai/vanna · 上手攻略

仓库：vanna-ai/vanna
链接：https://github.com/vanna-ai/vanna
分类：ai
作者：Tom
更新：2026-08-18

是什么

Vanna 是一个基于检索增强生成（RAG）的 Text-to-SQL 开源框架，帮助开发者用自然语言查询 SQL 数据库。v2.0 是完全重写版本（与 v0.x 不兼容），核心定位从「RAG + LLM 生成 SQL」升级为「面向企业的用户感知型数据分析 Agent 平台」——每个组件都知道当前操作用户是谁，并自动做行级别权限过滤。

核心能力： - 自然语言 → SQL → 可视化：用户提问 → LLM 推理出 SQL → 流式返回表格、Plotly 图表、自然语言摘要 - 多 LLM 支持：OpenAI、Anthropic（Claude）、Ollama、Azure、Google Gemini、AWS Bedrock、Mistral 等 - 多数据库支持：PostgreSQL、MySQL、Snowflake、BigQuery、Redshift、SQLite、Oracle、SQL Server、DuckDB、ClickHouse 等 - 企业级安全：行级安全（RLS）、审计日志、按用户限流、用户感知型工具权限体系 - 开箱即用 UI：自带 <vanna-chat> Web 组件，支持 React/Vue/纯 HTML 嵌入

Stars：约 23,820（2026-08）。

解决什么问题

传统 Text-to-SQL 的痛点： 1. Schema 盲区：LLM 不知道数据库结构，生成的 SQL 经常字段/表名错误 2. 权限黑箱：SaaS 多租户场景下，无法按用户过滤数据行 3. 部署复杂：需要自己搭 RAG pipeline、Embedding 服务、UI 前端 4. 企业级功能缺失：审计日志、限流、合规一个没有

Vanna v2 通过预置 RAG（DDL + 文本文档注入）+ Agent 架构 + 用户感知中间件，一站式解决以上问题。

快速安装

Python 包（推荐）

pip install vanna

⚠️ 注意：v2.0 API 与 v0.x 不兼容。若项目使用 v0.x，请参考 Migration Guide，或使用 LegacyVannaAdapter 做兼容包装。

可选：Anthropic LLM 支持

pip install anthropic

开发服务器（FastAPI）

# server.py
from fastapi import FastAPI
from vanna import Agent
from vanna.servers.fastapi.routes import register_chat_routes
from vanna.servers.base import ChatHandler
from vanna.core.user import UserResolver, User, RequestContext
from vanna.integrations.anthropic import AnthropicLlmService
from vanna.tools import RunSqlTool
from vanna.integrations.sqlite import SqliteRunner
from vanna.core.registry import ToolRegistry

app = FastAPI()

class MyUserResolver(UserResolver):
    async def resolve_user(self, request_context: RequestContext) -> User:
        token = request_context.get_header('Authorization')
        user_data = self.decode_jwt(token)
        return User(
            id=user_data['id'],
            email=user_data['email'],
            group_memberships=user_data['groups']
        )

llm = AnthropicLlmService(model="claude-sonnet-4-20250514")  # ⚠️ 版本号以官方最新为准
tools = ToolRegistry()
tools.register(RunSqlTool(sql_runner=SqliteRunner("./data.db")))

agent = Agent(
    llm_service=llm,
    tool_registry=tools,
    user_resolver=MyUserResolver()
)

chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler)

uvicorn server:app --reload

前端嵌入（无需构建）

<script src="https://img.vanna.ai/vanna-components.js"></script>
<vanna-chat
  sse-endpoint="https://your-api.com/api/vanna/v2/chat_sse"
  theme="dark">
</vanna-chat>

快速上手（Colab，30 秒）

直接打开官方 Notebooks：

# 打开这个 Colab
# https://colab.research.google.com/github/vanna-ai/vanna/blob/main/notebooks/quickstart.ipynb

使用内置的 Chinook 示例数据库（音乐商店），直接尝试： - "What are the top 5 selling albums?" - "Show me total sales by country" - "Which artists have the most tracks?"

核心用法

1. 基础 RAG Text-to-SQL（v0.x 兼容 / v2 遗留模式）

import vanna as vn
from vanna.local import LocalContext_OpenAI

vn.set_api_key("sk-...")  # OpenAI API Key
vn.set_llm_provider("openai_chat")
vn.train(ddl="""CREATE TABLE orders (
    id INTEGER PRIMARY KEY,
    customer_id INTEGER,
    amount DECIMAL(10,2),
    created_at TIMESTAMP
)""")
question = "What are the top 10 orders by amount?"
sql = vn.ask(question)
print(sql)

⚠️ 这是 v0.x 方式，v2 已移除 vn.ask() 等旧 API。

2. v2 Agent 模式（推荐新项目）

from vanna.core.tool import Tool, ToolContext, ToolResult
from pydantic import BaseModel, Field
from typing import Type

# 自定义工具示例：发送邮件
class EmailArgs(BaseModel):
    recipient: str = Field(description="Email recipient")
    subject: str = Field(description="Email subject")

class EmailTool(Tool[EmailArgs]):
    @property
    def name(self) -> str:
        return "send_email"

    @property
    def access_groups(self) -> list[str]:
        return ["send_email"]  # 仅 send_email 组可调用

    def get_args_schema(self) -> Type[EmailArgs]:
        return EmailArgs

    async def execute(self, context: ToolContext, args: EmailArgs) -> ToolResult:
        user = context.user  # 自动注入当前用户
        await self.email_service.send(from_email=user.email, to=args.recipient, subject=args.subject)
        return ToolResult(success=True, result_for_llm=f"Email sent to {args.recipient}")

tools.register(EmailTool())

3. 流式 SSE 前端交互

# 后端自动暴露：
# POST /api/vanna/v2/chat_sse  ← 流式端点
# GET  /                      ← 可选 Web UI

4. 用户感知行级安全

# 用户 alice（groups=["read_sales"]）发起请求
# → Agent 工具自动加 WHERE team_id IN ('sales') 过滤
# → 普通用户无法跨权限查看数据

典型适用场景

数据分析平台：面向业务人员的自然语言 BI 工具，无需写 SQL
多租户 SaaS：每个租户/用户只能看到自己有权限的数据行
企业内部数据门户：集成到现有 Web 应用，提供 Chat 界面
AI Agent 工具调用：作为 Agent 的 SQL 执行工具，支持权限控制
快速 POC：Colab 30 秒跑通 Text-to-SQL demo

坑与注意

坑	说明	应对
v0.x ≠ v2.0 API	v2 完全重写，`vn.ask()`、`vn.train()` 等旧 API 在 v2 不可用	使用 `LegacyVannaAdapter` 兼容包装旧项目，或走 v2 Agent API 重写
LLM 幻觉 SQL	即使有 RAG，复杂查询仍可能生成错误 JOIN 或聚合	生产环境务必在应用层做 SQL 审计 / 只读用户限制
向量数据库依赖	默认用 Chroma（本地），高并发需配置独立向量服务	评估阶段直接用默认，规模化后换 PGvector 或 OpenSearch
权限粒度	行级安全依赖 `group_memberships`，需提前设计用户组体系	接入前梳理好组织架构与数据权限矩阵
Streaming SSE	`<vanna-chat>` 组件依赖 SSE，`/chat_sse` 路径不能带 Base Path 反代	使用 Nginx 反代时注意路径重写
版本号标注	README 示例中 `claude-sonnet-4-20250514` 为占位	实际使用前在 Anthropic 模型页面核实最新模型名

与同类对比

特性	Vanna v2	Chat2DB	SQLChat	Dataherald
LLM 支持	任意（OpenAI/Anthropic/Ollama 等）	OpenAI only	OpenAI only	OpenAI + Claude
多数据库	20+	20+	5+	5+
RAG 架构	内置（DDL + 文档）	需手动配置	内置	内置
用户感知 RLS	✅ 原生	❌	❌	❌
自带 Web UI	✅（`<vanna-chat>` 组件）	✅	❌	❌
企业安全（审计/限流）	✅	❌	❌	部分
v2 Agent 架构	✅	❌	❌	❌
开源协议	MIT	Apache 2.0	闭源 SaaS	Apache 2.0
Stars	~23,800	~11,000	N/A	~3,600

Vanna v2 的差异化优势在于用户感知型 Agent和开箱即用 Web 组件，尤其适合多租户 SaaS 和需要权限管控的企业场景。

一句话推荐结论

若你需要快速把「自然语言查询 SQL」产品化，且有企业级权限管控需求，Vanna v2 是目前 Stars 最高、生态最完整的开源选择；若只需简单 Chat2DB 对话，Dataherald 更轻量。

来源： - GitHub README：https://github.com/vanna-ai/vanna - 官方文档：https://vanna.ai/docs - 快速上手 Colab：https://colab.research.google.com/github/vanna-ai/vanna/blob/main/notebooks/quickstart.ipynb - Migration Guide：https://github.com/vanna-ai/vanna/blob/main/MIGRATION_GUIDE.md

⚠️ 数字核验：Stars 数（~23,820）采自 GitHub 页面 2026-08；模型版本号（claude-sonnet-4-20250514）为占位符，请以 Anthropic 官方模型列表实时核实。