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 编辑器，查表名、回忆 status 字段里哪几种值算"完成"，二十分钟后把数字发过去。第二天，类似的问题又来一遍。WrenAI 就是针对这类工作设计的：它是一个开源的 GenBI（生成式 BI）引擎，把自然语言问题变成受治理的 SQL 和查询结果（自然语言转 SQL），并支持 PostgreSQL、Snowflake、DuckDB、ClickHouse、Databricks 等 22 个以上数据源。

它和"套壳 text-to-SQL"的区别在底层：WrenAI 把你的业务含义沉淀成一层叫 MDL（Modeling Definition Language）的语义层——表、字段、关系、指标全部是可 review 的 YAML 文件，AI 生成的 SQL 会先对着这层做计划和校验，再交给数据库执行。

10 分钟跑通 WrenAI 本地部署

WrenAI v5 是"CLI + AI agent"的组合，不需要 Docker，也没有独立的 Web 后端。环境只要两样：Python 3.11 及以上；如果你想让 AI agent 帮你操作，再装 Node.js 和 npx。

想读源码的话，把仓库拉下来看看（运行本身不依赖源码）：

git clone https://gitcode.com/GitHub_Trending/wr/WrenAI

然后按顺序执行，从安装到可查数一条流水线走完：

pip install "wrenai[memory,main]" # memory=语义记忆，main=交互界面 wren version wren profile add mydb --ui # 建连接配置，会打开浏览器表单 wren profile list # 确认配置已激活 wren profile debug # 测连接是否通

表单里填数据源类型和连接参数。DuckDB 是内置的，选它只需要填本地文件路径；连其他库要先装对应 connector，例如pip install "wrenai[postgres]"。每个数据源具体要哪些字段，直接跑wren docs connection-info postgres，输出和已安装版本严格一致，不用背。支持的数据源和 extra 对照见 docs/core/guides/connect.md。

最后建项目并绑定连接：

mkdir my-wren && cd my-wren wren context init # 生成项目骨架 wren context set-profile mydb # 锁定项目使用该连接

wren context init会在目录里生成一套 YAML：wren_project.yml、models/下每张表一个文件夹、relationships.yml存连接关系、knowledge/放业务知识。项目此时已经建好，但语义模型还是空的，下一步让 agent 来生成。

三个典型场景：问数、建模、看图表

问数：自然语言直接到 SQL

你不手写 SQL，由 AI agent（Claude Code、Cursor、Codex 等）来操作。先给 agent 装一个发现桩，它会自动探测你本地装了哪些客户端：

npx skills add Canner/WrenAI

之后在项目目录里直接用自然语言提问，比如"这个月下单超过一次的客户有几个？"。agent 会先用wren memory fetch找相关表和字段，再用wren memory recall查相似的历史提问，然后用 MDL 里的模型名（而不是裸表名）写 SQL，最后用wren --sql执行。不装 agent 也行，wren ask "<问题>" --guided能把问题包装成结构化提示词，喂给任意模型。

问得越多越准。每个问对的"问题-SQL"对都可以用wren memory store存进记忆，下次类似问题直接命中。

建模：把业务含义写进 MDL

MDL 是 WrenAI 的语义层。第一次接入数据库时，让 agent 用generate-mdl指南探测表结构和类型，逐张写出模型 YAML，并根据外键推断连接关系；你要做的只有给关键字段补描述。描述写得好，AI 的问数和记忆检索都会更准。

"营收"到底是amount还是credit_card_amount？这类口径规则写进knowledge/rules/下的 Markdown 文件，agent 生成 SQL 前会先读它。固定指标可以做成 cube，之后用wren cube query --cube revenue --measures total --time-dimension "order_date:month"直接查聚合结果。

看图表：一条命令出可分享的仪表盘

有了答案之后，让 agent 把它变成看板。它依次跑wren genbi build（组装一个纯浏览器端应用）、wren genbi verify（预检）、wren genbi open（本地预览，默认 http://127.0.0.1:8848/）。想要可分享的链接，把VERCEL_TOKEN写进~/.wren/.env，再跑wren genbi deploy即可。不部署也没关系，本地预览就够团队内部用。

实操：从一个问题到查询结果

用一个小例子走完整流程，全程在 agent 对话里完成。

第一步，准备数据。可以连自己的库，也可以直接用内置的 jaffle_shop 示例（一个电商样例，不需要你有现成数据库）。对 agent 说一句"用 Wren 基于内置 jaffle_shop 搭一个 DuckDB 环境"，它会建好本地样例库和连接 profile。

第二步，生成 MDL。对 agent 说：

Use the /wren skill to generate the MDL for the customers and orders tables, skipping the raw_* seeds and stg_* views.

agent 会拉取generate-mdl指南，探测 schema，写出models/*/metadata.yml和relationships.yml，最后依次跑wren context validate、wren context build、wren memory index。用wren context show和wren memory status确认即可。

第三步，提问："按累计订单金额，前 5 名客户是谁？"agent 内部走五个动作：

wren memory fetch --query "top customers by total order amount" wren memory recall --query "top customers" wren dry-run --sql 'SELECT ...' # 先校验，不返回数据 wren --sql 'SELECT c.name, SUM(o.amount) ...' wren memory store --nl "前5名客户" --sql '...'

结果以表格形式直接打印（下面是示意数据）：

第四步（可选），继续追问："把这个做成柱状图仪表盘，加一个按 status 过滤的控件，本地预览。"agent 跑 genbi 流程，8848 端口的页面出来后，你可以继续用自然语言调整，比如"改成折线图"。

完整的 15 分钟走查（含建库细节）在 docs/core/get_started/quickstart.md，常用命令速查见 docs/core/reference/cli.md。

常见卡点速查

下一步的三条路线

1. 换成你的真实数据：wren profile add建好生产库的 profile，让 agent 生成 MDL；如果项目里有 dbt，可以直接wren context import dbt --project-dir ./my-dbt从 dbt 产物导入，少手工一步。
2. 把口径钉死：高频指标做成 cube，容易出错的口径（单位、枚举值、去重规则）写进knowledge/rules/。这一步做的越细，agent 出错的概率越低，你 review 的时间越少。
3. 接进你自己的 agent：开源部分自带 MCP server，以及 wren-langchain 和 wren-pydantic 两个 SDK，可以把"问数-出 SQL-拿结果"这套能力嵌进你自己的 LangGraph 或 Pydantic AI 应用里。

【免费下载链接】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