agentic_huge_data_base / wiki
页面 Onyx · 8.6 知识图谱系统·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 8.6

8.6 · 知识图谱系统（Knowledge Graph System）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节8.6 状态全文译文 模块图谱与关系、文档对象与元数据、接口与服务契约、配置治理
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Knowledge Graph System 上一章8.5 下一章9
源码线索
  • backend/alembic/versions/7b9b952abdf6_update_entities.py
  • backend/alembic/versions/cec7ec36c505_kgentity_parent.py
  • backend/onyx/configs/kg_configs.py
  • backend/onyx/db/entities.py
  • backend/onyx/db/entity_type.py
  • backend/onyx/db/kg_config.py
  • backend/onyx/db/relationships.py
  • backend/onyx/document_index/vespa/kg_interactions.py
  • backend/onyx/kg/clustering/clustering.py
  • backend/onyx/kg/extractions/extraction_processing.py
模块标签
  • 图谱与关系
  • 文档对象与元数据
  • 接口与服务契约
  • 配置治理
  • 入库与解析

章节正文

知识图谱系统

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/8.6-knowledge-graph-system

知识图谱系统

相关源文件

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

  • backend/alembic/versions/7b9b952abdf6_update_entities.py
  • backend/alembic/versions/cec7ec36c505_kgentity_parent.py
  • backend/onyx/configs/kg_configs.py
  • backend/onyx/db/entities.py
  • backend/onyx/db/entity_type.py
  • backend/onyx/db/kg_config.py
  • backend/onyx/db/relationships.py
  • backend/onyx/document_index/vespa/kg_interactions.py
  • backend/onyx/kg/clustering/clustering.py
  • backend/onyx/kg/extractions/extraction_processing.py
  • backend/onyx/kg/models.py
  • backend/onyx/kg/resets/reset_source.py
  • backend/onyx/kg/resets/reset_vespa.py
  • backend/onyx/kg/setup/kg_default_entity_definitions.py
  • backend/onyx/kg/utils/extraction_utils.py
  • backend/onyx/kg/utils/formatting_utils.py
  • backend/onyx/kg/vespa/vespa_interactions.py
  • backend/onyx/prompts/kg_prompts.py
  • backend/onyx/server/kg/api.py
  • backend/onyx/server/kg/models.py
  • backend/tests/integration/tests/kg/test_kg_api.py

Onyx 中的知识图谱（KG）系统提供了从非结构化文档中提取信息的结构化表示。它通过将原始文本转换为存储在 Vespa 中的实体和关系网络，实现了复杂关系建模、以实体为中心的检索以及基于图谱的推理。

总览与配置

KG 子系统由全局设置和功能开关控制。启用后，系统会启动一个与标准向量索引并行的二级处理管线。

KG 配置设置

KGConfigSettings 类管理图谱系统的状态和行为：

  • KG_ENABLED：提取管线的全局开关 backend/onyx/kg/models.py:14-14。
  • KG_EXPOSED：决定 KG 功能是否在用户界面中可见 backend/onyx/kg/models.py:13-13。
  • KG_VENDOR：指定主要来源生态系统（例如 "LINEAR"、"JIRA"）backend/onyx/kg/models.py:15-15。
  • KG_BETA_PERSONA_ID：将系统链接到配置了 KnowledgeGraphTool 的特定 AI 助手（角色）backend/onyx/kg/models.py:21-21。

来源：backend/onyx/kg/models.py:12-21、backend/onyx/server/kg/api.py:49-54

提取管线

提取管线按照 KGStage 枚举定义的几个阶段推进文档：NOT_STARTED → EXTRACTING → EXTRACTED → NORMALIZED backend/onyx/kg/models.py:160-168。

1. 分类与指令准备

系统首先根据文档的来源和元数据确定其实体类型。例如，GitHub 文档可能会根据其 object_type 元数据被分类为 GITHUB_PR 或 GITHUB_ISSUE backend/onyx/kg/setup/kg_default_entity_definitions.py:93-130。

2. 实体与关系提取

