WrenAI 完整教程：十分钟跑通自然语言文本转 SQL 查数

WrenAI 完整教程十分钟跑通自然语言文本转 SQL 查数【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI业务同学又发消息来了“上个月各地区的销售额拉个图给我。”你正要去翻查询工具写 SQL突然觉得这个问题为什么不直接丢给一个程序WrenAI 干的就是这件事——把自然语言查数据库的提问变成可执行的 SQL文本转 SQL和图表结果。 项目速览它是什么、解决什么问题WrenAI 是一个开源的生成式 BIGenBI引擎核心是所谓的“开放上下文层”上面接你的 AI 编码助手Claude Code、Cursor、ChatGPT 或内部 copilot 都行下面连 PostgreSQL、BigQuery、Snowflake、DuckDB、ClickHouse、Databricks 等 20 多个数据源中间是两层东西——MDL 语义模型你维护的表关系和口径定义与 Memory 记忆系统验证过的问数对和业务规则。所有定义都是可以进 git 的 YAML 和 Markdown没有黑盒。三个核心卖点受治理的文本转 SQLSQL 先对着 MDL 语义层做计划、干跑校验再执行报错带结构化提示减少“看起来对但算错了”的情况语义长在 schema 之外口径、枚举含义、验证过的问答都存成文件用得越多答得越准从答案到仪表盘一句话生成浏览器端 GenBI 图表并部署到你自己的 Vercel 或 Cloudflare Pages。源码在仓库的core/wren/Python CLI和core/wren-core/Rust/DataFusion 执行引擎clone 下来可以直接读只想用的话走 PyPI 就行具体流程见官方 快速上手文档。 十分钟跑通安装与启动命令这版 WrenAI 是 agent 驱动的设计没有 Docker 容器要拉也没有微服务要起。前置条件只有 Python 3.11 和一个你顺手的编码 agent用 npx 需要 Node。你真正要敲的只有下面两组命令# 可选想看源码、参与开发就 clone只使用 CLI 的话 PyPI 即可 git clone https://gitcode.com/GitHub_Trending/wr/WrenAI # 安装 CLI。postgres 是数据源连接器memory 是语义记忆main 带浏览器配置表单 pip install wrenai[postgres,memory,main] # 给你的编码 agent 装一个发现 stub自动探测 Claude Code / Cursor / Cline npx skills add Canner/WrenAI然后在项目目录打开 agent只说一句话“用 Wren 技能帮我配置我的 Postgres 数据库。”它会自己走完 onboarding建连接 profile、搭项目骨架、跑第一条查询。手头没有数据库时可以说“用自带的 jaffle_shop 示例数据集”整条流程照样跑通。如果不想让 agent 代劳这两条命令是核心wren profile add sales-db --ui # 浏览器表单里填数据源和连接信息 wren profile debug # 验证连接密钥自动打码profile 存在~/.wren/profiles.yml。之后用wren context set-profile sales-db把 profile 绑到项目上全局 profile 再怎么切换这个项目的查询也不会指错地方。 工作流实操完成一次真实的数据分析以“回答业务同学的‘各地区销售额’”为主线全流程是四步。第一步连接数据源就是上面的wren profile add --ui加wren profile debug。想知道某个数据源要哪些连接字段敲wren docs connection-info postgresCLI 直接列出来不用背字段名。第二步自动建模让 agent 生成 MDL在项目目录里对 agent 说“给这个数据库搭一个 MDL 项目”。它会逐表内省结构、规范化类型、从外键和命名习惯推断关联在models/下每张表写一个模型 YAML拿不准的地方类似命名、含糊的外键会反问你一句。最后执行编译和索引wren context build wren memory index生成物全是可 review 的 YAMLagent 推错了一个关联打开relationships.yml改掉即可。第三步自然语言提问SQL 自动生成现在直接问“每个城市有多少客户下过订单”agent 内部走一条固定流水线wren memory fetch取相关表和字段 →wren memory recall找相似的历史问数对 → 对着模型名写 SQL → 执行 → 把验证过的问答存进knowledge/sql/。你也可以脱离 agent 直接跑wren --sql SELECT city, SUM(amount) AS total FROM orders GROUP BY city -o table答错了不用改模型往knowledge/rules/里写一条规则比如“收入必须用 net_revenue不是 gross_revenue”再跑一次wren memory index。这套质量闭环的完整做法见官方 Refine answer quality 指南。第四步把答案变成 GenBI 仪表盘答案满意后说一句“把它做成可以按城市筛选的仪表盘部署到 Vercel。”agent 会执行wren genbi build→ 本地预览wren genbi open默认 http://127.0.0.1:8848→wren genbi deploy最后给你一个可分享的 URL。数据有两种模式snapshot在构建时冻结数字纯浏览器运行、不需要后端适合交付的报表live查看时实时回源查询适合必须保鲜的看板。改图也是说人话“这张改成柱状图、去掉城市筛选”agent 重新构建即可。仪表盘底层是wren-core-wasm查询全部在浏览器里执行。 参数速查哪些旋钮值得调WrenAI 没有一整页的配置文件真正影响产出质量的旋钮是这几个参数 / 位置作用调优建议pip extras如wrenai[postgres,memory]数据源连接器与功能开关连接器按需装memory提供向量化语义召回不装则退化为关键词匹配models/*/metadata.yml的 descriptionagent 理解表字段的依据用业务语言写“收入是扣除退款后的净额”别复读字段名描述越好召回越准knowledge/rules/*.mdschema 里看不见的业务规则口径、规范表、默认过滤一个主题一个文件##作标题agent 选错表时优先在这里补规则wren memory index重建本地记忆索引改动 MDL 或 knowledge 后必须重跑否则召回不到新内容--time-dimensioncube 查询预聚合的时间粒度格式name:granularity时间粒度含糊是聚合错误的高发原因按月/周/季写清楚GenBI 数据模式snapshot / live仪表盘的数据从哪里来分享型报表用 snapshot必须实时更新的看板用 live三条实战建议第一次提问前确保wren context build和wren memory index都跑过跳过的话 agent 只能对着裸 schema 猜某个指标被反复问月营收、DAU把它提升成 cube度量和维度声明一次agent 走结构化查询不用每次手写 GROUP BYgit add knowledge/提交一下验证过的问答对就是文件新环境下次索引时自动继承同一份经验。 踩坑指南三个最高频问题一、连接能建、查询报错现象wren profile add顺利完成但wren --sql SELECT 1失败。原因最常见是云数据库 IP 白名单没放行、SSL 设置不匹配其次是凭据写错。处理跑wren profile debug看解析后的配置密钥打码逐项核对凭据和网络可达性云库先查 IP allowlist 和 SSL 要求。二、agent 选错表、算错口径现象问“上个月卖了多少钱”它用了毛收入字段或者查了废弃的customers_v3表。原因这类业务知识不在 schema 里agent 只能猜。处理写进knowledge/rules/“收入必须用 net_revenue”“分析用 customers 表”再执行wren memory index仍然反复错的高频指标提升成 cube 或 view。三、仪表盘部署后打开是 401现象wren genbi deploy提示成功浏览器打开 URL 却返回 401。原因新建的 Vercel 项目默认开启 Vercel AuthenticationDeployment Protection拦截所有未登录访问者。处理在 Vercel 控制台 Project → Settings → Deployment Protection 里关闭 Vercel Authentication只想要私密链接的话保持开启即可。 融入你的工作流想让查数不止于“能问”还有几个集成点值得知道MCP 服务wren serve mcp把项目的查询run_sql、dry_run、query_cube、schema、知识工具暴露给任意 MCP 客户端如 Claude Desktop、Cursor默认只读加--allow-write才允许存问答对框架 SDKwren-langchain和wren-pydantic把同一套上下文层做成 LangGraph / Pydantic AI 里的工具不用 shell out 调 CLI自动化报表wren --sql完全脚本化把月报 SQL 放进 cron 或 CI 任务每周重跑一次wren genbi build就有一份自动翻新的快照仪表盘浏览器端嵌入wren-core-wasm让 MDL 查询在纯客户端跑无服务器依赖适合给内部工具塞一个查询框。现在就能动手先执行pip install wrenai[memory,main]拿一个本地 CSV 或 DuckDB 文件让 agent 搭好 MDL再把你一直想问的那个业务问题丢给它答案对了就让它存进 memory。跑完这一轮你自然会感受到“治理过的文本转 SQL”和“让 agent 瞎猜 SQL”之间的差别。【免费下载链接】WrenAIGenBI (Generative BI) for AI agents, an open-source, governed text-to-SQL through an open context layer that turns natural-language questions into trusted dashboards, charts, and SQL across 20 data sources, such as BigQuery, Snowflake, PostgreSQL, ClickHouse, Amazon Redshift, Databricks and more.项目地址: https://gitcode.com/GitHub_Trending/wr/WrenAI创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考