Hkg Ontologizer Kgb MCP

🚀 知识图谱构建器MCP服务器

知识图谱构建器，利用集成了MCP（模型上下文协议）的本地AI模型，将文本或网页内容转换为结构化的知识图谱，并持久存储在Neo4j和Qdrant中。

🚀 快速开始

本项目能够借助本地AI模型和MCP集成，将文本或网页内容转换为结构化知识图谱。只需按照以下步骤操作，即可快速体验其强大功能。

✨ 主要特性

• 本地AI处理：通过Ollama或LM Studio使用本地模型进行实体提取。
• 大内容支持：通过智能分块处理任意大的内容（300MB+）。
• 网页内容提取：无大小限制地抓取和分析完整网页。
• 知识图谱生成：创建包含实体和关系的结构化图谱。
• 智能分块：通过句子边界检测自动对大内容进行分块。
• 实体合并：智能合并各分块中的重复实体。
• 实时可视化：处理分块时实时更新SVG图谱。
• 交互式SVG输出：实体类型颜色编码并跟踪进度。
• MCP集成：将数据存储在Neo4j（图数据库）和Qdrant（向量数据库）中。
• UUID跟踪：生成UUIDv8以在各系统中统一跟踪实体。
• Gradio界面：用户友好的网页界面，提供双JSON/SVG输出。

📊 提取的实体类型

• 👥 个人：姓名、个体、关键人物。
• 🏢 组织：公司、机构、团体。
• 📍 地点：地方、国家、地区、地址。
• 💡 概念：想法、技术、抽象概念。
• 📅 事件：特定事件、发生的事情、事故。
• 🔧 其他：不属于其他类别的杂项实体。

📦 安装指南

依赖安装

pip install -r requirements.txt

# 若需要完整的可视化功能：
pip install networkx matplotlib

环境变量配置

如需详细的配置说明和完整的环境变量参考，请参阅下面的 🎛️ 配置 部分。

快速启动配置：

# 基本设置（使用合理的默认值）
export MODEL_PROVIDER=ollama
export LOCAL_MODEL=llama3.2:latest

# 可选：自定义端点和处理限制
export OLLAMA_BASE_URL=http://localhost:11434
export CHUNK_SIZE=2000
export MAX_CHUNKS=0

注意：所有环境变量都是可选的，并且有合理的默认值。无需任何配置，应用程序也能运行。

本地模型设置

使用Ollama：

# 安装并启动Ollama
curl -fsSL https://ollama.ai/install.sh | sh
ollama serve

# 拉取模型
ollama pull llama3.2:latest

使用LM Studio：

1. 下载并安装LM Studio。
2. 在本地服务器加载模型。
3. 在端口1234上启动本地服务器。

💻 使用示例

基础用法

文本输入

粘贴任何文本内容进行分析：

苹果公司由史蒂夫·乔布斯、史蒂夫·沃兹尼亚克和罗纳德·韦恩于1976年创立。该公司总部位于加利福尼亚州库比蒂诺。

URL输入

提供网页URL进行提取和分析：

https://en.wikipedia.org/wiki/Artificial_intelligence

大内容处理（300MB+文件）

对于非常大的内容，如大语言模型对话记录：

# 示例：处理300MB的对话日志
# 系统将自动执行以下操作：
# 1. 检测大内容（默认超过2000个字符）
# 2. 在句子边界处智能分块
# 3. 使用本地AI模型处理每个分块
# 4. 合并和去重实体/关系
# 5. 在混合知识图谱（hKG）中进行完整的谱系跟踪存储

# 处理过程将显示进度：
# "正在分块处理大内容（314,572,800个字符）..."
# "正在处理157,286个分块..."
# "正在处理第1/157,286个分块（2000个字符）..."
# "合并结果：45,231个实体，128,904个关系"

输出格式

系统返回结构化的JSON知识图谱：

