12.4 · Graph Visualization

Graph Visualization（中文译文）

原始 DeepWiki 页面：https://deepwiki.com/topoteretes/cognee/12.4-graph-visualization

翻译时间：2026-05-27T08:45:20.794Z

翻译模型：deepseek-chat

原文字符数：12281

项目：Cognee (cognee)

---

图谱可视化

相关源文件

以下文件被用作生成此维基页面的上下文：

• cognee/__init__.py
• cognee/api/client.py
• cognee/api/v1/visualize/__init__.py
• cognee/api/v1/visualize/visualize.py
• cognee/infrastructure/engine/models/DataPoint.py
• cognee/modules/chunking/models/DocumentChunk.py
• cognee/modules/engine/models/Entity.py
• cognee/modules/engine/models/EntityType.py
• cognee/modules/pipelines/operations/run_tasks_base.py
• cognee/modules/pipelines/operations/run_tasks_with_telemetry.py
• cognee/modules/visualization/cognee_network_visualization.py
• cognee/shared/CodeGraphEntities.py
• cognee/shared/utils.py
• cognee/tasks/summarization/models.py
• cognee/tests/test_telemetry.py
• cognee/tests/unit/infrastructure/engine/test_identity_fields.py
• cognee/tests/unit/modules/visualization/visualization_test.py
• cognee/tests/unit/processing/utils/utils_test.py
• examples/custom_pipelines/organizational_hierarchy/organizational_hierarchy_pipeline_example.py
• examples/guides/consolidate_entity_descriptions_example.py
• examples/guides/custom_data_models.py
• examples/guides/custom_graph_model.py
• examples/guides/custom_prompts.py
• examples/guides/custom_tasks_and_pipelines.py
• examples/guides/graph_visualization.py
• examples/guides/importance_weight.py
• examples/guides/improve_quickstart.py
• examples/guides/ontology_quickstart.py

目的与范围

图谱可视化为 Cognee 构建的知识图谱提供了基于 HTML 的交互式可视化能力。本指南主要介绍以下内容：

• 使用 visualize_graph 和 visualize_multi_user_graph 函数
• 理解交互功能：缩放控制、搜索以及按模式着色（类型、任务、管线、节点集、用户）
• 在可视化中使用溯源追踪
• 聚合来自多个用户和数据集的图谱

该系统将图数据库中的图谱数据转换为自包含的 HTML 文件，并嵌入 D3.js 可视化。每个节点和边都携带溯源元数据（source_pipeline、source_task、source_user、source_node_set），可用于视觉过滤和颜色编码。

来源：cognee/api/v1/visualize/visualize.py:17-30，cognee/modules/visualization/cognee_network_visualization.py:22-112

---

系统架构

可视化系统检索带有溯源元数据的图谱数据，生成用于视觉过滤的颜色映射，并生成自包含的 HTML 文件。

可视化生成流程

graph TB
    subgraph "数据检索"
        ["get_graph_engine()"]
        ["graph_engine.get_graph_data()"]
    end

    subgraph "cognee_network_visualization.py"
        ["nodes_list: List[dict]<br/>- 按类型映射颜色<br/>- 提取溯源信息"]
        ["links_list: List[dict]<br/>- 映射源/目标<br/>- 提取权重"]

        ["_generate_provenance_colors():<br/>- task_color_map<br/>- pipeline_color_map<br/>- node_set_color_map<br/>- user_color_map"]

        ["_build_html():<br/>- 嵌入节点/边 JSON<br/>- 注入 HTML 模板"]
    end

    subgraph "存储与输出"
        ["graph_visualization.html"]
        ["LocalFileStorage.store()"]
    end

    ["get_graph_engine()"] --> ["graph_engine.get_graph_data()"]
    ["graph_engine.get_graph_data()"] --> ["nodes_list: List[dict]<br/>- 按类型映射颜色<br/>- 提取溯源信息"]
    ["graph_engine.get_graph_data()"] --> ["links_list: List[dict]<br/>- 映射源/目标<br/>- 提取权重"]
    ["nodes_list: List[dict]<br/>- 按类型映射颜色<br/>- 提取溯源信息"] --> ["_generate_provenance_colors():<br/>- task_color_map<br/>- pipeline_color_map<br/>- node_set_color_map<br/>- user_color_map"]

    ["nodes_list: List[dict]<br/>- 按类型映射颜色<br/>- 提取溯源信息"] --> ["_build_html():<br/>- 嵌入节点/边 JSON<br/>- 注入 HTML 模板"]
    ["links_list: List[dict]<br/>- 映射源/目标<br/>- 提取权重"] --> ["_build_html():<br/>- 嵌入节点/边 JSON<br/>- 注入 HTML 模板"]
    ["_generate_provenance_colors():<br/>- task_color_map<br/>- pipeline_color_map<br/>- node_set_color_map<br/>- user_color_map"] --> ["_build_html():<br/>- 嵌入节点/边 JSON<br/>- 注入 HTML 模板"]

    ["_build_html():<br/>- 嵌入节点/边 JSON<br/>- 注入 HTML 模板"] --> ["graph_visualization.html"]
    ["graph_visualization.html"] --> ["LocalFileStorage.store()"]

来源：cognee/modules/visualization/cognee_network_visualization.py:22-112，cognee/api/v1/visualize/visualize.py:17-30

---

图谱数据与溯源

可视化依赖于在管线执行过程中标记的溯源字段，以实现交互式过滤和着色。

溯源标记

在 run_tasks_base.py 中执行任务时，_stamp_provenance 函数会递归地用来源元数据更新 DataPoint 实例。这些元数据对于 UI 中的"按模式着色"功能至关重要。

代码实体到元数据的映射

