企业官网建设流程全解析

WrenAI 文本转SQL快速上手：让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

WrenAI 是一个开源的文本转SQL（text-to-SQL）与 GenBI 引擎，AI 代理通过它把自然语言问题变成可信的 SQL 和可分享的数据看板，覆盖 20+ 数据源。这篇安装教程与使用指南写给想把 text-to-SQL 接进自己项目的数据工程师和开发者。

快速开始：四步装好 WrenAI

环境要求一句话：Python 3.11+；希望用 Claude Code、Cursor 这类 AI 客户端代劳的话，再装个 Node.js/npm。不需要 Docker，也不需要云服务。

1. 安装 CLI

pip install "wrenai[postgres,memory]" # 核心引擎 + Postgres 连接器 + 本地记忆

核心包自带 DuckDB，本地文件可直接查；其他数据源按连接器追加，如wrenai[bigquery]、wrenai[snowflake]。

2. 验证安装

wren version # 输出一行 wrenai 版本号即成功

3. 给 AI 客户端装驱动（可选）

npx skills add Canner/WrenAI # 安装约 50 行的发现桩

它会自动探测已装的 AI 客户端。工作流指南不随桩全量安装，代理之后用wren skills get <name>按需拉取，内容始终与 CLI 版本一致。

4. 跑通第一条查询

不走 AI 客户端的最短路径是四条命令：

wren context init # 生成 wren_project.yml 和 models/ 骨架 wren profile add my-db --interactive # 录入并保存一个命名连接

wren context build # 把 YAML 编译成 target/mdl.json wren --sql 'SELECT COUNT(*) FROM "orders"' # 通过语义层执行查询

用 AI 客户端的话更省事：在项目目录里对它说“用 Wren 把我的 Postgres 建起来”，代理会自动执行 onboarding 流程——检查环境、建连接、搭项目、跑通首条查询。

功能拆解

MDL 语义层：SQL 为什么写得对

MDL（Modeling Definition Language）是一组 Git 友好的 YAML：模型、列、关系、视图、cube，描述的是数据“意味着什么”，而不只是“存在哪里”。wren context build把它编译成target/mdl.json，之后每条 SQL 都先对着这份清单做规划与 dry-plan 校验，出错时返回带提示的结构化错误。效果是同一个业务词（比如 revenue）在所有查询里含义一致，代理继承的是业务定义，而不是靠猜。

Memory：越用越准的本地记忆

原理是在本地维护一套 LanceDB 索引，配本地 embedding，不依赖外部向量服务。wren memory index建模式索引；wren memory fetch -q "..."按模式文本大小自动选策略——小于 3 万字符直接返回全文，更大则走向量检索取相关片段。每次成功的“问题→SQL”对都可以用wren memory store --nl "..." --sql "..."存下，下次同类问题wren memory recall会按语义相似度把旧查询捞回来当参考。

GenBI 看板：把一次回答变成可分享的链接

wren genbi build生成构建指令，代理据此在apps/<name>/写出浏览器端应用（由 wasm 引擎驱动，数据快照后纯前端运行），wren genbi verify做文件与密钥扫描预检，wren genbi open本地预览，wren genbi deploy一条命令发布到你自己的 Vercel 或 Cloudflare Pages 账号，返回可分享 URL。部署 token 只从~/.wren/.env读取，不会出现在命令行里。

实战走一遍：用 DuckDB 问数五步

场景：一个装了 DuckDB 数据库的目录（官方示例用的 jaffle_shop 电商样例最方便）。

第一步，登记连接。浏览器表单比手敲省事，填 duckdb 类型和数据库所在目录，wren profile debug可验证连通性：

wren profile add jaffle-shop --ui # 浏览器表单录入连接

第二步，建项目并锁定连接。

wren context init # 生成项目骨架 wren context set-profile jaffle-shop # 本项目从此只用这条连接

绑定后，别处执行wren profile switch不会把本项目查询导流到别的库。

第三步，描述表。在models/下为customers、orders各写一个metadata.yml（列名、类型、主键），在relationships.yml声明两表的多对一连接。💡 这一步可以直接让 AI 代理按 generate-mdl 指南自动探查库结构并生成，写完跑wren context validate校验。

第四步，编译并建索引。

wren context build # 编译 manifest wren memory index # 建立模式检索索引

第五步，提问。在代理里直接问“哪 5 个客户的终身价值最高？”。代理内部依次执行：wren memory fetch取相关表结构、wren memory recall找相似历史查询、写 SQL、wren --sql "..."执行，最后把成功的那对存入记忆。同一个问题再问，答案会更快更稳。

常见问题速查

首次执行wren memory命令卡住近一分钟（macOS）原因：约 800MB 的原生库（lancedb 与 torch）首次加载会触发 macOS 一次性 XProtect 安全扫描。 修复：等它跑完即可，仅每次安装或全新虚拟环境发生一次；装完可先手动跑一条 memory 命令“烧掉”这次等待。

pip install wrenai很慢或超时原因：部分网络环境访问 PyPI 源不畅，HuggingFace 模型下载同样可能超时。 修复：改用国内镜像源安装，并按 README 提示设置 HuggingFace 镜像环境变量后再执行 CLI。

SQL 报 table not found原因：查询走的是 MDL 语义层，对象名应是模型名而非物理表名；也可能是 manifest 还没编译。 修复：先执行wren context build，SQL 里改写模型名。

GenBI 部署成功，打开链接却显示 401原因：Vercel 新项目默认开启部署保护，未登录访问被拦。 修复：在 Vercel 项目的 Deployment Protection 设置中关闭 Vercel Authentication。

下一步

• 想要可分享的报表：按 GenBI 指南 走一遍wren genbi全流程；想让 Claude Desktop、Cursor 等 MCP 客户端也能查数，执行wren serve mcp启动进程内 MCP 服务器。
• 日常命令与参数查 CLI 参考，各数据源连接字段见 连接格式参考。

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