Hugging Face's logo

NLP-beginner
/
cs3319-project2

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

00_README —— 第一性原理文档包入口

本文件是 docs_first_principles/ 文档包的总入口与导航地图。所有数字与 docs_first_principles/_fact_sheet.md(权威事实表,状态日期 2026-06-18)保持一致;叙述性结论若与事实表冲突,以事实表为准。

1. 这个文档包解决什么问题

code/ 下有 30+ 个 Python 脚本,它们通过运行时 importlib 互相加载、共享约定(如 --split-seed 202、rank cutoff)而非显式接口,新读者很难从单点切入。reports/ 里的报告则偏向"结果叙事",对"为什么这样设计、为什么这个数字可信"讲得不够。

本文档包用第一性原理的方式,把整套方法拆成可独立理解的小单元,每篇文档回答一个"为什么":

  • 任务怎么定义、数据集有多稀疏?(01)
  • 整体两阶段架构长什么样?(02)
  • 数据从 txt 怎么流到 submission、中间产物怎么读?(03)
  • LightGCN 为什么"轻"、为什么用 BPR + 硬负采样、为什么是主分数?(04)
  • 为什么单一 LightGCN 分数不够、要手工图特征 + LightGBM 堆叠?(05)
  • 随机游走(DeepWalk/Node2Vec)补的是什么尺度信息?(06)
  • 高阶有向引用传播为什么是最终核心增益?(07)
  • 为什么验证最优阈值不能搬到测试、要用 rank cutoff?(08)
  • 方法是怎么一步步演进到 0.966 的?(09)
  • 30+ 脚本怎么导航、入口在哪?(10)
  • 实验结果对应论文哪些图表?(11)
  • 怎么复现?(12)
  • 答辩/审稿会被问什么?(13)
  • 哪些可直接写进 ACM 中文论文?(SUMMARY)

目标读者:懂一点 ML、但不完全熟悉图推荐系统的人。每篇先讲"为什么",再给"是什么",最后给代码定位与可迁移表述。

2. 本项目一句话概括

CS3319 Project 2 —— 在异构学术网络(6,611 作者 / 79,937 论文;author↔paper 二部、author↔author 合著、paper→paper 引用三类边)上的 author-paper 阅读推荐(二部图链路预测),对 ~2.05M(2,047,262)测试对输出 0/1,公开榜仅评 50% 测试集,评估指标为 F1。

3. 最终方法一句话概括

两阶段 stacking:Stage-1 由 LightGCN 集成、BPR-MF、DeepWalk/Node2Vec(7 块)、内容画像、显式图/meta-path、高阶引用传播 等多源生产 raw 分数与嵌入;Stage-2 由 259 维 LightGBM 二级 meta-learner 融合,测试决策用 rank-cutoff top 50% + 强制训练已知正边为 1。

4. 最终公开 F1 与最重要技术点

  • 最终公开 LB F1 = 0.96626,提交文件 validation_runs/dynamic_seed202/high_order_graph_stack/submissions/submission_rich_rw7_highorder_directed_r0.500000.csv(对应验证 1:1 OOF F1 = 0.966874,AUC = 0.994918)。
  • 最关键技术点 —— 高阶有向引用传播:作者历史论文经 k 步引用扩散到候选 $H_k = R\cdot C^k$,合著者历史论文扩散到候选 $G_k = S\cdot R\cdot C^k$,分别取 forward / backward / undirected 三向。其中 $S$=合著邻接、$R$=作者-论文邻接、$C$=引用邻接。实现见 code/high_order_graph_stack.py 的 build_high_order*。在 7-RW 集成(0.9649)之上叠加它,验证 F1 0.9649 → 0.9669、公开 F1 0.96252 → 0.96626,是最终阶段的核心增益来源。

5. 推荐阅读顺序

文档不是平的,有依赖关系。建议按下方链顺序读,每篇都为下一篇铺垫概念:

01 (任务定义 / 数据集规模与难度)
  └─► 02 (两阶段 stacking 架构总览)        ← 先有全局图,再钻细节
        └─► 03 (数据流与产物:txt → .npy → submission,怎么读中间文件)
              └─► 04 (LightGCN 第一性原理:主分数生产者)
                    └─► 05 (手工图特征 + LightGBM 二阶段堆叠:为何单分数不够)
                          ├─► 06 (随机游走 DeepWalk/Node2Vec:全局接近度)
                          └─► 07 (高阶有向引用传播:最终核心增益)
                                └─► 08 (校准与 rank cutoff:为何验证阈值不能搬测试)
                                      └─► 09 (实验演进时间线:0.885 → 0.966 怎么来的)
                                            ├─► 10 (代码地图与入口脚本)
                                            ├─► 11 (图表与论文章节映射)
                                            └─► 12 (复现指南)
                                                  └─► 13 (答辩 / 审稿常见问题)
                                                        └─► SUMMARY (论文级总览 + 可迁移 TeX)

