vanna 自然语言生成 SQL 实战指南

vanna 自然语言生成 SQL 实战指南

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

运营同事每天早晨都会发来同一类需求："拉一下昨天 Top 10 客户的营收。" 以前你要手写 SQL、跑批、截图发回群里。vanna 就是这个环节要解决的开源 Python 框架：你用自然语言提问，它生成 SQL、在数据库上执行，并把表格和图表流式返回。2.0 版本把它做成了一个 Agent 服务——自带 Web 聊天组件、按用户分权限、可审计。本文覆盖安装跑通、关键配置和三条部署路径；不覆盖 0.x 到 2.0 的完整迁移步骤，那部分见仓库根目录的 MIGRATION_GUIDE.md。

5分钟跑通

四步，全程不需要先注册任何服务。

1. 安装核心包。CLI 入口vanna和 FastAPI 服务器都在这个包里。

pip install "vanna[fastapi]"

终端执行pip show vanna，版本号为2.0.2即安装成功。

2. 用 Mock LLM 验证框架本身。这一步不消耗任何 API 额度，专门用来确认环境没问题。

python -m vanna.examples.mock_quickstart

终端出现Hello! I'm a helpful AI assistant created using the Vanna Agents framework.即表示 Agent 循环、消息流全部就绪。

3. 看看内置了哪些可直接运行的示例 Agent。

vanna --list-examples

预期输出以mock_quickstart、anthropic_quickstart、mock_sqlite_example等开头的列表。

4. 换上真实 LLM，起 Web 服务。

export ANTHROPIC_API_KEY=your-api-key vanna --framework fastapi --example anthropic_quickstart --port 8000

看到✓ Loaded example agent和🚀 Starting FastAPI server on http://0.0.0.0:8000后，浏览器打开http://localhost:8000，页面出现聊天框即可开始提问。API 文档同端口/docs下。

关键配置拆解

2.0 的行为集中在AgentConfig（src/vanna/core/agent/config.py）里。下面四个是对出结果影响最大的。

temperature：默认0.7，建议0.1~0.3。SQL 是确定性任务，温度高一点，模型就可能在表名、字段名上给出近义但错误的写法。

max_tool_iterations：默认10。控制 Agent 单轮最多调用几次工具。调到5~8能压住"模型反复试探"带来的延迟和 token 成本；但别设太小，多表 JOIN 类问题正常就需要 2~3 次查表加一次执行。

stream_responses：默认True，建议保持。前端组件的进度条、表格、图表都走这条流，关掉后聊天界面只剩最后一段文本，中间状态全丢。

LLM 与 Runner 选型：Agent 构造时传入llm_service和RunSqlTool的sql_runner，对应不同的 extras 依赖：

部署路径决策

如果你只是内部验证或个位数用户，选单机 Python：

1. pip install "vanna[fastapi,anthropic]"，装齐服务器与 LLM 依赖
2. 把ANTHROPIC_API_KEY写入环境或.env
3. vanna --framework fastapi --example anthropic_quickstart --port 8000
4. 用你熟悉的进程管理器（systemd、supervisor）托管这个命令

如果你要和生产环境一致、或多实例滚动发布，选容器化：

# Dockerfile FROM python:3.11-slim ENV PYTHONUNBUFFERED=1 # 只装必需的 extras：fastapi 服务器 + anthropic LLM RUN pip install --no-cache-dir "vanna[fastapi,anthropic]" EXPOSE 8000 # CLI 直接加载内置示例 Agent，无需携带业务代码 CMD ["vanna", "--framework", "fastapi", "--example", "anthropic_quickstart", "--port", "8000"]

docker build -t vanna-web . docker run -d -p 8000:8000 -e ANTHROPIC_API_KEY=your-api-key --name vanna vanna-web

无状态服务，多副本前挂一层负载均衡即可。

如果你不想养机器、按调用量付费，选 Serverless：不走 CLI，直接复用Agent，进程内单例避免每次冷启动重建。

# handler.py（云函数入口，Anthropic + SQLite 示例） import asyncio from vanna import Agent, User from vanna.core.registry import ToolRegistry from vanna.integrations.anthropic import AnthropicLlmService from vanna.integrations.sqlite import SqliteRunner from vanna.tools import RunSqlTool _agent = None # 云函数实例会被复用，单例避免每次请求重建 def _build() -> Agent: tools = ToolRegistry() tools.register(RunSqlTool(sql_runner=SqliteRunner("/opt/data/chinook.db"))) return Agent(llm_service=AnthropicLlmService(model="claude-sonnet-4-5"), tool_registry=tools) async def _ask(question: str) -> str: global _agent _agent = _agent or _build() user = User(id="anon", email="anon@example.com", group_memberships=["admin"]) parts = [] # send_message 是异步流式 API，逐块收集组件内容 async for comp in _agent.send_message(user=user, message=question, conversation_id="one-shot"): if hasattr(comp, "content"): parts.append(comp.content) return "".join(parts) def handler(event, context): return {"answer": asyncio.run(_ask(event.get("question", "")))}

踩坑实录

API 版本混用：照旧教程写from vanna.openai.openai_chat import OpenAI_Chat和vn.train(...)会困惑。2.0 主线是Agent+ToolRegistry，0.x 实现移到了 src/vanna/legacy/ 目录。新代码按 2.0 写；旧项目先找LegacyVannaAdapter包住，再逐步迁移。

可选依赖缺失：报ModuleNotFoundError: No module named 'anthropic'或'chromadb'。核心包只带基础依赖，每个 LLM、数据库、向量库都是独立 extra。执行pip install "vanna[fastapi,anthropic]"补齐，完整清单在 pyproject.toml 的optional-dependencies段。

Web 界面空白：服务起来了，浏览器却是空白页。CLI 默认从外部 CDN 加载前端组件脚本，内网环境连不上。加--dev --static-folder <本地静态目录>，或把--cdn-url指到你自托管的组件脚本。

SQL 块不显示：结果正常但看不到生成的 SQL。按默认配置，SQL 代码块只展示给admin组的用户。把你UserResolver返回的group_memberships里加上admin即可。

迭代提前中断：复杂问题 Agent 跑两三次工具就输出结论，SQL 不完整。调大AgentConfig(max_tool_iterations=8)，并检查是不是temperature过高导致模型过早收敛。

选型速查

把上表按规模裁剪，就是最小可行配置：单机加 Mock 起步，上了真实用户再切 LLM 与 Runner。更多实现细节可直接看 src/vanna/tools/ 的工具基类、src/vanna/integrations/ 的各数据库与 LLM 适配，以及 notebooks/quickstart.ipynb 里的完整示例。

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