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集成的強大功能，將任何內容轉換為結構化的知識圖譜！