BJTU_LTX Track1 - Temporal Link Prediction with Jittor

BJTU_LTX 战队参加计图人工智能挑战赛 Track1“基于图学习的动态推荐任务”的 A/B 榜实现。

战队：BJTU_LTX
作者：李同轩（litongxuan）
邮箱：25120324@bjtu.edu.cn
A 榜排名：30
A 榜最优总分：1.4104167109954262
B 榜排名：35
B 榜最优总分：0.8528166850365461
B 榜最优提交：result_b3_d4_natural_candidate_safe24001.zip

本仓库是 GitHub 公开代码仓库，包含完整源码、冻结配置、测试和复现文档；不包含官方数据、Test 标签、大型 checkpoint、embedding、预测数组或线上提交 ZIP。组委会私有审核包按 B 榜通知另外包含最优 checkpoint 和快速复验资产，两者的用途不同。

1. 项目简介

任务是动态时序图上的未来链接预测。每条测试查询包含 (source, time) 和 100 个官方候选目标节点，模型需要为候选节点赋分并将真实目标排在尽可能靠前的位置。

本项目只使用组委会提供的 data_A 和 data_B，不使用 Test 标签、伪标签、外部比赛数据、外部预训练权重或其他参赛队代码。所有历史特征均满足：

edge_time < query_time

Dataset3：非二部有向图

Dataset3 沿用 A 榜 Dataset1 的核心方法：

DirectedBPR128
→ Source/Destination TemporalDualEncoderRanker × 3 seeds
→ full-list candidate ranking
→ 129-feature bounded utility correction

Dataset4：大规模二部图

Dataset4 沿用 A 榜 Dataset2 的表示学习、多尺度历史池化和集成方法：

BipartiteBPR128 × 3 embedding geometries
→ 50/200/500 multi-scale history pooling
→ six-member TemporalPoolingRanker ensemble
→ query-wise z-score family fusion
→ temporal Anchor rank-percentile fusion

B 榜最终方案只对 historical seed 24001 槽位加入一个同架构的自然候选续训成员：

slot_24001 = 0.75 × B1_seed24001 + 0.25 × B3_natural_seed24001
historical / embedding-pair family = 0.67 / 0.33
neural / anchor = 0.65 / 0.35

“Natural Candidate”指真实正样本原本就存在于候选集中的训练/验证样本，不会人为向候选列表插入正样本。

2. 环境安装

官方复现目标环境：

Ubuntu 22.04
NVIDIA RTX 4090
CUDA Toolkit 12.4
Python 3.10.x
Jittor 1.3.10.0

Conda 安装：

conda env create -f environment.yaml
conda activate jittor-track1-audit
export cuda_arch=89
python scripts/check_environment.py --strict --with-jittor

venv 安装：

python3.10 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
export cuda_arch=89
python scripts/check_environment.py --strict --with-jittor

本队 B 榜训练服务器使用 RTX 3090，因此本地运行设置 cuda_arch=86。该差异只改变 CUDA 编译目标，不改变数据处理、模型结构、损失函数或融合配方。

3. 数据准备

比赛数据请从计图比赛官方赛题页面下载。本仓库不重新分发 Dataset3/Dataset4 原始数据。下载后将 data_B 组织为：

/path/to/data_B/
├── dataset3/
│   ├── train.csv
│   └── test.csv
└── dataset4/
    ├── train.csv
    └── test.csv

Dataset3/Dataset4 的 train.csv 包含 src,dst,time,split，test.csv 包含 src,time,c1,...,c100。程序保留官方候选 occurrence 顺序，不删除、添加或重排候选；同一行重复出现的相同 candidate ID 在写回时得到完全相同的分数。

4. 仓库结构

.
├── bboard/                    # B 榜训练、推理、融合和提交入口
├── configs/                   # A/B 榜冻结配置
├── src/
│   ├── track1_open/           # 共用 Jittor 模型、损失、数据与集成逻辑
│   └── competition/           # A 榜生产算法血缘与实验实现
├── scripts/                   # A 榜复现、环境检查和通用工具
├── tools/                     # 发布与运行时审计
├── tests/                     # 单元和集成合同测试
├── data/README.md             # 数据目录说明，不包含比赛数据
├── requirements.txt
├── environment.yaml
├── LICENSE
├── .gitignore
├── NOTICE
└── THIRD_PARTY.md

关键 B 榜入口：

文件	功能
`bboard/reproduce_bboard_sota.py`	从官方 `data_B` 和 A 初始化 checkpoint 完成 B3 续训
`bboard/infer_bboard_sota_from_checkpoints.py`	从组委会审核包的最优 checkpoint 执行全 Test 推理
`bboard/run_bboard_dataset3.py`	Dataset3 embedding、OOF、三种子 ranker 和 utility
`bboard/run_bboard_dataset4.py`	Dataset4 embedding、六成员排序器、Anchor 和融合
`bboard/run_bboard_d4_natural_forward.py`	seed24001 自然候选续训与 forward 验证
`bboard/build_bboard_submission.py`	生成并校验 `dataset3.csv`/`dataset4.csv`
`configs/bboard_b3_sota.json`	B3 成员、种子、损失、融合权重与合规合同

5. 训练

5.1 A 榜初始化来源

组委会允许 B 榜使用本队 A 榜模型继续训练。B 榜使用的 A 初始化 checkpoint 由本仓库中的 A 榜代码和官方 data_A 生成，不是外部预训练模型，也不包含 Test 标签。数据血缘为：

官方 data_A
→ A 榜 V25 模型训练
→ A initialization checkpoint
→ 官方 data_B
→ B 榜同架构续训
→ B 榜最终模型

生成 A 榜模型的入口为：