{
  "source": {
    "type": "text|url",
    "value": "input_value",
    "content_preview": "前200个字符..."
  },
  "knowledge_graph": {
    "entities": [
      {
        "name": "苹果公司",
        "type": "ORGANIZATION",
        "description": "成立于1976年的科技公司"
      }
    ],
    "relationships": [
      {
        "source": "史蒂夫·乔布斯",
        "target": "苹果公司",
        "relationship": "FOUNDED",
        "description": "史蒂夫·乔布斯创立了苹果公司"
      }
    ],
    "entity_count": 5,
    "relationship_count": 4
  },
  "visualization": {
    "svg_content": "<svg>...</svg>",
    "svg_file_path": "/path/to/knowledge_graph_12345678.svg",
    "visualization_available": true,
    "real_time_updates": false,
    "incremental_files_saved": 0,
    "entity_color_mapping": {
      "ORGANIZATION": "#4ECDC4",
      "PERSON": "#FF6B6B"
    },
    "svg_generation_timestamp": "2024-01-15T10:30:05Z",
    "visualization_engine": "networkx+matplotlib"
  },
  "metadata": {
    "model": "ollama:llama3.2:latest",
    "content_length": 150,
    "uuid": "xxxxxxxx-xxxx-8xxx-xxxx-xxxxxxxxxxxx",
    "neo4j_stored": true,
    "qdrant_stored": true,
    "timestamp": "2024-01-15T10:30:00Z",
    "hkg_metadata": {
      "processing_method": "single",
      "chunk_count": 1,
      "chunk_size": 2000,
      "chunk_overlap": 200,
      "source_type": "text",
      "supports_large_content": true,
      "max_content_size": "unlimited",
      "visualization_integration": {
        "real_time_visualization": false,
        "svg_files_generated": 1,
        "entity_color_tracking": true,
        "visualization_lineage": true,
        "incremental_updates": false,
        "neo4j_viz_metadata": true,
        "qdrant_viz_metadata": true
      }
    }
  }
}

🎨 实时图谱可视化

SVG生成特性

• 实体类型颜色编码：每种实体类型都有独特的颜色（人物=红色，组织=青色，地点=蓝色，概念=绿色，事件=黄色，其他=李子色）。
• 交互式布局：使用NetworkX弹簧布局算法自动进行图谱布局。
• 关系标签：边标签显示实体之间的关系类型。
• 实体信息：节点标签包含实体名称和类型。
• 图例：根据存在的实体类型自动生成图例。
• 统计信息：实时显示实体和关系的数量。

大内容实时处理

• 进度跟踪：可视化进度条显示分块处理完成情况。
• 增量更新：处理每个分块后更新图谱。
• 实时统计：实时显示发现的实体和关系总数。
• 增量文件保存：每个分块创建一个带时间戳的SVG文件。
• 最终可视化：将完整图谱保存为最终SVG文件。

文件输出

• 单内容：knowledge_graph_<uuid8>.svg
• 大内容（分块处理）：
  • 增量：knowledge_graph_<uuid8>_chunk_0001.svg、chunk_0002.svg 等。
  • 最终：knowledge_graph_<uuid8>.svg

大内容处理示例

# 处理300MB的对话日志：
# "正在分块处理大内容（314,572,800个字符）..."
# "正在处理157,286个分块..."

# 实时更新：
# "正在处理第1/157,286个分块（2000个字符）..."
# "实时图谱更新：更新后的图谱：5个实体，3个关系（第1/157,286个分块）"
# "保存增量图谱：knowledge_graph_12345678_chunk_0001.svg"

# "正在处理第2/157,286个分块（2000个字符）..."
# "实时图谱更新：更新后的图谱：12个实体，8个关系（第2/157,286个分块）"
# "保存增量图谱：knowledge_graph_12345678_chunk_0002.svg"

# ... 继续处理所有分块 ...

# "最终结果：45,231个实体，128,904个关系"
# "保存最终可视化图谱：knowledge_graph_12345678.svg"

🗄️ 混合知识图谱（hKG）存储与可视化集成

Neo4j集成（图数据库）

