agentic_huge_data_base / wiki
页面 Graphiti · 12.2 测试框架·DeepWiki 中文全文译文
DeepWiki 中文译文 / Graphiti / 12.2

12.2 · 测试框架（Testing Framework）

时序知识图谱与动态事实记忆 · 聚焦本章的模块关系、源码依据与实现要点。

项目Graphiti 章节12.2 状态全文译文 模块测试、发布与运维、配置治理、界面与交互、模型调用与提供方适配
项目要点页2.5 参考项目 项目章节目录Graphiti DeepWiki 原始章节Testing Framework 上一章12.1 下一章12.3
源码线索
  • .github/workflows/release-graphiti-core.yml
  • .github/workflows/typecheck.yml
  • .github/workflows/unit_tests.yml
  • Makefile
  • pytest.ini
  • tests/evals/data/longmemeval_data/README.md
  • tests/evals/data/longmemeval_data/longmemeval_oracle.json
  • tests/evals/eval_cli.py
  • tests/evals/eval_e2e_graph_building.py
  • tests/evals/pytest.ini
模块标签
  • 测试、发布与运维
  • 配置治理
  • 界面与交互
  • 模型调用与提供方适配
  • 接口与服务契约

章节正文

测试框架

原始 DeepWiki 页面https://deepwiki.com/getzep/graphiti/12.2-testing-framework

测试框架

相关源文件

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

  • .github/workflows/release-graphiti-core.yml
  • .github/workflows/typecheck.yml
  • .github/workflows/unit_tests.yml
  • Makefile
  • pytest.ini
  • tests/evals/data/longmemeval_data/README.md
  • tests/evals/data/longmemeval_data/longmemeval_oracle.json
  • tests/evals/eval_cli.py
  • tests/evals/eval_e2e_graph_building.py
  • tests/evals/pytest.ini
  • tests/evals/utils.py
  • tests/helpers_test.py
  • tests/test_add_triplet.py

本文档记录了用于测试 graphiti-core 库的结构、约定和工具。它涵盖了单元测试与集成测试的区别、使用的 pytest 标记和夹具、如何为集成测试配置数据库服务、评估框架（LongMemEval）以及可用于本地开发的 make 目标。

测试目录结构

测试位于仓库根目录下的 tests/ 目录中，其结构镜像了 graphiti_core/ 的结构。

tests/
├── helpers_test.py                    # 共享的夹具和断言辅助函数
├── test_node_int.py                   # 节点 CRUD 集成测试 [tests/test_node_int.py:1-213]
├── test_edge_int.py                   # 边 CRUD 集成测试 [tests/test_edge_int.py:1-203]
├── test_graphiti_int.py               # 完整的 add_episode 集成测试
├── cross_encoder/
│   └── test_bge_reranker_client_int.py # 重排序器集成测试 [tests/cross_encoder/test_bge_reranker_client_int.py:1-79]
├── utils/
│   └── maintenance/
│       └── test_entity_extraction.py  # 节点提取逻辑的单元测试 [tests/utils/maintenance/test_entity_extraction.py:1-226]
└── evals/                             # 评估框架（LongMemEval）
    ├── data/                          # 数据集文件（longmemeval_oracle.json）
    ├── eval_e2e_graph_building.py     # 端到端图构建评估逻辑 [tests/evals/eval_e2e_graph_building.py:1-181]
    └── eval_cli.py                    # 运行评估的 CLI 入口点 [tests/evals/eval_cli.py:1-41]

来源：tests/test_node_int.py:22-27, tests/test_edge_int.py:24-25, tests/evals/eval_cli.py:4-5, tests/cross_encoder/test_bge_reranker_client_int.py:19-20

测试分类

测试根据外部依赖需求分为不同类别。

类别pytest 标记所需外部服务运行内容
单元测试not integration无使用模拟的大语言模型（LLM）、嵌入向量生成器和图驱动的逻辑测试
数据库集成测试not integration（但需要数据库）Neo4j、FalkorDB、Kuzu节点/边 CRUD、使用模拟大语言模型（LLM）的完整管线
完整大语言模型（LLM）集成测试integrationNeo4j/FalkorDB + 真实大语言模型（LLM）API端到端的情节入库
评估不适用Neo4j + 真实大语言模型（LLM）API针对数据集的性能基准测试
测试类别决策流程

基于外部依赖的测试类别选择：

Graphiti · 测试类别决策流程 · 图 1
Graphiti · 测试类别决策流程 · 图 1

来源：pytest.ini:3-3, tests/evals/eval_e2e_graph_building.py:125-128

评估框架（LongMemEval）

Graphiti 包含一个专门的评估框架，位于 tests/evals/ 目录中。它使用 LongMemEval 数据集来衡量图构建质量和时间推理能力。

