Hugging Face's logo

NLP-beginner
/
cs3319-project2

Model card Files
xet
 Community
cs3319-project2 / WORKSPACE_STATUS.md
NLP-beginner's picture
NLP-beginner
CS3319 Project 2 final deliverable (public F1 = 0.96626)
f28d994
preview code
|
Raw
History Blame Contribute Delete
12.6 kB

WORKSPACE STATUS — CS3319 Project 2 Final Deliverable

本文件由代码仓库快速勘察生成,用于帮助后续开发者快速熟悉本目录。 最后更新:2026-06-17

一、项目简介

1.1 项目定位

本项目是 CS3319 推荐系统课程(Project 2)的最终交付物。

  • 业务目标:构建学术论文阅读推荐系统——在学术平台上为学者推荐其可能感兴趣/应阅读的论文。
  • 建模方式:形式化为**异构学术网络中的链路预测(Link Prediction)**问题。
  • 网络结构:
    • 节点:作者(author,0–6610)、论文(paper,0–79936)
    • 边:作者-论文阅读/引用关系(二部图)、作者-作者合著关系(无向)、论文-论文引用关系(有向)
  • 预测任务:对测试集中的每个 (author, paper) 对,输出 1(推荐)/0(不推荐)。
  • 评估指标:Public Leaderboard F1。
  • 最佳确认成绩:Public F1 = 0.96626
    • 方法:rich content + 7 个随机游走块 + 有向高阶引用传播 + LightGBM,rank top 50% 决策。

1.2 核心技术栈

  • 语言:Python 3.10
  • 数据处理:numpy、pandas、scipy
  • 传统机器学习:scikit-learn、lightgbm、xgboost
  • 深度学习 / GNN:torch、torch-geometric
  • 图嵌入 / 随机游走:gensim、node2vec、networkx
  • 核心模型族:LightGCN 风格异构图卷积推荐器(BPR loss + hard negatives),最终方案为多源特征 + LightGBM 二阶段堆叠。

1.3 数据来源

数据由 Acemap group 提供,采集自 GeoScience 领域顶刊:

  • 6,611 位作者、79,937 篇论文及其引用信息。
  • 论文节点附带预训练特征 feature.pkl。

二、目录结构解析 

26H1_cs3319_final_deliverable/
├── README.md                         项目总览、最佳成绩、复现命令
├── WORKSPACE_STATUS.md               本文件(项目现状日志)
│
├── code/                             核心:全部训练与提交生成脚本(详见第五节)
│
├── data_and_docs/                    官方数据 + 课程文档
│   ├── bipartite_train_ann.txt       训练集二部网络(author-paper)
│   ├── bipartite_test_ann.txt        测试集待预测对
│   ├── author_file_ann.txt           作者合著网络(无向)
│   ├── paper_file_ann.txt            论文引用网络(有向)
│   ├── feature.pkl                   论文预训练特征(约 156 MB)
│   ├── dataset.md / project_description.md / advice.md  数据/项目说明
│   ├── proposal.md                   开题提案
│   ├── references.md                 参考文献
│   ├── project_evaluation.md         评估说明
│   ├── project-example-2026-pygver.ipynb  官方示例 Notebook(PyG 版)
│   └── project2_ recmendation systems.pdf  课程项目书
│
├── checkpoints/                      LightGCN 模型权重(⚠️ 当前为空,见第四节)
│   ├── extra_models/
│   └── final_ens6/
│
├── cached_scores/                    早期缓存的分数/模型
│   ├── lgb_model.pkl / lgb_v2_model.pkl
│   ├── test_bpr_cos.npy / test_bpr_dot.npy
│   ├── test_lgb_scores.npy / test_lgb_v2_scores.npy
│   ├── test_known_mask.npy
│   ├── dot_full/
│   └── large_ensemble/
│
├── validation_runs/                  验证运行结果
│   ├── dynamic_summary.csv
│   ├── stack_ratio_analysis.csv
│   ├── stack_threshold_summary.csv
│   ├── dynamic_seed202/              (⚠️ 仅目录壳,内容缺失)
│   └── feature_cache/                (⚠️ 仅目录壳,内容缺失)
│
├── submissions/                      已确认的提交文件
│   ├── sub_ens6_t0.35.csv
│   ├── sub_ens6_t0.36.csv  ← 纯 LightGCN 路线最佳(公开 0.93044)
│   └── sub_ens6_t0.37.csv
│
├── reports/                          报告
│   ├── preliminary_report.md
│   ├── exploration_summary.md
│   └── final_report.md
│
├── notes/
│   └── experiment_history.md         完整实验历史(10 个阶段)
│
└── manifests/                        原始传输包的文件清单
    ├── package_manifest.txt          完整交付包文件+大小清单
    ├── final_deliverable_filelist.tsv
    ├── home_artifacts_manifest.txt
    └── key_files_sha256.txt