graph LR
    subgraph "代码实体空间：Cognee 核心"
        ["run_tasks_base.py"]
        ["DataPoint 类"]
        ["cognify()"]
    end

    subgraph "自然语言空间：溯源元数据"
        ["'source_pipeline'"]
        ["'source_task'"]
        ["'source_user'"]
        ["'source_node_set'"]
    end

    ["run_tasks_base.py"] -- "调用 _stamp_provenance" --> ["'source_pipeline'"]
    ["run_tasks_base.py"] -- "调用 _stamp_provenance" --> ["'source_task'"]
    ["DataPoint 类"] -- "存储元数据" --> ["'source_user'"]
    ["cognify()"] -- "触发管线" --> ["'source_node_set'"]

来源：cognee/infrastructure/engine/models/DataPoint.py:57-60，cognee/modules/pipelines/operations/run_tasks_base.py:33-91，cognee/__init__.py:23

节点类型颜色映射

在 cognee_network_visualization.py 中，默认颜色根据节点的 type 字段进行映射。如果 ontology_valid 为 True，则节点以中性浅灰色渲染，以区分已验证的模式元素。

节点类型	颜色	代码引用
Entity	#6510F4	cognee/modules/visualization/cognee_network_visualization.py:28
EntityType	#A550FF	cognee/modules/visualization/cognee_network_visualization.py:29
DocumentChunk	#0DFF00	cognee/modules/visualization/cognee_network_visualization.py:30
TextSummary	#6510F4	cognee/modules/visualization/cognee_network_visualization.py:31
ColumnValue	#747470	cognee/modules/visualization/cognee_network_visualization.py:34
DatabaseSchema	#6510F4	cognee/modules/visualization/cognee_network_visualization.py:36
默认	#7c3aed	cognee/modules/visualization/cognee_network_visualization.py:38
已验证	#D8D8D8	cognee/modules/visualization/cognee_network_visualization.py:47

---

核心函数

visualize_graph

这是生成当前图谱上下文可视化的主要入口点。它通过 GraphDBInterface 检索图谱数据，并将其处理为 HTML。

from cognee import visualize_graph

async def main():
    # 保存到指定路径
    await visualize_graph(destination_file_path = "./my_graph.html")

来源：cognee/api/v1/visualize/visualize.py:17-30，cognee/__init__.py:31

aggregate_multi_user_graphs

该函数通过遍历每个上下文并合并节点和边，聚合来自多个 (user, dataset) 对的图谱数据。它会用所有者的 source_user（电子邮件或 ID）标记节点。

多用户数据流

graph TD
    subgraph "代码实体空间：visualize.py"
        ["visualize_multi_user_graph()"]
        ["aggregate_multi_user_graphs()"]
        ["get_graph_engine()"]
    end

    subgraph "数据库空间"
        ["用户 A + 数据集 1"]
        ["用户 B + 数据集 2"]
    end

    ["visualize_multi_user_graph()"] --> ["aggregate_multi_user_graphs()"]
    ["aggregate_multi_user_graphs()"] --> ["get_graph_engine()"]
    ["get_graph_engine()"] -- "通过 graph_engine.get_graph_data() 获取" --> ["用户 A + 数据集 1"]
    ["get_graph_engine()"] -- "通过 graph_engine.get_graph_data() 获取" --> ["用户 B + 数据集 2"]
    ["aggregate_multi_user_graphs()"] -- "合并与去重" --> ["统一图谱数据"]

来源：cognee/api/v1/visualize/visualize.py:33-57，cognee/modules/visualization/cognee_network_visualization.py:115-156

---

交互功能

生成的 HTML 包含一个控制面板和由 D3.js 驱动的交互式画布。

导航与搜索

• 缩放控制："适应"、"放大"和"缩小"按钮可在图谱画布上实现平滑过渡。
• 搜索：输入框允许用户按名称高亮并放大到特定节点。
• 信息面板：点击节点会显示一个侧面板，其中包含节点的完整属性，包括自定义 Pydantic 模型（继承自 DataPoint）中定义的属性。

来源：cognee/modules/visualization/cognee_network_visualization.py:90-112，cognee/infrastructure/engine/models/DataPoint.py:27-64

按模式着色

可视化可以使用 _generate_provenance_colors 生成的确定性颜色映射，根据节点的溯源元数据动态重新着色：

• 类型：按节点类着色（例如 Entity、DocumentChunk）。
• 任务：按创建节点的特定管线任务着色（例如 extract_entities）。
• 管线：按来源管线着色（例如 cognify_pipeline）。
• 用户：按贡献用户的电子邮件或 UUID 着色，便于多用户分析。

来源：cognee/modules/visualization/cognee_network_visualization.py:11-19，cognee/modules/visualization/cognee_network_visualization.py:85-88

---

使用示例

可视化自定义模型

当使用自定义 Pydantic 模型进行图谱提取时，visualize_graph 会渲染模型中定义的特定实体类型和关系。

from cognee import remember, visualize_graph
from cognee.infrastructure.engine import DataPoint

class ProgrammingLanguage(DataPoint):
    name: str

async def run():
    await remember("Python 是一种编程语言。", graph_model = ProgrammingLanguage)
    await visualize_graph("custom_model.html")

来源：cognee/infrastructure/engine/models/DataPoint.py:27-64，cognee/api/v1/visualize/visualize.py:17-30

多用户聚合

from cognee.api.v1.visualize.visualize import visualize_multi_user_graph

async def show_all(user_dataset_pairs):
    # user_dataset_pairs 是一个 (User, Dataset) 元组列表
    await visualize_multi_user_graph(user_dataset_pairs, "combined_view.html")

来源：cognee/api/v1/visualize/visualize.py:33-57，cognee/modules/visualization/cognee_network_visualization.py:115-156