企业官网建设流程全解析

把一句话变成可执行的 SQL：Vanna 自然语言查数完整上手指南

【免费下载链接】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 项目：把一句人话交给它，它让大模型生成对应的 SQL、在你的数据库上执行，再以表格、图表和文字总结的形式返回结果。下面讲清它的机制、最小可用配置，以及真实使用中容易卡住的几个环节。

🧭 它到底是干嘛的：一句话进，SQL 和报表出

Vanna 的定位不是"SQL 翻译器"，而是一个可挂权限、可流式输出的 Agent 框架。它内部的工作方式接近 RAG：你事先把表结构、字段说明、往来的问答示例存进它的长期记忆，提问时先做向量检索，把最相关的上下文塞给大模型，再由模型写出 SQL 并调用你注册的数据库执行器跑数。2.0 版本的关键变化是"用户感知"——每个请求都会先解析出提问者是谁，工具执行和行级过滤都基于这个身份进行，同一个问题不同角色问出来，拿到的数据范围不一样。

Vanna 2.0 的整体架构：提问、Agent 推理、SQL 执行、流式组件返回的完整链路

🎯 值得试的理由：四个差异化卖点

查询本身知道"是谁在问"

这是它和普通 Text-to-SQL 脚本最大的区别。你实现一个 user_resolver 从 Cookie、JWT 或会话里取出身份，注册工具时声明权限组，框架就会在每次执行 SQL 前做行级过滤：销售只能查本区域订单，财务能看全部。所有查询还会写入审计日志，方便合规回溯。

前端不用自己写，流式输出开箱即用

后端会把进度、SQL 代码块、数据表格、Plotly 图表和文字总结逐段推给前端，而前端只需要一个<vanna-chat>Web 组件。它不绑定 React 或 Vue，一段脚本加一个标签就能嵌进现有页面，亮暗主题都支持。做数据类产品的团队可以直接省掉整个聊天界面。

模型和数据库都可选

LLM 侧支持 OpenAI、Anthropic、Google Gemini、AWS Bedrock、Mistral 和本地 Ollama；数据库侧覆盖 PostgreSQL、MySQL、SQLite、Snowflake、BigQuery、Oracle、DuckDB、ClickHouse 等。接入方式统一：一个 LlmService 加一个 SqlRunner，都是独立可插拔的类，换供应商不影响其他代码。

能嵌进你已有的系统

它不是要你另起炉灶，而是提供 FastAPI 和 Flask 两套路由注册，几行代码就能把/chat_sse流式端点挂进现有应用，鉴权继续用你自己的体系。需要加配额检查、日志、内容过滤时，有生命周期钩子和 LLM 中间件两个插入点，不用改主流程。

⚡ 最快上手路径：从安装到第一次查询要写多少代码

先装主包和你要用的模型 extras：

pip install "vanna[anthropic]" # 其余模型同理：vanna[openai]、vanna[ollama]

然后组装一个能查 SQLite 的最小 Agent：

from vanna import Agent, ToolRegistry from vanna.tools import RunSqlTool from vanna.integrations.sqlite import SqliteRunner from vanna.integrations.anthropic import AnthropicLlmService llm = AnthropicLlmService() # 从环境变量读取 ANTHROPIC_API_KEY tools = ToolRegistry() tools.register(RunSqlTool(sql_runner=SqliteRunner("./orders.db"))) agent = Agent(llm_service=llm, tool_registry=tools)

提问入口是agent.send_message(request_context, message)，注意它是异步生成器，逐段产出 UI 组件而不是返回一个字符串。不想自己写服务端的话，可以直接跑仓库自带的演示：python -m vanna.servers --example mock_sqlite_example，它会起一个带 SQLite 示例库的完整服务。想接自己的模型时，把示例里的 MockLlmService 换成上面的真实服务即可。

最容易卡住的两个环节：一是没装 extras，构造 LLM 客户端时会直接抛 ImportError，按报错提示装对应方括号依赖即可；二是习惯了 0.x 版本的同步ask()写法——2.0 是重写版，API 完全换了，老代码需要用LegacyVannaAdapter包一层过渡，详见 MIGRATION_GUIDE.md。

🔍 真实工作里怎么用：三个能对号入座的场景

提问时先检索相关上下文，再让大模型生成 SQL 的完整流程

电商仓配的运营每天上午会问一句"哪个仓积压超48小时未发货的订单最多"。以前她得找数据同学排期，现在直接问，Vanna 检索出库表的字段说明，生成的 SQL 加上限聚合，几秒内流式返回一张按仓库排序的表格，她顺手截了个图发到调度群。

一家客服 SaaS 给每个客户管理员开了查询入口。租户 A 的管理员问"本月超3天未关闭的工单有多少"，user_resolver 从 JWT 里取出租户 ID，SQL 执行前自动附加该租户的过滤条件——她永远只能看到自己公司的数据，而系统层面不需要为每个租户写一套隔离逻辑。

数据团队的分析师则把它当"草稿生成器"：让 Vanna 先出 SQL，自己核对口径后手动执行进正式分析。对准确性要求高、不敢让模型直接出结果的团队，这是目前最稳妥的用法。

从用户提问到生成 SQL、执行并返回结果的完整流程示意

🛠️ 踩坑与实用技巧：老手总结的四条经验

生成的 SQL 经常报错或口径不对。原因是大模型没见过你的表结构和业务术语，只靠通用知识猜字段。解法是把 schema 说明和"问法→SQL"的历史例子持续喂进它的长期记忆，让它按问题做向量检索；仓库里的论文 ai-sql-accuracy-2023-08-17.md 有一组对比数据，结论是上下文相关的示例对准确率的提升明显高于只给 schema。

装完包 import 就报错。Vanna 的 extras 是按需拆分的，基础包不含任何 LLM 客户端和数据库驱动。哪个报错就装哪个：pip install "vanna[postgres]"、vanna[snowflake]"这类。

旧项目升级 2.0 后全线跑不通。2.0 换了 Agent + 异步流式的新 API，和 0.x 不兼容。别硬改，先用LegacyVannaAdapter把老实例包起来，前端立刻拿到新版 Web 界面，后端按模块逐步迁移。

多用户上线后发现权限形同虚设。通常是只注册了工具，没接 user_resolver，或者工具没声明access_groups。这两个都配好，框架才会在执行前按用户组过滤；上线前建议用两个不同角色的账号各问一遍同一个问题，确认返回的数据范围不同。

它适合谁：哪类团队该用，哪类人可以先观望

最适合的是有真实数据库、有大量取数需求、又需要对外提供"聊天式查数"入口的团队——尤其是多租户 SaaS 或企业数据门户，行级权限和审计是刚需。如果你只是想在本地对一个 SQLite 文件做点探索，Agent、异步流式、权限解析这套骨架对你偏重，单模型直接生成 SQL 可能更省事，可以观望。已有 0.x 版本在跑的团队，先用适配器包起来享受新前端，再慢慢迁移。

下次有人问数据，把 Vanna 接上库让它去查。入口看 README.md，升级路线见 MIGRATION_GUIDE.md，Agent 实现读 src/vanna/core/agent/。

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