自然语言变可信 SQL：WrenAI 用 5 步搭出带 LangChain 的 Text-to-SQL 查询系统-编程实验室

自然语言变可信 SQL：WrenAI 用 5 步搭出带 LangChain 的 Text-to-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，但挑错了表、JOIN 条件靠猜、"营收"到底算amount还是 payments 表里的字段全靠蒙。问题不在模型能力，而在于它拿到的只有表结构，却没有你的业务口径。WrenAI 就是为此而生的开源项目：一个带语义层的 GenBI 引擎，配合 LangChain 官方集成的 wren-langchain，让自然语言查询直接落到你现有的数据库上，而且 22+ 数据源（PostgreSQL、Snowflake、BigQuery、ClickHouse、Databricks 等）都能接。

它凭什么让 SQL 变"可信"：先给上下文，再让模型动手

普通 Text-to-SQL 的做法是把 schema 塞进 prompt，让模型看着表名硬猜。WrenAI 换了个思路：在模型和数据库之间垫了两层东西。

MDL 语义层（Modeling Definition Language）：用 Git 友好的 YAML 文件描述模型、字段、表间关系，外加你批准的指标定义（cube）和业务规则（knowledge/目录下的说明文件）。"营收"、"活跃客户"这些词在哪个文件里是什么口径，一查便知，而不是埋在 prompt 里。
AI 上下文层（记忆系统）：本地 LanceDB 向量索引存下每次成功的"自然语言 → SQL"配对。下次有人问类似问题，系统先召回历史答案给模型参考，越用越准。

模型写完 SQL 也不是直接执行：引擎会做dry-plan 预演校验，查错表、JOIN 不成立会返回带提示的结构化错误，让模型自己改，而不是一脸自信地返回错误数字。下面是整体架构：

从零跑通：5 个动作，每个动作做完都有可验证的结果

整个流程是"agent 驱动"的：你只负责下达指令和确认，具体操作由你的 AI 编码助手（Claude Code、Cursor、Codex 等）调 Wren CLI 完成。

第 1 步：装好 CLI 和 skill，验证`wren version`

一条pip install wrenai装核心（内置 DuckDB，无需额外数据库），再跑npx skills add Canner/WrenAI给你的 AI 客户端装一个约 50 行的"wren"发现桩——它教 agent 如何按需从 CLI 拉取工作流指南。做完这步，你在终端敲wren version能看到版本号，就说明环境就绪。

第 2 步：用浏览器表单建连接 profile

运行wren profile add my-db --ui，会在浏览器里弹出一个表单，选数据源、填连接信息即可，不用手写 YAML。支持的连接方式在 docs/core/guides/connect.md 有完整清单，连接器实现见 core/wren/src/wren/connector/。做完这步，wren --sql "SELECT 1"能返回一行结果，连接就通了。

第 3 步：初始化项目并生成 MDL 模型

新建目录跑wren context init，会生成models/、cubes/、relationships.yml、knowledge/等目录骨架；然后把 profile 绑定到项目（wren context set-profile），这个绑定写死在项目配置里，之后全局切别的连接也不会误伤当前项目。接着对 agent 说一句"用 wren skill 探索数据库，为 customers 和 orders 生成 MDL"，它会自己探查表结构、推断外键关系、写模型 YAML 并跑校验。做完这步，wren context show能看到完整的模型清单，仓库里 examples/v5-jaffle/ 下有一份成品示例可以直接对照。

第 4 步：给项目喂业务上下文，建立记忆索引

这一步最容易被跳过，也是回答质量的分水岭。让 agent 执行 enrich-context 流程，把"营收 = orders.amount，不是按支付方式拆分的那些列"这类口径写进knowledge/rules/，再跑wren memory index建立向量索引。做完这步，wren memory status会显示索引里存了多少条可召回的示例。

第 5 步：开始提问，并把答案变成可分享的看板

直接在 agent 里问"哪个客户季度销售额最高？"，后台流程是：召回相关表 → 检索相似历史查询 → 基于 MDL 写 SQL → 校验执行 → 把成功的问答存回记忆。想进一步把答案变成果然可分享的看板，说一句"部署到 Vercel"即可，agent 会构建浏览器端应用并给出分享链接（细节见 docs/core/guides/genbi.md）。如果你用的是 LangChain / LangGraph 技术栈，sdk/wren-langchain/ 提供了现成集成：WrenToolkit.from_project一行拿到工具集，三行代码就能挂进你自己的 agent，示例代码在 sdk/wren-langchain/examples/。

进阶与避坑：这几个细节没人提前告诉你

DuckDB 的 url 填目录，不是 .duckdb 文件。profile 里填的是包含数据库文件的目录绝对路径，填成文件路径是新手最常见的连接失败原因，wren profile debug可以看到解析后的配置快速定位。
第一条wren memory命令会"假卡住"几十秒。它在首次加载 lancedb、torch 等约 800MB 的原生库，macOS 首次执行还会触发 XProtect 安全扫描。这是预期行为，跑完一次之后一切正常——演示前可以先手动跑一次热身。
别让中间表进模型。用 dbt 这类工具时，raw_*、stg_*中间层不要建模，一个业务概念只保留一张表，否则模型面对两张口径相近的表会自己挑错，这种错不会报错，只会算错数。
改了 MDL 文件必须重建。编辑了models/或relationships.yml之后要依次跑wren context validate、wren context build、wren memory index，否则查询还在用旧的编译产物。
部署到 Vercel 的预览链接默认会返回 401。这不是部署失败，而是新项目默认开启了登录访问，在项目的 Deployment Protection 设置里关闭 Vercel Authentication 即可公开访问。

它适合谁，又不太适合谁

适合：已有生产数据库、想让业务方用自然语言自助取数、且团队里已经在用 AI 编码助手的场景——它复用你现成的 agent，不要求再学一套新工具；也适合需要把指标口径版本化、可评审、可进 Git 的团队。不太适合：只是想对着单个 CSV 画一张图，或者只想让模型"裸猜"SQL、对准确性没要求的一次性查询——那些场景直接问模型就够了。另外注意开源边界：行级/列级权限控制、用户组访问控制、托管 GenBI UI 属于商业版能力，选型时如果安全合规依赖 RLS/CLS，要按 docs/core/concepts/oss_vs_commercial.md 里的边界评估。

WrenAI 的价值在于把"SQL 写对"这件事从模型的能力问题，变成了工程上可评审、可回归的上下文问题。把https://gitcode.com/GitHub_Trending/wr/WrenAI克隆下来，先按上面的 5 步用样例库跑通第一条自然语言查询，剩下的交给你的 agent。

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

自然语言变可信 SQL：WrenAI 用 5 步搭出带 LangChain 的 Text-to-SQL 查询系统