用自然语言查数据库Vanna 三步搞定 Text-to-SQL 的完整教程【免费下载链接】vanna Chat with your SQL database . Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval .项目地址: https://gitcode.com/GitHub_Trending/va/vanna你有没有遇到过这种场景业务方一句上个月销售额前十的客户是谁你就得翻表结构、手写 SQL、跑完再截图发过去Vanna 是一个用大模型把自然语言转成 SQL英文叫 Text-to-SQL的开源 Python 框架你问一句它自己写查询、执行、把结果以表格和图表流式返回。这篇教程带你三步跑通它并讲清楚上生产前要留意的坑。为什么它能直接回答你的问题Vanna 的核心思路是 RAG检索增强生成它不指望大模型背下你的库结构而是把表结构、业务示例等上下文动态喂给模型再由 Agent 调用内置的 SQL 执行工具完成生成 → 执行 → 汇总的闭环。它最差异化的一点是用户感知每个请求都带着身份进入系统查询按用户的权限组自动过滤天然支持行级安全Row-Level Security即同一个 SQL 对不同人返回不同范围的数据。几个关键能力一览能力说明流式响应进度、SQL 代码块、数据表、Plotly 图表、文字总结逐段推送用户感知身份贯穿系统提示词、工具执行和 SQL 过滤全链路数据库无关SQLite、PostgreSQL、MySQL、Snowflake、DuckDB 等通过 SqlRunner 接入模型无关OpenAI、Anthropic、Ollama、Gemini 等通过 LlmService 接入内置 Web 界面一个vanna-chat组件嵌进任意网页即可理解了这一点下面三步就能把最小闭环跑起来。 最短路径跑起来一条命令装好环境Vanna 2.0 需要 Python 3.9安装基础包后再按你要用的模型装对应扩展pip install vanna pip install vanna[anthropic] # 或 vanna[openai]、vanna[ollama]用本地数据库做演示最省事仓库自带的示例基于 Chinook 音乐库配合pip install vanna[anthropic]即可直接复现。最小配置一个 LLM 一个 SQL 工具 一个 AgentVanna 2.0 的 API 从训练式的VannaBase换成了 Agent 模式你不再逐条喂训练数据而是给 Agent 挂工具由它自主决定查什么。最小配置只需要三样东西import asyncio from vanna import Agent, AgentConfig, User from vanna.core.registry import ToolRegistry from vanna.integrations.anthropic import AnthropicLlmService from vanna.integrations.sqlite import SqliteRunner from vanna.tools import RunSqlTool # 1. 选一个大模型 llm AnthropicLlmService(modelclaude-sonnet-4-20250514) # 2. 注册 SQL 执行工具换成 PostgresRunner 就是生产库 tools ToolRegistry() tools.register(RunSqlTool(sql_runnerSqliteRunner(database_pathChinook.sqlite))) # 3. 组装 Agent agent Agent(llm_servicellm, tool_registrytools)如果你从 0.x 升级而来src/vanna/legacy/里的LegacyVannaAdapter可以包住旧实例先体验新界面不必一次改完。问出第一个数据问题agent.send_message是一个流式接口它会逐个吐出 UI 组件文本、数据表、通知等你遍历打印即可看到完整回答user User(idu1, usernamedemo, permissions[]) async def main(): async for component in agent.send_message( useruser, messageThis 数据库里有哪些表各自是干什么的, conversation_iddemo-1, ): if component.simple_component: print(component.simple_component.text) asyncio.run(main())跑完这一遍你就已经完成了自然语言 → SQL → 结果的全链路。想更直观地看效果可以直接起官方示例服务浏览器里用vanna-chat组件对话python -m vanna.servers --example claude_sqlite_example 走一个真实任务从提问到图表现在用一个接近实际业务的例子走完全流程。启动上面的示例服务后在聊天界面输入找出按专辑数量排序的前 5 位艺术家并可视化结果接下来你看到的不是一段返回的文本而是一连串流式推送的内容实时进度→生成的 SQL 代码块默认只对 admin 用户可见→可交互的数据表格DataFrameComponent 组件→Plotly 图表→自然语言总结。整个过程你随时知道它卡在哪一步而不是干等一个黑盒结果。背后发生了什么可以看这张流程图你的问题先经过身份解析Agent 决定调用run_sql工具工具按用户权限过滤后再执行结果以组件形式流回前端想在自己代码里消费这些组件逻辑和第一步一致遍历send_message的产出rich_component里就是数据表、图表这类富组件。⚠️ 上生产前要注意什么能跑通之后真正拉开差距的是下面几件事。每条先给结论再给做法。数据安全权限必须来自你的认证系统而不是 Vanna 自己发 token。结论是 Vanna 不做登录它只认你解析出来的用户身份。做法是实现一个UserResolver从 cookie、JWT 或 session 里读出User其中group_memberships决定能调哪些工具、能看到哪些行再给 Agent 挂AuditLogger落审计日志。多租户 SaaS 里这一步就是租户隔离的全部基础。准确性靠上下文而不是靠训练次数。模型答得准不准取决于它当时看到多少正确的表结构和业务示例。Vanna 2.0 通过agent_memory如 ChromaDB、Milvus 等向量库集成DefaultLlmContextEnhancer在每次提问时动态注入相关上下文对高频业务问题建议把问题 标准 SQL对沉淀进向量库效果明显好于只喂 DDL。性能重复问题和缓存交给中间件不要改 Agent。Vanna 把 LLM 调用包在可插拔的LlmMiddleware里缓存、成本控制、Prompt 改写都在这层做生命周期钩子LifecycleHook则适合放配额检查和日志别把这类逻辑塞进工具里。扩展边界业务动作做成工具别做成 SQL。发邮件、调内部 API 这类事继承Tool基类写一个自定义工具注册进ToolRegistry即可参考src/vanna/examples/mock_custom_tool.py的EmailTool写法。工具自带权限组校验这是在 SQL 外做业务的正规入口。适合谁不适合谁适合你如果你要给内部或客户做一个自然语言查数的入口且没有精力从零搭聊天前端和流式后端或者你是多租户产品需要每个用户看到不同数据范围又或者你团队有合规要求希望查询全程可审计。不适合你如果你追求的是亚秒级的 OLAP 实时大盘——LLM 生成 SQL 的时延和不确定性决定了它更适合探索式提问而非固定报表刷新或者你的核心诉求只是把一个固定问题转成 SQL 定时跑那一条手写 SQL 加调度器更稳不需要引入整个 Agent 栈。另外要诚实提醒一句2.0 是重写和 0.x 的 API 完全不同。网上大量Vanna 向量库训练的旧教程对应的是 legacy 版本看文档时认准 Agent 模式。 快速答疑问不想配 API Key能先本地体验吗能。pip install vanna[ollama]后把 LLM 换成 Ollama 的本地模型或者直接用仓库里的MockLlmService示例python -m vanna.examples.mock_sqlite_example先把工具链跑热。问怎么接入我们现有的 FastAPI 服务三步注册路由register_chat_routes(app, ChatHandler(agent))实现你自己的UserResolver前端放一个vanna-chat sse-endpoint...标签。完整示例在 README 的 Production Setup 一节核心源码见src/vanna/servers/fastapi/。问SQL 生成错了会怎样会不会乱改数据RunSqlTool执行的是模型写的 SQL生产环境建议数据库账号只给 SELECT 权限再叠加行级过滤和审计把写坏数据这条路从源头关掉。先做最小的一步回到开头Vanna 做的事就是把问一句自然语言变成拿到表和图中间写 SQL 的活交给 Agent。你现在不需要想清楚权限模型和向量库选型只需要装好包、挂一个 SQLite、问出第一个问题——上面三节代码拷下来改个数据库路径就能跑。跑通之后再沿着src/vanna/examples/里的生产级示例Claude SQLite FastAPI逐步替换成你自己的库和认证升级路径参考仓库里的MIGRATION_GUIDE.md。【免费下载链接】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），仅供参考