Intugle Mcp

由生成式 AI 驱动的自动化数据智能工具包。

将零散数据转化为互联的语义数据模型

概述

Intugle 是一个由生成式 AI 驱动的开源 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_PROVIDER：要使用的大模型提供商和模型（例如 openai:gpt-3.5-turbo），并遵循 LangChain 的约定
• API_KEY：大模型提供商的 API 密钥。变量的确切名称可能因提供商而异。

以下示例展示了如何在环境中设置这些变量：

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

快速入门

如需详细的实践介绍，请参阅我们的快速入门笔记本：

领域	Notebook	在 Colab 中打开
医疗保健	quickstart_healthcare.ipynb
科技制造	quickstart_tech_manufacturing.ipynb
快速消费品	quickstart_fmcg.ipynb
体育媒体	quickstart_sports_media.ipynb
Databricks Unity Catalog［医疗保健］	quickstart_healthcare_databricks.ipynb	仅限 Databricks Notebook
Snowflake Horizon Catalog［快速消费品］	quickstart_fmcg_snowflake.ipynb	仅限 Snowflake Notebook
原生 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（Model Context Protocol）服务，可向 AI 助手和由大模型驱动的客户端公开语义层。它的主要用途是让 Agent 使用 get_tables 和 get_schema 等工具来理解数据结构。

构建语义模型后，只需运行一条简单命令即可启动服务：

intugle-mcp

这样，AI Agent 就能以编程方式与数据上下文进行交互。它还支持使用该库进行氛围编程。

如需了解有关服务设置和连接常用客户端的详细说明，请参阅我们的完整文档。

社区

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

• 加入我们的 Discord

贡献

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

许可证

本项目采用 Apache License, Version 2.0 许可。详情请参阅 LICENSE 文件。 第三方软件声明请参阅 NOTICE 文件。