简化为单链:01 → 02 → 03 → 04 → 05 → 06 → 07 → 08 → 09 → 10 → 11 → 12 → 13 → SUMMARY。

理由:01 给任务与数据;02 给两阶段架构全局;03 给数据/产物的工程机制(读后续文档前先懂"分数文件怎么对齐");04 是主分数来源;05 解释为何单一分数不够、要堆叠;06/07 是 Stage-1 两个互补特征源(游走全局接近度 / 高阶引用传播);08 解释测试决策的特殊设计(rank cutoff);09 把全流程串成结果时间线;10/11/12 是工程导航、图表映射与复现;13 是答辩问答;SUMMARY 是可迁移论文产出。

docs_first_principles/_fact_sheet.md(权威事实表)是全部文档的数字真相源,不进论文正文,但写任何文档前应先查它。

6. 每篇文档一句话用途

文档 文件名 一句话用途
00 00_README.md 本文件:文档包入口、导航与全局数字索引。
01 01_problem_and_dataset.md 任务定义与数据集:异构图三类边、规模、F1 评测、稀疏/长尾难度。
02 02_architecture_overview.md 两阶段 stacking 架构总览:Stage-1 多源 + Stage-2 LightGBM + rank-cutoff。
03 03_data_flow_and_artifacts.md 数据流与产物:txt → 切分 → .npy 分数 → OOF → submission,文件名约定与缓存。
04 04_lightgcn_from_first_principles.md LightGCN 第一性原理:为何"轻"、BPR + 硬负采样、点积解码、主分数生产者。
05 05_feature_stacking_and_lightgbm.md 手工图/meta-path 特征 + LightGBM 二阶段融合:为何 stacking 是单阶段最大增益(+0.0174)。
06 06_random_walk_features.md 随机游走(DeepWalk / Node2Vec,7 块):补全局接近度信息。
07 07_high_order_citation_propagation.md 高阶引用传播:$H_k=R\cdot C^k$ / $G_k=S\cdot R\cdot C^k$,fwd/bwd/undir,最终核心增益。
08 08_calibration_and_rank_cutoff.md 校准与 rank cutoff:验证 1:1 → 测试分布漂移(阈值 0.4617 vs 迁移漂移 0.5242)。
09 09_experiment_timeline.md 实验演进时间线:baseline 0.8850 → 最终 0.9669 / 0.96626 的结果表与三段跃迁解读。
10 10_code_map_and_entrypoints.md 代码地图与入口:30+ 脚本分类、两大共享库、legacy、三条核心命令。
11 11_figures_and_paper_mapping.md 图表与论文章节映射:11 张图 caption + 与正文小节的对应。
12 12_reproduction_guide.md 复现指南:环境、最短/从零路径、快速验证、常见坑。
13 13_common_questions_for_the_author.md 答辩 / 审稿视角常见问题与回答(Q1–Qn)。
SUMMARY SUMMARY_FOR_PAPER.md 论文级总览:可直接进 TeX 的正式表述 + 图表素材清单。
— _fact_sheet.md 权威事实表(数字真相源,内部参考,不直接进正文)。

7. 哪些内容适合直接进论文(简版,详见 SUMMARY)

  • 方法演进表:验证 F1(1:1 OOF,seed=202)baseline 0.8850 → 0.9386(LightGCN)→ 0.9560(meta-path stacking)→ 0.95711(Post95 变体)→ 0.95763(content mean-cos)→ 0.95931(BPR-MF)→ 0.95990(rich content)→ 0.9621(DeepWalk/Node2Vec)→ 0.9649(7-RW)→ 0.9669(高阶有向);公开 F1 链 0.93044 → 0.95760 → 0.95996 → 0.96252 → 0.96626。
  • 259 维特征构成表:细分 12 项(rich rank4 / explicit18 / neg8 / topk3 / variant43 / content_mean4 / bpr4 / rich18 / 7×RW77 / RW-agg11 / 高阶无向24 / 高阶有向45),论文常按 10 大族归并。详见 SUMMARY_FOR_PAPER.md §6 与 _fact_sheet.md §2.5。
  • 高阶传播公式与消融:$H_k=R\cdot C^k$、$G_k=S\cdot R\cdot C^k$;108→190→214→259 维消融,验证 F1 0.964270 → 0.964947 → 0.966556 → 0.966874(无向高阶 +0.001609,有向高阶再 +0.000318)。
  • 决策规则:rank cutoff top 50% + test_known_mask.npy 强制已知正边,及其与验证最优概率阈值(0.4617)的对比论证。
  • 数据集难度:二部密度 ≈ 1.29e-3、56% 作者度=1、三类异构边规模。

