Vanna 部署实战：3 步跑通本地演示，再接上自己的数据库

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 不再是一个"调一下就完事"的类，而是一套前后端配合的服务。一次提问在系统里走的路如下：

各组件一句话说明：

官方论文里有一组对照数据值得看一眼：同样的问题，只给 LLM 表结构（Schema）时准确率可能只有 10%~34%，而带上下文的策略能拉到 69%~91%。这就是为什么 vanna 保留了"喂训练数据 / RAG"这条链路——想让 SQL 更准，就先把表结构、示例查询喂进去，而不是指望 LLM 凭空猜。

先选哪条 Vanna 部署路线：3 种规模对号入座

不要一上来就搭云端集群。先按这张表给自己定位，后文只展开前两条最常用路线：

路线 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 Key（OpenAI / 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_runner=SqliteRunner(database_path="Chinook.sqlite"))) # 开启流式，前端组件会实时渲染表格和图表 agent = Agent(llm_service=AnthropicLlmService(model="claude-sonnet-4-20250514"), tool_registry=tools, config=AgentConfig(stream_responses=True))

第 3 步：启动服务并提问。把这个 agent 传给VannaFlaskServer/VannaFastAPIServer即可；图省事也可以直接跑官方现成的 SQLite 示例：

# 内置示例：Claude + SQLite（Chinook 示例库） vanna --example claude_sqlite_example --port 8000

验证是否跑通：在聊天框问"前 10 名客户销售额是多少"，正常应依次看到：SQL 代码块（默认仅 admin 可见）→ 结果表格 → Plotly 图表 → 自然语言总结。图表长这样：

如果换 PostgreSQL / MySQL，只需把SqliteRunner换成对应集成（src/vanna/integrations/下都有现成 Runner），其余代码不动。完整可抄的示例都在 示例脚本目录。

翻车现场：Vanna 部署的 5 个高频报错

收尾：这份 Vanna 部署检查清单过完才算完

• vanna --list-examples能列出示例 Agent，且目标示例能正常启动
• GET /health返回 healthy
• 发一条消息，能看到流式进度 + 表格/图表（不只是纯文本回复）
• API Key 全部走环境变量或.env，代码里没有硬编码
• 换成真实 LLM 和真实数据库后，重新问了一个端到端问题并核对结果

上云时把服务装进容器即可，最小 Dockerfile：

FROM 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