ATOM：基于大语言模型的自适应优化动态时序知识图谱构建

iText2KG 现已更名为 ATOM。ATOM 是一种少样本、可扩展的方法，用于从非结构化文本中构建并持续更新时序知识图谱（TKG）。 （我们保留了仓库中的旧版 iText2KG，请参阅 README。）

概述

传统的静态知识图谱构建方法往往忽视了现实世界数据的动态性和时间敏感性，从而限制了其对持续变化的适应能力。此外，近年来出现的一些零样本或少样本方法虽然避免了特定领域的微调或对预构建本体的依赖，但通常存在多次运行结果不稳定以及关键事实覆盖不全的问题。

ATOM 将输入文档分解为最小的、自包含的“原子”事实，从而提高了抽取的全面性和稳定性。随后，基于这些原子事实生成原子级知识图谱，并以并行方式将其合并。

简而言之，ATOM 通过以下方式解决了上述局限性：

• ✅ 提升全面性：从较长文本中捕获更全面的事实覆盖（事实全面性提升约 31%，时间维度全面性提升约 18%）
• ✅ 确保稳定性：在多次运行中生成一致的时序知识图谱（稳定性提升约 17%）
• ✅ 实现可扩展性：通过并行架构支持大规模的动态时序更新。

🔥 最新消息

• [2025年10月20日] ATOM - 重大升级：

  • 全新架构设计：ATOM 现采用三模块并行流水线进行 DTKG 的构建与更新。
  • 原子事实分解：新增的第一模块将文本拆分为最小的“原子事实”，有效解决了 LLM 在长上下文中容易遗漏事实的“遗忘效应”问题。
  • 增强全面性与稳定性：新架构显著提升了性能：事实全面性提升约 31%，时间维度全面性提升约 18%，稳定性提升约 17%。
  • 双时间建模：实现了 t_obs 与 t_start/t_end 的双时间建模，以防止动态知识图谱中的时间归属错误。
  • 并行五元组抽取：第二模块直接从原子事实中并行抽取 (subject, predicate, object, t_start, t_end) 五元组。
  • 并行原子合并架构：第三模块采用高效的并行两两合并算法，相较于 Graphiti 延迟降低了 93.8%，相较于 iText2KG 则降低了 95.3%。
  • LLM 无关解析：用距离度量（余弦相似度）替代了耗时的 LLM 解析，实现了可扩展的并行合并。

• [2025年7月29日] iText2KG - 新功能与增强能力：

  • iText2KG_Star：推出了一种更简单的版本，可直接抽取关系，省去了单独的实体抽取步骤，从而减少了 token 消耗。
  • 基于事实的知识图谱构建：通过文档蒸馏器增强了基于事实的知识图谱构建框架。
  • 动态知识图谱：新增了支持构建随时间演化的动态知识图谱的功能。示例请参见：动态知识图谱构建。注意：该版本尚未处理时间或逻辑冲突。

• [2025年7月19日] iText2KG - 重大性能与可靠性更新：

  • 异步架构：核心方法已迁移到 async/await，以实现与 LLM API 的非阻塞 I/O。
  • 日志系统：引入了全面的日志记录机制，取代了原有的 print 语句。
  • 增强的批处理能力：提高了处理多篇文档和多次 LLM 调用的效率。
  • 更好的错误处理：增加了增强的错误处理和重试机制。

• [2024年10月7日] iText2KG - 最新功能：

  • 重构了代码，引入了实体、关系和知识图谱的数据模型。
  • 实体嵌入同时考虑名称（权重 0.6）和标签（权重 0.4），以区分不同概念（例如，Python:Language 与 Python:Snake）。
  • 在 build_graph 函数中新增了 max_tries 参数，用于应对 LLM 的幻觉问题。

• [2024年9月17日] iText2KG - 最新功能：

  • 兼容所有 LangChain 对话和嵌入模型。
  • build_graph 函数现在可以扩展现有图谱。
  • 兼容 Python 3.9 及以上版本。