8. 哪些是帮助理解代码的(不进论文)

  • 代码定位表:脚本↔函数↔行号(见 _fact_sheet.md 第 6 节,如 train_val_lgcn_ensemble.py:132-165 切分、high_order_graph_stack.py 的 build_high_order*);系统级导航见 10_code_map_and_entrypoints.md。
  • 运行时加载机制:无 utils.py,load_module() 用 importlib.util 把同目录脚本当库加载,train_val_lgcn_ensemble.py 与 stack_rank_calibration.py 是两大事实共享库。
  • 缓存约定:.npy(分数,val_*/test_*)、.npz(RW pair 特征)、feature_cache/ 的 cache-or-compute 文件名约定;详见 03_data_flow_and_artifacts.md。
  • --split-seed 负载:切分种子 baked 进每个分数文件,换 seed 必须端到端重跑。
  • 不一致台账:见 _fact_sheet.md 第 5 节(如列名 Index,Predicted vs "Id and Probability"、F1 系数、sparse-matrix 归属等),写论文时务必避开被裁决为"残留措辞/笔误"的版本。

9. 全部文档总表

文件名 用途(一句话) 面向谁 可直接进论文
00_README.md 文档包入口、导航、全局数字索引 所有人(先读) 部分(数据集/方法一句话)
01_problem_and_dataset.md 任务定义与数据集规模/难度 想了解任务背景者 是(Introduction/数据集节)
02_architecture_overview.md 两阶段 stacking 架构总览 理解整体方法者 是(方法架构图说明)
03_data_flow_and_artifacts.md 数据流与产物文件机制 理解中间产物/复现者 是(实验设置节)
04_lightgcn_from_first_principles.md LightGCN 第一性原理(主分数) 想懂主模型者 是(方法核心节)
05_feature_stacking_and_lightgbm.md 手工图特征 + LightGBM 堆叠 理解两阶段融合者 是(方法/特征工程节)
06_random_walk_features.md DeepWalk/Node2Vec(7 块) 理解游走特征者 是(特征工程节)
07_high_order_citation_propagation.md 高阶引用传播(核心增益) 想懂最终贡献者 是(方法/贡献亮点)
08_calibration_and_rank_cutoff.md 校准与 rank cutoff 决策动机 理解决策设计者 是(分析/讨论节)
09_experiment_timeline.md 实验演进时间线与结果表 拿结果数据/讲故事者 是(实验/结果节)
10_code_map_and_entrypoints.md 代码地图与入口脚本 导航 code/ 者 部分(实现概述节)
11_figures_and_paper_mapping.md 图表与论文章节映射 整理图表者 是(caption + 映射)
12_reproduction_guide.md 复现指南 复现者 部分(复现节)
13_common_questions_for_the_author.md 答辩/审稿常见问题 答辩准备者 部分(讨论/局限节)
SUMMARY_FOR_PAPER.md 论文级总览 + 可迁移 TeX 表述 论文写作者 是(整篇均可)
_fact_sheet.md 权威事实表(数字真相源) 全部文档作者 否(内部参考,不直接进正文)

可迁移到论文中的写法

下面给出可直接进 TeX 的正式表述(中文,保留英文术语):

任务定义(Introduction 节草稿) 本文研究异构学术网络上的 author-paper 阅读推荐,形式化为二部图链路预测问题。网络包含 6,611 名作者与 79,937 篇论文,以及三类边:author↔paper 二部边(共 682,421 条)、author↔author 无向合著边(9,663 条)、paper→paper 有向引用边(327,113 条)。给定 2,047,262 个待预测 author-paper 对,任务为对每对输出 0/1,以 F1 为评估指标(公开榜仅评测 50% 测试集)。该图二部正边密度仅约 $1.29\times10^{-3}$,且约 56% 的作者度数为 1,呈现显著的稀疏与长尾特性。

方法概述(Method 节草稿) 我们提出两阶段 stacking 架构。Stage-1 由多个互补模型生产原始分数与嵌入,包括异构协同过滤(LightGCN 集成)、矩阵分解(BPR-MF)、随机游走表示(7 个 DeepWalk/Node2Vec 块)、内容语义画像(基于 512 维 Universal Sentence Encoder 嵌入)以及高阶引用传播特征。Stage-2 由一个 259 维特征上的 LightGBM 二级 meta-learner 进行融合。核心贡献是高阶有向引用传播:令 $R$ 为作者-论文邻接、$S$ 为合著邻接、$C$ 为引用邻接,则 $H_k=R\cdot C^k$ 将作者历史论文经 $k$ 步引用扩散到候选,$G_k=S\cdot R\cdot C^k$ 进一步纳入合著者历史论文,并分别计算 forward、backward、undirected 三向得分。

决策规则(Experiment 节草稿) 由于验证集为人工 1:1 正负采样,LightGBM 输出概率在验证→测试分布漂移下无法直接迁移(验证最优阈值 0.4617,迁移到测试后正例率漂移至约 0.5242),因此测试阶段采用 rank cutoff 决策:按最终分数对测试对排序,预测 top 50% 为正,并强制出现在训练正边中的测试对为正。该方法在公开榜取得 F1 = 0.96626。