业务方催数据，还能让 AI 替你写 SQL？Vanna AI 自然语言生成 SQL 完整指南

业务方催数据，还能让 AI 替你写 SQL？Vanna AI 自然语言生成 SQL 完整指南

【免费下载链接】vanna🤖 Chat with your SQL database 📊. Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval 🔄.项目地址: https://gitcode.com/GitHub_Trending/va/vanna

Vanna AI 是一个 Python 写的自然语言生成 SQL 框架：你用日常语言提问，它替你生成 SQL、执行查询、返回表格和图表。数据分析师、业务团队，以及想给内部产品加一个"问数据库"入口的开发者都用得上。

被 SQL 卡住的取数流程

业务方在群里问："按销售额给我前 10 名客户"。分析师手上还压着两个报表，得先翻 schema、确认表名和字段，再写一条带 JOIN 和排序的查询。问的人等答案，写的人被打断，最后谁都不痛快。

Vanna 的思路很直接：让 LLM 来当翻译。2023 年它团队做的对比测试里，裸让模型看 schema 写 SQL，准确率只有约 3%；把表结构、文档和历史 SQL 作为上下文喂进去，同一批问题准确率到了约 80%（测试集为 20 个问题，结论见仓库内 papers/ai-sql-accuracy-2023-08-17.md）。这就是它整个设计的出发点——上下文比模型本身更关键。

一条查询是怎么跑完的

拿开头那个问题走一遍完整流程：

1. 用户在前端问"按销售额给我前 10 名客户"；
2. 请求带身份信息进入你的服务端，User Resolver 把它解析成用户对象，比如User(id=alice, groups=[read_sales])；
3. Agent 调用 Run SQL 工具生成并执行 SQL，工具会按用户权限做行级过滤；
4. 结果流式回传：先出数据表，再出 Plotly 图表，最后一段自然语言总结。

用代码说就是：

agent = Agent( llm_service=llm, tool_registry=tools, # 已注册 RunSqlTool user_resolver=MyUserResolver(), )

身份、权限、工具在这一层全部打通，具体字段和路由见 README.md 里的 Production Setup 示例。

从零开始：安装和最小配置

pip install vanna

Python 要求 3.9 以上，核心依赖（pandas、plotly、sqlalchemy 等）会自动装好。

最小配置只干三件事：选一个 LLM、选一个数据库 runner、注册 Run SQL 工具。

LLM 侧看 src/vanna/integrations/ 目录，OpenAI、Anthropic、Ollama、Azure、Google Gemini 都有现成服务类，本地跑就选 Ollama。数据库侧同理，SQLite、DuckDB、PostgreSQL、MySQL、ClickHouse、Snowflake 等都有独立 runner，本地演示一般直接用：

tools.register(RunSqlTool(sql_runner=SqliteRunner("./data.db")))

不需要向量库或额外服务，pip install完就能跑起来。

它到底能做到什么程度

用户感知的权限控制。身份会贯穿系统提示词、工具执行和 SQL 过滤三层；不同用户问同一个问题，看到的数据按权限组自动不同。SQL 代码块默认只对 admin 用户展示，普通用户只看到结果。

模型和数据库都不绑死。LLM 支持 OpenAI、Anthropic、Ollama、Azure、Gemini、Bedrock、Mistral 等；数据库覆盖 SQLite、DuckDB、PostgreSQL、MySQL、Snowflake、BigQuery、Oracle、SQL Server、ClickHouse、Presto、Hive 等，各有一个对应的 integration 包。

审计和限流内置。每次查询按用户留审计日志；按用户配额这类需求走生命周期钩子实现，不用自己拦请求。

准确率上保持克制：上面的 80% 来自 20 个问题的专项测试，且对上下文策略敏感——只喂 schema 时模型差距不大，喂足上下文后 Google 系模型能冲到第一、GPT-4 综合最强。真实库上的表现，建议先用 src/vanna/examples/ 里的样例跑你自己的表。

部署和集成：嵌进现有网页最省事

• 服务层：内置 FastAPI 和 Flask 两套路由，注册一下就能拿到POST /api/vanna/v2/chat_sse流式接口；也可以独立起服务。
• 前端层：一个<vanna-chat>Web Component，支持暗色主题、移动端适配，React、Vue、纯 HTML 都能直接放，复用你现有的 cookie 和 JWT 认证，不用再写一套聊天界面。
• 扩展层：继承Tool基类加工具（比如发邮件、调内部 API），用生命周期钩子加配额检查或内容过滤，用 LLM 中间件加缓存和成本统计；旧版 0.x 的用户可以用LegacyVannaAdapter先包一层平滑过渡，细节在 MIGRATION_GUIDE.md。

拿一个 SQLite 库试跑pip install vanna加上面那段最小配置，是验证它适不适合你业务场景最快的办法。

【免费下载链接】vanna🤖 Chat with your SQL database 📊. Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval 🔄.项目地址: https://gitcode.com/GitHub_Trending/va/vanna