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/vannaVanna AI 是一个开源的 Python 框架核心工作只有一句话把自然语言问题转成可执行的 SQL 并返回答案。它适合两类人——想让业务同事用大白话直接查数据库的开发者以及需要给现有产品加一个对话式取数入口、又不想自己从零搭聊天界面和权限体系的小团队。 先跑通一条命令装好五分钟问出第一条数据大多数 Text-to-SQL 方案卡在演示能看、上线难搞这一步。Vanna 的思路是先把最小闭环做短装包、接数据库、注册工具、挂上服务四件事做完就能问答。安装只需一条命令pip install vanna跑通的最小路径在 notebooks/quickstart.ipynb 里以 SQLite 为例用SqliteRunner接上库文件把RunSqlTool注册进ToolRegistry再交给Agent然后调用VannaFastAPIServer起服务。如果暂时没有 LLM 的 API Key仓库还提供了离线样例 src/vanna/examples/mock_quickstart.py用 Mock LLM 验证整个链路通不通不花一分钱。一个容易被忽略的起点建议先拿一个你自己很熟的库比如演示用的 Chinook做第一批问题把问法 → 正确 SQL的对照记下来。这批样本后面会直接决定生成质量下文会解释为什么。 原理决定准确率的不是模型是喂给模型什么上下文Vanna 的官方测试论文papers/ai-sql-accuracy-2023-08-17.md做过一组对照实验3 个 LLM × 3 种上下文策略 × 20 个问题共 180 次生成。结论比较反直觉——只给表结构schema总准确率约 3%。模型光靠字段名猜不出你的业务口径给少量固定 SQL 示例明显提升但各模型之间差距拉大弱模型依然不稳按问题检索最相关的历史 SQL 示例准确率跳到 80% 左右在复杂上下文场景下可到 88% 以上。这就是Agentic Retrieval在 Vanna 里的具体含义用户提问时系统先做相关性检索把历史上被验证过正确的相似查询捞出来拼进 prompt再交给 LLM 生成。它带来的实际影响是——模型选型是次要决策样本积累是主要决策。团队里业务问得越多、存下的正确 SQL 越多系统就越准这是个正反馈循环。架构上2.0 版本把整条链路重写成 Agent 形态请求进来后UserResolver 先从请求里解出用户身份Cookie、JWT、OAuth 均可接你自己的认证系统身份随后进系统提示词、工具执行和 SQL 过滤的每一个环节结果以流式组件表格、图表、摘要推给前端。 拿到手的不是文本是流式结果一次问答在vanna-chat组件里依次返回五样东西实时进度、SQL 代码块默认只对 admin 组可见、可交互的数据表、Plotly 图表以及一段自然语言摘要。全部走 SSE 流式推送不用等整条 SQL 跑完才出内容。前端集成成本是它比较突出的一个卖点页面里引入一个vanna-chat标签并指向你的 SSE 端点即可兼容 React、Vue 和纯 HTML自带深浅两套主题和移动端适配。组件源码在 frontends/webcomponent/想改交互可以自己编译。换句话说取数界面这块通常要外包或养前端的活它给你预置了。 权限、审计与配额多用户场景的三个默认能力给业务人员开放数据库查询绕不开三个问题谁能看到哪些行、每次查询有没有记录、资源消耗能不能控。Vanna 2.0 对这三点都是内置机制而非可选插件行级安全工具层根据用户所属权限组自动过滤查询结果同一张表不同人看到的行不同审计日志每个用户的每次查询都有独立记录面向合规场景按用户配额通过生命周期钩子在请求的关键节点挂检查逻辑限流、日志、内容过滤都走同一套扩展点。自定义能力也走明确的基类继承Tool基类就能加新工具比如发邮件、查外部接口access_groups属性声明该工具的权限组框架负责校验。LLM 调用外面还有一层 middleware 位置缓存、成本统计这类需求不用动 Agent 主逻辑。 覆盖范围模型与数据库都是任选其一维度内置支持LLMOpenAI、Anthropic、Google Gemini、Azure OpenAI、AWS Bedrock、Mistral、Ollama、vLLM 等数据库PostgreSQL、MySQL、SQLite、Snowflake、BigQuery、Redshift、Oracle、SQL Server、DuckDB、ClickHouse、Hive、Presto 等向量存储Agent 记忆ChromaDB、FAISS、Milvus、Qdrant、Pinecone、Weaviate、OpenSearch、Marqo、本地内存等服务端FastAPI、Flask 两套路由SSE 流式端点集成代码都在 src/vanna/integrations/ 下按厂商分目录选型时基本不需要胶水代码。用 Ollama 或 vLLM 跑本地模型也能接适合对数据出域敏感的场景——代价是本地小模型的 SQL 准确率会明显低于云端旗舰模型上面那组准确率数据里弱模型的表现可以当参照。⚖️ 收尾判断什么情况下值得引入 Vanna适合团队需要一个能对外提供、带权限和审计的取数入口且愿意持续沉淀问题—SQL样本或者已有认证体系只差一个把自然语言接进去的后端。需要先想清楚的代价准确率有下限依赖——上下文检索的样本库是冷启动阶段最弱的一环前期问得少时准确率会贴近只给 schema那档建议上线前用业务真实问题建一个小评测集仓库的 src/core/evaluation/ 提供了数据集、评估器和报告的完整骨架0.x 用户是重写而非升级——API 从VannaBase方法变成了 Agent 工具注册旧代码可用LegacyVannaAdapter包一层先接上新 UI再逐步迁移具体步骤见 MIGRATION_GUIDE.md。总评Vanna 把自然语言转 SQL从 demo 做到生产之间最麻烦的三段——权限过滤、流式前端、样本闭环——都给了默认实现。它不替你解决业务口径模糊的问题但把剩下的工程部分压缩到了几条配置和一次样本积累的周期。【免费下载链接】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），仅供参考