Wren Engine

面向AI智能体的开放上下文引擎

Wren Engine是 Wren AI背后的开放基础架构：一个语义化、受治理且适用于智能体的业务数据上下文层。

https://github.com/user-attachments/assets/037f2317-d8e5-41f2-9563-1e0bce4ef50c

为什么需要Wren Engine

AI智能体已经能够调用工具、浏览文档和编写代码。然而，它们仍然难以处理业务上下文。

企业数据不仅仅是数据仓库中的行数据，还包括定义、指标、关系、权限、血缘关系以及使用意图等信息。即使智能体可以连接到PostgreSQL或Snowflake，它仍然无法理解“净收入”、“活跃客户”或“销售漏斗覆盖率”在贵公司究竟意味着什么。

这不仅是我们提出的观点，在a16z的文章《你的数据智能体需要上下文》中也指出，仅具备连接能力和SQL生成能力的数据智能体，在缺乏业务定义、权威数据上下文以及解释公司实际运作方式的运营知识时，将难以发挥作用。

Wren Engine正是为了解决这一问题而诞生的。

它为AI智能体提供了一个可进行推理的上下文引擎，使智能体能够：

• 理解模型而非原始表
• 使用可信的指标而非自行编写SQL
• 按照关系进行查询而非猜测联接方式
• 遵守治理规则而非绕过限制
• 将自然语言转化为准确且可解释的数据访问请求

这是面向构建下一代智能体体验团队的开源上下文引擎。

愿景

我们相信，AI的未来并非仅仅依赖于工具调用，而是基于丰富的上下文系统，让智能体能够在对业务现实达成共识的基础上进行推理、检索、规划并采取行动。

Wren Engine就是我们为实现这一未来所作出的开源贡献。

它是Wren AI背后的语义与执行基础，并且设计为能够超越单一产品而广泛适用：

• 可嵌入MCP服务器和智能体工作流中
• 能够连接现代数据仓库、数据库和文件系统
• 表达力足够强大，可通过MDL建模业务语义
• 性能稳健，足以支持受治理的企业级应用场景
• 开放程度高，便于社区扩展、集成和二次开发

如果说Wren AI是完整的愿景，那么Wren Engine就是使这一愿景具备互操作性的开放核心。

Wren Engine的功能

Wren Engine将业务数据转化为智能体可用的上下文。

从高层次来看：

1. 您使用Wren的语义模型和MDL描述您的业务领域。
2. Wren Engine捕获智能体所需的上下文：模型、指标、关系和访问规则。
3. 它分析用户意图，并规划出针对底层数据源的正确查询。
4. MCP客户端和AI智能体通过清晰的接口与该上下文交互。
5. 团队会随着业务逻辑和系统的演进而不断优化模型。

这就是一条实用的开源路径，从文本到SQL，最终实现具备上下文感知的数据智能体。

这意味着您的智能体不再会问：“我应该查询哪张原始表？”

而是会问：“为了正确回答这个任务，我需要哪个业务概念、指标，或者受治理的上下文切片？”

专为智能体开发者打造

Wren Engine对于在以下工具中构建原生智能体工作流的开源社区尤为有用：

• OpenClaw
• Claude Code
• VS Code
• Claude Desktop
• Cline
• Cursor

如果您的环境能够支持MCP协议、调用HTTP API或嵌入语义服务，那么Wren Engine就可以成为您智能体背后的上下文层。

您可以利用它来实现以下场景：

• 基于可信业务定义的自然语言分析
• 能够跨受治理的企业数据回答问题的AI助手
• 可生成仪表盘、报告和工作流决策的智能体
• 需要真实业务上下文而非单纯模式转储的代码助手
• 应当以语义模型为基础而非临时编写SQL的内部AI工具

这一点在面向开发者的智能体环境中尤为重要，因为助手可能理解您的代码库，但仍然缺乏正确回答数据相关问题所需的业务上下文。

支持的数据源

Wren Engine旨在兼容现代数据栈，包括数据仓库、数据库和基于文件的数据源。

当前开源支持的连接器包括：

• Amazon S3
• Apache Spark
• Apache Doris
• Athena
• BigQuery
• ClickHouse
• Databricks
• DuckDB
• Google Cloud Storage
• 本地文件
• MinIO
• MySQL
• Oracle
• PostgreSQL
• Redshift
• SQL Server
• Snowflake
• Trino