• [2024年7月16日] iText2KG - 解决了两个主要的 LLM 幻觉问题：

  • 对于虚构实体，用提供的实体列表中与其最相似的实体进行替换。
  • 针对“遗忘效应”（未能分配关系），通过重新提示 LLM 来补全缺失的实体。

架构

ATOM 采用三模块并行流水线，从非结构化文本中构建并持续更新动态时间知识图谱（DTKG）。

模块-1（原子事实分解） 使用基于大语言模型的提示技术，以不超过400个标记的最佳分块大小，将时间 t 时观测到的输入文档 D_t 分解为时间原子事实 {f_{t,1}, ..., f_{t,m_t}}。每个时间原子事实都是一个简短、自包含的片段，仅传达一条信息。

模块-2（原子 TKG 构建） 并行地从每个原子事实 f_{t,i} 中提取五元组（quintuples），以构建原子时间知识图谱 G^t_i；同时对节点和关系进行嵌入，并在提取过程中通过将结束有效性事实转换为肯定形式来处理时间解析问题，仅修改 t_end 时间（例如，“约翰·多伊于2026年1月1日不再担任X公司的首席执行官” → (John_Doe, is_ceo, X, [.], [01-01-2026])）。

模块-3（并行原子合并） 采用二叉合并算法，通过迭代式成对并行合并原子 TKG，直至收敛。该过程包含三个解析阶段：(1) 实体解析，使用精确匹配或余弦相似度阈值 θ_E = 0.8；(2) 关系解析，忽略端点和时间戳合并关系名称，使用阈值 θ_R = 0.7；(3) 时间解析，对于具有相似 (e_s, r_p, e_o) 的关系，合并其观测时间和有效时间集合。

最终得到的时间知识图谱快照 G^t_s 会与先前的 DTKG G^{t-1} 合并，从而生成更新后的 DTKG：G^t。

---

ATOM 工作流示例

在观测日期 2007年1月9日，ATOM 处理事实“史蒂夫·乔布斯于2007年1月9日担任苹果公司首席执行官”，创建五元组 (Steve Jobs, is_ceo, Apple Inc., [09-01-2007], [.])，其中 t_start = [09-01-2007]，t_end = [.]（空/未知）。

随后，在观测日期 2011年10月5日，ATOM 处理更新：“史蒂夫·乔布斯于2011年10月5日不再担任苹果公司首席执行官”。如 模块-2 所述，这一 结束有效性事实 被转换为其肯定形式，仅修改 t_end 时间，生成 (Steve Jobs, is_ceo, Apple Inc., [.], [05-10-2011])。

在模块-3 的时间解析阶段，ATOM 检测到这两个五元组共享相同的 (e_s, r_p, e_o) 三元组，并合并它们的时间列表，最终生成五元组：(Steve Jobs, is_ceo, Apple Inc., [09-01-2007], [05-10-2011])。这正确地表示史蒂夫·乔布斯自2007年1月9日至2011年10月5日担任首席执行官，同时保持双时间建模，即 t_obs = [09-01-2007, 05-10-2011]，以追踪每条信息的观测时间。

更多技术细节，请参阅：

• atom/atom.py: 构建、合并和更新知识图谱的核心逻辑。

---

延迟与可扩展性

ATOM 通过用完全并行架构取代串行瓶颈，实现了显著的延迟降低（相比 Graphiti 降低93.8%，相比 iText2KG 降低95.3%）。

关键的架构优势包括：

1. 并行五元组提取：ATOM 在单个并行步骤中提取五元组。这避免了 iText2KG 和 Graphiti 采用的分别提取实体和关系的步骤，后者会增加两倍的大语言模型调用次数并延长延迟。
2. 独立于大语言模型的合并：该框架使用高效的距离度量（余弦相似度）进行实体/关系解析。这避免了基于大语言模型的解析所带来的计算瓶颈（Graphiti 采用的方式），并允许在图规模扩大时实现真正的并行化。
3. 并行原子合并：原子 TKG 通过迭代式成对算法合并，且该过程可并行运行（例如，8个线程，批大小为40）。
4. 早期时间解析：时间逻辑在提取阶段（模块-2）处理，而非在合并阶段。