• 将实体作为节点存储，包含属性和增强元数据。
• 创建实体之间的关系，并进行谱系跟踪。
• 在所有数据库中使用UUIDv8进行实体跟踪。
• 跟踪大内容处理的分块元数据。
• 记录处理方法（单块或分块）。
• 新增 - 可视化谱系：实体观测中包含以下可视化元数据：
  • SVG文件路径和可用性状态。
  • 图谱可视化的实体颜色映射。
  • 分块处理的实时更新跟踪。
  • 可视化引擎信息。
• 可通过MCP服务器工具访问。

Qdrant集成（向量数据库）

• 将知识图谱存储为向量嵌入，并包含增强元数据。
• 支持跨任意大小知识图谱的语义搜索。
• 维护每个知识图谱的元数据，包括分块信息。
• 跟踪内容长度、处理方法和分块数量。
• 支持跨大型文档集合的相似度搜索。
• 新增 - 可视化谱系：包括以下可视化跟踪信息：
  • 实体类型和颜色映射信息。
  • SVG生成时间戳和文件路径。
  • 实时可视化更新历史。
  • 大内容的增量SVG文件跟踪。
• 可通过MCP服务器工具访问。

具有可视化谱系的hKG统一跟踪

• 全系统UUIDv8：使用通用的祖先编码标识符。
• 内容谱系：跟踪大内容的处理和分块方式。
• 处理元数据：记录分块大小、重叠和处理方法。
• 实体来源：跟踪每个实体来自哪些分块。
• 关系映射：维护跨分块边界的关系。
• 语义一致性：确保知识图谱在各数据库之间的一致性。
• 新增 - 可视化谱系：完整跟踪可视化表示：
  • SVG文件来源：跟踪所有生成的可视化文件。
  • 颜色映射一致性：在各分块和存储系统中保持实体颜色分配一致。
  • 实时可视化历史：记录所有增量可视化更新。
  • 跨数据库可视化元数据：在Neo4j和Qdrant中同步可视化跟踪。
  • 增量可视化跟踪：完整记录实时图谱更新的审计轨迹。

🔧 技术细节

核心组件

• app.py：带有Gradio界面的主应用文件。
• extract_text_from_url()：网页抓取功能（app.py:41）。
• chunk_text()：通过句子边界检测进行智能内容分块（app.py:214）。
• merge_extraction_results()：智能合并分块结果（app.py:250）。
• get_entity_color()：实体类型颜色映射（app.py:299）。
• create_knowledge_graph_svg()：SVG图谱生成（app.py:311）。
• RealTimeGraphVisualizer：实时增量可视化（app.py:453）。
• extract_entities_and_relationships()：具有实时更新的AI实体提取（app.py:645）。
• extract_entities_and_relationships_single()：单分块处理（app.py:722）。
• build_knowledge_graph()：带有可视化的主要编排函数（app.py:795）。
• generate_uuidv8()：用于实体跟踪的UUID生成（app.py:68）。

与hKG集成和实时可视化的数据流

1. 输入处理：验证文本或URL输入。
2. 内容提取：对于URL进行网页抓取，对于文本输入直接使用文本。
3. 实时可视化器设置：初始化增量图谱可视化系统。
4. 内容分块：对于大内容（超过2000个字符）通过句子边界检测进行智能分块。
5. 实时更新的AI分析：本地模型处理每个分块以提取实体和关系。
6. 增量可视化：每个分块处理完成后实时更新SVG图谱。
7. 结果合并：智能去重和合并各分块中的实体和关系。
8. hKG元数据创建：生成用于谱系跟踪的处理元数据。
9. 图谱生成：创建带有增强元数据的结构化知识图谱。
10. 最终可视化：生成包含所有实体和关系的完整SVG图谱。
11. hKG存储：使用统一的UUIDv8跟踪，将数据持久存储在Neo4j（图）和Qdrant（向量）中。
12. 输出：返回包含完整知识图谱、hKG元数据和SVG可视化的JSON响应。

🎛️ 配置

环境变量参考

所有配置均通过环境变量处理。应用程序为所有设置提供了合理的默认值，无需任何配置即可运行，同时也支持完全自定义。

完整环境变量表

