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分钟跑通四步全程不需要先注册任何服务。安装核心包。CLI 入口vanna和 FastAPI 服务器都在这个包里。pip install vanna[fastapi]终端执行pip show vanna版本号为2.0.2即安装成功。用 Mock LLM 验证框架本身。这一步不消耗任何 API 额度专门用来确认环境没问题。python -m vanna.examples.mock_quickstart终端出现Hello! Im a helpful AI assistant created using the Vanna Agents framework.即表示 Agent 循环、消息流全部就绪。看看内置了哪些可直接运行的示例 Agent。vanna --list-examples预期输出以mock_quickstart、anthropic_quickstart、mock_sqlite_example等开头的列表。换上真实 LLM起 Web 服务。export ANTHROPIC_API_KEYyour-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 的行为集中在AgentConfigsrc/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 依赖组件常用选择为什么LLMAnthropic / OpenAI / Ollama云端模型质量稳定Ollama 适合内网离线SQL RunnerSQLite / Postgres / DuckDB本地演示用 SQLite生产对应装[postgres]等 extras记忆存储内置DemoAgentMemory/ ChromaDB / Qdrant演示用零依赖内存版生产上向量库部署路径决策如果你只是内部验证或个位数用户选单机 Pythonpip install vanna[fastapi,anthropic]装齐服务器与 LLM 依赖把ANTHROPIC_API_KEY写入环境或.envvanna --framework fastapi --example anthropic_quickstart --port 8000用你熟悉的进程管理器systemd、supervisor托管这个命令如果你要和生产环境一致、或多实例滚动发布选容器化# Dockerfile FROM python:3.11-slim ENV PYTHONUNBUFFERED1 # 只装必需的 extrasfastapi 服务器 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_KEYyour-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_runnerSqliteRunner(/opt/data/chinook.db))) return Agent(llm_serviceAnthropicLlmService(modelclaude-sonnet-4-5), tool_registrytools) async def _ask(question: str) - str: global _agent _agent _agent or _build() user User(idanon, emailanonexample.com, group_memberships[admin]) parts [] # send_message 是异步流式 API逐块收集组件内容 async for comp in _agent.send_message(useruser, messagequestion, conversation_idone-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 主线是AgentToolRegistry0.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_iterations8)并检查是不是temperature过高导致模型过早收敛。选型速查维度推荐配置本地验证vannaCLI mock_quickstart零 API key生产 LLMAnthropicclaude-sonnet-4-5或 OpenAI 高阶模型参数temperature0.2、max_tool_iterations5~8、stream_responsesTrue数据库演示 SQLite生产按 extras 装 Postgres/MySQL 等 Runner前端官方vanna-chat组件接/api/vanna/v2/chat_sse流式端点安全UserResolver挂你自己的鉴权审计默认开启把上表按规模裁剪就是最小可行配置单机加 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考