因此，模块-3 的并行合并过程仅占 ATOM 总延迟的13%。其余部分归因于 API 调用，可通过增大批大小或扩展本地大语言模型硬件进一步减少。

---

示例：时间建模（ATOM vs. Graphiti）

下图展示了 ATOM 和 Graphiti 在时间建模上的差异，以2020年1月9日至23日关于新冠疫情的新闻为例。对于 ATOM，时间戳以 UNIX 格式编码，以消除与字符串解析操作和时区转换计算相关的开销。

对于2020年1月23日观测到的事实“这种神秘的呼吸道病毒已传播到至少10个其他国家”，Graphiti 将观测时间视为有效开始时间（t_start），设置 valid_at = 23-01-2020，暗示传播发生在该特定日期。

相比之下，ATOM 的双时间建模将观测时间（t_obs = 23-01-2020）与有效时间分开保存。它认识到文章是在2020年1月23日发表的，但这并不意味着传播恰好发生在那一天——传播可能早在几天或几周前就已经发生。这种区分对于时间推理至关重要：Graphiti 会推断新闻中的所有事件都发生在文章发表之日，而 ATOM 则正确地建模了信息的观测时间与事件实际发生时间之间的区别，从而避免时间误指。

下图显示了 ATOM 和 Graphiti 在时间解析方面的比较。两个于2020年1月28日观测到的原子事实分别报告了1月24日（26人死亡）和1月27日（至少80人死亡）的死亡人数。左图（ATOM）：通过检测相似关系并扩展其有效时间历史（图中 t_end）来进行时间解析。右图（Graphiti）：为每个原子事实创建单独的关系，导致重复。此外，Graphiti 错误地将“截至2020年1月24日”和“截至2020年1月27日”理解为有效开始时间，而非有效结束时间，从而导致时间误指。

安装

pip install --update itext2kg

ATOM

大语言模型兼容性

ATOM 兼容 LangChain 支持的所有语言模型。要使用 ATOM，您需要同时具备聊天模型和嵌入模型。有关可用聊天模型，请参阅以下链接：https://python.langchain.com/docs/integrations/chat/。有关嵌入模型，请访问：https://python.langchain.com/docs/integrations/text_embedding/。

请确保在使用前为每个聊天模型安装必要的包。

ATOM 参数

初始化：

• llm_model: 一个用于从文本中提取关系的 LangChain 对话模型实例
• embeddings_model: 一个用于计算语义相似度的 LangChain 嵌入模型实例

build_graph 函数： （该函数也可用于构建静态知识图谱，只需固定一个任意的观测时间并传入你的原子事实即可）。

• atomic_facts (List[str]): 需要处理的原子事实列表（简短、自成一体的文本片段）
• obs_timestamp (str): 收集这些原子事实时的观测时间戳
• existing_knowledge_graph (KnowledgeGraph, 可选): 与新知识图谱合并的现有知识图谱
• ent_threshold (float, 默认值=0.8): 合并过程中实体消歧的相似度阈值
• rel_threshold (float, 默认值=0.7): 合并过程中关系消歧的相似度阈值
• entity_name_weight (float, 默认值=0.8): 相似度计算中实体名称的权重
• entity_label_weight (float, 默认值=0.2): 相似度计算中实体标签的权重
• max_workers (int, 默认值=8): 处理时的最大并行工作线程数

build_graph_from_different_obs_times 函数：

