Force-Directed Knowledge Graph Visualization

Knowledge Graph là gì trong GoClaw?

Knowledge Graph hoạt động qua ba tầng:

1. Extraction Layer — Sử dụng LLM để khai thác entities và relations từ văn bản hội thoại, với confidence scoring
2. Storage Layer — PostgreSQL với pgvector (embeddings), Full-Text Search (FTS), và hệ thống deduplication tự động
3. Visualization Layer — ReactFlow + D3 force-directed graph với hỗ trợ theme, depth visualization, và giới hạn 50 entities cho hiệu năng DOM

Kiến trúc tổng quan

Luồng xử lý chính

Schema và Entity Types

Các loại thực thể

Các trường quan trọng

Pipeline trích xuất thực thể

Chi tiết các bước

Relation Types

Tìm kiếm kết hợp (Hybrid Search)

Graph Traversal và Depth Visualization

Recursive CTE — Nơi cốt lõi

Traversal sử dụng PostgreSQL recursive CTE để đi qua graph:

WITH RECURSIVE paths AS (
    -- Anchor: start entity tại depth=1
    SELECT e.*, 1 AS depth,
           ARRAY[e.id::text] AS path,
           ''::text AS via
    FROM kg_entities e
    WHERE e.id = $start_id AND e.agent_id = $agent_id

    UNION ALL

    -- Forward: source → target
    SELECT e.*, p.depth + 1,
           p.path || e.id::text,
           r.relation_type
    FROM paths p
    JOIN kg_relations r ON p.id = r.source_entity_id
    JOIN kg_entities e ON r.target_entity_id = e.id
    WHERE p.depth < $max_depth
      AND NOT e.id::text = ANY(p.path)

    UNION ALL

    -- Reverse: target → source (prefix ~)
    SELECT e.*, p.depth + 1,
           p.path || e.id::text,
           '~' || r.relation_type
    FROM paths p
    JOIN kg_relations r ON p.id = r.target_entity_id
    JOIN kg_entities e ON r.source_entity_id = e.id
    WHERE p.depth < $max_depth
      AND NOT e.id::text = ANY(p.path)
)
SELECT ... FROM paths WHERE depth > 1

Traversal Result

interface KGTraversalResult {
  entity: KGEntity      // Dữ liệu thực thể đầy đủ
  depth: number         // Số hops từ thực thể gốc (1, 2, 3)
  path: string[]        // Các entity ID trên đường đi
  via: string           // Loại quan hệ ở hop cuối cùng
}

Minh hoạ Depth Traversal

Bắt đầu từ "Alice" và khám phá các mối quan hệ:

Chiến lược khử trùng lặp

Interactive 3D Graph Demo

Click vào node để highlight edges (glow + particles chạy dọc edge). Double-click mở chi tiết. Kéo chuột để xoay, scroll để zoom.

Force Layout Parameters

Entity Mass (ảnh hưởng kích thước và lực đẩy)

Adaptive Force Params v2.47.3

Force layout tự động scale theo số lượng node thực tế — tighter cho graph nhỏ (<30 nodes), spread cho graph lớn (60+):

Degree Centrality Selection v2.47.3

Trước đây, API trả entities theo created_at DESC — hub nodes cũ có nhiều connections có thể bị loại khỏi GRAPH_LIMIT. Giờ entities được sort by connection count (degree centrality) trước khi slice, đảm bảo hub nodes luôn xuất hiện trong graph.

Theme-Aware Rendering

Graph hỗ trợ chuyển đổi theme real-time. Khi theme thay đổi mà data không đổi, chỉ update màu node qua setNodes — không re-layout. Khi data thay đổi, full re-layout qua computeForceLayout.

10 cải tiến hiệu năng trong v2.47.x

1. O(1) Entity Lookup via Map

entities.find(e => e.id === id)
// O(n) mỗi lần selection

useMemo(() =>
  new Map(entities.map(e => [e.id, e]))
, [entities])
// O(1) lookup

2. Pre-computed Edge Style Constants

3. EntityNode Memoization

4. Force Simulation Tick Cap

5–7. Các fix bổ sung

8. Deferred Dialog Open v2.47.3

9. Memoized RelationsTable v2.47.3

10. Adaptive Force Params v2.47.3

Multi-Tenancy và Bảo mật

-- Single-tenant mode
WHERE agent_id = $1 AND user_id = $2 AND tenant_id = $3

-- Shared/admin mode (cross-user)
WHERE agent_id = $1 AND tenant_id = $2

API Reference