12.7 · 评估框架（Evaluation Framework）

评估框架

评估框架

Cognee 评估框架是一套内置工具，旨在对知识引擎在各种检索和推理任务中的性能进行基准测试。它提供了自动化的管线，用于语料库构建、问答执行以及使用行业标准基准和大语言模型（LLM）作为评判的评估器进行指标计算。

框架架构

该框架由四个顺序模块组成：

1. 语料库构建器：从基准测试中导入数据并填充 Cognee 知识图谱。
2. 答案生成器：使用各种 BaseRetriever 策略对处理后的数据执行查询。
3. 评估引擎：使用 DeepEval 或直接的大语言模型（LLM）评分，将生成的答案与"黄金"参考答案进行评分。
4. 指标仪表盘：可视化性能分布和置信区间。

数据流与组件交互

下图展示了从原始基准数据到最终评估指标的流程，并突出显示了每个阶段涉及的代码实体。

评估管线数据流

Cognee · 数据流与组件交互 · 图 1

来源：cognee/eval_framework/corpus_builder/corpus_builder_executor.py:13-68, cognee/eval_framework/answer_generation/answer_generation_executor.py:24-59, cognee/eval_framework/evaluation/deep_eval_adapter.py:17-88, cognee/eval_framework/metrics_dashboard.py:131-170

语料库构建器

CorpusBuilderExecutor 负责为评估准备环境。它使用 BenchmarkAdapter 实现来加载特定数据集，并编排 Cognee 入库管线。

• 初始化：接受一个基准名称（例如 "HotPotQA"、"BEAM"、"TwoWikiMultiHop"）和一个 task_getter 函数，该函数定义了管线的具体处理步骤 cognee/eval_framework/corpus_builder/corpus_builder_executor.py:13-30。
• 数据准备：在添加新语料库之前，通过 cognee.prune.prune_data() 和 cognee.prune.prune_system(metadata=True) 清理现有数据，以确保基准测试处于干净状态 cognee/eval_framework/corpus_builder/corpus_builder_executor.py:58-61。
• 任务执行：使用 run_pipeline 执行由 task_getter 返回的任务（例如 get_cascade_graph_tasks），从而在评估期间支持不同的图谱构建策略 cognee/eval_framework/corpus_builder/corpus_builder_executor.py:63-70, cognee/eval_framework/corpus_builder/task_getters/TaskGetters.py:14-20。
• 持久化：从基准测试生成或加载的问题会使用 Questions 模型保存到关系数据库中 cognee/eval_framework/corpus_builder/run_corpus_builder.py:19-34。

来源：cognee/eval_framework/corpus_builder/corpus_builder_executor.py:13-68, cognee/eval_framework/corpus_builder/run_corpus_builder.py:36-77, cognee/eval_framework/eval_config.py:10-13, cognee/eval_framework/corpus_builder/task_getters/TaskGetters.py:14-26

答案生成

AnswerGeneratorExecutor 负责对已构建的知识库执行问题查询。它支持 retriever_options 中定义的多种检索策略。

支持的检索器

核心逻辑位于 question_answering_non_parallel 中，它会遍历问题，通过 get_retrieved_objects 检索对象，构建上下文，并生成答案 cognee/eval_framework/answer_generation/answer_generation_executor.py:25-59。生成的答案会使用 Answers 模型持久化到关系数据库中 cognee/eval_framework/answer_generation/run_question_answering_module.py:20-34。

来源：cognee/eval_framework/answer_generation/answer_generation_executor.py:15-21, cognee/eval_framework/answer_generation/run_question_answering_module.py:37-71, cognee/eval_framework/answer_generation/answer_generation_executor.py:35-41

DeepEval 集成

Cognee 利用 DeepEval 进行基于大语言模型（LLM）的复杂评估。DeepEvalAdapter 将 Cognee 的内部答案格式映射为 DeepEval 库所需的 LLMTestCase 对象。

指标与评分

该框架支持多个指标：

• 正确性：使用带有特定标准（例如，惩罚遗漏细节）和可配置模型（如 gpt-4o-mini）的 GEval 指标 cognee/eval_framework/evaluation/deep_eval_adapter.py:90-105。
• 精确匹配（EM）：字符串级别的相等性检查 cognee/eval_framework/evaluation/deep_eval_adapter.py:22-22。
• F1 分数：单词级别的重叠度 cognee/eval_framework/evaluation/deep_eval_adapter.py:23-23。
• 上下文相关性：衡量检索到的上下文与查询的相关程度 cognee/eval_framework/evaluation/deep_eval_adapter.py:24-24。
• 上下文覆盖率：评估检索到的上下文是否包含必要信息 cognee/eval_framework/evaluation/deep_eval_adapter.py:25-25。

评估实现

Cognee · 指标与评分 · 图 2

来源：cognee/eval_framework/evaluation/deep_eval_adapter.py:17-88, cognee/eval_framework/eval_config.py:23-28

配置与执行

评估通过 EvalConfig 进行配置，可以通过环境变量或字典进行设置。它控制语料库构建、问答和评估引擎的参数 cognee/eval_framework/eval_config.py:6-46。

分布式评估（Modal）

对于大规模基准测试，Cognee 支持在 Modal 上运行评估。modal_run_eval 函数在容器化环境中编排整个流程，使用 modal.Volume 在多次运行之间持久化结果 cognee/eval_framework/modal_run_eval.py:49-98。它支持使用 asyncio.gather 并行运行多个配置 cognee/eval_framework/modal_run_eval.py:101-131。

指标仪表盘

该框架会生成一个 HTML 仪表盘，包含以下内容：

• 分数分布：通过 plotly.graph_objects 为每个指标创建的直方图 cognee/eval_framework/metrics_dashboard.py:13-28。
• 置信区间：所有指标的 95% 置信区间图，以确保统计显著性 cognee/eval_framework/metrics_dashboard.py:31-55。
• 详细说明：一个表格，将问题映射到其分数以及大语言模型（LLM）生成的评分理由（来自 DeepEval）cognee/eval_framework/metrics_dashboard.py:58-93。

来源：cognee/eval_framework/eval_config.py:6-46, cognee/eval_framework/modal_run_eval.py:49-131, cognee/eval_framework/metrics_dashboard.py:131-170