Wren AI 在数据技术栈中的定位开放上下文层Open Context Layer的架构成员手册【免费下载链接】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本文以 docs/core/concepts/stack_position.md 为骨架完整讲解 Wren AI 在数据技术栈中的确切位置它不替代数仓、不替代转换管道、不替代既有语义层而是作为位于数据基础设施与 AI Agent 之间的开放上下文层把 Agent 从我能看到 schema提升到我理解业务含义。读完本文你将掌握 Wren AI 的边界、它能提供的四类能力以及在没有语义层、已有 dbt 管道、已有语义层、多数仓等四种存量场景下的落地策略并能在源码层面印证每一处结论。Wren AI 坐落在技术栈的哪一层一句话总结 Wren AI 的定位Wren AI 不替代你的数仓、不替代你的转换管道、也不替代你现有的语义层。它位于数据基础设施与查询数据的 Agent 之间提供 Agent 安全地生成与交付可信 BI 所需的上下文。官方文档用一张分层图说明了这一位置原图见 stack_position.md┌──────────────────────────────────────────────────────┐ │ Your AI agents (Claude Code, Cursor, custom apps) │ └────────────────────────┬─────────────────────────────┘ │ ask questions, get context ▼ ┌──────────────────────────────────────────────────────┐ │ Wren AI - open context layer │ │ MDL · Memory · Skills · Governed execution │ └────────────────────────┬─────────────────────────────┘ │ planned, governed SQL ▼ ┌──────────────────────────────────────────────────────┐ │ Your warehouse, transformation pipeline, files │ │ (PostgreSQL, BigQuery, Snowflake, DuckDB, ...) │ └──────────────────────────────────────────────────────┘Wren AI 上方是提出问题的 Agent下方是存储答案的数据基础设施。Wren AI 处于二者之间负责把我能看到 schema转化为我知道业务的含义。这个上下文概念并非营销话术它在 what_is_context.md 中被明确拆解为五个层次而 Wren AI 负责把它们收拢成一个可检查、可版本化、任何 Agent 都能查询的统一表面上下文层次回答的问题示例状态结构化Structural存在什么数据表、列、类型、键、关系今日已提供语义化Semantic数据意味着什么模型、指标、计算字段、枚举标签、规范表今日已提供业务化Business这家公司是什么意思活跃客户、收入、流失、内部项目名、团队定义今日已提供运维化Operational这些数据应如何被安全使用已批准的连接路径、受认可的查询、查询时治理、禁止计算的内容开发中行为化Behavioral之前什么有效成功的自然语言→SQL 对、示例、反馈、记忆开发中第一层让 Agent 能读数据库中间两层让它懂业务最后两层帮它安全行事并持续改进。它不替代什么边界是设计不是妥协原文明确划定了 Wren AI 的非目标这些边界直接决定了集成方式你的数据仓库Wren AI 不存储任何行数据。你的数仓继续存行Wren AI 只把规划好的 SQL 送去执行。你的转换管道如果你已经用 dbt、自研 Python 或定时 SQL 把原始数据建模成干净的表请继续这样做。Wren AI 读取的是转换后的结果不拥有上游管道。仓库中的docs/core/guides/dbt-integration.md即为此场景而写。你现有的语义层如果你已经有面向业务的模型、指标或度量层Wren AI 可以叠加其上让 Agent 获得相同的定义而无需重建。你编写的 MDL 是面向 Agent 的契约agent-facing contract你已有的定义留在原地。你的 BI / 仪表盘工具Wren AI 为自主消费方Agent、脚本、嵌入式应用而生仪表盘继续使用你已有的工具。这一点在源码层面也能得到印证连接层由 20 个数据源 connector 组成见 core/wren/src/wren/connector/包含 PostgreSQL、BigQuery、Snowflake、ClickHouse、Redshift、Databricks、DuckDB 等实现其职责是执行规划后的 SQL而非存储。它提供什么四类能力的本质1. 面向 Agent 的上下文层五个上下文层次被收集为一个可检查、可版本化的表面任何 Agent 都能查询。承载这一表面的核心是MDLModeling Definition Language——Wren AI 的语义契约详细定义见 what_is_mdl.md。MDL 以可读的 YAML 描述模型、列、关系、计算字段、视图与 Cube并编译为引擎可用的target/mdl.json清单。仓库自带的 examples/v5-jaffle/ 项目是这一结构的真实样例models/customers/、models/orders/每模型一个文件夹relationships.yml统一声明模型间关系cubes/order_metrics/承载预聚合语义对象knowledge/下设rules/、glossary/、metrics/、caveats/、sql/等多个知识轴wren_project.yml声明schema_version: 5与数据源类型。2. 受治理的 SQL 平面Governed SQL PlaneWren AI 的 CLI 会把基于模型编写的 SQL 规划成可执行 SQL提供 dry-plan / dry-run 校验应用访问策略再经由数仓 connector 执行。Agent 不需要直接持有数据库凭据也不需要无限制的访问权限。对应的核心命令见 CLI 参考wren --sql SELECT * FROM orders LIMIT 5 # 规划并执行返回结果 wren dry-plan --sql SELECT order_id FROM orders # 仅展开 SQL不触碰数据库 wren dry-run --sql SELECT * FROM orders LIMIT 1 # 连接库做真实校验但不返回行 # OK规划管线由三部分协作完成见 architecture.mdsqlglot负责解析、限定引用与方言转译CTE rewriter识别被引用的 MDL 对象并把展开后的模型 SQL 注入为 CTEwren-coreRust 语义引擎见 core/wren-core/core/src/logical_plan/负责展开模型、关系、计算字段与视图的语义。访问策略policy注入发生在转译前业务规则knowledge/rules/会被织入计划。3. Agent 原生接口Agent-Native Interface包括三类Skills、面向主流 Agent 框架的SDK、以及为 LLM 编程代理设计的CLI——全部无需维护新的 UI。Skills是 Markdown 工作流指南教 Claude Code 等 AI 编码代理按正确顺序操作 CLI先建 MDL、再查上下文、后写 SQL、最后存储确认示例。内容随wrenaiwheel 一起发布通过wren skills get name按需获取版本永远与安装的 CLI 一致见 skills.md 与仓库中的 skills/wren/SKILL.md。可用技能包括onboarding、usage、generate-mdl、enrich-context、dlt-connector、genbi。SDK有 LangChain 与 Pydantic AI 两个实现仓库位于 sdk/wren-langchain/ 与 sdk/wren-pydantic/把同一套 plan-and-execute 管线包装为 Agent 工具。CLI本身是 Typer 薄封装与 Python SDK 共享编排代码均可嵌入 Agent 框架、notebook 与应用。4. 记忆与学习回路记忆是上下文的行为化层次详见 memory_system.mdwren memory index建立索引wren memory recall召回相似的已确认 NL→SQL 对wren memory store写入新确认的问答对。真相源是项目内可提交的 Markdownknowledge/sql/*.md索引是可重建的派生品因此记忆天然可审计、可分享。根据你的存量Wren AI 落位在哪场景一你没有语义层从 Wren AI 的上下文层开始。generate-mdl指南可在几分钟内从数仓 schema 搭建出 MDL 项目——你得到第一批受信任的语义定义而knowledge/rules/、记忆与治理则在它周围生长。之后通过 enrich-context 技能的 grill / auto-pilot 流程持续加深。这对应 generate-mdl 技能 的七阶段工作流连接 → 发现introspect 表/列/类型/外键→ 归一化类型wren utils parse-type→ 脚手架wren context init生成 YAML 项目→ 校验validate build→ 索引wren memory index→ 迭代精修。场景二你已有转换管道dbt、Coalesce、自研保留它。让 Wren AI 指向管道的输出表。MDL 描述这些表面向 Agent 的含义暴露哪些列、哪些 join 被批准、哪些计算可复用。管道继续拥有摄取与建模逻辑Wren AI 拥有建模后的数据与Agent之间那一层。仓库中的 dbt 集成指南 专门讲解如何对接 dbt 产物。场景三你已有语义层Wren AI 不与数据团队竞争。它的上下文层通过 Agent 可读、可推理的结构——MDL 文件、结构化检索、过往答案的记忆、受治理的执行原语——把同样的定义提供给 Agent。可以把它理解为你现有语义层的Agent 原生投影。场景四你有多套数仓Profile把连接凭据与项目定义分离。同一个 MDL 项目可以绑定到 dev / staging / prod 多套 profile——MDL 保持可移植凭据由 profile 携带。详见 manage_project.mdwren profile add pg-dev --from-file dev.yml --activate # 创建并激活 profile wren context set-profile pg-dev # 绑定到项目写入 wren_project.yml wren profile switch pg-prod # 按需切换全局活动 profileProfile 与项目的职责划分如下ProfileProject是什么连接凭据MDL 模型定义在哪~/.wren/profiles.yml全局project/wren_project.ymlmodels/作用域跨项目共享按项目、纳入版本控制机密包含不含可安全提交凭据通过${ENV_VAR}插值从.env注入解析顺序为os.environ→$CWD/.env→project/.env→~/.wren/.env连接信息以0600权限写盘。从源码看这一机制由 core/wren/src/wren/profile.py 与 core/wren/src/wren/config.py 支撑且有对应单元测试 test_profile_env_expansion.py 验证环境变量展开。哪里不适合用 Wren AI文档同样坦率地划出了不适配场景避免万能工具式的误用你只需要一个聊天式 BI 应用。Wren AI 是原语层而非聊天 UI。若你想要开箱即用的对话仪表盘商业版 Wren AI 或其他厂商产品更合适开源与商业版的边界见 oss_vs_commercial.md开源是完整引擎商业版在此基础上增加 Web UI、账户、SSO/RLS 等团队层能力。你希望零 schema 建模。即便是脚手架步骤也需要一定的 review。完全自动、无需审查的需求没有任何上下文层能诚实地满足。你主要查询非结构化文本。Wren AI 聚焦结构化业务数据基于文档的 RAG 是另一个问题域。为什么是叠加而非替代替换掉你的整个技术栈来换取一个查询得好的 AI Agent是让所有人都不满意的捷径。Wren AI 的设计模式正相反保留现有技术栈在其上增加一个可检查的层让每个 Agent 面对同一个受治理的表面。这正是它开源的动因业务上下文太重要不能锁在厂商产品里。你的 MDL、示例、查询历史与映射决策应该存在于你自己的仓库中接受团队的 review。仓库中的 MDL 确实以明文文件形式存在如 examples/v5-jaffle/models/orders/metadata.ymlknowledge/sql/中的 NL→SQL 对同样是可提交、可审查的普通文件——这从工程上保证了上下文属于你的团队。进阶阅读围绕本主题仓库内还有以下深度资料可以继续挖掘What does Wren AI mean by context?五层上下文的概念基础ArchitectureWren AI 内部的技术栈拆解规划引擎、wren-core、connector、记忆层Connect your data把 Wren AI 指向你的数仓profile 全流程Manage project多环境 profile 工作流与项目生命周期CLI referencewren query / dry-plan / dry-run / memory等命令的完整参数How does Wren AI keep agents from hallucinating?上下文层如何通过规划 校验防幻觉一句话收束Wren AI 的定位不是替代任何一层而是给每一层都加上Agent 能读懂的上下文——schema 告诉 Agent 存在什么MDL 告诉它数据意味着什么记忆与技能告诉它如何安全地使用并越用越好。【免费下载链接】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），仅供参考