三、运行与配置

3.1 环境配置(⚠️ 配置文件当前缺失)

README 引用的环境文件位于 env/ 目录:

env/environment-cs3319.yml
env/requirements-minimal.txt

注意:本目录下 env/ 文件夹不存在(本副本为精简包,详见第四节)。如需重建环境,可参照 manifests/package_manifest.txt 与 manifests/home_artifacts_manifest.txt 中的 conda-list-cs3319.txt 记录,或按以下核心依赖手动安装:

# Python 3.10
pip install numpy pandas scipy scikit-learn lightgbm xgboost \
            torch torch-geometric gensim node2vec networkx

3.2 快速验证最终结果(只读) 

cd cs3319_final_deliverable

# 查看最终验证指标(注:依赖 validation_runs/dynamic_seed202/,当前缺失)
cat validation_runs/dynamic_seed202/high_order_graph_stack/validation_summary.csv

# 查看最终提交生成摘要(注:同上,当前缺失)
cat validation_runs/dynamic_seed202/high_order_graph_stack/submission_summary.csv

预期关键验证行(README 记录):

rich_rw7_highorder_directed validation F1 = 0.966873736337297

3.3 复现最终高阶堆叠方法(⚠️ 依赖缺失,当前可能不可运行) 

python code/high_order_graph_stack.py \
  --package-root . \
  --split-seed 202 \
  --seed 202 \
  --n-splits 5 \
  --make-submission

依赖前提:需要 validation_runs/dynamic_seed202/(OOF/test 分数、随机游走权重)与 validation_runs/feature_cache/(高阶/富内容特征)。当前两者内容均缺失,直接运行大概率会因找不到输入文件而失败。

3.4 复现早期 6 模型 LightGCN 集成(⚠️ 权重缺失) 

python code/generate_ens6_submission.py \
  --package-root . \
  --device cuda:0   # 或 cpu

依赖前提:需要 checkpoints/final_ens6/model_lgcn_*.pt。当前该目录为空,无法直接运行。

四、当前状态与进度

4.1 开发阶段(已完成,据 notes/experiment_history.md)

项目经历了 10 个实验阶段,可归为四条主线:

阶段 方法 代表脚本 结果
A. GNN 基线 异构 GNN(SAGEConv/HeteroMeanConv + BCE/BPR) run_baseline.py、run_improved.py、run_v2.py 验证 F1 ≈ 0.885–0.92
B. LightGCN 主线 原生 LightGCN + BPR + hard negatives + 多 seed 集成 run_final.py、run_lgcn_final.py、generate_ens6_submission.py 公开 0.93044
C. 特征模型 LightGBM 结构特征 / BPR-MF / 随机游走 run_graph_features.py、extra_score_sources_ablation.py 公开 0.95760–0.96252
D. 高阶堆叠(最终) rich content + 7 RW 块 + 高阶引用传播 + LightGBM high_order_graph_stack.py 公开 0.96626

最终方法:LightGBM 二阶段堆叠,特征包括 LightGCN 分数/排名、图与元路径特征、内容余弦相似度、BPR-MF、富作者内容画像、7 个 DeepWalk/Node2Vec 块、随机游走一致性、高阶引用传播(A-P-P^k、A-A-P-P^k 等)。决策规则为 rank top 50%(而非概率阈值,更鲁棒地应对验证-测试分布偏移)。

4.2 ⚠️ 仓库当前状态(重要)

1) 非 Git 仓库

  • 本目录 .git 不存在,无法查看分支、未提交改动或提交历史。
  • 所有版本管理信息不可用,无法通过 git 追溯变更。

2) 精简/部分副本 与 README 及 manifests/package_manifest.txt 描述的完整交付包相比,本目录缺失多项关键产物:

缺失项 影响
env/(环境配置目录) 无法直接还原 conda/pip 环境
checkpoints/extra_models/、checkpoints/final_ens6/(权重 .pt) 无法复现任何 LightGCN 推理/集成
validation_runs/dynamic_seed202/(OOF/test 分数、RW 权重、最终提交) 无法复现/验证最终高阶堆叠方法
validation_runs/feature_cache/(高阶/富内容特征) 同上
submissions/ 中 sub_final3_*、sub_noforce_*、sub_forced_* 早期对比提交缺失

