PyEdmine是一个面向研究者的，易于开发与复现的教育数据挖掘代码库

PyEdmine提出了一个统一的实验流程，用于进行知识追踪、认知诊断、习题推荐和学习路径推荐的实验

PyEdmine约定了一个统一、易用的数据文件格式用于数据集处理，并已支持14个教育数据挖掘数据集

PyEdmine设计了一套代码框架用于训练和评估模型，并且基于该代码框架已经实现了28个知识追踪模型、7个认知诊断模型、3个习题推荐模型、4个学习路径推荐模型

<img src="asset/img/ExperimentalFlowChart.jpg" alt="PeEdmine 实验流程图" width="600"> 图片: PyEdmine 实验流程图

各任务的具体实验设置请查阅模型榜单上的说明，以下是PyEdmine各版本发布的说明

| Releases | Date |Description| |----------|-----------|-----------| | v0.1.0 | 3/26/2025 |初始发布版本| | v0.1.1 | 3/31/2025 |修复了一些bug，新增ATDKT、CLKT、DTransformer、GRKT、HDLPKT模型| | v0.2.0 | 4/9/2025 |beta版本，但是GRKT模型训练会报错（NaN），尚未解决| | v0.2.1 | 8/1/2025 |修复了一些bug，集成了学习路径推荐任务| | v0.2.2 | 8/3/2025 |修复了学习路径推荐的一些bug| | v0.2.3 | 8/3/2025 |使用基于装饰器的模型注册机制，移除手动维护的 model_table| | v1.0.0 | 8/15/2025 |稳定版（长期支持），新增qDKT_CORE、AKT_CORE和DisKT模型和一些新的KT指标

v1.0.0是项目的第一个长期支持版本（LTS），并且与之前所有已发布版本完全向后兼容。未来更新仅会添加新模型，不会破坏现有接口或功能。建议新用户直接使用此版本，老用户直接升级到此版本

安装
快速开始
数据集扩展
参考代码库
免责声明

安装

从pip安装

pip install edmine

从源文件安装（推荐）

git clone git@github.com:ZhijieXiong/pyedmine.git && cd pyedmine
pip install -e .

主要依赖

必须依赖：pandas、numpy、sklearn、torch

非必需依赖：dgl 是部分认知诊断模型所需的；hyperopt 用于自动化参数调优；wandb 用于记录实验数据；tqdm 用于模型评估阶段。

快速开始

概览

请从 GitHub 下载 PyEdmine 的源代码，然后使用 examples 目录中提供的脚本完成数据预处理、数据集划分、模型训练与模型评估。PyEdmine 框架的基本流程如下，请按顺序执行：

1、目录配置：通过 settings.json 文件配置数据与模型的存放路径，然后运行set_up.py以生成必要的目录；

2、数据预处理：下载原始数据集并放置到指定位置，然后使用 examples 中提供的脚本进行数据预处理，以获得统一格式的数据文件。数据集信息可在这里查看；

3、数据集划分：对执行了统一格式处理后的数据，基于特定实验设置进行数据集划分。PyEdmine 提供了五种实验设置：两种知识追踪任务的设置（分别借鉴 PYKT 与 SFKT）、一种认知诊断任务的设置（借鉴 NCD）、一种离线习题推荐任务和一种离线学习路径推荐任务的设置；

4、模型训练：examples 中提供了每个模型的训练启动脚本，更多信息可参考这里；

5、模型评估：examples 中也提供了每个模型的评估脚本，并根据不同任务实现了不同维度与粒度的评估指标，包括冷启动评估、无偏评估等；

6、其它特性：（1）PyEdmine 针对部分模型实现了基于贝叶斯优化的自动参数调整方法；（2）PyEdmine 可通过参数设置启用 wandb 功能；（3）绘制学生知识状态变化图。

每一步的具体操作说明，请参阅下文。

目录配置

在examples目录下创建settings.json文件，在该文件中配置数据目录和模型目录，格式如下

{
  "FILE_MANAGER_ROOT": "/path/to/save/data",
  "MODELS_DIR": "/path/to/save/model"
}

然后运行脚本

python examples/set_up.py

则会自动生成（内置处理代码的）数据集的原始文件存放目录和经过统一处理的文件的存放目录，其中各数据集的原始存放目录（位于/path/to/save/data/dataset_raw）如下

