WrenAI 文本转SQL实战指南15分钟跑通你的第一个自然语言查询【免费下载链接】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/WrenAIWrenAI 文本转SQL 能把你的大白话问题变成可校验、能执行的 SQL直连 PostgreSQL、DuckDB 等 22 数据源返回结果。按这套步骤走一遍15 分钟装好 CLI 并跑通第一次自然语言查询。适合数据分析师、后端开发和业务运营。项目速览一句话定位面向 AI Agent 的开源 GenBI 引擎核心是受管的文本转SQL外加一层可信的 AI 上下文。核心能力一受管文本转SQL——生成的 SQL 对着语义层 MDL 做规划并先干跑校验而不只是看起来对。核心能力二把答案变成可部署的看板一键发布到你自己的 Vercel / Cloudflare 账号。核心能力三知识可版本化业务定义、示例、记忆都落成 Git 友好的文件随时可审查。适用人群想让 Agent 产出可信 BI 的数据分析师、做集成的后端开发、要自助取数的业务运营。环境与启动环境依赖很轻一张表说清工具最低版本一句话用途Python3.11运行wrenCLI 与 SDKpip随 Python安装wrenai包Node.js有 npx 即可安装 Agent 发现桩skillsDuckDB1.5.0内置零配置本地数据源随包带一键安装命令路径A# 安装核心包含 DuckDB一条命令装好 CLI 记忆 UI pip install wrenai[memory,main] # 校验安装成功 wren version手动部署命令路径B# 建独立虚拟环境隔离依赖 python3 -m venv ~/.venvs/wren source ~/.venvs/wren/bin/activate # 安装核心包 记忆索引 pip install wrenai[memory,main] # 需要接 PostgreSQL 时再补装对应连接器 pip install wrenai[postgres] # 校验版本 wren version验证环境装好了吗python3 --version # 应 ≥ 3.11 node --version # 有 npx 即可 wren version # 应输出 0.x.x git --version⚠️ 最容易踩的环境坑Windows 用户别直接在 PowerShell 里跑进 WSL2 或 Git Bash 再执行否则路径和 venv 激活都会翻车。核心引擎拆解WrenAI 文本转SQL 的工作方式用输入 → 处理链路 → 输出拆开看就清楚了。输入一句自然语言问题比如本季度销售 Top10 客户。处理链路编号步骤每步一件事记忆检索从本地 LanceDB本地向量库专门存语义向量做检索的数据库里捞出与问题相关的表、列和相似历史查询。上下文装配把 MDLModeling Definition Language建模定义语言用 YAML 描述表/列/关系里的模型、业务规则拼成给大模型看的上下文。SQL 规划基于模型名而非裸表名生成走语义层的受管 SQL。干跑校验用dry-plan在真正执行前先验证 SQL 能否解析、列是否存在。执行落库经 Apache DataFusionRust 写的 SQL 执行引擎把查询打到 22 数据源并取回结果。关键组件各管一摊MDL 语义层描述数据意味着什么是 SQL 规划的事实来源。记忆索引LanceDB存 NL→SQL 成功对和语义向量越用越准。DataFusion 引擎跨 22 数据源的统一执行层。WrenAI 文本转SQL 最小可用配置片段# jaffle-profile.yml连接本地 DuckDB 的最小可用配置 datasource: duckdb # 数据源类型 url: /path/to/jaffle_shop_duckdb # 放 .duckdb 的目录不是文件 format: duckdb # 存储格式动手实操从建库到问出第一个问题全程用零基础设施的 jaffle_shopdbt Labs 的公开电商样例含 customers / orders 两张分析表 DuckDB不用云、不用 Docker。Step 1为本地库建连接档案profile做什么给本地 jaffle_shop 数据库建一个连接档案。怎么操作# 连接信息写成 YAML cat jaffle-profile.yml YAML datasource: duckdb url: /path/to/jaffle_shop_duckdb format: duckdb YAML # 导入并设为可用 wren profile add jaffle-shop --from-file jaffle-profile.yml预期看到什么wren profile list里 jaffle-shop 标为 activewren profile debug显示连接成功。Step 2初始化 Wren 项目并绑定档案做什么建 Wren 项目并把连接锁到项目上。怎么操作mkdir -p ~/jaffle-wren cd ~/jaffle-wren wren context init # 生成项目骨架 wren context set-profile jaffle-shop # 绑定连接档案预期看到什么目录里出现wren_project.yml和models/、knowledge/等文件夹。Step 3让 Agent 生成 MDL 并建记忆索引做什么探索数据库、生成 MDL 模型文件、建语义记忆索引。怎么操作在 Claude Code 等项目目录里输入Use the /wren skill to explore the DuckDB database and generate the MDL for the customers and orders tables. Skip the raw_* and stg_* objects.预期看到什么models/customers、models/orders各出现metadata.ymlwren context build通过wren memory status显示已建索引。Step 4问出第一个自然语言问题做什么用大白话问业务问题拿到受管 SQL 和结果。怎么操作wren memory fetch --query top customers by revenue # 检索相关表列 wren --sql SELECT status, COUNT(*) n FROM orders GROUP BY status -o table预期看到什么终端打印出结果表且wren dry-plan --sql ...能预览规划出的真实 SQL。完整调用链长这样场景落地场景一业务分析师自助取数痛点市场团队要按地区统计 Q4 销售额但没人会写 SQL每次都得找数据组排队。操作路径数据分析师用 WrenAI 建好销售库的 MDL把销售额 amount写进knowledge/rules/。市场同事直接问西部地区哪些产品 Q4 增长最快WrenAI 召回相似历史查询、生成受管 SQL 并返回结果表。把满意的 NL→SQL 对用wren memory store存下下次同类问题秒回。收益取数从排队等数据组降到自己问一句业务同学零 SQL 也能拿数。场景二数据开发调试复杂查询痛点开发要写一张跨 5 张表的对账 SQL裸表名记不住列名写错要等跑起来才报错。操作路径把对账库导入 MDL统一用模型名而非裸表名引用。先wren dry-plan --sql ...干跑规划出的真实 SQL 一眼能查错。确认无误再wren --sql ... -o table落库执行。常用查询存进knowledge/sql/供团队复用。收益列名/关联错误在干跑阶段就暴露省掉反复跑真实查询的时间。场景三把查询变成可分享的看板痛点老板要一份月度营收 订单量看板手动建 BI 报表得排期。操作路径建一个 revenue cubewren cube query --cube revenue --measures total,order_count --time-dimension order_date:month。让 Agent 用 genbi 指南基于该 cube 构建浏览器端看板。本地wren genbi open预览改成柱状图、加状态筛选。配好部署 token 后wren genbi deploy发布拿到可分享 URL。收益从排期建报表变成问一句话就能发链接管理层自主取数。避坑与进阶常见问题速查pip install wrenai慢或失败 → 默认 PyPI 源访问慢 →pip install wrenai -i https://pypi.tuna.tsinghua.edu.cn/simple首次wren memory index卡几十秒 → macOS XProtect 首扫 lancedb/torch 原生库约 800MB→ 装完先跑一次任意wren memory命令预热后续正常。查询返回空或报列不存在 → 没建 MDL 就直接查裸库Agent 缺业务上下文 → 先wren context init→ 让 Agent 生成 MDL →wren context build。改了models/后查询还是旧逻辑 → 没重新编译 manifest →wren context validate wren context build wren memory index。性能调优的三个方向用 cube 预聚合查询走聚合层而非全表扫wren cube query --cube revenue --measures total \ --time-dimension order_date:month给字段写清描述让记忆检索命中更准、上下文更小properties: description: 订单金额销售额口径控制返回行数避免大结果拖慢wren --sql SELECT * FROM orders LIMIT 100 -o table进阶路线入门跑通 jaffle_shop会问问题、会存 NL→SQL读 快速上手。进阶接自己的数据库、建 cube、加业务规则读 连接数据源 与 cube 指南。深度读懂 MDL 与记忆系统、用 SDK 集成到自己的 Agent读 MDL 概念 与 SDK 概览。社区入口官方文档docs/core/CLI 命令参考docs/core/reference/cli.md完整示例项目v5-jaffleexamples/v5-jaffle/Agent 技能说明skills/【免费下载链接】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），仅供参考