Canner/WrenAI · 上手攻略

仓库：Canner/WrenAI
链接：https://github.com/Canner/WrenAI
分类：ai
作者：Tom
更新：2026-07-13

这是什么

Canner/WrenAI 是 开源 GenBI（Generative BI）引擎，核心能力是让 AI Agent 通过自然语言生成可信的 SQL 查询、可治理的业务仪表盘。它不是简单的 text-to-SQL 工具——它通过一层开放 Context Layer（MDL 语义模型），把业务定义、数据血缘、查询记忆等「业务知识」注入 Agent 的推理过程，从根本上解决「LLM 自信满满写出错误 SQL」的问题。

2026 年 5 月，原 Wren Engine 合并进本仓库作为 core/，形成统一的语义引擎 + Agent SDK + Skills 的完整栈。License 为 Apache-2.0。

一句话定位：Text-to-SQL 的可信化方案，不只是「让 SQL 生成变快」，而是「让生成的 SQL 业务上正确」。

解决什么问题

问题	传统方案	WrenAI
LLM 生成 SQL 错	用更强的模型	用业务语义层约束
不知道数据血缘	查文档	MDL 语义模型自动解析
业务定义（枚举、单位、批准联接）没人知道	口口相传或放在数据库外	放在 MDL 里，Git 版本控制
生成的 SQL 不可信	加人工审核	dry-run + structured errors 自动校验
各 Agent 重复出错	各自独立	共享上下文层，所有 Agent 共用
想生成可分享仪表盘	需要 BI 工程师	Agent 直接生成并一键部署

快速安装

方式一：pip 安装（推荐）

pip install wrenai              # 核心包（含 DuckDB）
pip install "wrenai[postgres,memory]"  # 加 Postgres 连接 + 记忆模块

# 中国大陆用户遇 pip 超时用清华镜像
pip install wrenai -i https://pypi.tuna.tsinghua.edu.cn/simple

# HuggingFace 模型下载超时，加这个环境变量
export HF_ENDPOINT=https://hf-mirror.com

方式二：npx 安装 Agent Skill（用于 Claude Code / Cursor 等）

npx skills add Canner/WrenAI
# 自动检测 Claude Code、Cursor、Cline、Codex 等

安装后，Agent Skill 会自动接管后续工作流引导。

核心用法

工作流概览

Day 1（Agent 驱动）：
  wren skills get onboarding   → 建立项目 + 首次查询（Generate）
  wren skills get enrich-context → 注入业务上下文（Know）
  wren skills get genbi         → 构建并部署仪表盘（Deploy）

日常使用：
  wren query --sql 'SELECT ...'        → 通过 MDL 语义层执行 SQL
  wren ask "谁是最热卖的前10客户？"   → 自然语言转 SQL（有引导）

1. Agent 驱动的工作流

Step 1：建立项目（ onboarding）

# 在 Claude Code / Cursor 中对 Agent 说：
"Use Wren to set up my Postgres database."

# Agent 会：
# 1. 运行 wren skills get onboarding
# 2. 检查环境
# 3. 创建连接配置
# 4. 运行首次查询验证

Step 2：注入业务上下文（enrich-context）

# 把本地业务文档（如 raw/ 目录下的需求文档）注入 MDL
wren skills get enrich-context

# grill 模式（一次一个问题）:
wren enrich-context --mode grill

# auto-pilot 模式（Agent 自动读目录并提议）:
wren enrich-context --mode auto-pilot

Step 3：自然语言问数据

# 对较弱模型加 --guided 包装
wren ask "Who are our top 10 customers by sales this quarter?" --guided

# 对强模型直接问
wren ask "谁是这个季度销售额前10的客户？" --direct

Step 4：生成并部署仪表盘

# 让 Agent 生成交互式仪表盘并一键部署到 Vercel
wren skills get genbi
# Agent 会：
# 1. 构建浏览器端 GenBI app（wren-core-wasm）
# 2. 本地预览
# 3. 部署到你的 Vercel 或 Cloudflare Pages
# 4. 返回可分享的 URL

2. MDL 语义模型（核心概念）

MDL（Modeling Definition Language）是 WrenAI 的核心抽象层，定义：

// 示例 MDL 结构
{
  "models": [
    {
      "name": "customers",
      "columns": [
        {"name": "id", "type": "INTEGER"},
        {"name": "name", "type": "VARCHAR"},
        {"name": "segment", "type": "VARCHAR"}  // 业务定义：segment 枚举值 [VIP, Regular, New]
      ]
    }
  ],
  "relationships": [
    // 业务批准的关系，不允许跨关系 JOIN
  ],
  "metrics": [
    {"name": "total_sales", "expression": "SUM(orders.amount)"}
  ],
  "access_control": {
    // 行级 / 列级权限
  }
}