.
├── SLP
│   ├── family.csv
│   ├── psycho.csv
│   ├── school.csv
│   ├── student.csv
│   ├── term-bio.csv
│   ├── term-chi.csv
│   ├── term-eng.csv
│   ├── term-geo.csv
│   ├── term-his.csv
│   ├── term-mat.csv
│   ├── term-phy.csv
│   ├── unit-bio.csv
│   ├── unit-chi.csv
│   ├── unit-eng.csv
│   ├── unit-geo.csv
│   ├── unit-his.csv
│   ├── unit-mat.csv
│   └── unit-phy.csv
├── assist2009
│   └── skill_builder_data.csv
├── assist2009-full
│   └── assistments_2009_2010.csv
├── assist2012
│   └── 2012-2013-data-with-predictions-4-final.csv
├── assist2015
│   └── 2015_100_skill_builders_main_problems.csv
├── assist2017
│   └── anonymized_full_release_competition_dataset.csv
├── edi2020
│   ├── images
│   ├── metadata
│   │   ├── answer_metadata_task_1_2.csv
│   │   ├── answer_metadata_task_3_4.csv
│   │   ├── question_metadata_task_1_2.csv
│   │   ├── question_metadata_task_3_4.csv
│   │   ├── student_metadata_task_1_2.csv
│   │   ├── student_metadata_task_3_4.csv
│   │   └── subject_metadata.csv
│   ├── test_data
│   │   ├── quality_response_remapped_private.csv
│   │   ├── quality_response_remapped_public.csv
│   │   ├── test_private_answers_task_1.csv
│   │   ├── test_private_answers_task_2.csv
│   │   ├── test_private_task_4.csv
│   │   ├── test_private_task_4_more_splits.csv
│   │   ├── test_public_answers_task_1.csv
│   │   ├── test_public_answers_task_2.csv
│   │   └── test_public_task_4_more_splits.csv
│   └── train_data
│       ├── train_task_1_2.csv
│       └── train_task_3_4.csv
├── junyi2015
│   ├── junyi_Exercise_table.csv
│   ├── junyi_ProblemLog_original.csv
│   ├── relationship_annotation_testing.csv
│   └── relationship_annotation_training.csv
├── moocradar
│   ├── problem.json
│   ├── student-problem-coarse.json
│   ├── student-problem-fine.json
│   └── student-problem-middle.json
├── poj
│   └── poj_log.csv
├── slepemapy-anatomy
│   └── answers.csv
├── statics2011
│   └── AllData_student_step_2011F.csv
└── xes3g5m
    ├── kc_level
    │   ├── test.csv
    │   └── train_valid_sequences.csv
    ├── metadata
    │   ├── kc_routes_map.json
    │   └── questions.json
    └── question_level
        ├── test_quelevel.csv
        └── train_valid_sequences_quelevel.csv

数据预处理

你可以选择使用我们的数据集预处理脚本

python data_preprocess/kt_data.py

该脚本会生成数据集经过统一格式处理后的文件（位于/path/to/save/data/dataset/dataset_preprocessed）

注意：Ednet-kt1数据集由于原始数据文件数量太多，需要首先使用脚本examples/data_preprocess/generate_ednet_raw.py对用户的数据按照5000为单位进行聚合，并且因为该数据集过于庞大，所以预处理默认是只使用交互序列最长5000名用户的数据

或者你可以直接下载已处理好的数据集文件（位于dataset/dataset_preprocessed下）

数据集划分

你可以选择使用我们提供的数据集划分脚本，划分好的数据集文件将存放在/path/to/save/data/dataset/settings/[setting_name]下

python examples/knowledge_tracing/prepare_dataset/pykt_setting.py  # 知识追踪
python examples/cognitive_diagnosis/prepare_dataset/ncd_setting.py  # 认知诊断
python examples/exercise_recommendation/preprare_dataset/offline_setting.py  # 习题推荐

你也可以直接下载划分后的数据集文件（位于dataset/settings下），然后将其存放在/path/to/save/data/dataset/settings目录下

或者你也可以参照我们提供的数据集划分脚本来设计自己的实验处理流程

模型训练

对于无需生成包含额外信息的模型，直接运行训练代码即可，如