请参阅项目文档中的连接器API说明，以获取最新的连接方案和功能支持信息。

开始使用

通过MCP使用Wren Engine

如果您希望通过Claude Code或其他支持MCP的IDE使用Wren Engine，请从这里开始：

• 快速入门：使用Wren Engine + Claude Code与jaffle_shop聊天
• Claude Desktop快速入门
• 了解Wren AI项目结构

MCP服务器包含：

• 用于连接和MDL设置的本地Web界面
• 只读模式，以提高智能体使用的安全性
• 清单部署和验证工具
• 用于远程模式发现的元数据工具

学习相关概念

• 什么是上下文？
• 什么是建模定义语言（MDL）？
• Wren Engine 与 LLM 结合的优势
• 你的数据代理需要上下文
• 利用 Apache DataFusion 为 AI 代理提供语义 SQL 支持

Wren Engine 与其他数据工具的对比

人们常常将 Wren Engine 与 DataHub 等元数据目录服务、原始数据库 MCP 服务器、BI 语义工具或文本转 SQL 代理进行比较。

其根本区别在于：

• 这些工具通常帮助代理查找数据或生成 SQL；
• 而 Wren Engine 则通过上下文引擎帮助代理理解业务含义，并生成正确的查询。

工具类型	它为代理提供的功能	Wren Engine 增加的价值
数据目录服务	表、列、血缘关系、负责人、描述	业务模型、指标、关系以及受治理约束的查询规划
原始数据库或模式访问	直接访问模式并执行 SQL	在原始表之上构建业务层，使代理无需猜测意图
BI 或语义工具	针对分析工作流的精选指标和实体	专为 MCP 和代理工作流设计的开放上下文层
文本转 SQL 代理	从自然语言快速生成 SQL	通过将生成过程基于明确的业务定义，提升准确性

许多团队会同时需要两者：

• 一个元数据目录来盘点和记录数据资产；
• Wren Engine 将这些数据转化为代理可用的上下文。

这样做之所以重要：

• 查询结果更准确，因为连接和指标是明确定义的，而非凭猜测得出；
• 查询结果更一致，因为所有代理都使用相同的业务定义；
• 数据访问更安全，因为治理规则可以融入查询规划中；
• 减少对提示工程的依赖，因为上下文直接存在于引擎中，而非提示中。

如果没有 Wren，代理可能知道数据在哪里，却仍然无法正确回答问题。

仓库结构

该仓库包含核心引擎模块：

模块	功能
wren-core	基于 Apache DataFusion 的 Rust 上下文引擎，用于 MDL 分析、规划和优化
wren-core-base	共享的清单和建模类型
wren-core-py	PyO3 绑定，将引擎暴露给 Python
ibis-server	FastAPI 服务器，用于查询执行、验证、元数据和连接器
mcp-server	适用于 AI 代理和兼容 MCP 的客户端的 MCP 服务器

辅助模块包括 wren-core-legacy、example、mock-web-server 以及基准测试工具。

开发者入口

• wren-core/README.md
• wren-core-py/README.md
• ibis-server/README.md
• mcp-server/README.md

本地开发

常见工作流程：

# Rust 上下文引擎
cd wren-core
cargo check --all-targets

# Python + 连接器服务器
cd ibis-server
just install
just dev

# MCP 服务器
cd mcp-server
# 请参阅模块 README 获取基于 uv 的设置说明

项目状态

Wren Engine 正在开源社区中积极发展。当前的重点是强化上下文引擎、执行路径以及与 MCP 的集成，以更好地支持实际的代理工作流。

如果你目前正在构建基于代理的应用，现在正是参与的好时机。

社区

• 加入我们的 Discord 社区
• 打开一个 GitHub 问题
• 探索 Wren AI，了解更广泛的产品愿景
• 阅读 a16z 的市场观点：你的数据代理需要上下文

Wren Engine 专为那些相信 AI 需要更好的上下文，而不仅仅是更好的提示词的开发者打造。

Wren Engine 快速上手指南

