Vanna 2.0 实战：自然语言生成SQL-育师

Vanna 2.0 实战：自然语言生成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 2.0 是用自然语言生成SQL的Python框架，适合数据分析师和内部系统开发者。没有它，你得手写SQL，还得自己搭聊天界面。读完这篇，你能拿到一份最小可运行的配置，和一份上生产前的检查清单。

Vanna到底替你省了什么事

没有Vanna时，每次数据问题的流程是：业务方丢来一句话，你查表结构、写SQL、跑出来、再手动把截图发过去。不熟的表结构要反复查文档，列名写错一次就返工一次。

接入Vanna后，流程压缩成一句话：用户在对话框输入自然语言问题，Agent生成SQL、执行、把表格和图表流式推回前端。模型写SQL时，RAG（把相关资料"喂"给模型参考的检索技术）会提供表结构和示例查询；执行失败时，报错信息也会传回让模型自行修正。

主要省下三件事：

手写SQL：自然语言问一句，SQL自动生成并执行
聊天前端：vanna-chat组件丢进任意页面，不用自己写
权限过滤：每个查询按用户身份和组自动限定范围

三步跑通Vanna

第一步，装。一条命令，要求Python 3.9及以上：

pip install vanna

终端里pip show vanna能看到版本号，即成功。

第二步，配。接上LLM，注册SQL执行工具。下面用Anthropic和SQLite举例，换OpenAI、Ollama也是同样写法：

from vanna import Agent from vanna.core.registry import ToolRegistry from vanna.tools import RunSqlTool from vanna.integrations.anthropic import AnthropicLlmService from vanna.integrations.sqlite import SqliteRunner # 选择你的LLM llm = AnthropicLlmService(model="claude-sonnet-4-5") # 注册SQL执行工具，指向你自己的数据库 tools = ToolRegistry() tools.register(RunSqlTool(sql_runner=SqliteRunner("./data.db"))) agent = Agent(llm_service=llm, tool_registry=tools)

这段代码跑完没有报错，说明配置通过。

第三步，跑。一条命令起一个演示服务：

python -m vanna.servers --example mock_quickstart

终端打印出服务地址后，打开页面提一个问题，看到回复流式返回即成功。

Vanna在你的工作里能干什么

当你需要回答临时数据问题的时候。业务方问"销售额前十的客户是谁"，过去你写查询、截图、发过去，下次再问还得重写。现在直接把这句话丢进对话框，进度提示、数据表格、图表、一句话总结依次流式返回，图表可以直接分享。

当你需要把数据入口开放给全公司的时候。Vanna自带FastAPI和Flask集成，注册好路由后，你现有的登录态会被自动解析成用户身份，查询按该用户所属的组自动限定范围。HR能看到薪资表，其他人看不到，权限逻辑不用你手写。

当你需要超出SQL范围的能力的时候。继承Tool基类，把发邮件、建工单等业务逻辑封装成工具注册进去，Agent会根据问题自动选用。入口始终是一个对话框，用户不用学新操作。

上生产之前要检查什么

安全隔离

挂上你自己的UserResolver（用户身份解析器）→ 每个请求拿到真实用户身份
给工具设置access_groups → 不在组内的用户调不动这个工具
开启行级过滤 → 同一张表查询，每个用户只看到自己的数据

性能调优

在LLM调用上挂中间件（middleware）→ 加上缓存和成本统计
在AgentConfig里限制最大迭代次数 → Agent不会循环重试烧掉预算

监控与日志

开启审计日志（audit）组件 → 每条查询按用户留痕，合规可查
接上可观察性（observability）追踪 → 每次请求的完整链路可回放
用评估模块跑回归数据集 → 模型升级后准确率变化一眼可见

踩过的坑 & 解法

生成的SQL总是报错

原因：模型不认识你的表结构，列名全靠猜。解法：把表DDL和常用示例查询注册进Agent Memory（内置ChromaDB等向量库），让RAG检索提供。验证：同一个问题连问三遍，全部成功。

不同用户查到了彼此的数据

原因：用户身份没解析出来，行级过滤没触发。解法：实现UserResolver，从请求头里解析出用户和所属组，传给Agent。验证：用两个不同账号登录，对比同一问题的查询结果。

前端只有文字，没有表格和图表

原因：流式没开，或者组件没指向流式接口。解法：AgentConfig里开启stream_responses，把vanna-chat的sse-endpoint指向chat_sse接口。验证：界面里表格和图表逐个流式出现。

装完就报ImportError

原因：LLM驱动和数据库连接器都是可选依赖，基础包不带。解法：装对应extras，比如pip install vanna[anthropic] vanna[postgres]。验证：Python里import对应模块，不再抛ImportError。

接下来可以往哪走

想加新工具：参考工具实现源码，复制一份改execute逻辑即可。
想改请求处理流程：看workflow处理源码，在前后插入自己的逻辑。
从0.x升级：先读迁移指南，用LegacyVannaAdapter包住旧实例，新旧接口并行跑。

下次有人问"上个月的销售额是多少"，你不用再打开数据库，把这句话丢进对话框就行。今天就动手：挑一个手头的小SQLite库，把三步配置跑完，问出第一个问题。

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

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考