python examples/knowledge_tracing/train/dkt.py  # 使用默认参数训练DKT模型
python examples/cognitive_diagnosis/train/ncd.py  # 使用默认参数训练NCD模型

对于需要预先生成额外信息的模型，例如DIMKT需要预先计算难度信息、HyperCD需要预先构造知识点超图信息，则需要先运行模型对应的额外信息生成脚本，如

python examples/knowledge_tracing/dimkt/get_difficulty.py  # 生成DIMKT需要的难度信息
python examples/cognitive_diagnosis/hyper_cd/construct_hyper_graph.py  # 生成HyperCD需要的图信息

学习路径推荐任务需要知识追踪模型作为环境模拟器，因此需要先训练好一个知识追踪模型，PyEdmine目前实现了基于qDKT和LPKT4LPR的环境模拟器

基于Epoch的训练器，训练时会得到类似如下的输出

2025-06-19 10:59:21 start loading and processing dataset
2025-06-19 10:59:38 start training
2025-06-19 10:59:44 epoch 1   , valid performances are main metric: 0.76521  , AUC: 0.76521  , ACC: 0.84833  , MAE: 0.23686  , RMSE: 0.34025  , train loss is predict loss: 0.406844    , current best epoch is 1
2025-06-19 11:00:11 epoch 2   , valid performances are main metric: 0.77796  , AUC: 0.77796  , ACC: 0.85032  , MAE: 0.23244  , RMSE: 0.33654  , train loss is predict loss: 0.376817    , current best epoch is 2
2025-06-19 11:00:40 epoch 3   , valid performances are main metric: 0.78149  , AUC: 0.78149  , ACC: 0.85163  , MAE: 0.22629  , RMSE: 0.33514  , train loss is predict loss: 0.371912    , current best epoch is 3
2025-06-19 11:01:08 epoch 4   , valid performances are main metric: 0.78366  , AUC: 0.78366  , ACC: 0.85256  , MAE: 0.22437  , RMSE: 0.33424  , train loss is predict loss: 0.369758    , current best epoch is 4
2025-06-19 11:01:37 epoch 5   , valid performances are main metric: 0.78437  , AUC: 0.78437  , ACC: 0.85268  , MAE: 0.21839  , RMSE: 0.33416  , train loss is predict loss: 0.368626    , current best epoch is 4

...

2025-06-19 11:06:12 epoch 37  , valid performances are main metric: 0.78987  , AUC: 0.78987  , ACC: 0.85457  , MAE: 0.2147   , RMSE: 0.33187  , train loss is predict loss: 0.362751    , current best epoch is 21
2025-06-19 11:06:17 epoch 38  , valid performances are main metric: 0.7907   , AUC: 0.7907   , ACC: 0.85463  , MAE: 0.21792  , RMSE: 0.3316   , train loss is predict loss: 0.362828    , current best epoch is 21
2025-06-19 11:06:23 epoch 39  , valid performances are main metric: 0.78943  , AUC: 0.78943  , ACC: 0.85388  , MAE: 0.22209  , RMSE: 0.33233  , train loss is predict loss: 0.362957    , current best epoch is 21
2025-06-19 11:06:29 epoch 40  , valid performances are main metric: 0.79026  , AUC: 0.79026  , ACC: 0.85434  , MAE: 0.21326  , RMSE: 0.33218  , train loss is predict loss: 0.362876    , current best epoch is 21
2025-06-19 11:06:35 epoch 41  , valid performances are main metric: 0.79023  , AUC: 0.79023  , ACC: 0.8546   , MAE: 0.22441  , RMSE: 0.33173  , train loss is predict loss: 0.362758    , current best epoch is 21
best valid epoch: 21  , train performances in best epoch by valid are main metric: 0.79207  , AUC: 0.79207  , ACC: 0.85297  , MAE: 0.22056  , RMSE: 0.33278  , main_metric: 0.79207  , 
valid performances in best epoch by valid are main metric: 0.7898   , AUC: 0.7898   , ACC: 0.85434  , MAE: 0.21901  , RMSE: 0.33197  , main_metric: 0.7898   ,

基于Step的训练器，训练时会得到类似如下的输出

2025-08-01 19:16:44 start loading and processing dataset
2025-08-01 19:17:08 start training
2025-08-01 19:17:28 step 100      : train loss is concept state loss: 0.

Pyedmine

Install / Use

README

安装