Vanna 是一个基于 Python 的开源框架，通过大语言模型（LLM）和 RAG 技术，将自然语言问题精准转化为 SQL 查询。它提供内置的流式 Web UI 组件和企业级安全特性（如行级权限控制），专为需要构建智能数据库交互应用的开发者和企业设计，支持任何 LLM 和数据库。
一分钟了解#
Vanna 是一个能够将自然语言转化为 SQL 查询的 AI 智能体框架，特别强调了在企业环境中的安全性和准确性。不同于简单的 Text-to-SQL 工具，它采用 RAG（检索增强生成）技术来提高 SQL 生成的精确度，并在 2.0 版本中引入了"用户感知"机制，确保数据查询符合用户权限。它自带一个名为 <vanna-chat> 的 Web 组件，可以直接嵌入到现有系统中，提供流式的图表和表格反馈。
核心价值：在保证企业级安全（行级权限、审计日志）的前提下，通过极少的代码将任何 SQL 数据库转变为支持自然语言查询的智能应用。
快速上手#
安装难度：低 - [标准的 Python 包安装，需配置 LLM 和数据库连接]
pip install vanna
适合我的场景吗？
- ✅ 构建内部 BI 工具：让非技术人员通过对话查询公司数据库。
- ✅ SaaS 数据应用：需要为不同用户提供不同数据权限的多租户系统。
- ❌ 非 SQL 数据源：如果你的数据主要在 NoSQL 或文件中，可能需要大量适配工作。
- ❌ 极度简单的查询：如果只需要硬编码的几个接口，引入 LLM 可能过于复杂。
核心能力#
1. 高精度的 Text-to-SQL - 解决 LLM 幻觉问题#
- 结合 RAG 技术，利用数据库schema和历史查询记录来提高生成 SQL 的准确性，能够处理复杂的业务逻辑。 实际价值：显著降低生成的 SQL 报错率，减少人工修正成本，使 AI 回答更可信。
2. 用户感知的安全机制 - 解决多租户权限问题#
- 请求会自动携带用户身份信息，并在执行 SQL 前应用行级安全过滤（RLS），确保用户只能看到被授权的数据。 实际价值：企业级数据安全，无需手动在提示词中处理权限逻辑，天然符合合规要求。
3. 开箱即用的 Web UI - 解决前端开发难题#
- 提供
<vanna-chat>自定义组件，支持流式返回表格、图表和摘要，无需从零构建聊天界面。 实际价值：极大缩短开发时间，提供专业级的用户体验（支持深色模式、移动端适配）。
技术栈与集成#
开发语言：Python (后端), TypeScript (前端组件) 主要依赖：FastAPI / Flask (Web 框架), Pydantic (数据校验) 集成方式：
- LLM 支持：OpenAI, Anthropic, Ollama, Azure, Google Gemini, AWS Bedrock 等。
- 数据库支持：PostgreSQL, MySQL, Snowflake, BigQuery, SQLite, Oracle 等。
- 认证集成：支持 JWT, Cookies, OAuth 等现有的认证体系。
生态与扩展#
- 自定义工具：可以通过继承
Tool类来扩展 Agent 的能力，例如查询后发送邮件或调用外部 API。 - 生命周期钩子：允许在请求的不同阶段（如生成 SQL 前、执行 SQL 后）插入自定义逻辑，如内容过滤、配额检查或日志记录。
维护状态#
- 开发活跃度：高度活跃，目前已发布 2.0 版本，架构重写以支持企业级特性。
- 最近更新：近期持续更新中，增加了对更多 LLM 和流式响应的支持。
- 社区响应：拥有大量的 GitHub 讨论、Issue 和社区贡献，文档完善。
商用与许可#
许可证：MIT License
- ✅ 商用：允许
- ✅ 修改：允许
- ⚠️ 限制：无特殊限制，非常宽松。
文档与学习资源#
- 文档质量：完善
- 官方文档：vanna.ai/docs/
- 示例代码：提供完整的 FastAPI 集成示例和自定义工具示例。