MDL 文件存放在项目中，Git 版本控制，完全透明可审查。

3. 连接数据源

# 连接 Postgres
wren connect --type postgres --host localhost --port 5432 --db mydb

# 连接 BigQuery
wren connect --type bigquery --project my-gcp-project --dataset my_dataset

# 支持的数据源（22+）：
# PostgreSQL, BigQuery, Snowflake, ClickHouse,
# Amazon Redshift, Databricks, DuckDB, MySQL, ...

4. SDK 集成（LangChain / LangGraph）

# LangChain 集成
from wren_langchain import WrenAI

wren = WrenAI(
    project_dir="./my-wren-project",
    model="claude-3-5-sonnet"
)

result = wren.ask("What were our top products last month?")
print(result["sql"])       # 可信 SQL
print(result["answer"])    # 自然语言回答
print(result["chart"])     # 图表配置

5. 本地查询（不走 Agent）

# 直接 SQL 查询（通过 MDL 语义层）
wren query --sql 'SELECT * FROM customers LIMIT 10'

# Dry-run 验证（不实际执行，用于审核）
wren query --sql 'SELECT * FROM orders' --dry-run

# 结构化错误（含纠错提示）
wren query --sql 'SELECT wrong_column FROM orders'
# 返回：列不存在，是否想用 order_id？

典型适用场景

让 AI Agent 产生可信 BI：不只是 SQL 对，还要是业务上对的 SQL
多 Agent 共享业务上下文：公司有一套 MDL，所有 Agent（Claude Code、Cursor 等）共用
非技术人员用自然语言查数据：WrenAI 作为中间语义层，保障 SQL 正确性
一键生成可分享仪表盘：从自然语言问题到 Vercel 部署的完整链路
数据治理与合规：MDL 提供行级/列级权限，数据访问可审计
已有数据仓库不想换：直接连 BigQuery / Snowflake / Redshift，不搬家

坑与注意

坑	说明
需要理解 MDL	语义模型有学习曲线，不理解 MDL 用不好这个工具
国产数据库支持有限	官方列表主要是国际主流数仓，国内阿里云/腾讯云数仓未列明支持
Model Context 有依赖	MDL 里需要先定义好业务语义，冷启动成本不低
技能生态还小	Agent Skill 生态（`wren skills`）还在早期，npx 生态不如 npm 成熟
HuggingFace 模型下载	国内下载 HuggingFace 模型容易超时，需要加 `HF_ENDPOINT` 镜像
PyPI 包名和项目名混淆	PyPI 包名是 `wrenai`，但仓库叫 WrenAI，容易搜不到
v1 vs v2 过渡期	2026-05 刚合并，legacy/v1 分支已冻结，新文档可能还不够完善

⚠️ 特别提醒：数据治理是严肃的事。WrenAI 的 MDL 语义层需要人工维护业务定义，如果维护者不熟悉业务，错误语义反而会让 AI 生成「看起来对但业务上错」的 SQL。建议 MDL 上线前有数据团队review。

与同类对比

维度	WrenAI	Vanna.ai	SQLChat	LangChain + SQL
定位	GenBI 语义平台	Text-to-SQL	对话式 SQL	开发框架
Context Layer	✅ MDL（版本控制）	⚠️ Prompt 工程	❌ 无	❌ 无
仪表盘生成	✅ 一键部署	❌ 无	❌ 无	❌ 无
Agent 生态	✅ MCP / Claude Code	❌	⚠️ API	✅
数据源数	22+	10+	少数	取决于 DB 驱动
许可证	Apache-2.0	AGPL（商业需许可）	闭源	Apache-2.0
学习曲线	较陡（MDL）	平缓	平缓	陡

结论：如果你需要的不只是「LLM 写 SQL」，而是「LLM 在业务规则约束下写出可信 SQL 并生成可分享仪表盘」，WrenAI 是目前开源生态里方案最完整的。如果只是轻量 text-to-SQL，Vanna.ai 或直接调 API 更简单。

一句话推荐结论

开源 GenBI 的完整实现，通过 MDL 语义层从根本上解决 LLM 生成错误 SQL 的问题，支持 22+ 数据源和 Agent 原生集成，适合已有明确数据治理需求的团队；MDL 有一定学习曲线，且 2026-05 刚完成 v1→v2 合并，文档尚在完善中。