3 步把 vanna 跑起来自然语言生成 SQL 从本地到生产的避坑指南【免费下载链接】vanna Chat with your SQL database . Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval .项目地址: https://gitcode.com/GitHub_Trending/va/vannavanna 是一个开源的 Python RAG检索增强生成框架让业务同事直接用自然语言查数据库自动生成并执行 SQL。本文带你走一遍 vanna 部署的完整路径装环境、拿到第一条 SQL、选部署姿势、上线前三道保险5 分钟上手。它到底在干嘛一句话把你的表结构和历史 SQL喂给向量数据库提问时先检索相关上下文再交给 LLM大语言模型拼出 SQL。核心流程其实很短自然语言提问 → 向量检索DDL / 文档 / 参考 SQL→ LLM 生成 → 执行 SQL → 返回结果vanna 2.0 还在这个链路上加了用户身份层每条查询都会带上你是谁、能看哪些行结果表、图表通过流式组件推给内置的 Web 聊天界面。整体架构长这样不用深究底层原理只要记住两点先 train 再 ask以及换个 LLM / 数据库 换个组件组合。从零到跑通5 分钟拿到第一条自然语言 SQL打开终端按时间线走一遍。1. 装环境。要求 Python 3.9建个虚拟环境后pip install vanna即可想要 OpenAI 和 ChromaDB本地向量库支持就带上对应 extras 安装例如pip install vanna[openai] vanna[chromadb]。2. 配密钥。把 LLM 的 API Key 放进环境变量OPENAI_API_KEY后面代码里直接读别写死在文件里。3. 写最小可运行示例。继承向量库和聊天模型两个组件先 train 后 ask就这么短import os from vanna.openai.openai_chat import OpenAI_Chat from vanna.chromadb.chromadb_vector import ChromaDB_VectorStore class MyVanna(OpenAI_Chat, ChromaDB_VectorStore): def __init__(self, configNone): OpenAI_Chat.__init__(self, config) ChromaDB_VectorStore.__init__(self, config) vn MyVanna(config{api_key: os.environ[OPENAI_API_KEY], model: gpt-4o}) # 训练喂 DDL 和参考 SQL vn.train(ddlCREATE TABLE customers (id INT PRIMARY KEY, name VARCHAR(100), created_at TIMESTAMP)) vn.train(sqlSELECT COUNT(*) FROM customers) # 提问拿到自然语言生成的 SQL print(vn.ask(有多少个客户))train 这一步是踩坑高发区只喂 DDL 时 LLM 能生成 SQL但业务口径比如活跃客户怎么定义它猜不到补一两条train(documentation...)和真实 SQL 示例准确率肉眼可见地涨。跑完vn.ask(...)打印出 SELECT 语句就算跑通了。更多组件组合方式可以看仓库里的 examples 目录 和 legacy 版说明想升级到 2.0 的 Agent 架构迁移指南 有逐条对照。跑通之后呢给 vanna 部署挑个姿势个人原型到小团队生产三种姿势按规模选别一步到位上云部署姿势适合谁一句话建议本地 虚拟环境自己验证想法最快pip install完事向量库数据放本机Docker Compose小团队共用应用、PostgreSQL、ChromaDB 三个容器一条命令起云平台 / K8s多人、要审计和扩缩容先把 compose 版跑稳再谈编排密钥走平台 SecretCompose 方案里应用容器只暴露一个 HTTP 端口环境变量注入 API Key 和数据库连接串数据卷挂住向量库目录然后docker compose up -dvanna 的服务端自带 FastAPI / Flask 两套接入见 servers 目录挂到你现有 Web 服务里就行不用单独运维一个vanna 服务器。生产前必做的三件事密钥别硬编码。OPENAI_API_KEY、数据库连接串一律走环境变量或平台的 Secret 管理。代码库泄露 钱包泄露这条没有商量余地。加个健康检查。起一个/health端点探两件事向量库连得上、LLM 可调用。上游网关或容器编排挂了自动摘流量别等用户报错才发现。给查询设超时。LLM 响应慢、SQL 跑大表更慢两边都设上限LLM 调用超时 30 秒左右SQL 执行超时按你的库来。再顺手开上审计日志谁问了什么、跑了什么 SQL 都有据可查。⚠️ 顺带一提LLM 生成的 SQL 本质是高置信度的建议对外部用户暴露查询能力时务必用只读账号连库并开启行级权限过滤——vanna 2.0 的用户感知层就是干这个的。下一步至此从终端第一行命令到生产防护vanna 的自然语言生成 SQL 全链路你已经走完了。想再进一步把vn.train喂上你库里真实的 DDL 和历史查询跑一轮准确率对比或者直接用仓库自带的 quickstart 笔记本 边跑边改——训练语料质量才是准确率的第一杠杆。【免费下载链接】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），仅供参考