Wren Engine 是一个专为 AI Agent 设计的开源上下文引擎。它通过语义模型（MDL）将原始数据转化为具备业务含义的上下文，帮助 AI Agent 理解指标、关系和治理规则，从而生成准确的查询而非盲目猜测 SQL。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统: Linux, macOS 或 Windows (WSL2 推荐)
• 运行时依赖:
  • Rust: 用于编译核心引擎 (wren-core)。建议安装最新稳定版。
  • Python: 3.9 或更高版本，用于运行连接器服务器和 MCP 服务。
  • Just: 任务运行器（可选但推荐，用于简化开发命令），可通过 cargo install just 安装。
  • uv (可选): 用于管理 Python 依赖和 MCP 服务器环境。
• 数据源: 至少拥有一个可连接的数据源（如 PostgreSQL, DuckDB, CSV 文件等）用于测试。

安装步骤

Wren Engine 由多个模块组成，最核心的使用方式是通过 MCP Server 让 AI Agent 调用，或通过 Ibis Server 进行 API 交互。以下是基于源码的快速设置流程。

1. 克隆仓库

git clone https://github.com/Canner/wren-engine.git
cd wren-engine

2. 设置核心引擎与连接器服务 (Ibis Server)

此步骤安装用于执行查询和处理元数据的后端服务。

# 进入 ibis-server 目录
cd ibis-server

# 安装依赖 (需要已安装 just 工具，若未安装可直接使用 pip/uv)
just install

# 或者手动安装 Python 依赖
pip install -r requirements.txt

3. 设置 MCP 服务器 (推荐用于 AI Agent)

如果您希望将 Wren Engine 集成到 Claude Desktop、Cursor 或其他支持 MCP 的 IDE 中：

# 进入 mcp-server 目录
cd ../mcp-server

# 使用 uv 设置环境 (推荐)
uv sync

# 或者使用 pip
pip install -e .

注意: 国内开发者若遇到 PyPI 下载缓慢，可在安装命令前添加国内镜像源，例如： pip install -i https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

基本使用

最简单的方式是通过 MCP 协议让 AI Agent 直接与 Wren Engine 交互。以下以配置本地 MCP 并连接一个简单的数据集为例。

第一步：准备业务语义模型 (MDL)

Wren Engine 的核心是 MDL (Modeling Definition Language)。您需要定义一个 JSON 文件来描述业务模型。以下是一个极简的 manifest.json 示例（假设您有一个本地的 jaffle_shop DuckDB 文件）：

{
  "models": [
    {
      "name": "orders",
      "tableReference": {
        "schema": "main",
        "table": "orders"
      },
      "columns": [
        {
          "name": "order_id",
          "type": "INTEGER",
          "expression": "order_id"
        },
        {
          "name": "amount",
          "type": "DOUBLE",
          "expression": "amount"
        }
      ],
      "primaryKey": "order_id"
    }
  ],
  "metrics": [],
  "relationships": []
}

第二步：启动 MCP 服务器

在 mcp-server 目录下，配置并启动服务。您可以将其配置为读取上述 manifest 并连接到数据源。

如果是本地开发测试，可以直接通过命令行参数或配置文件指定数据源和 manifest 路径。以下是一个典型的启动逻辑（具体参数请参考 mcp-server 下的配置文档）：

# 在 mcp-server 目录下运行
# 假设您已配置好环境变量或使用配置文件指向您的 manifest 和数据源
uv run mcp_server --manifest-path ../example/manifest.json --data-source duckdb

第三步：在 AI 客户端中连接

以 Claude Desktop 或支持 MCP 的 Cursor/VS Code 为例，在配置文件中添加 Wren Engine 的 MCP 服务器路径。

Claude Desktop 配置示例 (claude_desktop_config.json):

{
  "mcpServers": {
    "wren-engine": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/wren-engine/mcp-server", "mcp_server"],
      "env": {
        "WREN_MANIFEST_PATH": "/path/to/your/manifest.json",
        "WREN_DATA_SOURCE": "duckdb"
      }
    }
  }
}

重启 AI 客户端后，您就可以直接使用自然语言提问，例如：

"Show me the total order amount."

Wren Engine 会自动解析您的 MDL 模型，理解 amount 是业务指标，并生成正确的查询计划，而不是让 AI 去猜测表结构。

替代方案：直接 API 调用 (Ibis Server)

如果不使用 MCP，也可以直接启动 Ibis Server 进行 HTTP 调用：

# 在 ibis-server 目录下
just dev
# 或
python -m uvicorn main:app --reload

服务默认启动在 http://localhost:8000。您可以通过 POST 请求发送 SQL 或 MDL 查询请求。