python scripts/reproduce_sota.py \
  --dataset all \
  --config configs/v25_sota.json \
  --data-root /path/to/data_A \
  --output outputs/a_v25 \
  --seed 20260731

B 榜控制器的 --assets 指向一个包含 a_initialization/ 的本地目录。组委会私有审核包已附带该目录；GitHub 仓库遵循开源规范，不提交大型权重。如不使用审核包资产，需先执行上述 A 榜训练，再将 Dataset1 的三个生产TemporalDualEncoder checkpoint 和 Dataset2 的六个生产 Model-A checkpoint 按 docs/B_BOARD_SUBMISSION_GUIDE.md 中的 A 初始化目录映射组织。

5.2 完整 B3 训练

首次正式运行应使用新输出目录，不添加 --resume：

python bboard/reproduce_bboard_sota.py \
  --dataset all \
  --config configs/bboard_b3_sota.json \
  --data-root /path/to/data_B \
  --assets /path/to/a_initialization_assets \
  --output outputs/b3_train \
  --seed 20260823 \
  --build-submission

只运行一个场景时，将 --dataset all 替换为 dataset3 或 dataset4，并去掉 --build-submission。

configs/bboard_b3_sota.json 是冻结生产配方。控制器会校验配置中的成员种子、替换比例、融合权重和数据合同；不匹配时明确报错。

6. 评测与推理

组委会私有审核包按 B 榜通知包含最优 checkpoint。解压后可使用：

python bboard/infer_bboard_sota_from_checkpoints.py \
  --dataset all \
  --config configs/bboard_b3_sota.json \
  --data-root /path/to/data_B \
  --assets /path/to/audit_package/assets \
  --output outputs/b3_checkpoint_inference \
  --build-submission

该入口实际加载 Jittor embedding/ranker/Anchor checkpoint 和 Dataset3 LightGBM utility model，重建历史输入，对全部 Test 候选执行 forward，然后生成：

outputs/b3_checkpoint_inference/result_b3_d4_natural_candidate_safe24001.zip

最终 ZIP 只包含 dataset3.csv 和 dataset4.csv；每行 100 个 [0,1] 分数，无表头并保留八位小数。

7. 结果说明

比赛代码侧的排序指标为 Mean Reciprocal Rank（MRR）。对查询集合 (Q)，定义为：

[ \mathrm{MRR} = \frac{1}{|Q|} \sum_{i=1}^{|Q|} \frac{1}{\mathrm{rank}_i} ]

其中，(\mathrm{rank}_i) 表示第 (i) 条查询中真实目标节点在 100 个候选节点中的排名。 Track1 B 榜模型总分为：

[ \mathrm{Score} = \mathrm{MRR}{Dataset3} + \mathrm{MRR}{Dataset4} ]

项目	结果
B 榜排名	35
B 榜最优总分	`0.8528166850365461`
最优提交	`result_b3_d4_natural_candidate_safe24001.zip`

组委会未向参赛者提供 Dataset3/Dataset4 的单项线上真值，因此不在文档中推测或虚构单项线上 MRR。

从训练数据重新训练时，GPU、CUDA、Jittor kernel 和浮点执行顺序可能导致末位数值差异，因此不承诺重建 ZIP 与历史线上 ZIP 逐字节相同；但模型结构、训练目标、固定成员种子、候选合同和融合配方保持一致。私有审核包中的生产 checkpoint 用于核验最终生产模型推理；GitHub 仓库本身不提交大型训练产物。

8. 可复现性

项目使用流水线级固定种子：

20260823

各模型成员的固定种子记录在 configs/bboard_b3_sota.json。命令行 --seed 只控制调度、辅助随机过程和运行身份，不覆盖配置中显式指定的生产成员种子。

正式训练会在输出目录保存阶段产物和 B3_REPRODUCTION_REPORT.json。输入文件、配置或 A 初始化 checkpoint 缺失，以及 candidate/duplicate 合同失败时，程序会明确报错，不会使用零向量、均值成员或统计规则静默回退。

首次正式运行不应添加 --resume。中断后，只有当源码、官方输入、冻结配置、成员种子和输出目录均未改变时才可添加 --resume。

9. A 榜到 B 榜的一致性

B 榜没有替换 A 榜核心架构。改动集中于超大规模节点空间的工程化实现、 B 榜 forward validation 配置和一个受限的同架构成员继续训练。

项目	A 榜	B 榜
非二部场景	Dataset1 DirectedBPR + TemporalDualEncoder	Dataset3 同架构续训
二部场景	Dataset2 BipartiteBPR + Model-A	Dataset4 同架构续训
历史池化	50/200/500	50/200/500，memmap 分块实现
排序损失	full-list CE + hardest BPR	保持一致
规模工程	直接 ID 空间	compact ID、memmap、分块推理
B3 增量	无	seed24001 槽位加入 25% 同架构自然候选续训分量

result_b2_d4_model_a_scale_safe24001.zip 是 B3 之前冻结的生产基线，只用于比较新模型相对于既有系统的候选排序变化，不作为 B3 的训练、推理或融合输入。B3 最终分数不读取该提交包中的 score array。

5% Top1 变化上限和 replacement_mix=0.25 在 W1–W4 forward 验证阶段冻结。Test Top1 变化率 4.8238% 只是部署后的无标签行为审计指标，不用于重新选择模型、调整融合权重或修改候选预测。

10. 第三方依赖与许可证

所有神经表示、时序编码器、candidate ranker、ranking loss、optimizer、模型训练和推理均使用 Jittor/JittorGeometric。LightGBM 只用于 Dataset3的 129 维有界后排序 utility calibrator，不使用外部数据或 Test 标签。

本项目以 MIT License 开源。第三方项目的用途、来源和许可证见THIRD_PARTY.md 和 NOTICE。比赛数据不随仓库分发，仍受组委会条款约束。