• atomic_facts_with_obs_timestamps (dict): 字典，键为观测时间戳（str），值为每个时间戳对应的原子事实列表
• existing_knowledge_graph (KnowledgeGraph, 可选): 与新知识图谱合并的现有知识图谱
• ent_threshold (float, 默认值=0.8): 合并过程中实体消歧的相似度阈值
• rel_threshold (float, 默认值=0.7): 合并过程中关系消歧的相似度阈值
• entity_name_weight (float, 默认值=0.8): 相似度计算中实体名称的权重
• entity_label_weight (float, 默认值=0.2): 相似度计算中实体标签的权重
• max_workers (int, 默认值=8): 处理时的最大并行工作线程数

示例：从文本构建动态时空知识图谱

以下是一个基本示例，展示了如何使用 ATOM 从 2020 年 COVID-NYT 的原子事实中构建动态时空知识图谱。

⚠️ 性能提示：为了获得最佳性能，建议在专用的 Python 脚本中运行 ATOM，而不是在 Jupyter 笔记本中运行。这是因为 ATOM 的并行处理架构在笔记本环境中容易因事件循环冲突和线程竞争而导致显著的性能下降。

更复杂的示例即将推出……

---

import pandas as pd
import asyncio
import ast

# 使用 LangChain 封装导入 LLM 和嵌入模型
from langchain_openai import ChatOpenAI, OpenAIEmbeddings
from itext2kg.atom import Atom
from itext2kg import Neo4jStorage

# 设置 OpenAI LLM 和嵌入模型（将“##”替换为您的 API 密钥）
openai_api_key = "#"
openai_llm_model = ChatOpenAI(
    api_key=openai_api_key,
    model="gpt-4.1-2025-04-14",
    temperature=0,
    max_tokens=None,
    timeout=None,
    max_retries=2,
)

openai_embeddings_model = OpenAIEmbeddings(
    api_key=openai_api_key,
    model="text-embedding-3-large",
)

# 加载 2020 年 COVID-NYT 数据集的 pickle 文件
news_covid = pd.read_pickle("../datasets/atom/nyt_news/2020_nyt_COVID_last_version_ready.pkl")

# 定义一个辅助函数，将数据框中的原子事实转换为字典，
# 其中键为观测日期，值为该日期的所有原子事实组合。
def to_dictionary(df:pd.DataFrame, max_elements: int | None = 20): 

    if isinstance(df['factoids_g_truth'][0], str):
        df["factoids_g_truth"] = df["factoids_g_truth"].apply(lambda x:ast.literal_eval(x))
    grouped_df = df.groupby("date")["factoids_g_truth"].sum().reset_index()[:max_elements]
    return {
        str(date): factoids for date, factoids in grouped_df.set_index("date")["factoids_g_truth"].to_dict().items()
        }

# 将数据框转换为所需的字典格式
news_covid_dict = to_dictionary(news_covid)

# 使用 OpenAI 模型初始化 ATOM 流水线
atom = Atom(llm_model=openai_llm_model, embeddings_model=openai_embeddings_model)

# 在不同观测时间戳上构建知识图谱
kg = await atom.build_graph_from_different_obs_times(
    atomic_facts_with_obs_timestamps=news_covid_dict,
    
)

# 使用 Neo4j 可视化生成的知识图谱
URI = "bolt://localhost:7687"
USERNAME = "neo4j"
PASSWORD = "##"
Neo4jStorage(uri=URI, username=USERNAME, password=PASSWORD).visualize_graph(knowledge_graph=kg)

评估脚本、数据集和提示词

2020 年 COVID-19 动态时空数据集位于 ./datasets/atom 文件夹中（也可在 huggingface 上获取）。要复现结果，相关脚本位于 ./evaluation 文件夹中。提示词则位于 ./itext2kg/atom/models/schemas/ 文件夹中。

公开协作

我们欢迎社区贡献以改进 ATOM。

引用

