Vanna：开源数据分析代理框架，支持多数据库与企业级安全管控

一、Vanna是什么？

Vanna是一个以“自然语言驱动数据洞察”为核心的开源框架，旨在降低数据分析的技术门槛，让非技术人员也能通过日常语言获取数据结论。其设计理念是“让数据对话更简单”——无论是业务人员的自然语言提问（如“今年Q3各区域销售额同比增长多少？”），还是技术人员的复杂分析需求，Vanna都能通过AI能力转换为可执行的操作（如生成SQL查询、输出可视化图表），并返回结构化结果。

Vanna包含两个主要版本，分别面向不同场景：

• Vanna 2.0+（新一代）：定位为“Web优先、用户感知”的代理框架（Agent Framework），聚焦生产级数据分析场景。它将用户身份、权限管理嵌入全流程，支持与现有系统（如认证体系、数据库权限）无缝集成，适合企业级应用开发。

• Legacy版本（旧版本）：基于检索增强生成（RAG）技术的SQL生成框架，核心是通过向量存储“训练”模型理解数据库结构（表名、字段、关系等），从而将自然语言准确转换为SQL。该版本更适合快速验证需求或轻量化场景。

简单来说，Vanna就像一个“数据翻译官”+“分析助手”：它能听懂人类语言，看懂数据库结构，还能根据用户权限生成合规的分析结果，最终让数据使用更高效、更安全。

二、功能特色

Vanna的两个版本在功能上各有侧重，但核心目标一致：降低自然语言与数据之间的转换成本。以下从版本差异和共性优势两方面展开说明。

2.1 版本核心功能对比

为了更清晰区分两个版本的定位，我们通过表格对比其核心功能：

2.2 Vanna 2.0+ 核心特色

作为新一代框架，Vanna 2.0+在Legacy版本基础上强化了“生产级”能力，主要特色包括：

• 用户感知设计，权限贯穿全流程
  Vanna 2.0+将用户身份（如员工ID、部门）和权限（如“只能查看本部门数据”）作为核心变量，嵌入从提问解析到结果返回的每一步。例如，当用户提问“各区域销售额”时，系统会自动根据用户所属部门过滤数据（如仅返回“华东区”数据），无需额外开发权限逻辑。这种设计避免了“数据越权访问”风险，尤其适合多部门协作的企业场景。

• Web优先架构，降低开发成本
  提供预构建的Web组件，包括聊天界面（支持输入提示、历史记录）、结果展示区（表格、图表渲染）和后端接口（基于FastAPI/Flask）。开发者无需从零开发UI，只需通过简单配置（如对接企业现有认证系统的Cookies或JWT），即可快速部署一个可用的数据分析聊天工具。例如，集成JWT认证后，系统可自动识别登录用户身份，无需额外开发用户验证模块。

• 多模态流式响应，结果更直观
  响应内容不仅限于文本，还支持动态返回表格（查询结果）、图表（如柱状图、折线图，基于Plotly生成）、SQL代码块（方便技术人员验证）等。例如，用户提问“近半年销售额趋势”时，系统会先返回可视化折线图，再附上生成的SQL和数据表格，满足不同用户的需求。

• 灵活的工具生态与工作流
  内置“工具注册机制”，支持将常用操作（如SQL执行、文件导出、数据清洗）封装为工具，供AI代理调用。同时，提供“工作流触发器”（WorkflowTrigger），允许开发者拦截用户消息，执行确定性逻辑（如处理命令/help、校验权限、启动状态化流程），无需调用大模型。例如，当用户发送/export 2023时，触发器可直接触发“导出2023年数据为Excel”的操作，无需AI解析，提升效率。

• 企业级安全与可观测性
  安全方面，支持行级安全（RLS，与数据库权限联动）、操作审计日志（记录谁在何时执行了什么查询）、接口速率限制（防止恶意请求）；可观测性方面，提供追踪钩子（Tracking Hooks），支持集成Prometheus等监控工具，方便开发者调试和监控系统运行状态。