属性	详情
MODEL_PROVIDER	字符串
LOCAL_MODEL	字符串
OLLAMA_BASE_URL	字符串
LMSTUDIO_BASE_URL	字符串
CHUNK_SIZE	整数
CHUNK_OVERLAP	整数
MAX_CHUNKS	整数
HF_TOKEN	字符串

配置方法

1. 环境变量（推荐）

# 核心模型配置
export MODEL_PROVIDER=ollama
export LOCAL_MODEL=llama3.2:latest
export OLLAMA_BASE_URL=http://localhost:11434

# 大内容处理
export CHUNK_SIZE=2000
export CHUNK_OVERLAP=200
export MAX_CHUNKS=0

2. Shell配置（.bashrc/.zshrc）

# 添加到 ~/.bashrc 或 ~/.zshrc
export MODEL_PROVIDER=ollama
export LOCAL_MODEL=llama3.2:latest
export OLLAMA_BASE_URL=http://localhost:11434
export CHUNK_SIZE=2000
export CHUNK_OVERLAP=200
export MAX_CHUNKS=0

3. Python环境文件（.env）

# 在项目根目录创建 .env 文件
MODEL_PROVIDER=ollama
LOCAL_MODEL=llama3.2:latest
OLLAMA_BASE_URL=http://localhost:11434
LMSTUDIO_BASE_URL=http://localhost:1234
CHUNK_SIZE=2000
CHUNK_OVERLAP=200
MAX_CHUNKS=0

模型提供商配置

Ollama配置（默认）

# 基本Ollama设置
export MODEL_PROVIDER=ollama
export LOCAL_MODEL=llama3.2:latest
export OLLAMA_BASE_URL=http://localhost:11434

# 替代模型
export LOCAL_MODEL=mistral:7b          # Mistral 7B
export LOCAL_MODEL=codellama:13b       # Code Llama 13B
export LOCAL_MODEL=llama3.2:3b         # Llama 3.2 3B（更快）
export LOCAL_MODEL=phi3:mini           # Phi-3 Mini（轻量级）

# 远程Ollama实例
export OLLAMA_BASE_URL=http://192.168.1.100:11434

LM Studio配置

# 基本LM Studio设置
export MODEL_PROVIDER=lmstudio
export LOCAL_MODEL=any-model-name      # LM Studio的模型名称可灵活设置
export LMSTUDIO_BASE_URL=http://localhost:1234

# 自定义LM Studio端口
export LMSTUDIO_BASE_URL=http://localhost:8080

# 远程LM Studio实例
export LMSTUDIO_BASE_URL=http://192.168.1.200:1234

大内容处理配置

分块大小优化

# 小分块（处理速度快，分块数量多）
export CHUNK_SIZE=1000
export CHUNK_OVERLAP=100

# 中等分块（性能平衡）
export CHUNK_SIZE=2000    # 默认
export CHUNK_OVERLAP=200  # 默认

# 大分块（分块数量少，上下文更多）
export CHUNK_SIZE=4000
export CHUNK_OVERLAP=400

# 非常大的分块（上下文最大，速度慢）
export CHUNK_SIZE=8000
export CHUNK_OVERLAP=800

处理限制

# 无限制处理（默认）
export MAX_CHUNKS=0

# 仅处理前100个分块（测试用）
export MAX_CHUNKS=100

# 处理前1000个分块（中等数据集）
export MAX_CHUNKS=1000

# 处理前10000个分块（大型数据集）
export MAX_CHUNKS=10000

性能调优指南

速度优化

# 较小分块、较少重叠、有限处理
export CHUNK_SIZE=1000
export CHUNK_OVERLAP=50
export MAX_CHUNKS=500
export LOCAL_MODEL=llama3.2:3b  # 更快的模型

质量优化

# 较大分块、更多重叠、无限制处理
export CHUNK_SIZE=4000
export CHUNK_OVERLAP=400
export MAX_CHUNKS=0
export LOCAL_MODEL=llama3.2:latest  # 完整模型

内存受限系统