@article{lairgi2024atom,
  title={ATOM: AdapTive and OptiMized dynamic temporal knowledge graph construction using LLMs},
  author={Lairgi, Yassir and Moncla, Ludovic and Benabdeslem, Khalid and Cazabet, R{\'e}my and Cl{\'e}au, Pierre},
  journal={arXiv preprint arXiv:2510.22590},
  year={2025},
  url={https://arxiv.org/abs/2510.22590},
  eprint={2510.22590},
  archivePrefix={arXiv},
  primaryClass={cs.AI}
}

ATOM (原 iText2KG) 快速上手指南

ATOM 是一个基于大语言模型（LLM）的自适应、优化动态时序知识图谱（TKG）构建工具。它通过将非结构化文本分解为最小化的“原子事实”，并行提取五元组并进行高效合并，显著提升了知识图谱构建的完整性、稳定性和扩展性。

环境准备

在开始之前，请确保您的开发环境满足以下要求：

• 操作系统：Linux, macOS 或 Windows
• Python 版本：Python 3.9 或更高版本
• 前置依赖：
  • pip 包管理工具
  • 有效的 LLM API 密钥（如 OpenAI API Key，或其他兼容 LangChain 的模型）
  • 推荐安装 langchain 相关库以利用其广泛的模型支持

安装步骤

您可以直接通过 PyPI 安装最新版本的工具包（包名仍为 itext2kg）：

pip install --upgrade itext2kg

提示：如果您在中国大陆地区遇到下载速度慢的问题，建议使用国内镜像源加速安装：

pip install --upgrade itext2kg -i https://pypi.tuna.tsinghua.edu.cn/simple

基本使用

ATOM 的核心工作流包含三个并行模块：原子事实分解、原子 TKG 构建和平行原子合并。以下是一个最简化的 Python 使用示例，展示如何从文本构建动态时序知识图谱。

1. 导入模块与初始化

from atom import ATOM
from langchain_openai import ChatOpenAI
import os

# 设置 API Key (请以实际环境变量或硬编码方式配置)
os.environ["OPENAI_API_KEY"] = "your-api-key-here"

# 初始化 LLM 模型
llm = ChatOpenAI(model="gpt-4o", temperature=0)

# 初始化 ATOM 引擎
# 可根据需要调整线程数 (num_threads) 和批次大小 (batch_size) 以优化性能
atom_engine = ATOM(llm=llm, num_threads=8, batch_size=40)

2. 构建动态时序知识图谱

准备包含时间信息的文本数据。ATOM 能够自动识别观察时间（t_obs）并推断事实的有效起止时间（t_start, t_end）。

# 示例文档列表：每个文档包含文本内容和观察时间戳
documents = [
    {
        "text": "Steve Jobs was the CEO of Apple Inc. on January 9, 2007.",
        "observation_time": "2007-01-09"
    },
    {
        "text": "Steve Jobs is no longer the CEO of Apple Inc. on October 5, 2011.",
        "observation_time": "2011-10-05"
    }
]

# 执行构建/更新操作
# 该函数会自动处理原子事实分解、五元组提取及并行合并
dynamic_kg = atom_engine.build_graph(documents)

# 查看生成的图谱结果
print(dynamic_kg)

3. 结果说明

执行上述代码后，ATOM 将输出一个合并后的时序知识图谱。针对上述示例，系统将正确生成如下五元组逻辑：

• 实体关系：(Steve Jobs, is_ceo, Apple Inc.)
• 时间范围：t_start: 2007-01-09, t_end: 2011-10-05
• 观察时间：系统会保留两条信息的原始观察时间 (t_obs)，以区分事实发生时间与信息获取时间，避免时序归因错误。

进阶提示

• 增量更新：build_graph 函数支持传入现有的图谱对象，从而实现知识的连续动态更新。
• 异步处理：底层架构已迁移至 async/await 模式，在处理大量文档时能显著提高 I/O 效率。
• 自定义阈值：可在初始化时调整实体分辨率 (theta_E) 和关系分辨率 (theta_R) 的余弦相似度阈值，以适应不同领域的精度需求。