2.3 Legacy版本核心特色

Legacy版本聚焦“快速实现自然语言转SQL”，适合轻量化场景，核心特色包括：

• RAG增强的SQL生成能力
  通过“训练”过程让模型理解数据库结构：开发者需先向Vanna输入数据库的元数据（表名、字段描述、示例SQL等），系统会将这些信息转换为向量存储（如PgVector、ChromaDB）；当用户提问时，Vanna会检索相关元数据，辅助大模型生成更准确的SQL。例如，若数据库中有sales表（含region、amount字段），训练后用户提问“华东区销售额”，系统可生成SELECT SUM(amount) FROM sales WHERE region='华东'。

• 多向量存储与数据库兼容
  支持主流向量存储（如AzureSearch、PineCone、FAISS）和数据库（如Snowflake、Oracle、MySQL），开发者可根据现有技术栈选择适配方案。例如，使用PostgreSQL的团队可直接集成PgVector作为向量存储，无需额外部署工具。

• 轻量化部署，开箱即用
  无需复杂配置，通过PyPI安装后，几行代码即可启动SQL生成功能。例如，连接到本地MySQL数据库并训练后，可直接在命令行或Jupyter Notebook中使用自然语言提问，快速验证效果。

三、技术细节

Vanna的技术设计围绕“自然语言到数据洞察的全链路优化”展开，两个版本的核心技术架构既有差异，也有共性。

3.1 整体架构

• Vanna 2.0+架构：采用“代理（Agent）+工具（Tools）+存储（Storage）+Web层”的分层设计（如图1简化示意）：

• Agent层：核心决策模块，负责解析用户提问、调用工具、生成响应。内置大模型接口（如Anthropic Claude、OpenAI GPT），通过提示词工程引导模型理解任务。

• Tools层：工具注册与执行中心，包含内置工具（如SQLExecutor、ChartGenerator）和自定义工具接口，支持同步/异步执行。

• Storage层：管理用户会话、权限配置、审计日志等数据，支持对接SQLite、PostgreSQL等数据库。

• Web层：基于FastAPI/Flask的后端接口，提供预构建的前端组件（HTML/JS），支持CORS、认证中间件。

• Legacy版本架构：更简单的“RAG+大模型”架构：

• 输入层：接收用户自然语言提问和数据库元数据。

• 向量存储层：存储元数据向量，负责检索相关信息。

• 大模型层：结合检索结果生成SQL。

• 输出层：返回SQL代码，需外部工具执行并展示结果。

3.2 核心技术组件

Vanna依赖多项技术实现功能，以下是关键组件及支持列表（表格形式呈现）：

3.3 关键技术亮点

• 用户权限与数据安全的深度耦合（Vanna 2.0+）：
  系统通过“用户上下文”（User Context）传递身份信息，在调用工具（如SQLExecutor）时自动注入权限条件。例如，若用户属于“市场部”，SQLExecutor会在生成的SQL后自动追加AND department='市场部'，确保数据访问符合行级安全规则。这种设计避免了权限逻辑与业务逻辑的混杂，降低了开发复杂度。

• RAG技术的优化实现（Legacy版本）：
  为提升SQL生成准确性，Legacy版本对RAG流程做了针对性优化：

• 元数据预处理：自动提取表关系（如外键关联）、字段类型（如日期、数值），生成结构化描述，减少歧义。

• 检索增强：采用“多轮检索”策略，先检索表名，再根据表名检索字段，最后结合示例SQL优化生成结果。

• 流式响应与前端交互（Vanna 2.0+）：
  通过SSE（Server-Sent Events）实现流式响应，前端可实时展示内容（如先显示“正在生成图表”，再逐步渲染结果），提升用户体验。同时，前端组件支持自定义主题（如匹配企业UI风格）和结果导出（如Excel、PDF）。

四、应用场景

Vanna的两个版本因定位不同，适用场景各有侧重，但均围绕“自然语言驱动数据分析”展开。