关键组件
  • 数据集：使用 longmemeval_oracle.json，这是一个用于长期记忆评估的开源数据集 tests/evals/data/longmemeval_data/longmemeval_oracle.json:1-56。
  • 评估逻辑：eval_e2e_graph_building.py 实现了 build_graph 和 eval_graph 函数。它将"候选"图（使用当前代码构建）与"基线"图（先前生成并存储在 baseline_graph_results.json 中）进行比较 tests/evals/eval_e2e_graph_building.py:73-102。
  • 评判大语言模型（LLM）：一个大语言模型（LLM）（通常是 GPT-4.1-mini）充当评判者，使用 eval_add_episode_results 提示来确定候选提取结果是否比基线质量更高 tests/evals/eval_e2e_graph_building.py:168-174。
评估流程

评估系统遵循特定流程来比较图构建性能：

  1. 基线生成：运行 build_baseline_graph 来入库情节并将结果保存为 JSON 文件 tests/evals/eval_e2e_graph_building.py:105-123。
  2. 候选构建：使用当前候选配置运行 build_graph tests/evals/eval_e2e_graph_building.py:136-138。
  3. 大语言模型（LLM）评判：使用 EvalAddEpisodeResults 模型对候选结果与基线进行评分 tests/evals/eval_e2e_graph_building.py:168-171。
运行评估

通过 tests/evals/eval_cli.py 触发评估。

# 构建基线结果
uv run python -m tests.evals.eval_cli --multi-session-count 5 --session-length 10 --build-baseline

# 针对现有基线运行评估
uv run python -m tests.evals.eval_cli --multi-session-count 5 --session-length 10

来源：tests/evals/eval_cli.py:7-36

pytest 夹具和辅助函数

共享的测试夹具和断言辅助函数定义在 tests/helpers_test.py 中。

驱动选择

tests/helpers_test.py 中的 graph_driver 夹具会根据环境变量动态选择和初始化图驱动 tests/helpers_test.py:116-127。这使得测试可以针对不同的图数据库运行。

Graphiti · 驱动选择 · 图 2
Graphiti · 驱动选择 · 图 2

标题：图驱动选择流程

来源：tests/helpers_test.py:33-66, tests/helpers_test.py:87-114

模拟嵌入向量生成器

mock_embedder 夹具提供了一个模拟的 EmbedderClient，它会为给定的输入返回确定性的、随机生成的嵌入向量 tests/helpers_test.py:165-180。这确保了依赖嵌入向量的测试运行快速且不需要外部服务。

代码实体交互图

如何使用模拟对象测试内部提取逻辑：

Graphiti · 代码实体交互图 · 图 3
Graphiti · 代码实体交互图 · 图 3

来源：tests/utils/maintenance/test_entity_extraction.py:33-49, tests/utils/maintenance/test_entity_extraction.py:70-96, tests/utils/maintenance/test_entity_extraction.py:110-124

必需的环境变量

集成测试需要支持的图数据库和 AI 提供商的连接详情。

数据库凭证
  • NEO4J_URI、NEO4J_USER、NEO4J_PASSWORD：由 Neo4jDriver 使用 tests/helpers_test.py:68-70。
  • FALKORDB_HOST、FALKORDB_PORT、FALKORDB_USER、FALKORDB_PASSWORD：由 FalkorDriver 使用 tests/helpers_test.py:72-75。
  • KUZU_DB：由 KuzuDriver 使用 tests/helpers_test.py:81-81。
  • NEPTUNE_HOST、NEPTUNE_PORT、AOSS_HOST：由 NeptuneDriver 使用 tests/helpers_test.py:77-79。

这些变量可以在 .env 文件中设置，也可以直接在环境中设置。对于持续集成（CI），它们在 GitHub Actions 工作流中配置 /.github/workflows/unit_tests.yml:87-91。

AI 提供商密钥
  • OPENAI_API_KEY：与 OpenAI 模型交互的测试所需。
  • 其他大语言模型（LLM）/嵌入向量生成器提供商的密钥（例如 ANTHROPIC_API_KEY、GOOGLE_API_KEY）可能特定提供商集成测试所需。

来源：tests/helpers_test.py:31-31, tests/helpers_test.py:68-81, /.github/workflows/unit_tests.yml:87-91

本地运行测试

使用标准的 pytest 命令或 make 目标来执行测试套件。

Make 目标
  • make test：仅运行单元测试，排除标记为 integration 的测试。它会通过设置环境变量来禁用 FalkorDB、Kuzu 和 Neptune 驱动 Makefile:28-29。
  • make check：依次执行 format、lint 和 test 目标 Makefile:32-32。
pytest 命令
# 运行所有测试（如果设置了环境变量，则包括集成测试）
uv run pytest

# 运行特定的集成测试
uv run pytest tests/test_node_int.py

# 运行单元测试，排除标记为集成测试的测试
uv run pytest -m "not integration"

# 仅运行集成测试
uv run pytest -m "integration"
异步配置

异步测试通过 pytest.ini 中的 asyncio_mode = auto 设置自动运行 pytest.ini:5-5。夹具循环作用域设置为 function pytest.ini:4-4。

来源：Makefile:10-33, pytest.ini:1-6