Semantic Metrics Modeling Assistant

🚀 語義指標建模助手

這是一個可用於生產環境的MCP代理，能幫助數據團隊定義、驗證和可視化語義指標，具備企業級的數據持久化、信任評分和商業智能（BI）集成功能。

🚀 快速開始

安裝

# 克隆倉庫
git clone https://github.com/jkelleman/semantic-metrics-modeling-assistant.git
cd semantic-metrics-modeling-assistant

# 安裝依賴
pip install -e .

# 運行MCP服務器
python -m semantic_metrics.server

# 或者運行測試
pytest tests/

數據庫設置

該代理在首次運行時會自動創建一個SQLite數據庫（metrics.db），包含以下內容：

• 指標定義表
• 變更歷史跟蹤
• 驗證測試結果
• 使用統計信息
• 信任評分演變

使用示例

基礎用法

定義一個新指標：

define_metric(
    name="Active Users",
    description="Daily unique user logins",
    calculation="COUNT(DISTINCT user_id) WHERE login_date = CURRENT_DATE",
    owner="@data-team",
    tags=["engagement", "daily"]
)

高級用法

檢查增強信任評分：

check_trust_score("Active Users")

# 返回結果：
# Trust Score: 87/100 ↗️
# Tests: 4 passing (35/35 points) ✅
# Usage: 12 dashboards, 8 users (18/20 points)
# Freshness: Updated 2 hours ago (14/15 points)
# Documentation: Complete with examples (15/15 points)
# Ownership: @data-team (15/15 points)
#
# Trend: ▂▄▆█ (improving over 30 days)
# Recommendations: Add integration tests for edge cases

可視化指標譜系：

visualize_lineage("Revenue per Customer")

# 返回ASCII樹結構：
# Revenue per Customer
#   ├── Total Revenue
#   │   ├── Order Amount (raw.orders)
#   │   └── Refunds (raw.refunds)
#   └── Customer Count
#       └── Unique Customers (raw.users)

生成Mermaid圖表：

generate_mermaid_diagram("Revenue per Customer")

# 返回結果：
# ```mermaid
# flowchart TD
#     A[Revenue per Customer] --> B[Total Revenue]
#     A --> C[Customer Count]
#     B --> D[Order Amount]
#     B --> E[Refunds]
#     C --> F[Unique Customers]
# ```

導出到BI工具：

# 導出到Looker
export_to_looker("Active Users")
# 生成：active_users.lkml

# 導出到Tableau
export_to_tableau("Active Users")
# 生成：active_users.tds (XML)

# 導出到dbt
export_to_dbt("Active Users")
# 生成：active_users.yml

✨ 主要特性

🗄️ 企業級數據持久化

• SQLite數據庫 - 具備完整審計跟蹤的持久化存儲
• 五表架構 - 包含指標、歷史記錄、測試、使用情況和信任評分
• 變更跟蹤 - 記錄所有指標修改的完整歷史
• 支持版本控制 - 專為Git集成和回滾設計

💬 對話式指標定義

通過自然對話定義指標：

"Define 'Active Users' as daily unique logins"
"Create a metric for revenue per customer"
"What's the definition of our churn rate metric?"

📊 BI工具集成

將指標導出到行業標準平臺：

• Looker (LookML) - 生成可用於生產環境的LookML文件
• Tableau (TDS) - 以Tableau數據源XML格式導出
• dbt - 創建dbt指標YAML定義

🎯 增強的信任評分

使用加權算法進行復雜的質量評估：

• 測試（權重35%） - 驗證測試覆蓋率和通過率
• 使用情況（權重20%） - 跨團隊和儀表板的採用率
• 數據新鮮度（權重15%） - 考慮時間衰減的數據陳舊度
• 文檔（權重15%） - 完整性和清晰度
• 所有權（權重15%） - 明確的責任歸屬
• 趨勢分析 - 通過迷你圖跟蹤質量隨時間的變化

🎨 可視化譜系和依賴關係

提供現代可視化選項，幫助理解指標關係：

• Mermaid圖表 - 適用於GitHub、Notion、Confluence的精美流程圖
• ASCII樹 - 適合終端的依賴關係可視化
• 影響分析 - 在更改前瞭解下游影響
• 循環依賴檢測 - 識別並解決衝突

✅ 全面測試

具備可用於生產環境的測試覆蓋率：

• 35+項測試 - 涵蓋數據庫、信任評分、導出器和工具
• pytest框架 - 使用行業標準的測試框架和測試用例
• 90%以上覆蓋率 - 核心功能經過全面驗證
• 支持CI/CD - 支持持續集成的自動化測試

📚 詳細文檔

問題所在

數據團隊面臨系統性挑戰：

• 指標氾濫 - 核心業務指標存在多個相互衝突的定義
• 信任缺失 - 缺乏質量信號導致指標選擇隨意和報告不一致
• 認知負擔過重 - 複雜的依賴鏈和譜系難以理解
• 治理分散 - 所有權和驗證流程不規範或缺失

解決方案

該助手通過以下方式解決這些挑戰：

• 抽象層 - 自然語言界面簡化了YAML配置的複雜性
• 透明度機制 - 多維信任評分使質量可見
• 治理自動化 - 內置的所有權、測試和文檔提示
• 可觀測性工具 - 跟蹤使用情況和監控數據新鮮度

🔧 技術細節

架構

