拓冰网站定制 
人工智能AI AgentRAG数据库后端数据可视化【免费下载链接】vanna Chat with your SQL database . Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval .项目地址https://gitcode.com/GitHub_Trending/va/vanna点击查看免费下载导读Vanna 2.0 将自然语言 → SQL → 答案的产品链路升级为用户感知的 Agent 框架用户身份与权限贯穿系统提示词、工具执行、SQL 过滤、审计日志的每一层并内置流式 Web 组件、企业级安全行级权限、审计、限流与生产就绪的 FastAPI/Flask 服务。本文以仓库 README.md 为骨架结合 Agent 核心实现、工具系统、用户模型 与 FastAPI 路由 等源码带你掌握三件事把vanna-chat组件嵌入任意网页、用UserResolverToolRegistryAgent组装带自建鉴权的生产级问答服务、通过自定义Tool与transform_args实现行级数据权限。从 0.x 迁移的用户还可直接套用文末的两条迁移路径。一、Vanna 2.0 是什么1.1 核心定位与产品链路Vanna 2.0 的定位不再是单机版 SQL 生成工具而是企业级用户感知 Agent 框架当前仓库版本见 pyproject.tomlrequires-python 3.9。核心链路自然语言问题 → Agent 生成 SQL → 工具执行查询 → 流式返回表格/图表/摘要1.2 一次问答返回的五类流式产物依据 README.md用户用自然语言提问后会实时收到流式进度更新Streaming Progress UpdatesSQL 代码块——默认仅对admin用户展示交互式数据表格Interactive Data Table图表——Plotly 可视化自然语言摘要Natural Language Summary全部通过Server-Sent EventsSSE实时推送到前端vanna-chat组件。SSE 端点实现在 src/vanna/servers/fastapi/routes.pyPOST /api/vanna/v2/chat_sse将请求包装为RequestContext含 cookies、headers、remote_addr、query_params再经ChatHandler.handle_stream()逐帧输出data: {json}\n\n并设置Cache-Control: no-cache、Connection: keep-alive、X-Accel-Buffering: no关闭 nginx 缓冲等流式响应头。1.3 2.0 相对 0.x 的变化一览维度Vanna 0.xVanna 2.0用户上下文无User对象携带权限贯穿整个系统交互模型直接方法调用vn.ask()Agent 化 流式组件工具形态单体方法模块化Tool类 Schema响应形态纯文本 / DataFrame富 UI 组件表格、图表、代码训练方式vn.train() 向量库系统提示词、Context Enrichers、RAG 工具数据库连接vn.connect_to_postgres()SqlRunner实现作为依赖注入Web UI无需自建内置 Web 组件 后端流式无默认 SSE权限无基于组的工具访问控制审计日志无内置审计日志系统该对比表综合自 README.md 与 MIGRATION_GUIDE.md二、系统架构与核心概念架构总览前端为可嵌入任意页面的vanna-chatWeb 组件后端为 Python Server可集成 FastAPI/Flask 或挂载到现有服务。核心的 User-Aware Agent 模块包含 User ResolverCookie/JWT 身份解析、角色与数据级权限、可选 LLMClaude、GPT 等、动态系统提示词、用户感知工具集SQL 执行、SQL 记忆、图表生成、自定义工具以及可观测性、评估、限流、审计等可选能力。2.1 请求处理时序README.md 给出的核心时序2.2 四个关键概念User Resolver用户解析器——由你定义如何从请求中提取用户身份cookies、JWTs 等。接口定义在 src/vanna/core/user/resolver.py只需实现async def resolve_user(request_context) - User。User-Aware Tools用户感知工具——工具自动根据用户组归属检查权限见下文 4.3 节权限判定。Streaming Components流式组件——后端流式推送结构化 UI 组件表格、图表、状态卡同时提供 Rich 组件与 Simple 组件双轨。Built-in Web UI内置 Web UI——预置的vanna-chat组件渲染所有内容实现位于 frontends/webcomponent/src/components/vanna-chat.ts。2.3 Agent 的 7 大扩展点从 Agent 类文档 可以看到框架刻意设计的 7 个可插拔扩展点lifecycle_hooks在消息与工具执行生命周期挂钩配额检查、日志、内容过滤llm_middlewares拦截/转换 LLM 请求与响应缓存、提示词工程、成本追踪error_recovery_strategy带重试逻辑的错误恢复context_enrichers向工具执行上下文注入额外数据RAG、记忆、文档llm_context_enhancer增强系统提示词与消息上下文默认DefaultLlmContextEnhancer接入 AgentMemoryconversation_filters在调用 LLM 前过滤会话历史observability_provider收集遥测与监控数据Agent.send_message()的完整执行流程agent.py依次为解析用户 → 触发 WorkflowHandler可选短路 LLM→ 加载/新建会话 → 注入 ContextEnrichers → 按用户拉取工具 Schema → 构建并增强系统提示词 → 进入LLM 请求 ↔ 工具执行循环受max_tool_iterations约束→ 流式产出UiComponent→ 保存会话并触发after_message钩子。三、快速上手Web 组件 现有 FastAPI 应用3.1 前端把组件嵌入任意网页README.md 的最小接入方式!-- Drop into any existing webpage -- script srchttps://img.vanna.ai/vanna-components.js/script vanna-chat sse-endpointhttps://your-api.com/chat themedark /vanna-chat组件直接复用你现有的cookies/JWTs做鉴权与 React、Vue 或纯 HTML 均兼容。前端由 api-client.ts 建立 SSE 连接并解析ChatStreamChunk交给 rich-component-system.ts 的ComponentManager渲染themedark通过:host([themedark])切换设计令牌vanna-chat.ts。3.2 后端与现有 FastAPI 应用集成带你的鉴权README.md 给出的完整示例核心三步定义 UserResolver → 组装 Agent → 注册路由。from fastapi import FastAPI from vanna import Agent from vanna.servers.fastapi.routes import register_chat_routes from vanna.servers.base import ChatHandler from vanna.core.user import UserResolver, User, RequestContext from vanna.integrations.anthropic import AnthropicLlmService from vanna.tools import RunSqlTool from vanna.integrations.sqlite import SqliteRunner from vanna.core.registry import ToolRegistry # Your existing FastAPI app app FastAPI() # 1. Define your user resolver (using YOUR auth system) class MyUserResolver(UserResolver): async def resolve_user(self, request_context: RequestContext) - User: # Extract from cookies, JWTs, or session token request_context.get_header(Authorization) user_data self.decode_jwt(token) # Your existing logic return User( iduser_data[id], emailuser_data[email], group_membershipsuser_data[groups] # Used for permissions ) # 2. Set up agent with tools llm AnthropicLlmService(modelclaude-sonnet-4-5) tools ToolRegistry() tools.register(RunSqlTool(sql_runnerSqliteRunner(./data.db))) agent Agent( llm_servicellm, tool_registrytools, user_resolverMyUserResolver() ) # 3. Add Vanna routes to your app chat_handler ChatHandler(agent) register_chat_routes(app, chat_handler) # Now you have: # - POST /api/vanna/v2/chat_sse (streaming endpoint) # - GET / (optional web UI)前端只需指向你的鉴权端点vanna-chat sse-endpoint/api/vanna/v2/chat_sse/vanna-chat源码级细节User 模型Pydantic 模型src/vanna/core/user/models.py字段为id、username、email、metadata、group_memberships且extraallow可扩展。group_memberships是后续所有权限判定的依据。RequestContext由路由层自动构造routes.pyUserResolver 从其中提取身份。RunSqlTool定义于 src/vanna/tools/run_sql.py接收注入的SqlRunner实现SQLite、PostgreSQL、MySQL、Snowflake、BigQuery、DuckDB、ClickHouse 等见 src/vanna/integrations参数模型RunSqlToolArgs仅含sql字段src/vanna/capabilities/sql_runner/models.py。安装方式按需安装集成如pip install vanna[fastapi,anthropic]完整 extras 见 pyproject.tomlflask/fastapi/servers/postgres/mysql/clickhouse/bigquery/snowflake/duckdb/google/anthropic/openai/ollama 等。四、自定义工具与用户感知权限Agent 的工具即权限模型是 2.0 的核心设计工具通过声明access_groups获得自动化的用户级权限控制。README.md 的完整示例from vanna.core.tool import Tool, ToolContext, ToolResult from pydantic import BaseModel, Field from typing import Type class EmailArgs(BaseModel): recipient: str Field(descriptionEmail recipient) subject: str Field(descriptionEmail subject) class EmailTool(Tool[EmailArgs]): property def name(self) - str: return send_email property def access_groups(self) - list[str]: return [send_email] # Permission check def get_args_schema(self) - Type[EmailArgs]: return EmailArgs async def execute(self, context: ToolContext, args: EmailArgs) - ToolResult: user context.user # Automatically injected # Your business logic await self.email_service.send( from_emailuser.email, toargs.recipient, subjectargs.subject ) return ToolResult(successTrue, result_for_llmfEmail sent to {args.recipient}) # Register your tool tools.register(EmailTool())4.1 工具基类的四个必须实现依据 Tool 抽象基类成员类型说明nameproperty - str工具唯一名称LLM 依据它发起调用descriptionproperty - str工具用途描述会进入系统提示词get_args_schema() - Type[T]方法返回 Pydantic 参数模型Tool.get_schema()会将其转为model_json_schema()供 LLM 使用execute(context, args) - ToolResultasync方法核心执行逻辑context.user自动注入当前用户access_groups为可选属性默认返回空列表表示对所有用户开放。ToolContext除user外还携带conversation_id、request_id、agent_memory、observability_provider与metadata含ui_features_available。4.2 工具执行路径5 步流水线ToolRegistry.execute 的完整链路查找工具——未注册返回ToolResult(successFalse, errorTool x not found)组权限校验——调用_validate_tool_permissionsregistry.py取用户组集合 ∩ 工具 access_groups 集合非空即放行工具未声明access_groups时对所有用户开放。失败返回Insufficient group access并触发审计参数校验——args_model.model_validate(tool_call.arguments)Pydantic 校验参数转换transform_args——行级安全RLS的关键钩子默认 NoOp但子类可重写在执行前对参数做用户化改造如给 SQL 追加WHERE tenant_id ...、过滤可选列表、脱敏敏感字段也可返回ToolRejection拒绝执行执行与审计——成功后把execution_time_ms写入结果 metadata按AuditConfig记录访问检查、调用与结果也就是说README 强调的Row-level security — Queries automatically filtered per user permissions正是通过重写transform_args或让自定义SqlRunner读取context.user在 SQL 执行前注入过滤条件实现的而非事后修补。五、企业级进阶特性README.md 罗列的能力结合源码逐一展开5.1 AgentConfig 可调参数AgentConfig 提供均含默认值参数默认值作用max_tool_iterations10单轮最大工具迭代次数防无限循环超限会流式输出警告并建议调整stream_responsesTrue是否流式响应关闭时走_send_llm_request一次性请求路径agent.pyauto_save_conversationsTrue自动持久化会话配合ConversationStoreinclude_thinking_indicatorsTrue是否输出思考过程指示temperature0.7LLM 采样温度范围 0.0~2.0max_tokensNone单次 LLM 响应的 token 上限ui_featuresUiFeatures()前端 UI 功能的分组访问控制audit_configAuditConfig()审计日志开关与粒度配置5.2 UI 功能级权限UiFeatures不仅工具连前端展示什么也按用户分组控制。UiFeatures 复用与工具相同的集合交集逻辑默认规则DEFAULT_UI_FEATURESUI 功能默认可见组tool_names工具名admin, usertool_arguments工具参数admintool_error工具错误详情admintool_invocation_message_in_chat工具调用消息adminmemory_detailed_results记忆详细结果admin这正是SQL 代码块默认仅 admin 可见的实现机制Agent 执行循环中通过can_user_access_feature决定是否向该用户流式输出工具名、参数、错误详情agent.py。空列表表示对所有用户开放也可用register_feature注册自定义 UI 功能。5.3 审计日志AuditConfigAuditConfig 提供细粒度开关enabled、log_tool_access_checks、log_tool_invocations、log_tool_results、log_ai_responses默认 Truelog_ui_feature_checks默认 False可能噪声大include_full_ai_responses默认 False隐私考虑不记录完整响应sanitize_tool_parameters默认 True自动脱敏密码、token 等敏感参数。Agent 构造时若传入audit_logger且审计开启会自动挂到 ToolRegistryagent.py。5.4 生命周期钩子、LLM 中间件与可观测性Lifecycle Hooksbefore_message/after_message/before_tool/after_tool四个时机agent.py典型用途是按用户配额限流与内容过滤。LLM Middlewaresbefore_llm_request/after_llm_response两个方向用于缓存、提示词工程、成本追踪agent.py。ObservabilityObservabilityProvider在用户解析、会话加载、系统提示词构建、工具执行、LLM 调用等每个阶段创建 span 并记录时长指标如agent.tool.execute、llm.request.duration、agent.message.duration。Context Enrichers 与 Conversation Filters前者在工具执行前向ToolContext注入 RAG 记忆/文档后者在构造 LLM 请求前裁剪会话历史控制 token 用量。Conversation StorageConversationStore按用户持久化/恢复会话历史默认MemoryConversationStore可替换为本地文件等实现见 src/vanna/integrations/local。六、从 0.x 迁移到 2.06.1 迁移总览与两条路径Vanna 2.0 是一次彻底重写README.md 给出的两条路径与 MIGRATION_GUIDE.md 一致快速包装Quick wrap——用LegacyVannaAdapter包装现有 Vanna 0.x 实例立即获得新版 Web UI 与流式能力改动最小渐进迁移Gradual migration——逐步迁移到新的 Agent API 与工具体系推荐路径先用 Legacy Adapter 快速迁移 → 逐步把关键路径重写为原生 2.0 架构 → 完全迁移后移除适配器。6.2 策略一Legacy Adapter 快速迁移MIGRATION_GUIDE.md 完整示例pip install vanna[flask,anthropic]from vanna import Agent, AgentConfig from vanna.servers.fastapi import VannaFastAPIServer from vanna.core.user import UserResolver, User, RequestContext from vanna.legacy.adapter import LegacyVannaAdapter from vanna.integrations.anthropic import AnthropicLlmService # Assume you already have a working vn object from your existing code: # vn MyVanna(config{model: gpt-4, api_key: your-key}) # vn.connect_to_postgres(...) # vn.train(ddl...) # etc. # NEW: Define user resolution (required in 2.0) class SimpleUserResolver(UserResolver): async def resolve_user(self, request_context: RequestContext) - User: user_email request_context.get_cookie(vanna_email) if not user_email: raise ValueError(Missing vanna_email cookie) # Admin users get admin group membership if user_email adminexample.com: return User(idadmin_user, emailuser_email, group_memberships[admin]) # Regular users get user group membership return User(iduser_email, emailuser_email, group_memberships[user]) # NEW: Wrap with legacy adapter # This automatically registers run_sql and memory tools from your VannaBase instance tools LegacyVannaAdapter(vn) # NEW: Set up LLM for the new Agent framework llm AnthropicLlmService( modelclaude-haiku-4-5, api_keyYOUR_ANTHROPIC_API_KEY ) # NEW: Create agent with legacy adapter as tool registry agent Agent( llm_servicellm, tool_registrytools, # LegacyVannaAdapter is a ToolRegistry user_resolverSimpleUserResolver(), configAgentConfig() ) # NEW: Create and run server server VannaFastAPIServer(agent) if __name__ __main__: # Run with: python your_script.py # Or: uvicorn your_module:server --host 0.0.0.0 --port 8000 server.run(host0.0.0.0, port8000)LegacyVannaAdapter 做了什么依据 adapter.py 实现继承ToolRegistryAgentMemory构造时自动把存量VannaBase方法注册为工具通过LegacySqlRunneradapter.py把vn.run_sql()包装为run_sql工具对 user 与 admin 组开放将vn.get_training_data()暴露为可搜索记忆search_saved_correct_tool_uses工具可选保存新训练数据save_question_tool_args工具admin 专属保留既有数据库连接与训练数据优点代码改动极小、保留训练数据、可渐进迁移、立即获得 Web UI 与流式能力。限制所有请求共享同一 VannaBase 实例用户感知有限无法利用行级安全缺少部分高级特性。6.3 策略二全量迁移到新架构MIGRATION_GUIDE.md 展示了新旧写法对照旧式多继承ChromaDB_VectorStore OpenAI_Chat、vn.train()vn.generate_sql()的写法全部替换为UserResolverToolRegistryAgentVannaFastAPIServer数据库连接改为SqlRunner注入如PostgresRunner(host..., dbname..., user..., password..., port5432)训练数据从向量库 vn.train()改为系统提示词 Context Enrichers RAG 工具。优点全部新特性、真正的用户感知、更强安全与权限、生产就绪架构。代价需重写代码、改造训练数据方案、学习曲线更陡。迁移决策速查来自 MIGRATION_GUIDE.md需求推荐策略最小改动快速迁移策略一Legacy Adapter全面使用新特性策略二全量迁移同时支持新旧代码先策略一再渐进迁移新项目策略二全量迁移七、适用场景依据 README.mdVanna 2.0 特别适合数据类应用需要自然语言交互界面的数据分析应用多租户 SaaS需要用户感知权限的租户隔离场景团队协作希望直接使用预置 Web 组件 后端的一体化方案企业环境有安全与审计合规要求的内部系统富流式响应需求需要实时返回表格、图表、SQL 的应用已有鉴权体系需要复用现有登录认证系统的集成场景八、相关资源导航迁移完整步骤MIGRATION_GUIDE.mdAgent 核心实现src/vanna/core/agent/agent.py、src/vanna/core/agent/config.py工具系统src/vanna/core/tool/base.py、src/vanna/core/registry.py、src/vanna/tools/run_sql.py用户与鉴权src/vanna/core/user/resolver.py、src/vanna/core/user/models.py服务端集成src/vanna/servers/fastapi/routes.py、src/vanna/servers/fastapi/app.py前端组件frontends/webcomponent/src/components/vanna-chat.ts存量迁移适配src/vanna/legacy/adapter.py数据库/LLM 集成按需查阅 src/vanna/integrations安装与依赖声明pyproject.toml赞分享人工智能AI AgentRAG数据库后端数据可视化【免费下载链接】vanna Chat with your SQL database . Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval .项目地址https://gitcode.com/GitHub_Trending/va/vanna点击查看免费下载相关推荐Bindu Speech-to-Text 实战用 Gemini 2.0 Flash 构建 A2A 语音转写 AgentBindu Speech to Text 实战用 Gemini 2.0 Flash 构建 A2A 语音转写 Agent 本文基于 Bindu 仓库中的 spesmolagents Text-to-SQL 实战用 CodeAgent SQLAlchemy 构建会写 SQL 的智能体smolagents Text to SQL 实战用 CodeAgent SQLAlchemy 构建会写 SQL 的智能体 本文是一份基于 smolage人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱AG-UI Ruby SDK 实战指南用 ag-ui-protocol 构建 Agent-User 交互服务端AG UI Ruby SDK 实战指南用 ag ui protocol 构建 Agent User 交互服务端 ag ui protocol 是 AG UI人工智能AI Agent上一篇CodeWhale simplify 技能完整指南3 步安全给代码瘦身附避坑自查清单下一篇老 Mac 装新版 macOS 实战用 OpenCore Legacy Patcher 顺利接投影仪与多屏创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Vanna 2.0 实战指南：构建用户感知（User-Aware）的 Text-to-SQL Agent 服务
人工智能AI AgentRAG数据库后端数据可视化【免费下载链接】vanna Chat with your SQL database . Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval .项目地址https://gitcode.com/GitHub_Trending/va/vanna点击查看免费下载导读Vanna 2.0 将自然语言 → SQL → 答案的产品链路升级为用户感知的 Agent 框架用户身份与权限贯穿系统提示词、工具执行、SQL 过滤、审计日志的每一层并内置流式 Web 组件、企业级安全行级权限、审计、限流与生产就绪的 FastAPI/Flask 服务。本文以仓库 README.md 为骨架结合 Agent 核心实现、工具系统、用户模型 与 FastAPI 路由 等源码带你掌握三件事把vanna-chat组件嵌入任意网页、用UserResolverToolRegistryAgent组装带自建鉴权的生产级问答服务、通过自定义Tool与transform_args实现行级数据权限。从 0.x 迁移的用户还可直接套用文末的两条迁移路径。一、Vanna 2.0 是什么1.1 核心定位与产品链路Vanna 2.0 的定位不再是单机版 SQL 生成工具而是企业级用户感知 Agent 框架当前仓库版本见 pyproject.tomlrequires-python 3.9。核心链路自然语言问题 → Agent 生成 SQL → 工具执行查询 → 流式返回表格/图表/摘要1.2 一次问答返回的五类流式产物依据 README.md用户用自然语言提问后会实时收到流式进度更新Streaming Progress UpdatesSQL 代码块——默认仅对admin用户展示交互式数据表格Interactive Data Table图表——Plotly 可视化自然语言摘要Natural Language Summary全部通过Server-Sent EventsSSE实时推送到前端vanna-chat组件。SSE 端点实现在 src/vanna/servers/fastapi/routes.pyPOST /api/vanna/v2/chat_sse将请求包装为RequestContext含 cookies、headers、remote_addr、query_params再经ChatHandler.handle_stream()逐帧输出data: {json}\n\n并设置Cache-Control: no-cache、Connection: keep-alive、X-Accel-Buffering: no关闭 nginx 缓冲等流式响应头。1.3 2.0 相对 0.x 的变化一览维度Vanna 0.xVanna 2.0用户上下文无User对象携带权限贯穿整个系统交互模型直接方法调用vn.ask()Agent 化 流式组件工具形态单体方法模块化Tool类 Schema响应形态纯文本 / DataFrame富 UI 组件表格、图表、代码训练方式vn.train() 向量库系统提示词、Context Enrichers、RAG 工具数据库连接vn.connect_to_postgres()SqlRunner实现作为依赖注入Web UI无需自建内置 Web 组件 后端流式无默认 SSE权限无基于组的工具访问控制审计日志无内置审计日志系统该对比表综合自 README.md 与 MIGRATION_GUIDE.md二、系统架构与核心概念架构总览前端为可嵌入任意页面的vanna-chatWeb 组件后端为 Python Server可集成 FastAPI/Flask 或挂载到现有服务。核心的 User-Aware Agent 模块包含 User ResolverCookie/JWT 身份解析、角色与数据级权限、可选 LLMClaude、GPT 等、动态系统提示词、用户感知工具集SQL 执行、SQL 记忆、图表生成、自定义工具以及可观测性、评估、限流、审计等可选能力。2.1 请求处理时序README.md 给出的核心时序2.2 四个关键概念User Resolver用户解析器——由你定义如何从请求中提取用户身份cookies、JWTs 等。接口定义在 src/vanna/core/user/resolver.py只需实现async def resolve_user(request_context) - User。User-Aware Tools用户感知工具——工具自动根据用户组归属检查权限见下文 4.3 节权限判定。Streaming Components流式组件——后端流式推送结构化 UI 组件表格、图表、状态卡同时提供 Rich 组件与 Simple 组件双轨。Built-in Web UI内置 Web UI——预置的vanna-chat组件渲染所有内容实现位于 frontends/webcomponent/src/components/vanna-chat.ts。2.3 Agent 的 7 大扩展点从 Agent 类文档 可以看到框架刻意设计的 7 个可插拔扩展点lifecycle_hooks在消息与工具执行生命周期挂钩配额检查、日志、内容过滤llm_middlewares拦截/转换 LLM 请求与响应缓存、提示词工程、成本追踪error_recovery_strategy带重试逻辑的错误恢复context_enrichers向工具执行上下文注入额外数据RAG、记忆、文档llm_context_enhancer增强系统提示词与消息上下文默认DefaultLlmContextEnhancer接入 AgentMemoryconversation_filters在调用 LLM 前过滤会话历史observability_provider收集遥测与监控数据Agent.send_message()的完整执行流程agent.py依次为解析用户 → 触发 WorkflowHandler可选短路 LLM→ 加载/新建会话 → 注入 ContextEnrichers → 按用户拉取工具 Schema → 构建并增强系统提示词 → 进入LLM 请求 ↔ 工具执行循环受max_tool_iterations约束→ 流式产出UiComponent→ 保存会话并触发after_message钩子。三、快速上手Web 组件 现有 FastAPI 应用3.1 前端把组件嵌入任意网页README.md 的最小接入方式!-- Drop into any existing webpage -- script srchttps://img.vanna.ai/vanna-components.js/script vanna-chat sse-endpointhttps://your-api.com/chat themedark /vanna-chat组件直接复用你现有的cookies/JWTs做鉴权与 React、Vue 或纯 HTML 均兼容。前端由 api-client.ts 建立 SSE 连接并解析ChatStreamChunk交给 rich-component-system.ts 的ComponentManager渲染themedark通过:host([themedark])切换设计令牌vanna-chat.ts。3.2 后端与现有 FastAPI 应用集成带你的鉴权README.md 给出的完整示例核心三步定义 UserResolver → 组装 Agent → 注册路由。from fastapi import FastAPI from vanna import Agent from vanna.servers.fastapi.routes import register_chat_routes from vanna.servers.base import ChatHandler from vanna.core.user import UserResolver, User, RequestContext from vanna.integrations.anthropic import AnthropicLlmService from vanna.tools import RunSqlTool from vanna.integrations.sqlite import SqliteRunner from vanna.core.registry import ToolRegistry # Your existing FastAPI app app FastAPI() # 1. Define your user resolver (using YOUR auth system) class MyUserResolver(UserResolver): async def resolve_user(self, request_context: RequestContext) - User: # Extract from cookies, JWTs, or session token request_context.get_header(Authorization) user_data self.decode_jwt(token) # Your existing logic return User( iduser_data[id], emailuser_data[email], group_membershipsuser_data[groups] # Used for permissions ) # 2. Set up agent with tools llm AnthropicLlmService(modelclaude-sonnet-4-5) tools ToolRegistry() tools.register(RunSqlTool(sql_runnerSqliteRunner(./data.db))) agent Agent( llm_servicellm, tool_registrytools, user_resolverMyUserResolver() ) # 3. Add Vanna routes to your app chat_handler ChatHandler(agent) register_chat_routes(app, chat_handler) # Now you have: # - POST /api/vanna/v2/chat_sse (streaming endpoint) # - GET / (optional web UI)前端只需指向你的鉴权端点vanna-chat sse-endpoint/api/vanna/v2/chat_sse/vanna-chat源码级细节User 模型Pydantic 模型src/vanna/core/user/models.py字段为id、username、email、metadata、group_memberships且extraallow可扩展。group_memberships是后续所有权限判定的依据。RequestContext由路由层自动构造routes.pyUserResolver 从其中提取身份。RunSqlTool定义于 src/vanna/tools/run_sql.py接收注入的SqlRunner实现SQLite、PostgreSQL、MySQL、Snowflake、BigQuery、DuckDB、ClickHouse 等见 src/vanna/integrations参数模型RunSqlToolArgs仅含sql字段src/vanna/capabilities/sql_runner/models.py。安装方式按需安装集成如pip install vanna[fastapi,anthropic]完整 extras 见 pyproject.tomlflask/fastapi/servers/postgres/mysql/clickhouse/bigquery/snowflake/duckdb/google/anthropic/openai/ollama 等。四、自定义工具与用户感知权限Agent 的工具即权限模型是 2.0 的核心设计工具通过声明access_groups获得自动化的用户级权限控制。README.md 的完整示例from vanna.core.tool import Tool, ToolContext, ToolResult from pydantic import BaseModel, Field from typing import Type class EmailArgs(BaseModel): recipient: str Field(descriptionEmail recipient) subject: str Field(descriptionEmail subject) class EmailTool(Tool[EmailArgs]): property def name(self) - str: return send_email property def access_groups(self) - list[str]: return [send_email] # Permission check def get_args_schema(self) - Type[EmailArgs]: return EmailArgs async def execute(self, context: ToolContext, args: EmailArgs) - ToolResult: user context.user # Automatically injected # Your business logic await self.email_service.send( from_emailuser.email, toargs.recipient, subjectargs.subject ) return ToolResult(successTrue, result_for_llmfEmail sent to {args.recipient}) # Register your tool tools.register(EmailTool())4.1 工具基类的四个必须实现依据 Tool 抽象基类成员类型说明nameproperty - str工具唯一名称LLM 依据它发起调用descriptionproperty - str工具用途描述会进入系统提示词get_args_schema() - Type[T]方法返回 Pydantic 参数模型Tool.get_schema()会将其转为model_json_schema()供 LLM 使用execute(context, args) - ToolResultasync方法核心执行逻辑context.user自动注入当前用户access_groups为可选属性默认返回空列表表示对所有用户开放。ToolContext除user外还携带conversation_id、request_id、agent_memory、observability_provider与metadata含ui_features_available。4.2 工具执行路径5 步流水线ToolRegistry.execute 的完整链路查找工具——未注册返回ToolResult(successFalse, errorTool x not found)组权限校验——调用_validate_tool_permissionsregistry.py取用户组集合 ∩ 工具 access_groups 集合非空即放行工具未声明access_groups时对所有用户开放。失败返回Insufficient group access并触发审计参数校验——args_model.model_validate(tool_call.arguments)Pydantic 校验参数转换transform_args——行级安全RLS的关键钩子默认 NoOp但子类可重写在执行前对参数做用户化改造如给 SQL 追加WHERE tenant_id ...、过滤可选列表、脱敏敏感字段也可返回ToolRejection拒绝执行执行与审计——成功后把execution_time_ms写入结果 metadata按AuditConfig记录访问检查、调用与结果也就是说README 强调的Row-level security — Queries automatically filtered per user permissions正是通过重写transform_args或让自定义SqlRunner读取context.user在 SQL 执行前注入过滤条件实现的而非事后修补。五、企业级进阶特性README.md 罗列的能力结合源码逐一展开5.1 AgentConfig 可调参数AgentConfig 提供均含默认值参数默认值作用max_tool_iterations10单轮最大工具迭代次数防无限循环超限会流式输出警告并建议调整stream_responsesTrue是否流式响应关闭时走_send_llm_request一次性请求路径agent.pyauto_save_conversationsTrue自动持久化会话配合ConversationStoreinclude_thinking_indicatorsTrue是否输出思考过程指示temperature0.7LLM 采样温度范围 0.0~2.0max_tokensNone单次 LLM 响应的 token 上限ui_featuresUiFeatures()前端 UI 功能的分组访问控制audit_configAuditConfig()审计日志开关与粒度配置5.2 UI 功能级权限UiFeatures不仅工具连前端展示什么也按用户分组控制。UiFeatures 复用与工具相同的集合交集逻辑默认规则DEFAULT_UI_FEATURESUI 功能默认可见组tool_names工具名admin, usertool_arguments工具参数admintool_error工具错误详情admintool_invocation_message_in_chat工具调用消息adminmemory_detailed_results记忆详细结果admin这正是SQL 代码块默认仅 admin 可见的实现机制Agent 执行循环中通过can_user_access_feature决定是否向该用户流式输出工具名、参数、错误详情agent.py。空列表表示对所有用户开放也可用register_feature注册自定义 UI 功能。5.3 审计日志AuditConfigAuditConfig 提供细粒度开关enabled、log_tool_access_checks、log_tool_invocations、log_tool_results、log_ai_responses默认 Truelog_ui_feature_checks默认 False可能噪声大include_full_ai_responses默认 False隐私考虑不记录完整响应sanitize_tool_parameters默认 True自动脱敏密码、token 等敏感参数。Agent 构造时若传入audit_logger且审计开启会自动挂到 ToolRegistryagent.py。5.4 生命周期钩子、LLM 中间件与可观测性Lifecycle Hooksbefore_message/after_message/before_tool/after_tool四个时机agent.py典型用途是按用户配额限流与内容过滤。LLM Middlewaresbefore_llm_request/after_llm_response两个方向用于缓存、提示词工程、成本追踪agent.py。ObservabilityObservabilityProvider在用户解析、会话加载、系统提示词构建、工具执行、LLM 调用等每个阶段创建 span 并记录时长指标如agent.tool.execute、llm.request.duration、agent.message.duration。Context Enrichers 与 Conversation Filters前者在工具执行前向ToolContext注入 RAG 记忆/文档后者在构造 LLM 请求前裁剪会话历史控制 token 用量。Conversation StorageConversationStore按用户持久化/恢复会话历史默认MemoryConversationStore可替换为本地文件等实现见 src/vanna/integrations/local。六、从 0.x 迁移到 2.06.1 迁移总览与两条路径Vanna 2.0 是一次彻底重写README.md 给出的两条路径与 MIGRATION_GUIDE.md 一致快速包装Quick wrap——用LegacyVannaAdapter包装现有 Vanna 0.x 实例立即获得新版 Web UI 与流式能力改动最小渐进迁移Gradual migration——逐步迁移到新的 Agent API 与工具体系推荐路径先用 Legacy Adapter 快速迁移 → 逐步把关键路径重写为原生 2.0 架构 → 完全迁移后移除适配器。6.2 策略一Legacy Adapter 快速迁移MIGRATION_GUIDE.md 完整示例pip install vanna[flask,anthropic]from vanna import Agent, AgentConfig from vanna.servers.fastapi import VannaFastAPIServer from vanna.core.user import UserResolver, User, RequestContext from vanna.legacy.adapter import LegacyVannaAdapter from vanna.integrations.anthropic import AnthropicLlmService # Assume you already have a working vn object from your existing code: # vn MyVanna(config{model: gpt-4, api_key: your-key}) # vn.connect_to_postgres(...) # vn.train(ddl...) # etc. # NEW: Define user resolution (required in 2.0) class SimpleUserResolver(UserResolver): async def resolve_user(self, request_context: RequestContext) - User: user_email request_context.get_cookie(vanna_email) if not user_email: raise ValueError(Missing vanna_email cookie) # Admin users get admin group membership if user_email adminexample.com: return User(idadmin_user, emailuser_email, group_memberships[admin]) # Regular users get user group membership return User(iduser_email, emailuser_email, group_memberships[user]) # NEW: Wrap with legacy adapter # This automatically registers run_sql and memory tools from your VannaBase instance tools LegacyVannaAdapter(vn) # NEW: Set up LLM for the new Agent framework llm AnthropicLlmService( modelclaude-haiku-4-5, api_keyYOUR_ANTHROPIC_API_KEY ) # NEW: Create agent with legacy adapter as tool registry agent Agent( llm_servicellm, tool_registrytools, # LegacyVannaAdapter is a ToolRegistry user_resolverSimpleUserResolver(), configAgentConfig() ) # NEW: Create and run server server VannaFastAPIServer(agent) if __name__ __main__: # Run with: python your_script.py # Or: uvicorn your_module:server --host 0.0.0.0 --port 8000 server.run(host0.0.0.0, port8000)LegacyVannaAdapter 做了什么依据 adapter.py 实现继承ToolRegistryAgentMemory构造时自动把存量VannaBase方法注册为工具通过LegacySqlRunneradapter.py把vn.run_sql()包装为run_sql工具对 user 与 admin 组开放将vn.get_training_data()暴露为可搜索记忆search_saved_correct_tool_uses工具可选保存新训练数据save_question_tool_args工具admin 专属保留既有数据库连接与训练数据优点代码改动极小、保留训练数据、可渐进迁移、立即获得 Web UI 与流式能力。限制所有请求共享同一 VannaBase 实例用户感知有限无法利用行级安全缺少部分高级特性。6.3 策略二全量迁移到新架构MIGRATION_GUIDE.md 展示了新旧写法对照旧式多继承ChromaDB_VectorStore OpenAI_Chat、vn.train()vn.generate_sql()的写法全部替换为UserResolverToolRegistryAgentVannaFastAPIServer数据库连接改为SqlRunner注入如PostgresRunner(host..., dbname..., user..., password..., port5432)训练数据从向量库 vn.train()改为系统提示词 Context Enrichers RAG 工具。优点全部新特性、真正的用户感知、更强安全与权限、生产就绪架构。代价需重写代码、改造训练数据方案、学习曲线更陡。迁移决策速查来自 MIGRATION_GUIDE.md需求推荐策略最小改动快速迁移策略一Legacy Adapter全面使用新特性策略二全量迁移同时支持新旧代码先策略一再渐进迁移新项目策略二全量迁移七、适用场景依据 README.mdVanna 2.0 特别适合数据类应用需要自然语言交互界面的数据分析应用多租户 SaaS需要用户感知权限的租户隔离场景团队协作希望直接使用预置 Web 组件 后端的一体化方案企业环境有安全与审计合规要求的内部系统富流式响应需求需要实时返回表格、图表、SQL 的应用已有鉴权体系需要复用现有登录认证系统的集成场景八、相关资源导航迁移完整步骤MIGRATION_GUIDE.mdAgent 核心实现src/vanna/core/agent/agent.py、src/vanna/core/agent/config.py工具系统src/vanna/core/tool/base.py、src/vanna/core/registry.py、src/vanna/tools/run_sql.py用户与鉴权src/vanna/core/user/resolver.py、src/vanna/core/user/models.py服务端集成src/vanna/servers/fastapi/routes.py、src/vanna/servers/fastapi/app.py前端组件frontends/webcomponent/src/components/vanna-chat.ts存量迁移适配src/vanna/legacy/adapter.py数据库/LLM 集成按需查阅 src/vanna/integrations安装与依赖声明pyproject.toml赞分享人工智能AI AgentRAG数据库后端数据可视化【免费下载链接】vanna Chat with your SQL database . Accurate Text-to-SQL Generation via LLMs using Agentic Retrieval .项目地址https://gitcode.com/GitHub_Trending/va/vanna点击查看免费下载相关推荐Bindu Speech-to-Text 实战用 Gemini 2.0 Flash 构建 A2A 语音转写 AgentBindu Speech to Text 实战用 Gemini 2.0 Flash 构建 A2A 语音转写 Agent 本文基于 Bindu 仓库中的 spesmolagents Text-to-SQL 实战用 CodeAgent SQLAlchemy 构建会写 SQL 的智能体smolagents Text to SQL 实战用 CodeAgent SQLAlchemy 构建会写 SQL 的智能体 本文是一份基于 smolage人工智能AI AgentAgent 框架工具调用代码智能体MCP ClientsAgent 沙箱AG-UI Ruby SDK 实战指南用 ag-ui-protocol 构建 Agent-User 交互服务端AG UI Ruby SDK 实战指南用 ag ui protocol 构建 Agent User 交互服务端 ag ui protocol 是 AG UI人工智能AI Agent上一篇CodeWhale simplify 技能完整指南3 步安全给代码瘦身附避坑自查清单下一篇老 Mac 装新版 macOS 实战用 OpenCore Legacy Patcher 顺利接投影仪与多屏创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考