4.1 Vanna 2.0+ 适用场景

• 企业级数据分析平台
  适合大型企业构建内部数据门户：支持多部门用户登录（对接企业LDAP/SSO），不同部门用户只能查看权限内数据（如财务部看成本、销售部看业绩），系统自动生成图表和结论，减少数据分析师的重复工作。例如，某零售企业用Vanna 2.0+搭建“数据助手”，门店经理可通过聊天界面查询“今日本店销售额”，系统返回实时数据和环比分析，无需IT团队介入。

• 现有系统的数据分析模块集成
  可作为插件嵌入CRM、ERP等系统，为业务人员提供“在工作流中直接提问”的能力。例如，在CRM中查看客户信息时，用户可直接提问“该客户近3个月的复购率”，系统调用Vanna生成SQL查询客户数据库，返回结果后嵌入CRM界面，无需切换工具。

• 带状态化流程的数据分析工具
  利用工作流触发器实现复杂分析流程，如“月度报表自动生成”：用户发送/monthly-report 2023-10，触发器调用SQLExecutor查询10月数据，再调用ChartGenerator生成趋势图，最后通过FileExporter导出为PPT，全程自动化完成。

4.2 Legacy版本适用场景

• 快速验证自然语言转SQL需求
  适合初创团队或个人开发者验证“用自然语言操作数据库”的可行性：无需搭建复杂系统，安装后连接数据库并导入元数据，即可测试SQL生成效果。例如，开发者可在Jupyter Notebook中用Legacy版本快速测试“如何通过自然语言查询用户留存率”，评估是否需要进一步投入开发。

• 轻量化数据查询工具
  用于小型团队内部的数据查询，如部门共享的MySQL数据库，非技术人员可通过聊天工具（如Slack机器人）提问，Legacy版本生成SQL后执行并返回结果。例如，运营人员提问“本周新注册用户数”，机器人调用Legacy生成SQL并返回数字，无需麻烦开发人员写查询。

• 教学与学习工具
  可作为SQL学习辅助工具：学生输入自然语言需求（如“查询成绩大于90的学生姓名”），Legacy版本返回对应的SQL，帮助理解SQL语法与逻辑。

五、使用方法

Vanna的两个版本安装和使用方式不同，以下分别介绍基础流程（以Python环境为例）。

5.1 Vanna 2.0+（开发版）使用步骤

Vanna 2.0+目前为开发版，需从GitHub安装，适合开发者构建应用：

步骤1：安装依赖

# 安装核心包，同时集成Flask后端和Anthropic大模型
pip install --force-reinstall --no-cache-dir 'vanna[flask,anthropic] @ git+https://github.com/vanna-ai/vanna.git@v2'

步骤2：配置大模型与数据源

创建app.py，配置Anthropic API密钥（需自行申请）和数据库连接：

from vanna.flask import VannaFlaskApp
from vanna.anthropic import Claude

# 初始化大模型（以Claude为例）
vn = Claude(
  api_key="你的Anthropic API密钥",
  model="claude-3-sonnet-20240229" # 支持的模型列表见官方文档
)

# 连接数据库（以PostgreSQL为例）
vn.connect_to_postgres(
  host="localhost",
  dbname="你的数据库名",
  user="用户名",
  password="密码",
  port=5432
)

# 启动Flask应用
app = VannaFlaskApp(vn)
app.run(debug=True, port=8080) # 访问http://localhost:8080即可打开Web界面

步骤3：使用Web界面交互

启动后访问http://localhost:8080，即可看到聊天界面：

• 输入自然语言提问（如“查询近30天的订单量”），系统会生成SQL、执行并返回表格+图表。

• 支持切换用户（模拟不同权限）、导出结果、查看历史记录。

5.2 Legacy版本使用步骤

Legacy版本可通过PyPI安装，适合快速测试：

步骤1：安装包

pip install vanna # 稳定版

步骤2：初始化并训练模型

创建legacy_demo.py，连接数据库并导入元数据（训练模型）：