┌─────────────────────────────────────────┐
│  Conversational Interface (MCP Tools)   │
├─────────────────────────────────────────┤
│  • define_metric()                      │
│  • validate_metric()                    │
│  • visualize_lineage()                  │
│  • check_trust_score()                  │
│  • search_metrics()                     │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  Metric Repository                      │
├─────────────────────────────────────────┤
│  • Stores metric definitions            │
│  • Tracks lineage and dependencies      │
│  • Collects usage and quality metadata  │
└─────────────────────────────────────────┘
                    ↓
┌─────────────────────────────────────────┐
│  Data Source Integrations               │
├─────────────────────────────────────────┤
│  • dbt project files                    │
│  • LookML models                        │
│  • YAML metric specs                    │
│  • SQL queries                          │
└─────────────────────────────────────────┘

設計原則

1. 對話優先

通過自然語言界面抽象複雜的YAML配置。優先考慮對話式交互，減少語法記憶的學習成本。

2. 展示而非告知

優先使用可視化表示而非文本描述。將譜系呈現為有向無環圖（DAG），使依賴關係一目瞭然。

3. 通過透明度建立信任

將質量指標作為一等屬性展示。多維信任評分提供有關指標可靠性的可操作信號。

4. 漸進式披露

實現信息層次結構，默認顯示高級摘要，同時保留深入查看詳細元數據的功能。

5. 默認治理

設計界面使治理成為最簡單的路徑。使用提示、驗證和必填字段來強制執行最佳實踐，而不增加額外的操作負擔。

使用場景

數據團隊成員

“我需要創建一個大家都能信任的客戶終身價值指標。”

助手幫助：

• 用通俗易懂的語言定義指標
• 驗證SQL邏輯
• 檢查是否有類似的現有指標
• 設置所有權和文檔
• 添加到指標目錄

分析工程師

“為什麼我的儀表板顯示的收入數字與財務部門的不同？”

助手幫助：

• 比較收入指標定義
• 展示譜系和數據源
• 確定定義分歧的地方
• 推薦標準指標

數據負責人

“哪些指標最關鍵，需要更好的治理？”

助手幫助：

• 按使用情況和信任評分展示指標
• 識別高使用、低信任的指標
• 跟蹤治理覆蓋範圍
• 隨時間監控指標健康狀況

技術棧

• Python 3.10+ - 核心編程語言
• FastMCP - MCP協議實現
• SQLite - 持久化數據庫存儲
• pytest - 測試框架，包含35+項測試
• YAML/JSON - 指標定義和導出格式
• Mermaid - 現代圖表生成工具

MCP工具（共13個）

指標管理

質量與信任

可視化

導出與集成

高級功能

項目展示內容

用戶體驗技能

• 降低認知負擔 - 設計抽象層，在不犧牲系統功能的前提下簡化複雜系統
• 信任設計 - 通過透明的質量信號和複雜的加權評分算法建立信任
• 漸進式披露 - 信息架構在可發現性和詳細程度之間取得平衡
• 對話式用戶界面 - 用於技術配置的自然語言界面

技術技能

• MCP開發 - 具備13個工具和1500+行代碼的生產級AI代理
• 數據庫設計 - 採用五表架構和完整審計跟蹤的SQLite持久化存儲
• 數據建模 - 語義層設計模式和指標定義框架
• 系統架構 - 治理自動化和可觀測性工具
• 測試 - 使用pytest進行35+項測試，核心功能覆蓋率達90%以上
• 集成模式 - 支持Looker、Tableau和dbt的BI工具導出器

領域專業知識

• 指標治理 - 建立所有權模型、驗證框架和文檔標準
• 數據譜系 - 構建依賴圖和進行影響分析
• 數據可觀測性 - 跟蹤數據新鮮度、使用時間衰減進行質量監控和使用分析
• 語義層 - 現代數據棧模式和指標建模最佳實踐

項目重要性

作為微軟的首席內容設計師，在處理數據和AI系統時，該項目展示了：

1. 對數據團隊挑戰的深刻理解 - 在生產環境中直接面對指標氾濫和信任缺失問題的經驗
2. 面向技術用戶的用戶體驗設計 - 設計抽象層，在保留系統功能的同時降低認知負擔
3. 信任和可觀測性設計 - 通過透明的質量工具和加權評分應用企業級治理模式
4. AI增強工作流程 - 利用MCP增強（而非替代）人類決策和領域專業知識
5. 可用於生產環境的實現 - 35+項測試、數據庫持久化和BI集成，可用於實際部署

這代表了企業數據平臺所需的以用戶為中心的設計：無縫的治理、可衡量的信任和可管理的複雜性。

📄 許可證

本項目採用 MIT許可證。

近期改進

✅ SQLite數據庫 - 採用五表架構實現全持久化 ✅ BI集成 - 支持Looker和Tableau導出工具 ✅ 增強的信任評分 - 採用帶時間衰減和趨勢的加權算法 ✅ Mermaid圖表 - 用於文檔的現代可視化 ✅ 測試套件 - 使用pytest進行35+項測試，覆蓋率達90%以上

完整技術細節請參閱 IMPLEMENTATION_SUMMARY.md。

關於作者

Jen Kelleman
資深產品設計師

我致力於設計AI和數據體驗，通過透明、完善的系統降低認知負擔並建立信任。

聯繫方式

• 領英
• Medium
• AI內容設計手冊

其他項目

• MCP-Oreilly - 用於內容設計、會議分析和文檔的三個生產級MCP代理
• AI內容設計手冊 - 全面的AI系統用戶體驗寫作指南

一次一個指標，讓數據治理以用戶為中心。