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

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

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

2.0 版本新特性

🔐 全链路用户感知 — 根据用户权限自动过滤查询

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

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

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

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

从 0.x 版本升级？ 请参阅 迁移指南 | 有哪些变化？

快速开始

使用示例数据体验

快速开始

配置

配置指南

Web 组件

<!-- 可嵌入任何现有网页 -->
<script src="https://img.vanna.ai/vanna-components.js"></script>
<vanna-chat
  sse-endpoint="https://your-api.com/chat"
  theme="dark">
</vanna-chat>

使用您现有的 cookies/JWTs。兼容 React、Vue 或原生 HTML。

功能特性

用自然语言提问，即可获得：

1. 流式进度更新

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

3. 交互式数据表格

4. 图表（Plotly 可视化）

5. 自然语言总结

所有内容均实时流式传输到您的 Web 组件。

为什么选择 Vanna 2.0？

✅ 即刻上手

• 生产就绪的聊天界面
• 连接您数据库的自定义智能体
• 可嵌入任何网页

✅ 企业级安全

全链路用户感知 — 用户身份贯穿系统提示、工具执行和 SQL 过滤
行级安全 — 根据用户权限自动过滤查询
审计日志 — 记录每位用户的每次查询，满足合规要求
速率限制 — 通过生命周期钩子实现按用户配额控制

✅ 包含精美的 Web UI

预构建的 <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, JWTs, OAuth 令牌
您的框架： FastAPI, Flask

✅ 可扩展且开箱即用

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

架构

工作原理

sequenceDiagram
    participant U as 👤 用户
    participant W as 🌐 <vanna-chat>
    participant S as 🐍 您的服务器
    participant A as 🤖 智能体
    participant T as 🧰 工具

    U->>W: "显示第四季度销售额"
    W->>S: POST /api/vanna/v2/chat_sse (附带认证)
    S->>A: 用户(id=alice, groups=[read_sales])
    A->>T: 执行 SQL 工具（用户感知）
    T->>T: 应用行级安全
    T->>A: 过滤后的结果
    A->>W: 流式传输：表格 → 图表 → 总结
    W->>U: 显示精美的 UI

核心概念：

1. 用户解析器 — 您定义如何从请求中提取用户身份（cookies、JWTs 等）
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

# 您现有的 FastAPI 应用
app = FastAPI()

# 1. 定义您的用户解析器（使用您自己的认证系统）
class MyUserResolver(UserResolver):
    async def resolve_user(self, request_context: RequestContext) -> User:
        # 从 cookies、JWTs 或会话中提取
        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']  # 用于权限控制
        )

# 2. 使用工具设置智能体
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. 将 Vanna 路由添加到您的应用中
chat_handler = ChatHandler(agent)
register_chat_routes(app, chat_handler)

# 现在您拥有：
# - POST /api/vanna/v2/chat_sse (流式端点)
# - GET / (可选的 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="邮件收件人")
    subject: str = Field(description="邮件主题")

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

    @property
    def access_groups(self) -> list[str]:
        return ["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"邮件已发送至 {args.recipient}")

# 注册您的工具
tools.register(EmailTool())

高级功能

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

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

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

对话存储 — 按用户持久化和检索对话历史

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

上下文增强器 — 添加 RAG、记忆或文档以增强智能体响应

智能体配置 — 控制流式传输、温度、最大迭代次数等

适用场景

Vanna 非常适合：
- 📊 需要自然语言界面的数据分析应用
- 🔐 需要用户感知权限的多租户 SaaS
- 🎨 希望获得预构建 Web 组件 + 后端的团队
- 🏢 有安全/审计要求的企业环境
- 📈 需要丰富流式响应（表格、图表、SQL）的应用
- 🔄 与现有认证系统集成

社区与支持

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

迁移说明

从 Vanna 0.x 升级？

Vanna 2.0 是一个完全重写的版本，专注于用户感知智能体和生产环境部署。主要变化：

• 新 API：基于智能体，而非 VannaBase 类方法
• 用户感知：每个组件现在都知晓用户身份
• 流式传输：丰富的 UI 组件，而非文本/数据框
• Web 优先：内置 <vanna-chat> 组件和服务器

迁移路径：

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

查看完整的 迁移指南 获取分步说明。

许可证

MIT 许可证 — 详情请见 LICENSE。

由 Vanna 团队 ❤️ 构建 | 官网 | 文档 | 讨论区