Vanna 2.0：将问题转化为数据洞察

自然语言 → SQL → 答案。 现在具备企业级安全性和用户感知权限。

https://github.com/user-attachments/assets/476cd421-d0b0-46af-8b29-0f40c73d6d83

2.0版本新增功能

🔐 每层用户感知 — 查询会根据用户权限自动过滤

🎨 现代化网页界面 — 精美的预建 <vanna-chat> 组件

⚡ 流式响应 — 实时表格、图表和进度更新

🔒 企业级安全 — 行级安全、审计日志、速率限制

🔄 生产就绪 — FastAPI 集成、可观测性、生命周期钩子

从0.x升级？ 请参阅 迁移指南 | 更新内容？

开始使用

使用示例数据尝试

快速开始

配置

配置

Web 组件

<!-- Drop into any existing webpage -->
<script src="https://img.vanna.ai/vanna-components.js"></script>
<vanna-chat
  sse-endpoint="https://your-api.com/chat"
  theme="dark">
</vanna-chat>

使用您现有的 cookies/JWT。适用于 React、Vue 或纯 HTML。

你将获得

以自然语言提问并获得回复：

1. 流式进度更新

2. SQL 代码块（默认仅显示给“管理员”用户）

3. 交互数据表

4. 图表（Plotly 可视化）

5. 自然语言总结

全部实时流式传输到你的网页组件。

为什么选择 Vanna 2.0？

✅ 即刻开始使用

• 生产级聊天界面
• 使用你的数据库自定义代理
• 嵌入到任何网页中

✅ 企业级安全

每一层都可识别用户 — 身份通过系统提示、工具执行和 SQL 过滤流动 行级安全 — 查询根据用户权限自动过滤 审计日志 — 每个查询按用户跟踪以确保合规 速率限制 — 通过生命周期钩子设置每用户配额

✅ 包含美观的网页界面

预构建 <vanna-chat> 组件 — 无需自己构建聊天界面 流式表格与图表 — 丰富组件，而不仅仅是文本 响应式与可定制 — 适用于移动端、桌面端，支持浅色/深色主题 框架无关 — 支持 React、Vue、纯 HTML

✅ 与你的技术栈兼容

任何 LLM： OpenAI、Anthropic、Ollama、Azure、Google Gemini、AWS Bedrock、Mistral 等 任何数据库： PostgreSQL、MySQL、Snowflake、BigQuery、Redshift、SQLite、Oracle、SQL Server、DuckDB、ClickHouse 等 你的认证系统： 自带 — cookies、JWT、OAuth 令牌 你的框架： FastAPI、Flask

✅ 可扩展但有推荐方案

自定义工具 — 扩展 Tool 基类 生命周期钩子 — 配额检查、日志记录、内容过滤 LLM 中间件 — 缓存、提示工程 可观察性 — 内置追踪与指标

建筑学

运作方式

sequenceDiagram
    participant U as 👤 User
    participant W as 🌐 <vanna-chat>
    participant S as 🐍 Your Server
    participant A as 🤖 Agent
    participant T as 🧰 Tools

    U->>W: "Show Q4 sales"
    W->>S: POST /api/vanna/v2/chat_sse (with auth)
    S->>A: User(id=alice, groups=[read_sales])
    A->>T: Execute SQL tool (user-aware)
    T->>T: Apply row-level security
    T->>A: Filtered results
    A->>W: Stream: Table → Chart → Summary
    W->>U: Display beautiful UI

关键概念：

1. 用户解析器 — 您定义如何从请求中提取用户身份（cookies、JWT 等）
2. 用户感知工具 — 工具会根据用户的组成员资格自动检查权限
3. 流式组件 — 后端将结构化的 UI 组件（表格、图表）流式传输到前端
4. 内置 Web UI — 预构建的 <vanna-chat> 组件可以漂亮地渲染所有内容

使用您的认证进行生产设置

这是一个将 Vanna 与您现有的 FastAPI 应用和认证集成的完整示例：

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

# Your existing FastAPI app
app = FastAPI()

# 1. Define your user resolver (using YOUR auth system)
class MyUserResolver(UserResolver):
    async def resolve_user(self, request_context: RequestContext) -> User:
        # Extract from cookies, JWTs, or session
        token = request_context.get_header('Authorization')
        user_data = self.decode_jwt(token)  # Your existing logic

        return User(
            id=user_data['id'],
            email=user_data['email'],
            group_memberships=user_data['groups']  # Used for permissions
        )

# 2. Set up agent with tools
llm = AnthropicLlmService(model="claude-sonnet-4-5")
tools = ToolRegistry()
tools.register(RunSqlTool(sql_runner=SqliteRunner("./data.db")))

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

# 3. Add Vanna routes to your app
chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler)

# Now you have:
# - POST /api/vanna/v2/chat_sse (streaming endpoint)
# - GET / (optional web UI)

然后在你的前端:

<vanna-chat sse-endpoint="/api/vanna/v2/chat_sse"></vanna-chat>

查看 完整文档 以了解自定义工具、生命周期钩子和高级配置

自定义工具

使用自定义工具扩展 Vanna，以满足您的特定使用场景：

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"]  # Permission check

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

    async def execute(self, context: ToolContext, args: EmailArgs) -> ToolResult:
        user = context.user  # Automatically injected

        # Your business logic
        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}")

# Register your tool
tools.register(EmailTool())

高级功能

Vanna 2.0 包含用于生产环境的强大企业功能：

生命周期钩子 — 在请求生命周期的关键点添加配额检查、自定义日志记录、内容过滤

LLM 中间件 — 在 LLM 调用周围实现缓存、提示工程或成本跟踪

对话存储 — 持久化并检索每个用户的对话历史

可观测性 — 内置追踪和指标集成

上下文增强器 — 添加 RAG、记忆或文档以增强代理响应

代理配置 — 控制流、温度、最大迭代次数等

使用案例

Vanna 适用于：

• 📊 具有自然语言接口的数据分析应用程序
• 🔐 需要用户感知权限的多租户 SaaS
• 🎨 想要预构建 Web 组件后台的团队
• 🏢 具有安全/审计要求的企业环境
• 📈 需要丰富流响应（表格、图表、SQL）的应用程序
• 🔄 与现有身份验证系统集成

社区与支持

• 📖 完整文档 — 完整指南和 API 参考
• 💡 GitHub 讨论 — 功能请求和问答
• 🐛 GitHub 问题 — Bug 报告
• 📧 企业支持 — support@vanna.ai

迁移说明

Upgrading from Vanna 0.x?

Vanna 2.0 是一次完全重写，专注于用户感知代理和生产部署。主要变化：

• 新 API：基于代理而非 VannaBase 类方法
• 用户感知：每个组件现在都知道用户身份
• 流式处理：丰富的 UI 组件而非文本/数据框
• 以 Web 为先：内置 <vanna-chat> 组件和服务器

迁移路径：

1. 快速包装 — 使用 LegacyVannaAdapter 包装现有 Vanna 0.x 实例，即可立即获取新的 Web UI
2. 渐进迁移 — 逐步迁移到新的 Agent API 和工具

查看完整的 迁移指南 获取逐步操作说明。

许可

MIT 许可证 — 详情请参见 LICENSE。

由 Vanna 团队 ❤️ 打造 | 网站 | 文档 | 讨论