Vanna 部署实战3 步跑通本地演示再接上自己的数据库【免费下载链接】vanna Chat with your SQL database . Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval .项目地址: https://gitcode.com/GitHub_Trending/va/vanna业务方问一句上个季度卖了多少常规路径是翻仪表盘 → 没有 → 找分析师 → 等一周。Vanna一个自然语言转 SQL 的开源框架把这条路压缩进一个聊天框把自然语言问题翻译成 SQL、执行、再把结果表和图表流式吐回来。本文按 Vanna 2.0 的源码结构讲清 vanna 部署全流程——从本地零成本尝鲜到接入真实 LLM 与数据库、最后带 Web 界面命令可直接照跑。一图看懂 Vanna 部署的核心链路先建立整体印象vanna 2.0 不再是一个调一下就完事的类而是一套前后端配合的服务。一次提问在系统里走的路如下各组件一句话说明组件干什么你能改什么vanna-chat前端组件现成的聊天界面扔进任意网页即可主题、端点地址Python 服务提供 SSE 流式接口Flask/FastAPI 二选一可挂进你已有的应用鉴权方式、路由Agent 核心编排 LLM 与工具知道当前用户是谁、有什么权限系统提示词、最大迭代次数RunSqlTool执行 SQL、把结果还给 LLM支持按用户过滤行换数据库 Runner官方论文里有一组对照数据值得看一眼同样的问题只给 LLM 表结构Schema时准确率可能只有 10%~34%而带上下文的策略能拉到 69%~91%。这就是为什么 vanna 保留了喂训练数据 / RAG这条链路——想让 SQL 更准就先把表结构、示例查询喂进去而不是指望 LLM 凭空猜。先选哪条 Vanna 部署路线3 种规模对号入座不要一上来就搭云端集群。先按这张表给自己定位后文只展开前两条最常用路线维度路线 A本地尝鲜路线 B单机小团队路线 C云上生产门槛最低不需要任何 API Key用 mock LLM1 个 LLM Key 1 个数据库需要鉴权、反向代理、密钥管理成本0LLM 调用费服务器 LLM 调用费适用规模10 分钟验证链路十几人的内部工具多租户 SaaS要行级权限、审计路线 C 的形态很简单vanna 的服务就是一个标准的 Flask/FastAPI 应用怎么上云就按你平时部署 Python Web 服务的方式走容器化、挂密钥、放内网。文末给一段能直接用的 Dockerfile。本地实操3 步跑通 Vanna 部署演示不需要 API Key前置条件Python 3.9项目声明requires-python 3.9装个 venv 之类的虚拟环境工具。第 1 步拿到源码并安装。vanna 2.0 是重写后的 Agent 框架建议从源码装# 克隆源码 git clone https://gitcode.com/GitHub_Trending/va/vanna cd vanna # 安装核心包 服务器依赖flask / fastapi pip install -e .[servers]第 2 步用内置示例启动服务。官方 CLI 内置了一批示例 Agent其中 mock 系列用假 LLM 回复专门用来不花钱验证链路# 列出所有可用示例mock / openai / sqlite 等 vanna --list-examples # 启动 mock 演示服务默认端口 8000 vanna --example mock_quickstart --port 8000第 3 步打开浏览器。访问http://localhost:8000能看到预置的聊天界面发一句话mock Agent 会流式回复并展示进度组件。验证是否跑通——别只看页面再敲两个接口# 健康检查应返回 {status: healthy} curl http://localhost:8000/health # 通过 SSE 流式接口发一条消息应看到分片推送 curl -N -X POST http://localhost:8000/api/vanna/v2/chat_sse \ -H Content-Type: application/json \ -d {message: Introduce yourself}浏览器里能看到流式输出、/health返回 healthy说明服务链路CLI → FastAPI → ChatHandler → 前端组件是通的。接上真实数据库和真实 LLM把 Vanna 部署推到可用状态前置条件一个 LLM 的 API KeyOpenAI / Anthropic / 本地 Ollama 任选一个能连的数据库先用 SQLite 最省事。第 1 步装对应扩展。每个 LLM、每个数据库都是独立 extras按需加# 以 Anthropic 为例OpenAI 换成 .[openai]本地模型用 .[ollama] pip install -e .[anthropic] # PostgreSQL / MySQL / Snowflake 等数据库驱动同理如 .[postgres]第 2 步把 SQL 工具挂上 Agent。这是整个框架最核心的 15 行模式与官方示例脚本一致# 真实 LLM SQLite模式摘自官方示例脚本 from vanna import Agent, AgentConfig from vanna.core.registry import ToolRegistry from vanna.integrations.sqlite import SqliteRunner from vanna.tools import RunSqlTool from vanna.integrations.anthropic import AnthropicLlmService tools ToolRegistry() # 把执行 SQL工具注册给 Agent指向你的 SQLite 库文件 tools.register(RunSqlTool(sql_runnerSqliteRunner(database_pathChinook.sqlite))) # 开启流式前端组件会实时渲染表格和图表 agent Agent(llm_serviceAnthropicLlmService(modelclaude-sonnet-4-20250514), tool_registrytools, configAgentConfig(stream_responsesTrue))第 3 步启动服务并提问。把这个 agent 传给VannaFlaskServer/VannaFastAPIServer即可图省事也可以直接跑官方现成的 SQLite 示例# 内置示例Claude SQLiteChinook 示例库 vanna --example claude_sqlite_example --port 8000验证是否跑通在聊天框问前 10 名客户销售额是多少正常应依次看到SQL 代码块默认仅 admin 可见→ 结果表格 → Plotly 图表 → 自然语言总结。图表长这样如果换 PostgreSQL / MySQL只需把SqliteRunner换成对应集成src/vanna/integrations/下都有现成 Runner其余代码不动。完整可抄的示例都在 示例脚本目录。翻车现场Vanna 部署的 5 个高频报错现象最可能的原因定位思路装完报ModuleNotFoundError: No module named vanna装成了 PyPI 旧版或 extras 没带上确认在源码目录执行pip install -e .[servers]pip show vanna看版本启动即报[error] ...API_KEY is not setKey 不在进程环境里写进本地.env用 python-dotenv 加载或先export再启动Chinook database not found示例 SQLite 文件不在预期路径把示例库文件放到脚本同级目录再重跑示例代码里写了预期路径页面能开但聊天气泡一直空白前端组件脚本没加载CDN 不通或静态文件缺失启动时加--dev从本地静态目录加载组件再看浏览器 Network 面板回答极慢半天没首字LLM API 延迟高或没开流式确认stream_responsesTrue尝鲜阶段可先换本地 Ollama收尾这份 Vanna 部署检查清单过完才算完vanna --list-examples能列出示例 Agent且目标示例能正常启动GET /health返回 healthy发一条消息能看到流式进度 表格/图表不只是纯文本回复API Key 全部走环境变量或.env代码里没有硬编码换成真实 LLM 和真实数据库后重新问了一个端到端问题并核对结果上云时把服务装进容器即可最小 DockerfileFROM python:3.11-slim WORKDIR /app COPY pyproject.toml README.md ./ COPY src ./src # 安装核心包 服务器依赖extras 按需追加 RUN pip install --no-cache-dir -e .[servers] EXPOSE 8000 # 用官方 CLI 起一个示例 Agent 服务 CMD [vanna, --example, mock_quickstart, --port, 8000]服务、CLI 与路由的实现细节可以看 服务器与 CLI 源码想改聊天界面则看 Web 组件源码。【免费下载链接】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），仅供参考