from vanna.legacy import VannaDefault

# 初始化（以OpenAI GPT-3.5为例）
vn = VannaDefault(
  model="gpt-3.5-turbo",
  api_key="你的OpenAI API密钥",
  vector_db="chroma" # 使用Chroma作为向量存储
)

# 连接数据库（以MySQL为例）
vn.connect_to_mysql(
  host="localhost",
  user="root",
  password="密码",
  database="test_db"
)

# 训练：导入表结构（自动获取）和示例SQL
vn.train(ddl="""
  CREATE TABLE sales (
    id INT PRIMARY KEY,
    region VARCHAR(50),
    amount DECIMAL(10,2),
    sale_date DATE
  )
""") # 可手动输入表结构，或用vn.get_ddl()自动获取

vn.train(sql="SELECT region, SUM(amount) FROM sales GROUP BY region") # 导入示例SQL

步骤3：生成SQL并执行

# 自然语言提问
question = "各区域的总销售额是多少？"
sql = vn.generate_sql(question)
print("生成的SQL：", sql)

# 执行SQL并获取结果
result = vn.run_sql(sql)
print("查询结果：", result)

运行后，系统会输出对应的SQL和查询结果，例如：

生成的SQL： SELECT region, SUM(amount) FROM sales GROUP BY region
查询结果： [('华东', 15000.00), ('华北', 12000.00)]

六、常见问题解答（FAQ）

6.1 如何选择Vanna 2.0+和Legacy版本？

• 若需要构建企业级应用（带权限、Web界面、复杂工作流），选择Vanna 2.0+；

• 若仅需快速实现自然语言转SQL（无权限需求、轻量化），选择Legacy版本。

6.2 Vanna支持哪些大模型？是否需要付费？

Vanna本身开源免费，但依赖的大模型（如GPT-4、Claude）需用户自行申请API密钥并支付费用。支持的免费模型需通过API对接（如本地部署的Llama 3），具体可参考官方文档的模型集成列表。

6.3 如何确保生成的SQL安全？

• Vanna 2.0+通过用户权限自动过滤数据（如行级安全），并支持SQL语法校验（防止注入攻击）；

• Legacy版本需手动添加安全逻辑（如限制查询表范围），建议仅在内部可信环境使用。

6.4 能否自定义工具或工作流？

Vanna 2.0+支持：

• 自定义工具：通过@tool装饰器注册函数，例如：

  @vn.register_tool
  def send_email(to: str, content: str):
    """发送邮件给指定用户"""
    # 实现邮件发送逻辑

• 工作流触发器：通过@workflow_trigger拦截消息，例如：

  @vn.register_workflow_trigger
  def handle_export(message: str):
    if message.startswith("/export"):
      # 处理导出逻辑
      return {"type": "file", "content": "导出内容"}

6.5 向量存储需要单独部署吗？

部分向量存储（如FAISS）为本地库，无需部署；分布式向量存储（如PineCone、AzureSearch）需在对应平台申请服务并配置API密钥。

七、相关链接

• GitHub仓库：https://github.com/vanna-ai/vanna

• Vanna 2.0+文档：https://github.com/vanna-ai/vanna/blob/v2/README.md

• Legacy版本文档：https://vanna.ai/docs/

• 示例Notebooks：https://github.com/vanna-ai/vanna/tree/main/notebooks

八、总结

Vanna作为一款聚焦“自然语言驱动数据洞察”的开源框架，通过Vanna 2.0+（企业级代理框架）和Legacy版本（轻量化RAG工具）覆盖了从快速验证到生产部署的全场景需求。其核心优势在于降低数据分析门槛（自然语言交互）、支持多技术栈集成（数据库、大模型、向量存储），以及Vanna 2.0+新增的用户权限管控和Web组件，让企业能安全、高效地构建数据分析应用。无论是业务人员的日常查询，还是开发者的系统集成，Vanna都提供了灵活的解决方案，是连接自然语言与数据的实用工具。