| # 助教验收说明（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`，用于加载权重演示）。 |
|
|
| ```bash |
| # 方式 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） |
|
|
| ```bash |
| # 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. 直接核对最终提交（无需运行代码） |
|
|
| 若只想快速核对结果，不用跑代码： |
|
|
| ```bash |
| # 验证集指标 |
| 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」一节运行： |
|
|
| ```bash |
| 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 节「结果真实性承诺」）。 |
| |
