内容
# MCP 语义层在 Databricks 上
> 一个受管的 MCP 语义层在 Databricks 上 — 指标视图 + Genie Space +
> UC 函数 + Unity AI 网关，封装了一个薄的自定义 MCP 服务器，
> 添加同义词解析、认证信号和提示模板。
在 Databricks 上部署真正的巴西电子商务数据集（~100K 订单，2016-2018 年）—
从 Delta 奖章到原生的指标视图，再到自定义的 MCP 服务器作为 Databricks 应用程序。
> **这里是新来的吗？** 从 [`docs/ONBOARDING.md`](docs/ONBOARDING.md) 开始 —
> 介绍、原因、设置步骤和每个组件的概述。
## 架构
```mermaid
flowchart TD
C[Claude Desktop / Cursor / Agent Bricks]
C -- "MCP（可流式 HTTP）" --> APP
subgraph APP[自定义 MCP 服务器<br>Databricks 应用程序：mcp-olist]
S[同义词解析器]
B[认证徽章]
P[提示模板]
end
APP --> UC[UC 函数 MCP]
APP --> GS[Genie Space MCP]
APP --> SQL[(Databricks SQL MCP)]
APP --> VS[(矢量搜索 MCP)]
subgraph GATEWAY[Unity AI 网关]
GW[4 服务策略<br>个人识别信息 / 跨区域 / 速率限制 / 认证]
end
APP -- 每次调用 --> GATEWAY
subgraph UC_LAKEHOUSE[Unity 目录<br>main.olist_ecommerce]
BR[(bronze_*)] --> SI[(silver_*)] --> GO[(gold_*)]
GO --> MV[(指标视图)]
MV --> GENIE[Genie Space<br>Olist 业务分析]
end
UC -.查询.-> UC_LAKEHOUSE
GS -.查询.-> UC_LAKEHOUSE
SQL -.查询.-> UC_LAKEHOUSE
```
## 为什么这个项目存在
Databricks 在 DAIS 2026 上发布了大部分语义层 —
指标视图、Genie One、托管的 MCP 服务器、Unity AI 网关。
**仍然存在三个企业级空白，需要厂商每年支付 50 万美元来填补：**
| 空白 | 含义 | 该项目的实现 |
|-----|---------------|-------------------------------|
| **同义词解析** | "AOV" / "平均篮子" / "平均订单价值" 必须指向同一个指标 | `src/synonym_resolver.py`（YAML 驱动） |
| **认证信号** | 代理必须在查询前知道一个指标是否是 "财务级别" 的 | `src/certification.py`（读取指标视图注释标签） |
| **提示模板** | 可重复使用的分析工作流（趋势、周期比较、卖家诊断） | `src/prompts.py`（4 个已注册的提示） |
其他所有功能 — 指标视图、Genie Space、UC 函数 MCP、矢量搜索 MCP、Unity AI 网关强制执行 —
都是 Databricks 原生的。该项目**只构建了 3 个空白的增量**，大约 2K LOC 的自定义代码。
## 什么是原生的，什么是我们构建的
| Databricks 原生（零代码） | 我们构建的（3 个空白） |
|---------------------------------------------|---------------------------------------------|
| 指标视图（UC 管理的指标） | 同义词解析器 (`src/synonym_resolver.py`) |
| Genie Space / Genie One | 认证徽章 (`src/certification.py`) |
| UC 函数 MCP（管理的查询） | 提示模板 (`src/prompts.py`) |
| Databricks SQL MCP | 薄的 FastMCP 包装器 (`src/server.py`) |
| 矢量搜索 MCP | Unity AI 网关策略存根 (`src/policies.py`) |
| Unity 目录（3 级命名空间） | Databricks 资产包 (`databricks.yml`) |
| Unity AI 网关（运行时策略强制执行） | Databricks 应用程序清单 (`app.yaml`) |
## 设置
```bash
git clone https://github.com/<you>/mcp-semantic-layer-databricks.git
cd mcp-semantic-layer-databricks
# 1. 本地 Python 环境
make setup # venv + pip install -e .[dev]
cp .env.example .env # 填写 DATABRICKS_HOST/TOKEN/HTTP_PATH
# 2. Databricks CLI
databricks auth login # 认证 auto-healer 配置文件
# 3. 验证和部署整个包（笔记本 + 应用程序 + 作业）
databricks bundle validate
databricks bundle deploy -p auto-healer
# 4. 运行整个管道一次（bronze → silver → gold → 指标视图 → UC 函数 → Genie）
databricks bundle run olist_pipeline -p auto-healer
```
对于粒度控制 — 运行单个笔记本任务：
```bash
make load-bronze
make build-silver
make build-gold
make deploy-metric-views
make deploy-uc-functions
make configure-genie
```
## 示例聊天记录
```
┌─── Claude Desktop （附加到 mcp-olist MCP 服务器） ──────────────────┐
│ │
│ 你：上季度按州划分的总收入是多少？ │
│ │
│ Claude: 让我先检查可用的指标。 │
│ │
│ [工具：list_metrics] │
│ → 🟢 权威的 `revenue_metrics` 属主：@finance │
│ → 🟢 权威的 `delivery_metrics` 属主：@operations │
│ → 🟡 估计的 `seller_metrics` 属主：@marketplace │
│ → 🟢 权威的 `customer_metrics` 属主：@analytics │
│ │
│ 我将使用 `revenue_metrics` （🟢 权威的），按 customer_state 分组│
│ 和 order_quarter，季度 = 2018-Q2。 │
│ │
│ [工具：query_metric（metric="total_revenue"， │
│ time_grain="quarter"， │
│ dimensions=["customer_state"])] │
│ │
│ 🟢 权威的 · 27 行 · time_grain=quarter │
│ │
│ | customer_state | quarter | total_revenue | │
│ | -------------- | --------- | ------------- | │
│ | SP | 2018-Q2 | 624,391.02 | │
│ | RJ | 2018-Q2 | 218,444.70 | │
│ | MG | 2018-Q2 | 193,707.66 | │
│ | ... | ... | ... | │
│ │
│ ```sql │
│ SELECT customer_state, order_quarter, SUM(total_revenue) │
│ FROM main.olist_ecommerce.revenue_metrics │
│ WHERE order_quarter = '2018-04-01' │
│ GROUP BY customer_state, order_quarter │
│ ``` │
│ │
│ 圣保罗占 2018 年第二季度收入的约 38%。 │
└─────────────────────────────────────────────────────────────────────────┘
```
## 项目布局
```
mcp-semantic-layer-databricks/
├── databricks.yml # DAB：部署应用程序 + 管道作业
├── app.yaml # Databricks 应用程序清单（mcp-olist）
├── Dockerfile # 容器固定（可选 — DAB 无需它）
├── requirements.txt # 运行时依赖项（镜像 pyproject.toml）
├── pyproject.toml # 本地开发：pip install -e .
├── Makefile # 设置 / load-bronze / ... / deploy-mcp / 测试
│
├── data/olist/ # 8 个 Olist CSV 文件（真实的 Kaggle 数据）
│
├── notebooks/ # 6 个 Databricks 笔记本（通过 DAB 部署）
│ ├── 01_load_bronze.py
│ ├── 02_build_silver.py
│ ├── 03_build_gold.py
│ ├── 04_create_metric_views.py # 原生指标视图 DDL
│ ├── 05_register_uc_functions.py # 受管的 UC SQL 函数
│ └── 06_configure_genie_space.py # Genie One ontology + 示例问题
│
├── src/ # 约 2K LOC 的自定义代码
│ ├── server.py # FastMCP 入口点（流式 HTTP）
│ ├── tools.py # 5 个 MCP 工具
│ ├── resources.py # 3 个 MCP 资源
│ ├── prompts.py # 4 个提示模板
│ ├── synonym_resolver.py # 空白 1：自然语言 → 指标视图
│ ├── certification.py # 空白 2：认证徽章
│ ├── policies.py # Unity AI 网关策略伪代码
│ └── gen_client.py # 托管的 Databricks MCP 服务器的包装器
│
├── semantic/
│ └── synonyms.yml # 同义词词典（由 synonym_resolver 读取）
│
├── tests/
│ ├── unit/ # 纯 Python 测试（无需 Databricks）
│ ├── integration/ # 需要实时 UC 连接
│ └── golden/ # 手动计算的 CSV 比较
│
└── docs/
├── architecture-faq.md
└── olist-demo-walkthrough.md
```
## 测试
```bash
# 单元测试（同义词、徽章、提示 — 纯 Python，无需 Databricks）
make test # → pytest tests/unit
# 集成测试（指标视图、UC 函数、Genie、MCP 工具 — 需要实时 UC）
DATABRICKS_TOKEN=... pytest tests/integration -v
# 黄金测试（收入 + 交付总值与 CSV 计算的预期值）
DATABRICKS_TOKEN=... pytest tests/golden -v
```
## 许可证
MIT。参见 `LICENSE`。