提取分为两种方式：

  • 隐式提取：使用文档元数据创建实体和关系，无需调用大语言模型（LLM）（例如，将 "creator" 邮箱映射到 EMPLOYEE 实体）backend/onyx/kg/utils/extraction_utils.py:173-181。
  • 深度提取：使用大语言模型（LLM）和 MASTER_EXTRACTION_PROMPT 在文本内容中识别实体和关系 backend/onyx/kg/utils/extraction_utils.py:332-337。
提取数据流

下图展示了从原始文档片段到结构化暂存实体的转换过程。

提取管线流程

Onyx · 提取数据流 · 图 1
Onyx · 提取数据流 · 图 1

来源：backend/onyx/kg/extractions/extraction_processing.py:45-95、backend/onyx/kg/utils/extraction_utils.py:332-337、backend/onyx/db/entities.py:25-47

聚类与归一化

一旦实体进入 KGEntityExtractionStaging 表，就必须进行归一化处理，以确保对同一真实世界实体的不同提及被合并。

有源实体聚类

"有源"实体（与特定来源关联，如 JIRA 工单）使用字符串相似度进行聚类。

  • _cluster_one_grounded_entity：使用 pg_trgm 相似度运算符从 Postgres 中检索相似实体 backend/onyx/kg/clustering/clustering.py:147-188。
  • 阈值：使用 KG_CLUSTERING_RETRIEVE_THRESHOLD（默认 0.6）进行初始检索，使用 KG_CLUSTERING_THRESHOLD（默认 0.96）进行最终合并 backend/onyx/configs/kg_configs.py:129-136。
转入生产环境

聚类完成后，通过 transfer_entity() 将实体从暂存区移至生产环境的 KGEntity 表 backend/onyx/db/entities.py:104-116。此过程会将文档的 kg_stage 更新为 NORMALIZED backend/onyx/db/entities.py:156-157。

来源：backend/onyx/kg/clustering/clustering.py:147-192、backend/onyx/db/entities.py:104-165、backend/onyx/configs/kg_configs.py:129-136

Vespa 知识图谱交互

知识图谱不仅存储在 Postgres 中，还会与 Vespa 同步，以实现图谱感知的搜索。

文档到图谱的链接

Vespa 中的每个文档片段都包含与其关联的图谱组件的字段：

  • kg_entities：片段中提及或与之相关的实体 ID 列表。
  • kg_relationships：关系 ID 列表。
同步过程

update_kg_chunks_vespa_info 函数负责在归一化后协调 Vespa 记录的更新 backend/onyx/document_index/vespa/kg_interactions.py:12-16。它使用 get_kg_vespa_info_update_requests_for_document 收集与特定 document_id 关联的所有实体和关系，并准备 KGUChunkUpdateRequest 对象 backend/onyx/document_index/vespa/kg_interactions.py:33-61。

Vespa 同步架构

Onyx · 同步过程 · 图 2
Onyx · 同步过程 · 图 2

来源：backend/onyx/document_index/vespa/kg_interactions.py:33-61、backend/onyx/kg/resets/reset_vespa.py:34-40、backend/onyx/kg/vespa/vespa_interactions.py:13-30

实体类型建模

实体类型使用 KGEntityTypeDefinition 模型定义，该模型包含描述、有源类型和属性映射指令。

实体类型（示例）描述有源来源
LINEAR用于问题/改进的正式 Linear 工单DocumentSource.LINEAR
JIRA用于问题/改进的正式 Jira 工单DocumentSource.JIRA
GITHUB_PR请求将变更合并到代码库DocumentSource.GITHUB
EMPLOYEE在组织内工作的人员None（无源）
属性转换

metadata_attribute_conversion 映射定义了文档元数据键如何转换为图谱属性或关系。例如，在 Jira 中，reporter_email 元数据被转换为指向 EMPLOYEE 实体的 is_creator_of 关系 backend/onyx/kg/setup/kg_default_entity_definitions.py:69-76。

来源：backend/onyx/kg/setup/kg_default_entity_definitions.py:18-130、backend/onyx/kg/models.py:82-89、backend/onyx/db/entity_type.py:52-92