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系统用户体验写作指南

一次一个指标，让数据治理以用户为中心。