Hkg Ontologizer Kgb MCP

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

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

🚀 快速开始

安装依赖

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

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

启动应用程序

python app.py

应用程序将启动一个带有MCP服务器功能的Gradio界面。

✨ 主要特性

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

📊 提取的实体类型

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

📦 安装指南

本地模型设置

对于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个关系"
# "保存最终SVG可视化：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响应。

配置

环境变量参考

所有配置都通过环境变量处理。应用程序为所有设置提供了合理的默认值，允许在不进行任何配置的情况下运行，同时也提供了完全的自定义选项。

完整的环境变量表

配置方法

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集成的强大功能，将任何内容转化为结构化的知识图谱！