# 资源有限时的平衡设置
export CHUNK_SIZE=1500
export CHUNK_OVERLAP=150
export MAX_CHUNKS=1000
export LOCAL_MODEL=phi3:mini  # 轻量级模型

配置验证

应用程序会自动验证配置设置：

• 模型提供商：验证 MODEL_PROVIDER 为 "ollama" 或 "lmstudio"。
• URL：验证提供商URL是否可访问。
• 数值：确保 CHUNK_SIZE、CHUNK_OVERLAP 和 MAX_CHUNKS 为有效整数。
• 模型可用性：检查指定的模型在提供商上是否可用。

配置故障排除

常见问题及解决方案

1. 模型提供商无响应

# 检查Ollama是否正在运行
curl http://localhost:11434/api/version

# 检查LM Studio是否正在运行
curl http://localhost:1234/v1/models

# 解决方案：启动相应服务
ollama serve  # 对于Ollama
# 或者启动LM Studio GUI并启用本地服务器

2. 模型未找到

# 列出可用的Ollama模型
ollama list

# 拉取缺失的模型
ollama pull llama3.2:latest

# 对于LM Studio：在GUI中加载模型

3. 大内容处理时的内存问题

# 减小分块大小并设置限制
export CHUNK_SIZE=1000
export MAX_CHUNKS=100

# 使用更轻量级的模型
export LOCAL_MODEL=llama3.2:3b

4. 处理速度慢

# 优化速度
export CHUNK_SIZE=1500
export CHUNK_OVERLAP=100
export MAX_CHUNKS=500
export LOCAL_MODEL=phi3:mini

示例配置场景

场景1：开发环境设置

# 快速迭代，有限处理
export MODEL_PROVIDER=ollama
export LOCAL_MODEL=llama3.2:3b
export CHUNK_SIZE=1000
export CHUNK_OVERLAP=100
export MAX_CHUNKS=50

场景2：生产环境设置

# 高质量，无限制处理
export MODEL_PROVIDER=ollama
export LOCAL_MODEL=llama3.2:latest
export CHUNK_SIZE=3000
export CHUNK_OVERLAP=300
export MAX_CHUNKS=0

场景3：大型数据集处理

# 针对300MB+文件进行优化
export MODEL_PROVIDER=ollama
export LOCAL_MODEL=llama3.2:latest
export CHUNK_SIZE=2000
export CHUNK_OVERLAP=200
export MAX_CHUNKS=0

场景4：资源受限环境

# 最小化资源使用
export MODEL_PROVIDER=ollama
export LOCAL_MODEL=phi3:mini
export CHUNK_SIZE=800
export CHUNK_OVERLAP=50
export MAX_CHUNKS=200

高级配置

自定义模型端点

# 基于Docker的Ollama
export OLLAMA_BASE_URL=http://ollama-container:11434

# Kubernetes服务
export OLLAMA_BASE_URL=http://ollama-service.default.svc.cluster.local:11434

# 负载均衡器
export OLLAMA_BASE_URL=http://ollama-lb.example.com:11434

动态配置

应用程序在启动时读取环境变量。要更改配置：

1. 设置新的环境变量。
2. 重启应用程序。
3. 配置更改将立即生效。

错误处理

对以下情况进行全面的错误处理：

• 无效的URL或网络故障。
• 缺少本地模型或API端点。
• 大语言模型响应的JSON解析错误。
• 格式错误或为空的输入。
• 数据库连接问题。
• 无效的配置值。
• 模型提供商连接问题。
• 大内容处理时的内存限制问题。

🔍 hKG MCP集成与可视化谱系

应用程序与MCP服务器集成，实现混合知识图谱存储，并进行完整的可视化跟踪：

• Neo4j：带有增强元数据和可视化谱系的图数据库存储和查询。
• Qdrant：带有分块跟踪和可视化元数据的向量数据库，用于语义搜索。
• 统一跟踪：在所有存储系统中使用UUIDv8进行实体谱系和可视化来源跟踪。
• 元数据持久化：处理方法、分块数量、内容谱系和SVG生成跟踪。
• 大内容支持：通过分块和实时可视化无缝处理300MB+的内容。
• 可视化集成：在所有存储系统中进行完整的可视化表示跟踪。

