助教验收说明（SUBMISSION README — for the TA）

一句话：本项目为 CS3319 Project 2（学术论文阅读推荐 / 作者-论文异构图链接预测），最终公开榜单 F1 = 0.96626、验证集 F1 = 0.966874。 验收只需 3 步、纯 CPU、数秒：解压 → 装依赖 → 跑一个 notebook，即可看到提交被逐位复现。

0. 本包是什么（What's in this package）

项	内容
任务	异构学术网络（6,611 作者 / 79,937 论文）上的作者-论文链接预测，指标 F1
最终方法	259 维多源特征（LightGCN + BPR-MF + 7×DeepWalk/Node2Vec + 高阶引用传播 + content-rich + meta-path）上的 LightGBM 二阶段堆叠；决策用 rank-cutoff top 50% + 强制已知正样本
最终成绩	公开 F1 0.96626 · 验证 F1 0.966874 · AUC 0.994918
论文	`ACM_Conference_Proceedings_Primary_Article_Template/cs3319_final_paper_cn.pdf`（中文，ACM 双栏）
代码	`code/run_inference.ipynb`（验收入口，加载权重复现提交）+ `code/*.py`（完整实验脚本）
AI 标注	见根目录 `AI_USAGE.md`

⚠️ 这是一个精简可运行包。大体积中间产物（2.5 GB 验证中间结果、完整随机游走特征等）未打入本 zip，但可在 Hugging Face 备份仓库获取（见第 5 节）。本包已包含验收所需的一切。

1. 目录结构（Key layout）

cs3319_final_deliverable/
├── SUBMISSION_README.md          ← 本文件（先读我）
├── README.md                     ← 完整项目说明与全流程复现命令
├── AI_USAGE.md                   ← AI 内容使用声明
├── code/
│   ├── run_inference.ipynb       ← ★ 验收入口：加载权重 → 复现最终提交
│   └── *.py                      ← 完整实验/提交生成脚本
├── checkpoints/                  ← LightGCN 训练权重（final_ens6 6 个 + extra_models）
├── cached_scores/                ← LightGBM 模型、测试分数、已知正样本掩码
├── validation_runs/dynamic_seed202/high_order_graph_stack/
│   ├── rich_rw7_highorder_directed_test_pred.npy   ← 最终系统测试集推理输出
│   ├── rich_rw7_highorder_directed_oof.npy         ← OOF 分数
│   ├── validation_summary.csv                      ← 验证指标
│   └── submissions/
│       └── submission_rich_rw7_highorder_directed_r0.500000.csv  ← ★ 最终提交（公开 0.96626）
├── data_and_docs/                ← 官方数据（边文件 + feature.pkl + 测试对）+ 课程文档
├── env/                          ← 环境依赖（requirements-minimal.txt / environment-cs3319.yml）
├── reports/                      ← 报告（preliminary / exploration / final）
└── ACM_Conference_Proceedings_Primary_Article_Template/
    └── cs3319_final_paper_cn.pdf ← 论文 PDF（同目录有 .tex / .bib 源码）

2. 环境准备（Environment，约 2 分钟）

需要 Python 3.10。验收 notebook 仅依赖 numpy + pandas（可选 torch，用于加载权重演示）。

# 方式 A：最小依赖（够跑验收 notebook）
python -m pip install numpy pandas

# 方式 B：完整依赖（可跑全流程实验）
python -m pip install -r env/requirements-minimal.txt
# 或 conda：
# conda env create -f env/environment-cs3319.yml

推荐 Python 3.10。若只想验收，方式 A 即可，无需 GPU、无需 torch。

3. ★ 三步验收（Verification in 3 steps）

# 1) 解压（若尚未解压）
unzip cs3319_final_deliverable.zip
cd cs3319_final_deliverable

# 2) 装依赖（最小集即可）
python -m pip install numpy pandas

# 3) 运行验收 notebook（纯 CPU，数秒）
jupyter notebook code/run_inference.ipynb
#   或命令行直接执行：
jupyter nbconvert --to notebook --execute --ExecutePreprocessor.kernel_name=python3 \
    code/run_inference.ipynb --output run_inference.executed.ipynb

预期输出（Expected output）

notebook 会逐步打印，关键两处：

逐位一致 / exact match : 2047262 / 2047262 -> True
OK Reproduction verified: regenerated submission is byte-identical to the stored final submission.

验证集 F1   / validation F1 : 0.966874
公开榜单 F1 / public LB F1  : 0.96626

看到 exact match : 2047262 / 2047262 -> True 即代表：从训练系统的缓存推理输出出发，应用论文的 rank-cutoff 决策规则，逐位复现了最终提交 CSV。这就是对「模型权重有效、决策规则正确、结果可复现」的完整证明。

notebook 第 5 节为可选项：用 torch.load 直接载入一个 LightGCN 权重文件，证明训练好的 GNN 权重确实在包内且可在 CPU 载入。无 torch 时会自动跳过，不影响上面结论。

4. 直接核对最终提交（无需运行代码）

若只想快速核对结果，不用跑代码：

# 验证集指标
cat validation_runs/dynamic_seed202/high_order_graph_stack/validation_summary.csv
# → rich_rw7_highorder_directed, validation_f1=0.966874, auc=0.994918, n_features=259

# 最终提交文件存在性与正例比例（应 = 0.5）
python -c "import pandas as pd; d=pd.read_csv('validation_runs/dynamic_seed202/high_order_graph_stack/submissions/submission_rich_rw7_highorder_directed_r0.500000.csv'); print(d.shape, d.Predicted.mean())"
# → (2047262, 2) 0.5

5.（可选）完整管线复现（Full pipeline reproduction）

本 zip 只含「加载权重→复现提交」所需产物。若需从原始数据重训全部模型（LightGCN / DeepWalk / LightGBM），需要大体积中间特征，可从 Hugging Face 备份仓库拉取（URL 见交付邮件/最终报告），然后按 README.md 的「Command Reproduction」一节运行：

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

该路径纯 CPU 可跑（LightGBM），但需 cached_scores/、validation_runs/feature_cache/、randomwalk_systematic/ 等完整缓存（数分钟）。重训 LightGCN 本身需 GPU。

6. 常见问题（Troubleshooting）

现象	处理
`ModuleNotFoundError: numpy/pandas`	`pip install numpy pandas`
notebook 找不到仓库根目录	从仓库根或 `code/` 目录启动均支持；切勿把 notebook 单独拷出
第 5 节 `(跳过) torch 权重加载需要 PyTorch`	正常，非必需；装 `torch`（CPU 版）后可看到权重加载
想看完整训练代码	`code/train_val_lgcn_ensemble.py`（数据/划分/best_f1）、`code/high_order_graph_stack.py`（最终堆叠器）
提交文件格式	两列 `Index,Predicted`，Predicted ∈ {0,1}，共 2,047,262 行，正例比例 0.5

7. AI 内容标注

本交付物的 AI 使用情况（论文/文档/图表/notebook 等）已在 AI_USAGE.md 中逐产物如实标注。所有实验数值均来自真实实验，AI 未参与数值生成/伪造。

8. 联系

如验收遇阻，请按第 3 步命令把 notebook 输出贴回；该命令在本机已验证通过（见 AI_USAGE.md 第 4 节「结果真实性承诺」）。