12.4 · 图谱可视化

图谱可视化

图谱可视化

相关源文件

本章引用的主要源码文件：

• 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 文件。

可视化生成流程

来源：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 中的"按模式着色"功能至关重要。

代码实体到元数据的映射

来源：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，则节点以中性浅灰色渲染，以区分已验证的模式元素。

核心函数

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）标记节点。

多用户数据流

来源：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