jittor-BJTU_LTX-Track1A

北京交通大学 BJTU_LTX 战队参加计图 Track1 的开源实现。仓库包含从官方 data_A 训练、推理、评测到提交 ZIP 验证的完整代码；不使用外部数据、预训练权重或 Test 标签。

当前公开方案的线上成绩为 1.4104167109954262：

方案	Dataset1	Dataset2	线上分数
V25 SOTA	V19 时序双编码器 + V22.1 反事实修正	Model-A embedding-diversity ensemble	1.4104167109954262

最终提交包未纳入 Git：其 SHA256 为 b692a3b265113fd1bbebfb3a72766b8bfb1b6b67f2706c989f34f5410ae6a049。成员 SHA 和完整实验指标见结果说明与 configs/v25_sota.json。

方法概览

Dataset1：独立的 source/destination temporal encoder，使用严格历史 edge_time < t，通过乘积、差值、余弦和双线性交互进行 100 候选排序；三个固定种子融合后，用 V22.1 的高精度反事实动作修正少量查询。
Dataset2：时间窗安全的 BipartiteBPR128 表示，Model-A 对 50/200/500 条历史做候选交互，优化 0.8 × full-list CE + 0.2 × hardest BPR。最终使用四个历史 ranker 与两个独立 embedding/ranker 成员做 query-zscore 集成，再与冻结 anchor 做 duplicate-safe rank-percentile 融合。
所有分支保持官方 100 个 candidate occurrence 顺序，重复 candidate ID 始终同分。

架构和数据流见 ARCHITECTURE.md。

环境安装

验证环境：

Python 3.14.6
Jittor 1.3.11.0
CUDA 11.8，cuda_arch=86
NVIDIA RTX 3090

git clone https://github.com/LTX129/jittor-BJTU_LTX-Track1A.git
cd jittor-BJTU_LTX-Track1A

python3.14 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
pip install -r requirements.txt

export cuda_arch=86
python scripts/check_environment.py --config configs/v25_sota.json

Jittor 的 CUDA 自检会触发本地编译，可单独运行：

python scripts/check_environment.py \
  --config configs/v25_sota.json \
  --with-jittor

数据准备

仅使用比赛平台提供的 data_A，仓库不分发原始数据。目录必须为：

data_A/
├── dataset1/
│   ├── train.csv
│   └── test.csv
└── dataset2/
    ├── train.csv
    └── test.csv

校验文件 schema、候选宽度和输入 SHA：

python scripts/prepare_data.py --data-root /path/to/data_A

详见 data/README.md。

训练

从零可运行的参考方案

下面的命令只读取官方 CSV，使用 Jittor 训练两个时序 BPR 模型，并直接生成合法 submission。它用于审核机端到端复现与环境确认，不依赖本队中间缓存：

python scripts/train_reference.py \
  --data-root /path/to/data_A \
  --output outputs/reference \
  --seed 20260730

先进行小样本 smoke test：

python scripts/train_reference.py \
  --data-root /path/to/data_A \
  --output outputs/smoke \
  --smoke

V25 榜单方案

V25 的真实生产代码完整保存在 src/competition/，统一配置位于 configs/v25_sota.json。准备文档所列时间窗与特征缓存后执行：

python scripts/run_pipeline.py \
  --config configs/v25_sota.json \
  --stage all \
  --resume

命令会保存实际配置、完整命令和日志至 outputs/<UTC时间>_all/。首次运行前请阅读 REPRODUCIBILITY.md；大型缓存和 checkpoint 按官方规范不提交 Git，均由仓库中的代码从 data_A 生成。

评测、推理与打包

本地指标使用正样本的 optimistic tied rank：

rank = 1 + count(score_j > score_positive)
MRR  = mean(1 / rank)

训练控制器完成后，生产打包和专用 validator 会自动运行。也可独立组合两个 score 数组：

python scripts/build_submission.py \
  --dataset1 outputs/dataset1_scores.npy \
  --dataset2 outputs/dataset2_scores.npy \
  --output outputs/result.zip

python scripts/validate_submission.py \
  --package outputs/result.zip \
  --output outputs/result.validation.json

提交前运行：

python -m pytest -q
python tools/release_audit.py

结果说明

V25 线上：1.4104167109954262
Dataset2 严格 OOF 相对 V24.1：MRR +0.0023099699
A/B/C：+0.0038837660 / +0.0015060891 / +0.0026862876
Bootstrap P(delta > 0) = 0.9992
无 Test 标签、无 Test 自适应、无外部数据

从零参考方案的成绩会低于 V25：它刻意省略了几十 GB 的历史 OOF 缓存和多模型集成。榜单方案代码、固定种子、配置、报告和资产 lineage 均已公开，可从官方数据重建；不同 CUDA/Jittor kernel 可能造成细微数值差异。

仓库结构

configs/             固定训练与提交配置
data/                官方数据说明（不含数据）
docs/                架构、复现、结果和审计文档
scripts/             环境、训练、推理、打包入口
src/track1_open/     清晰的模型、合同与集成实现
src/competition/     最终成绩所用原始生产代码
tests/               时间、候选、重复和 ZIP 合同测试
tools/               发布前静态审计
outputs/             本地日志、权重和结果（Git 忽略）

开源与引用

代码采用 MIT License。第三方依赖与来源见 THIRD_PARTY.md 和 NOTICE。

作者：litongxuan
邮箱：25120324@bjtu.edu.cn
GitHub：https://github.com/LTX129/jittor-BJTU_LTX-Track1A
GitLink：https://gitlink.org.cn/LTX129/jittor-BJTU_LTX-Track1A