结论:当前目录本质是代码 + 数据 + 文档 + 部分早期缓存的快照,不包含最终方法所需的权重与缓存特征,因此无法直接复现最终成绩 0.96626。如需完整复现,需从原始传输包(参见 manifests/)重新获取缺失的大体积产物。

4.3 未完成 / 受限事项

  • 恢复 env/ 环境配置文件,或补全依赖清单以便重建运行环境。
  • 恢复 checkpoints/ 下的 LightGCN 权重,以支持推理/集成复现。
  • 恢复 validation_runs/dynamic_seed202/ 与 feature_cache/,以支持最终高阶方法的复现与验证。
  • (可选)初始化 Git 仓库以启用版本管理:git init。

五、核心脚本速查表

训练 / 基线类

脚本 用途
run_baseline.py 官方 Notebook 基线(HeteroMeanConv + cosine + 阈值搜索)
run_improved.py 改进异构 GNN(HeteroConv+SAGEConv + 残差/LN + MLP 解码 + hard negatives)
run_v2.py SAGEConv + BPR 排序变体
run_final.py 原生 LightGCN 最终版(早期)
run_lgcn_final.py 原生 LightGCN(主线稳定版)
run_lgcn_v2.py L2 归一化 LightGCN 变体(效果劣于原生)
run_graph_features.py 手工图特征 + LightGBM
run_ultimate.py Ultimate 综合实验
compare_gnn.py GNN 架构搜索(可学习层权/GAT/SAGE/Deep/Wide LightGCN)

动态验证 / 集成训练类(README 核心)

脚本 用途
train_val_lgcn_ensemble.py 动态验证 LightGCN 训练与分数生成(核心)
train_dynamic_feature_fusion.py 动态特征融合训练
train_val_mf_bpr.py MF + BPR 训练
train_val_sage_bpr.py SAGE + BPR 训练
train_val_hgt_bpr.py HGT + BPR 训练
evaluate_val_checkpoints.py 验证 checkpoint 评估

消融 / 特征构建类

脚本 用途
extra_score_sources_ablation.py Content-mean-cos / BPR-MF / ranker 分数源消融
node2vec_deepwalk_ablation.py DeepWalk / Node2Vec 初始消融
randomwalk_systematic_ablation.py 系统随机游走特征实验(产出最终 7 块)
randomwalk_ensemble_ablation.py / randomwalk_one_ablation.py RW 集成/单块消融
content_rich_ablation.py Rich feature.pkl 内容特征构建
post95_ablation.py Post95 消融
high_order_model_compare.py 高阶模型对比

提交生成类

脚本 用途
high_order_graph_stack.py 最终:高阶引用传播实验 + 提交生成(产出 0.96626)
generate_ens6_submission.py 6 模型 LightGCN 集成提交
generate_post95_submission.py Post95 LightGCN + 图/内容特征提交
generate_extra_bprmf_submission.py BPR-MF 提交
generate_node2vec_deepwalk_submission.py DeepWalk/Node2Vec 提交
generate_randomwalk_ensemble_submission.py 随机游走集成提交(喂入最终阶段)
generate_randomwalk_single_submission.py 单随机游走提交
generate_content_rich_submission.py Content-rich 提交
generate_dot_submission.py Dot 内积提交
generate_large_ensemble_submission.py 大型集成提交
generate_conservative_rw_blends.py 保守随机游走混合

堆叠 / 校准 / 搜索类

脚本 用途
rich_randomwalk_stack.py Rich 随机游走堆叠
score_level_meta_stack.py 分数级元堆叠
stack_rank_calibration.py 堆叠排序校准
error_group_calibration.py 错误分析/阈值扫描/分组校准/边界模型
search_dynamic_fusion.py / search_val_fusion.py 动态/验证融合搜索
make_notebook_style_split.py Notebook 风格数据划分

六、建议阅读顺序(熟悉项目)

  1. README.md —— 全局概览与复现命令
  2. data_and_docs/dataset.md + project_description.md —— 任务与数据定义
  3. notes/experiment_history.md —— 完整方法演进史(强烈推荐)
  4. reports/final_report.md —— 最终方案与结论
  5. reports/preliminary_report.md + exploration_summary.md —— 早期探索