Wren AI 完整上手指南：3 步接入数据库，让 AI 用自然语言写出可信的 SQL-港品优选

Wren AI 完整上手指南：3 步接入数据库，让 AI 用自然语言写出可信的 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 Agent 直接写 SQL 不难，难的是它写的 SQL 你敢不敢用。表结构它能看懂，但status = 4是退款、"营收"该用哪个字段、哪张表才是权威版本——这些只有你的团队知道。结果就是 Agent 自信满满地给出一个"看起来对"的答案，直到你核对数据才发现错了。

Wren AI 要解决的就是这个问题。它是一个开源的生成式 BI（GenBI）引擎，核心能力是受治理的 text-to-SQL：自然语言问题进来，先经过语义层（MDL）规划、再经 dry-plan 校验，最后才在数据源上执行。支持 PostgreSQL、BigQuery、Snowflake、ClickHouse、Amazon Redshift、Databricks、DuckDB 等 20 多种数据源，并且生成的答案可以一键部署成可分享的仪表盘。

它凭什么比"直接让 LLM 写 SQL"更靠谱

Wren AI 的关键词不是"生成"，而是"治理"。三件事构成了它的地基：

语义层 MDL：用 Git 友好的 YAML 文件描述你的数据"意味着什么"——模型、字段、表关系、计算字段、指标（cubes）。Agent 不再对着裸 schema 猜，而是按团队确认过的定义来规划查询。
记忆层 Memory：历史确认过的"自然语言 → SQL"对存在项目文件里，配合本地向量索引（LanceDB）做语义召回。你问过一次"每月营收"，下次换个问法它也能找到那次的答案。
受治理的执行：dry-plan 校验、行数限制、带提示的结构化报错，把 Agent 生成的 SQL 圈在护栏内执行。

这三层都落在普通文件里，可以 review、可以 diff、可以随代码一起版本管理——不锁在任何厂商的界面里。

如架构图所示，上层的 Claude Code、Cursor 等各类 AI Agent 通过查询进入 Wren AI 的开放上下文层（MDL + Memory + 受治理访问），再由它以方言 SQL 执行到底层数据源。访问方式有 CLI、Python SDK 和 WASM 三种，对应命令行、Agent 编排和浏览器端仪表盘三个场景。

快速体验：用示例库 15 分钟跑通第一个问题

官方给了一条不需要自己数据库的路径——基于 dbt 的 jaffle_shop 示例库 + DuckDB，全程本地，约 15 分钟。完整步骤见 docs/core/get_started/quickstart.md，核心命令只有四步：

1. 安装 CLI（默认自带 DuckDB 连接器）

pip install "wrenai[memory,main]" wren version

2. 建连接 profile 并初始化项目

wren profile add jaffle-shop --ui # 浏览器表单里填 DuckDB 目录 wren context init # 生成 models/ views/ cubes/ knowledge/ 项目骨架 wren context set-profile jaffle-shop

3. 让 Agent 生成 MDL

装一个约 50 行的技能桩（自动识别 Claude Code、Cursor 等客户端），然后在项目目录里对 Agent 说"用 Wren 探索 jaffle_shop 的 customers 和 orders 表，生成 MDL"。它会内省表结构、推断关系、写好模型文件，并执行wren context validate和wren context build完成校验与编译。

4. 开始提问

"本月下单超过一次的客户有多少？"

Agent 会按固定套路工作：wren memory fetch取相关表字段 →wren memory recall找相似历史查询 → 基于 MDL 写 SQL →wren --sql执行 →wren memory store存入本次问答。问得越多，召回越准，系统会越用越顺。

不想搭这套流程的话，仓库里还有一个开箱即查的项目示例 examples/v5-jaffle/，可以直接看一个完整的 MDL 项目长什么样。

接你自己的数据库：一条 pip 命令加一个 profile

接入自有数据源时，流程与上面完全一致，只是多装一个连接器 extra：

pip install "wrenai[postgres,bigquery,snowflake,clickhouse,redshift]" wren profile add my-db --interactive

每个连接器需要的字段名不必背，CLI 会按当前安装的版本生成：wren docs connection-info postgres即可。所有连接器的实现集中在 core/wren/src/wren/connector/，支持列表和字段规范见 docs/core/guides/connect.md。

从一条答案到一个可分享的仪表盘

text-to-SQL 只解决了一半问题，另一半是"这个答案我想发给别人看"。Wren AI 的 GenBI 能力就是干这个的：对 Agent 说"把上面的营收分析做成可筛选的仪表盘并部署到 Vercel"，它会走 genbi 工作流：

wren genbi build用 MDL 上下文和固定版本的wren-core-wasm生成应用规格；
Agent 在apps/<name>/下写一个自包含的浏览器端应用并快照数据，纯前端运行、无需后端；
本地预览，你用自然语言让它改（"换成柱状图"、"去掉状态筛选"）；
确认无误后wren genbi deploy部署到你自己的 Vercel 或 Cloudflare Pages 账号，返回一个可分享的 URL。

仪表盘跑在wren-core-wasm（WebAssembly 构建）之上，查询仍在浏览器端执行，数据不经过任何第三方服务——连接信息始终在你手里。

哪些知识真正决定答案质量

工具本身只是放大器，真正拉开差距的是你喂给它的上下文。Wren AI 把这部分也做成了文件，方便持续经营：

models/*/metadata.yml：给表和字段补上业务描述，描述越好，检索越准；
knowledge/rules/：业务规则与命名约定，比如"营收一律指订单 amount 字段，退款单要剔除"；
knowledge/sql/：确认过的自然语言-SQL 对，是 Agent 的 few-shot 示例库，机制细节见 docs/core/concepts/memory_system.md；
relationships.yml：修正表连接条件——错误的关系是导致静默错答的头号原因。

改完任何文件，跑一遍wren context validate && wren context build && wren memory index即可生效。MDL 的完整概念说明在 docs/core/concepts/what_is_mdl.md，命令速查见 docs/core/reference/cli.md。

开始之前，先想清楚一件事

Wren AI 适合"业务定义散落在人脑和文档里、Agent 反复猜错"的团队；如果你只是要从单个 CSV 出一次图表，它的上下文建设成本就不划算了。它的开源边界也很清楚：MDL 语义层、受治理 text-to-SQL、MCP 服务、CLI 和 20+ 连接器全部 Apache-2.0 免费，行级/列级安全、托管 UI 等属于商业版。

仓库里已经有一个能问出答案的最小路径：装 CLI → 建 profile → 让 Agent 生成 MDL → 问第一个问题。今晚就可以在你的数据库上跑起来，看看它第一次生成的 SQL 和你的定义差了多远——那个差距，就是 Wren AI 能帮你持续缩小的部分。

创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考

企业官网建设流程全解析