通过MCP增强的hKG功能

• 实体来源：跟踪每个实体来自哪些内容分块及其可视化表示。
• 关系谱系：维护跨分块边界的关系和可视化边跟踪。
• 内容祖先：使用UUIDv8编码进行分层内容跟踪和可视化文件谱系。
• 处理审计：完整记录大内容的处理方式和可视化生成过程。
• 语义搜索：跨任意大小知识图谱的向量相似度搜索和可视化元数据搜索。
• 新增 - 可视化谱系：完整的可视化跟踪包括：
  • SVG文件来源：跟踪所有生成的可视化文件及其时间戳。
  • 实体颜色一致性：在所有分块和存储系统中保持颜色映射一致。
  • 实时可视化历史：记录处理过程中的每个增量图谱更新。
  • 跨数据库可视化同步：在Neo4j和Qdrant中同步可视化元数据。
  • 增量可视化审计：完整记录大内容实时更新的轨迹。

可视化增强存储

• Neo4j实体观测 现在包括：
  • SVG文件路径和生成状态。
  • 实体颜色分配以确保视觉一致性。
  • 分块处理的实时更新计数。
  • 可视化可用性和引擎信息。
• Qdrant向量内容 现在包括：
  • 用于相似度搜索的实体颜色映射信息。
  • SVG生成时间戳和文件路径。
  • 实时可视化更新元数据。
  • 大内容可视化的增量文件跟踪。

在配置了MCP服务器的Claude Code环境中运行时，MCP工具将自动可用。

🎯 hKG可视化架构

集成可视化谱系系统

hKG系统现在在传统知识图谱存储的基础上，维护完整的可视化谱系：

┌─────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
│   源文本        │───▶│  分块 + AI处理       │───▶│  实体/关系提取     │
│   (300MB+)      │    │                      │    │                     │
└─────────────────┘    └──────────────────────┘    └─────────────────────┘
                                 │                           │
                                 ▼                           ▼
┌─────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
│  实时SVG生成    │◀───│  增量图谱可视化     │◀───│  合并结果 + 去重    │
│                 │    │                      │    │                     │
└─────────────────┘    └──────────────────────┘    └─────────────────────┘
         │                        │                           │
         ▼                        ▼                           ▼
┌─────────────────┐    ┌──────────────────────┐    ┌─────────────────────┐
│  SVG文件存储    │    │  可视化元数据创建   │    │  hKG存储            │
│  (增量)         │    │                      │    │  (Neo4j + Qdrant)   │
└─────────────────┘    └──────────────────────┘    └─────────────────────┘

可视化元数据流程

1. 实时更新：每个分块生成带有进度跟踪的增量SVG。
2. 颜色一致性：在所有分块和存储系统中保持实体颜色一致。
3. 文件谱系：完整记录所有生成的SVG文件的审计轨迹。
4. 跨数据库同步：在Neo4j和Qdrant中同步可视化元数据。
5. 来源跟踪：关联源分块、实体及其可视化表示。

hKG对大内容（300MB+）的优势

• 可视化进度监控：处理过程中实时监控图谱演变。
• 分块级可视化：每个处理阶段的单个SVG文件。
• 完整审计轨迹：从源文本到最终可视化的完整谱系。
• 交叉引用能力：将实体关联回其源分块和可视化外观。
• 可扩展可视化：以一致的性能处理任意大的图谱。

📊 开发

项目结构

KGB-mcp/
├── app.py                 # 主应用程序
├── requirements.txt       # 依赖项
├── CLAUDE.md             # Claude Code说明
├── ARCHITECTURE.md       # 系统架构
├── test_core.py          # 核心功能测试
└── test_integration.py   # 集成测试

测试

# 运行核心测试
python test_core.py

# 运行集成测试
python test_integration.py

借助本地AI和MCP集成的强大功能，将任何内容转换为结构化的知识图谱！