cognee 语义记忆图谱（Semantic Memory Map）：基于 Embedding 的知识图谱含义空间可视化指南

cognee 语义记忆图谱Semantic Memory Map基于 Embedding 的知识图谱含义空间可视化指南【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cogneecognee 的图可视化提供了一种按“含义”而非“拓扑”排布的 Semantic 标签页每个节点被放置在其 Embedding 的二维投影位置语义相近的节点自然聚集让知识图谱中潜藏的实体簇结构一眼可见。本文以 SEMANTIC_MAP.md 为骨架结合其生产渲染路径源码完整讲解该标签页的四步工作原理、使用方式、可调配置项如SEMANTIC_MAP_PROJECTION与设计取舍。读完后你将能用三行代码生成带 Semantic 标签页的自包含 HTML 图谱并理解其背后的 embedding 关联、PCA/UMAP 投影、无依赖 k-means 聚类与 token 替换渲染机制。什么是语义记忆图谱Semantic Memory Map 是 cognee 图可视化 中的一个独立视图tab。与经典的结构布局按节点在流水线中的拓扑位置排布例如 文档 → 分块 → 实体 → 类型 → 摘要 → 上下文不同它把整张图铺在一个**“含义空间”**中每个节点落在其 Embedding 向量的 2-D 投影坐标上语义相似的节点彼此靠近形成可读的实体簇图谱的潜在结构——相关实体的自然分组——无需任何人工标注即可一目了然。该视图的关键工程承诺是零额外计算成本它直接复用cognify期间 cognee 已经存储的向量查询/渲染时不会重新计算 Embedding浏览器端只接收 2-D 坐标和预计算的邻居列表绝不传输原始 Embedding 向量保护隐私并大幅缩小 HTML 体积。从源码结构看Semantic 数据链路是生产渲染路径cognee_network_visualization内置的一部分而不是对输出 HTML 的二次 patch——这一点在官方演示脚本 semantic_memory_map.py 的文档字符串中被明确强调。工作原理四步确定性的渲染管线生产渲染路径cognee_network_visualization见 cognee_network_visualization.py在四个步骤中构建 Semantic 标签页全部步骤都受同一个确定性节点采样embedding_join.select_nodes上限 2000约束。下面是每一步的实现细节。第一步embedding_join —— 把图节点关联到已存储的向量embedding_join.py 负责把图谱节点与其存储的向量做连接。其核心巧妙之处在于图节点 id 与其向量行 id 是完全一致的两侧都使用str(data_point.id)因此节点可以直接关联到{Type}_{field}形式的向量集合如Entity_name、DocumentChunk_text无需任何映射表。关键实现要点按类型分组每集合一次批量查询fetch_node_embeddings先按节点type分组根据默认的DEFAULT_INDEX_FIELDS映射Entity→name、EntityType→name、TextSummary→text、DocumentChunk→text、TextDocument→name推导出集合名再对每个集合执行一次批量的retrieve(..., include_vectorTrue)绝不逐节点查询LanceDB 专属关键字与优雅降级include_vector是 LanceDB-only 关键字。代码通过inspect.signature(vector_engine.retrieve)探测能力而非捕获异常不支持的适配器上返回的TypeError会触发回退——批量重新 Embedding 该类型的索引字段因为存储向量就是embed(field)重新计算的向量与其一致代价是每次渲染产生额外 Embedding 调用可诊断的命中率日志fetch_node_embeddings会记录resolved N/M node embeddings across K collection(s)。当输入非空但解析结果为 0 时会输出 warning列出缺失的集合与未映射的类型让“空白地图”变得可诊断而非静默失败。此外SEMANTIC_NODE_CAP 2000与SAMPLE_SEED 42定义了上限与采样种子select_nodes按 id 排序后若超出上限则用固定种子的random.Random(SAMPLE_SEED)抽取确定性样本——保证同一图谱每次运行采样到相同的节点子集快照测试依赖这一点。向量获取、投影、聚类、去重叠四步全部只在该子集上运行。第二步semantic_layout —— PCA 投影为确定的 2-D 坐标semantic_layout.py 中的compute_positions将 Embedding 投影到 2-DPCAnumpy SVD默认方法_pca_2d先做中心化再对full_matricesFalse的 SVD 取前两个右奇异向量作为主轴投影为 2-D 坐标。符号稳定化是关键——原始 SVD 的符号是任意的代码强制每个主轴上绝对值最大的特征载荷为正保证同样的输入永远产出同样的布局快照测试断言精确相等见 test_semantic_layout.py 中test_pca_deterministic_across_runs归一化与固定坐标按轴 min-max 归一化到[-SPREAD, SPREAD]SPREAD 1.0得到“钉死”的位置——布局只计算一次、不做力导向模拟这正是仓库的 layout-once 规则无向量节点的兜底没有向量的节点被放在其已定位邻居的质心带种子抖动迭代传播可解析链式无向量节点若完全无已定位邻居孤点则落在确定性的圆环上1.15 * SPREAD半径确定性去重叠_deoverlap用种子抖动 40 轮迭代的松弛把距离小于MIN_SEPARATION0.02的点推开让稠密簇保持可读O(n²)/轮在 2000 节点上限下可接受。可选 UMAP设置环境变量SEMANTIC_MAP_PROJECTIONumap且已安装umap-learn时改用 UMAPumap.UMAP(n_components2, random_stateseed, n_jobs1)投影未安装时静默回退 PCA。_umap_2d的ImportError捕获保证了 CI 等无 UMAP 环境不出错。第三步semantic_clusters —— 全维向量上的 k-means 聚类与最近邻semantic_clusters.py 负责两件事聚类运行在“全维度”Embedding 上而非 2-D 投影上——避免分组反映的是有损布局的伪结构而是真实的语义结构纯 numpy 的 k-means无 scikit-learnkmeans使用种子的 k-means 初始化_kmeans_pp_init、固定迭代顺序argmin 平局取最小簇索引、空簇保留质心最大 50 轮迭代CLUSTER_SEED 42跨运行结果完全一致。聚类数量由default_k决定k min(12, max(2, round(sqrt(n/2))))其中 n 是有向量的节点数n 2时返回 1。每个节点还会预计算top-5 余弦邻居TOP_NEIGHBORS 5自排除、稳定平局顺序供悬停面板使用。簇标签compute_clusters接收可注入的label_fn默认default_label——它从成员节点中挑选度数/重要性最高、名字可读的前 3 个真实Entity节点拼接成标签UUID/哈希形状或超过 40 字符_MAX_LABEL_NAME的名字会被_usable_name跳过没有可用名字的簇退回其主导节点类型如TextSummary再退到cluster。label_fn是接入 LLM 摘要器的唯一接缝——文档中明确写道“聚类从不计算一个随后被丢弃的标签”一行 LLM summarizer 不过是另一个label_fn实现。第四步token 替换 —— 组合成最终 HTML编排器cognee_network_visualization读取 template.html随后依次替换__SEMANTIC_*__token先替换各视图的JS 代码块__SEMANTIC_LAYOUT_JS__→semantic_layout.emit_js输出的window._semanticPositions __SEMANTIC_POSITIONS__;__SEMANTIC_VIEW_JS__→ semantic_map.js 全文再替换JSON 数据 payload__SEMANTIC_POSITIONS__与__SEMANTIC_CLUSTERS__所有 JSON 都经_safe_json_embed编码转义/以安全嵌入script。整体 best-effort 容错_semantic_payload将 取向量 → 投影 → 聚类 包在try/except中任何失败取向量、投影、聚类都只记录 warning两个 token 被替换为null标签页显示友好的空状态——经典渲染拓扑视图绝不因 Semantic 标签页失败而中断。这一点在多处源码注释中被反复强调是设计的第一原则。使用方式三步生成语义图谱Semantic 标签页自动出现在任何visualize_graph()的输出中无需额外配置import cognee from cognee.api.v1.visualize.visualize import visualize_graph await cognee.add(...your text...) await cognee.cognify() await visualize_graph(destination_file_pathgraph.html)打开生成的 HTML 后点击Semantic标签或在 URL 后追加#semantic直接深链到该标签页——该行为由 semantic_map.js 末尾的window.location.hash #semantic检查实现。标签页内支持交互说明Cluster / Type 切换按语义簇或本体类型重新着色节点state.colorBy颜色模式切换按钮.sem-color-btn悬停节点点亮其最近邻top-5 余弦邻居并列出其图谱关系最多 8 条见relationsFor图例过滤点击图例条目将视图隔离到单个簇或类型其余节点透明度降至 0.12isolationOpacity缩放滚轮或屏幕上的缩放控件d3.zoomscaleExtent 0.2–12含放大/缩小/重置按钮Semantic ⇄ Structural 切换在“钉死的含义空间布局”与“有界力导向布局”之间切换——后者是仓库中唯一允许的力模拟以语义屏幕坐标为种子、固定 200 tick显式离开语义视图Recall 覆盖层从会话层读取历史 recall 查询事件kind search点亮该查询在含义空间中检索到的节点红色描边命中节点全不透明、其余降至 0.06状态栏会显示N nodes · M clusters如1200 nodes · 8 clusters直观反映当前采样的规模。可运行的端到端示例仓库提供了官方演示脚本 semantic_memory_map.py它运行真实 cognee 流水线prune→remember→visualize_graph输入三组刻意多主题的文本计算先驱 / 爵士乐 / 海洋科学以产生明显的独立簇python examples/guides/semantic_memory_map.py脚本要求环境中有 LLM 与 Embedding 的密钥如LLM_API_KEY与cognify的需求完全一致无 Embedding 时标签页显示友好的空状态经典渲染不受影响。产物默认输出到~/semantic_memory_map.html。面向 API 调用的按需计算除了 HTML 渲染路径cognee_network_visualization还导出了独立的按需计算入口build_visualization_payload(graph_data, schema_data, search_events)返回经preprocess的 JSON 快照刻意不包含语义位置/簇避免所有调用方为从未打开的标签页承担取向量与 PCA 的成本build_semantic_payload(graph_data, schema_data)仅当调用方需要语义数据时JSON API 即如此才运行_semantic_payload并返回{semantic_positions: ..., semantic_clusters: ...}。这两者的拆分见 cognee_network_visualization.py正是“按需付费”原则的实现HTML 路径无条件运行语义计算而纯 JSON 客户端可按需取用。关键配置项与源码参数一览配置项 / 常量默认值来源与作用SEMANTIC_MAP_PROJECTIONpca环境变量见 cognee_network_visualization.py。设为umap时在装有umap-learn时使用 UMAP否则回退 PCASEMANTIC_NODE_CAP2000embedding_join.py。语义图渲染的最大节点数同时约束向量获取与下游 O(n²) 布局/邻居遍历SAMPLE_SEED42embedding_join.py。超上限时的确定性采样种子LAYOUT_SEED42semantic_layout.py。PCA/UMAP 与去重叠的随机种子SPREAD1.0归一化坐标盒的半宽渲染端映射到画布屏幕映射区间为 [-1.2, 1.2]MIN_SEPARATION0.02去重叠强制的最小间距归一化单位CLUSTER_SEED42semantic_clusters.py。k-means 与邻居计算种子TOP_NEIGHBORS5每个节点预计算的余弦最近邻数量供悬停面板DEFAULT_INDEX_FIELDSEntity→name等embedding_join.py。类型到索引字段的映射决定向量集合名{Type}_{field}设计取舍与验证聚类在全维 Embedding 上运行而非 2-D 投影因此分组反映真实结构而非布局伪影确定性PCA 符号约定、种子化 k-means/采样、钉死的位置使布局可复现——test_semantic_layout.py 断言r1 r2精确相等test_semantic_clusters.py 覆盖聚类与邻居逻辑select_nodes的种子采样保证快照测试稳定零新增依赖numpy本就是核心依赖完成 PCA 与 k-meansUMAP 是SEMANTIC_MAP_PROJECTIONumap背后的可选懒加载非 cognee 依赖隐私与体积浏览器只收到 2-D 坐标与邻居 id 列表原始 Embedding 向量永不离开服务端build_semantic_payload与__SEMANTIC_POSITIONS__/__SEMANTIC_CLUSTERS__token 的 payload 形状即为证据。适用前提与限制语义地图依赖cognify期间写入向量库的 Embedding若图节点缺少对应{Type}_{field}集合例如从未执行过 Embedding 写入fetch_node_embeddings会记录缺失集合并返回空结果标签页呈现空状态而非报错非 LanceDB 向量适配器会触发逐渲染的 re-embed 回退批量、非逐节点产生额外 LLM Embedding 调用成本这是无include_vector能力适配器的固有代价语义布局上限为 2000 节点确定性采样超大图的其余节点不会出现在语义视图中但拓扑视图不受影响该文档所描述的 UMAP 可选路径与SEMANTIC_MAP_PROJECTION环境变量以当前仓库 cognee_network_visualization.py 的实现为准。参考资源功能文档SEMANTIC_MAP.md生产编排器cognee_network_visualization.pyEmbedding 关联embedding_join.py语义布局semantic_layout.py语义聚类semantic_clusters.py前端视图semantic_map.js端到端示例semantic_memory_map.py单元测试test_semantic_layout.py、test_semantic_clusters.py【免费下载链接】cogneeCognee is the open-source AI memory platform for agents. Give your AI agents persistent long-term memory across sessions with a self-hosted knowledge graph engine.项目地址: https://gitcode.com/GitHub_Trending/co/cognee创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考