Intugle MCP Server

基于 GenAI 的自动化数据智能工具包。

将碎片化数据转化为互联的语义数据模型

概述

Intugle 基于 GenAI 的开源 Python 库能够在您现有的数据系统之上构建语义数据模型。其核心功能是发现数据资产之间有意义的链接和关系——并通过数据画像、分类和业务术语表对其进行丰富。借助这一互联的知识层，您可以启用语义搜索并自动生成查询，从而创建统一的数据产品，使数据集成和探索更快、更准确，并大幅减少手动操作。

适用人群

• 数据工程师与架构师 通常需要花费数周时间手动对碎片化的数据资产进行画像、分类和拼接。借助 Intugle，他们可以端到端地自动化这一过程，发现有意义的链接和关系，即时生成互联的语义层。
• 数据分析师与科学家 在开始真正的分析之前，往往要花费大量时间进行数据准备和预处理。Intugle 通过提供上下文智能，自动生成 SQL 和富含关系与业务含义的可复用数据产品，从而加速这一过程。
• 业务分析师与决策者 常因依赖技术团队获取答案而效率低下。Intugle 通过支持自然语言查询和语义搜索，消除了这一瓶颈，使他们能够按需获取可信的洞察。

功能特性

• 语义数据模型 - 将原始、碎片化的数据集转化为智能语义图谱，捕获实体、关系和上下文——这是互联智能的基础。
• 业务术语表与语义搜索： 自动生成业务术语表，并启用理解含义而非仅匹配关键词的搜索——使数据对技术和业务用户都更易于访问。
• 数据产品 - 即时生成 SQL 和富含上下文的可复用数据产品，消除手动数据管道，加速从数据到洞察的过程。
• 概念搜索 - 根据自然语言查询生成数据产品计划，弥合业务问题与可执行数据产品定义之间的鸿沟。详情请参阅文档。

支持的集成

类别	集成
数据仓库	Snowflake, Databricks
数据库	SQLite, PostgreSQL, SQL Server, MySQL
本地	Pandas, DuckDB (CSV, Parquet, Excel)

Streamlit 应用

intugle 库包含一个 Streamlit 应用程序，提供用于构建和可视化语义数据模型的交互式 Web 界面。

https://github.com/user-attachments/assets/402c3f3d-baf3-4ece-ba55-4e06437defc5

要使用 Streamlit 应用，请安装带有 streamlit 扩展的 intugle：

pip install intugle[streamlit]

您可以使用 intugle-mcp 命令或 uvx 启动 Streamlit 应用程序：

intugle-streamlit
# Or using uvx
uvx --from intugle[streamlit] intugle-streamlit

在终端中打开提供的 URL（通常是 http://localhost:8501）即可访问该应用。更多详情，请参阅 Streamlit 应用文档。

要在 Google Colab 等云环境中运行该应用，请参考我们的 Streamlit 快速入门笔记本。

快速入门

安装

对于 Windows 和 Linux，您可以按照以下步骤操作。对于 macOS，请参阅下方 macOS 部分的额外步骤。

安装前，建议创建一个虚拟环境：

python -m venv .venv
source .venv/bin/activate

然后，安装该软件包：

pip install intugle

macOS

对于 macOS 用户，您可能需要安装 libomp 库：

brew install libomp

如果您使用的是从 python.org 下载的官方安装程序安装的 Python，可能还需要通过在终端中运行以下命令来安装 SSL 证书。请将 3.XX 替换为您具体的 Python 版本。如果您使用 Homebrew 安装的 Python，则无需执行此步骤。

/Applications/Python\ 3.XX/Install\ Certificates.command

配置

在运行项目之前，您需要配置一个 LLM。它用于执行诸如生成业务术语表和预测表之间链接等任务。

您可以通过设置以下环境变量来配置 LLM：

• LLM_PROVIDER：要使用的 LLM 提供商和模型（例如 openai:gpt-3.5-turbo），遵循 LangChain 的约定
• API_KEY：您的 LLM 提供商 API 密钥。具体的变量名称可能因提供商而异。

以下是在您的环境中设置这些变量的示例：

export LLM_PROVIDER="openai:gpt-3.5-turbo"
export OPENAI_API_KEY="your-openai-api-key"

快速入门

有关项目的详细、动手入门介绍，请参阅我们的快速入门笔记本：

领域	笔记本	在 Colab 中打开
医疗保健	quickstart_healthcare.ipynb
科技制造	quickstart_tech_manufacturing.ipynb
快速消费品	quickstart_fmcg.ipynb
体育媒体	quickstart_sports_media.ipynb
Databricks Unity Catalog [医疗保健]	quickstart_healthcare_databricks.ipynb	仅限 Databricks 笔记本
Snowflake Horizon Catalog [快速消费品]	quickstart_fmcg_snowflake.ipynb	仅限 Snowflake 笔记本
原生 Snowflake 与 Cortex Analyst [科技制造]	quickstart_native_snowflake.ipynb
原生 Databricks 与 AI/BI Genie [科技制造]	quickstart_native_databricks.ipynb
Streamlit 应用	quickstart_streamlit.ipynb
概念搜索	quickstart_conceptual_search.ipynb
复合关系预测	quickstart_basketball_composite_links.ipynb

