Hkg Ontologizer Kgb Mcp

笔记 Python

🚀 知识图谱构建器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：

下载并安装LM Studio。
在本地服务器加载模型。
在端口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_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_.svg
大内容（分块处理）：
- 增量文件：knowledge_graph__chunk_0001.svg、chunk_0002.svg等。
- 最终文件：knowledge_graph_.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集成和实时可视化的数据流

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

配置

环境变量参考

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

完整的环境变量表

变量	类型	默认值	是否必需	描述	示例值
`MODEL_PROVIDER`	字符串	`"ollama"`	否	要使用的AI模型提供商	`"ollama"`, `"lmstudio"`
`LOCAL_MODEL`	字符串	`"llama3.2:latest"`	否	本地模型标识符	`"llama3.2:latest"`, `"mistral:7b"`, `"codellama:13b"`
`OLLAMA_BASE_URL`	字符串	`"http://localhost:11434"`	否	Ollama API端点	`"http://localhost:11434"`, `"http://192.168.1.100:11434"`
`LMSTUDIO_BASE_URL`	字符串	`"http://localhost:1234"`	否	LM Studio API端点	`"http://localhost:1234"`, `"http://127.0.0.1:1234"`
`CHUNK_SIZE`	整数	`2000`	否	用于AI处理的每个分块的字符数	`1000`, `2000`, `4000`, `8000`
`CHUNK_OVERLAP`	整数	`200`	否	分块之间的重叠字符数，用于上下文	`100`, `200`, `400`, `500`
`MAX_CHUNKS`	整数	`0`	否	要处理的最大分块数（0表示无限制）	`0`, `100`, `1000`, `5000`
`HF_TOKEN`	字符串	`None`	否	HuggingFace API令牌（旧版，未使用）	`"hf_xxxxxxxxxxxx"`

配置方法

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

动态配置

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

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

错误处理

全面的错误处理涵盖以下情况：

无效的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)  │
│                 │    │                      │    │  + 可视化元数据     │
└─────────────────┘    └──────────────────────┘    └─────────────────────┘

可视化元数据流程

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

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

0 条评论
分类：笔记