这些数据集将引导您完成以下步骤：

• 生成语义模型 → 统一层，用于转换碎片化数据集，为互联智能奠定基础。
  • 1.1 数据画像与分类 → 分析您的数据源，了解其结构、数据类型和其他特征。
  • 1.2 发现数据间的链接与关系 → 揭示跨碎片化表的有意义连接（主键与外键），包括复合键。
  • 1.3 生成业务术语表 → 创建业务友好的术语，并使用它们结合上下文查询数据。
  • 1.4 启用语义搜索 → 智能搜索，理解含义而非仅匹配关键词——使数据对技术和业务用户都更易于访问。
  • 1.5 可视化语义模型→ 以 YAML 文件形式获取语义层的丰富元数据，并以图谱形式进行可视化。
• 构建统一数据产品 → 只需跨数据表选择属性，让工具包利用语义层自动生成包含所有必要连接、转换和聚合的查询。执行这些查询即可生成可复用的数据产品。

文档

有关更详细的信息、高级用法和教程，请参阅我们的完整文档站点。

用法

项目的核心工作流程包括使用 SemanticModel 构建语义层，然后使用 DataProduct 从该层生成数据产品。

from intugle import SemanticModel

# Define your datasets
datasets = {
    "allergies": {"path": "path/to/allergies.csv", "type": "csv"},
    "patients": {"path": "path/to/patients.csv", "type": "csv"},
    "claims": {"path": "path/to/claims.csv", "type": "csv"},
    # ... add other datasets
}

# Build the semantic model
sm = SemanticModel(datasets, domain="Healthcare")
sm.build()

# Access the profiling results
print(sm.profiling_df.head())

# Access the discovered links
print(sm.links_df)

有关详细的代码示例和完整演练，请参阅我们的快速入门笔记本。

数据产品

一旦语义模型构建完成，您可以使用 DataProduct 类从语义层生成统一的数据产品。

from intugle import DataProduct

# Define an ETL model
etl = {
  "name": "top_patients_by_claim_count",
  "fields": [
    {
      "id": "patients.first",
      "name": "first_name",
    },
    {
      "id": "patients.last",
      "name": "last_name",
    },
    {
      "id": "claims.id",
      "name": "number_of_claims",
      "category": "measure",
      "measure_func": "count"
    }
  ],
  "filter": {
    "sort_by": [
      {
        "id": "claims.id",
        "alias": "number_of_claims",
        "direction": "desc"
      }
    ],
    "limit": 10
  }
}

# Create a DataProduct and build it
dp = DataProduct()
data_product = dp.build(etl)

# View the data product as a DataFrame
print(data_product.to_df())

语义搜索

语义搜索功能允许您使用自然语言搜索数据集中的列。它基于 Qdrant 向量数据库构建。

有关完整的设置说明（包括 Docker 命令和环境变量），请参阅语义搜索文档。

用法

构建语义模型后，您可以使用 search 方法执行语义搜索。该搜索函数返回一个 pandas DataFrame，其中包含搜索结果，包括列的画像指标、类别、表名和表术语表。

from intugle import SemanticModel

# Define your datasets
datasets = {
    "allergies": {"path": "path/to/allergies.csv", "type": "csv"},
    "patients": {"path": "path/to/patients.csv", "type": "csv"},
    "claims": {"path": "path/to/claims.csv", "type": "csv"},
    # ... add other datasets
}

# Build the semantic model
sm = SemanticModel(datasets, domain="Healthcare")
sm.build()
# Perform a semantic search
search_results = sm.search("reason for hospital visit")

# View the search results
print(search_results)

有关详细的代码示例和完整演练，请参阅我们的快速入门笔记本。

MCP 服务器

Intugle 包含一个内置的 MCP（模型上下文协议）服务器，可将您的语义层暴露给 AI 助手和 LLM 驱动的客户端。其主要目的是允许代理通过使用 get_tables 和 get_schema 等工具来理解您的数据结构。

一旦您的语义模型构建完成，您可以通过一个简单的命令启动服务器：

intugle-mcp

这使得 AI 代理能够以编程方式与您的数据上下文进行交互。这也支持使用该库进行“氛围编码”。

有关设置服务器和连接您喜爱的客户端的详细说明，请参阅我们的完整文档。

社区

加入我们的社区，提出问题、分享您的项目并与其他用户交流。

• 加入我们的 Discord

贡献

欢迎贡献！请参阅 CONTRIBUTING.md 文件了解指南。

许可证

本项目基于 Apache License, Version 2.0 许可。详情请参阅 LICENSE 文件。 第三方软件声明可在 NOTICE 文件中查看。