jittor-BJTU_LTX-Track1A

北京交通大学 BJTU_LTX 战队参加计图 Track1 的开源实现。代码只使用组委会 提供的 data_A，不使用外部比赛数据、预训练权重、Test 标签、伪标签或 Test 自适应策略。

当前公开方案对应线上成绩 1.4104167109954262：

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

线上提交包未纳入 Git，其 SHA256 为 b692a3b265113fd1bbebfb3a72766b8bfb1b6b67f2706c989f34f5410ae6a049。 成员 SHA、固定参数和 OOF 指标见 configs/v25_sota.json 与 结果说明。

代码审核冻结版本为 release ref **a-board-audit-v25**。审核 ZIP 根目录的 SOURCE_REVISION.json 记录该 ref 的完整 commit SHA；code/ 由该 commit 直接导出并进行逐文件校验。提交材料前必须确认 GitHub 与 GitLink 的 master 均解析到该 SHA；GitHub 另保留同名冻结分支。

方法概览

• Dataset1：source/destination temporal encoder 分别编码严格历史 edge_time < t，通过乘积、差值、余弦和双线性交互进行 100 候选排序； 三个固定种子融合后，V22.1 反事实策略只修正少量高置信查询。
• Dataset2：时间安全的 BipartiteBPR128 表示；Model-A 对 50/200/500 条 source 历史做候选交互，优化 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。

1. 环境安装

审核目标环境与组委会要求一致：

• Ubuntu 22.04
• Python 3.10.x
• Jittor 1.3.10.0
• CUDA toolkit 12.4
• NVIDIA RTX 3090，cuda_arch=86

git clone https://github.com/LTX129/jittor-BJTU_LTX-Track1A.git
cd jittor-BJTU_LTX-Track1A
git checkout a-board-audit-v25

conda env create -f environment.yaml
conda activate jittor-track1-audit
export cuda_arch=86

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

也可使用 Python 3.10 虚拟环境：

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

check_environment.py --strict 会逐项检查 Python、所有精确固定的依赖、 cuda_arch 和 nvcc 12.4；任何不一致都会返回非零退出码。

线上 SOTA 的原始实验 lineage 使用较新的 Python/Jittor 和较旧 CUDA toolkit。 该信息仅保留在配置的 original_training_environment 字段中；公开审核入口已 移除旧版本运行时阻断，并以官方审核环境为唯一支持目标。

2. 数据准备

仓库不分发官方原始数据。目录必须为：

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 \
  --no-link \
  --output outputs/data_audit.json

3. 训练与复现

公开版本提供两条互补且真实可运行的闭环。二者都只读取官方 CSV，不要求 私有 checkpoint、冻结 score array 或历史缓存。

3.1 生产组件训练审核（推荐审核入口）

这条路径在真实官方行上依次执行：

1. D1/D2 严格时间切分；
2. D1/D2 BipartiteBPR128 的真实 Jittor 优化步骤；
3. D1 TemporalDualEncoderRanker 的真实 forward、loss、backward；
4. 129 维 D1 action utility 特征与 LightGBM Huber 校准；
5. D2 TemporalPoolingRanker 的 full-list CE + hardest-BPR；
6. score ensemble、重复候选 tied writeback；
7. 两成员 ZIP 与全部格式合同验证。

python scripts/reproduce.py \
  --profile audit \
  --data-root /path/to/data_A \
  --output outputs/v25_audit \
  --seed 20260731 \
  --rows 32

第一次运行会编译 Jittor CUDA 算子。实测 Python 3.10 + Jittor 1.3.10.0 真实训练链路报告见 PY310_TRAINING_PIPELINE_REPORT.json。

3.2 从官方数据生成完整行数参考提交

该路径从四个官方 CSV 训练两个 Jittor BipartiteBPR 模型，对全部 Test 行推理， 并生成 submission-shaped ZIP：

python scripts/reproduce.py \
  --profile reference \
  --data-root /path/to/data_A \
  --output outputs/v25_reference \
  --seed 20260731

等价兼容命令：

python scripts/run_pipeline.py \
  --stage all \
  --data-root /path/to/data_A \
  --output outputs/v25_reference \
  --resume

参考提交用于证明“官方 CSV → Jittor 训练 → 全量推理 → ZIP → validator” 闭环，模型规模小于榜单六成员系统，因此不宣称复现 1.4104167109954262。

3.3 V25 榜单方案的复现边界

最终算法的模型类、损失、时间切分、特征、固定种子、集成和历史生产入口均保留 在 src/track1_open/、src/competition/ 与配置中。按官方“不提交大权重和 训练产物”规范，本仓库和轻量审核 ZIP 不携带 checkpoint、embedding、缓存、 最终 score array 或参考 submission。

因此本发布版明确不把“冻结预测序列化”冒充模型复现，也不声称无训练产物时可 逐字节恢复线上 ZIP。可保证的是：

• 生产神经组件在 Python 3.10/Jittor 1.3.10 上完成真实训练与 forward 冒烟；
• 从官方数据生成完整合法 submission 的闭环可直接运行；
• 榜单方案代码、参数、数据合同和实验 lineage 完整公开；
• 不同 CUDA kernel 与从零随机训练允许产生合理数值差异。

详细 DAG、输入输出和资源说明见 REPRODUCIBILITY.md。

4. 评测、推理与打包

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

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

独立打包和验证：

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/runtime_compat_audit.py
python tools/release_audit.py

5. Jittor 实现边界

核心可学习表示与排序系统基于 Jittor：

• D1/D2 embedding；
• D1 temporal dual encoder；
• D2 temporal pooling ranker；
• listwise CE、Lambda-MRR/SoftRR、BPR 和优化器；
• 神经模型训练及推理。

LightGBM 只用于 Dataset1 的稀疏 post-ranking utility calibrator：输入是本队 构造的 129 维时间安全特征，不接触外部数据或 Test 标签，默认 KEEP，最多对 5% 查询执行一次候选交换。其训练代码、特征和固定参数均公开。

若组委会要求“所有学习模块均必须由 Jittor 实现”，LightGBM 的合规性需要由 组委会书面确认；当前材料不隐瞒该边界，也不把它描述为 Jittor 模型。

6. 结果说明

• 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 自适应、外部数据或预训练权重

7. 仓库结构

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

src/competition/artifacts_v16*/code/ 与 src/competition/artifacts_v17/code/ 的名称源自追加式实验目录，但发布内容 仅为生产链仍依赖的 Python 合同源码；该路径下的 checkpoint、数组、缓存和 日志始终由 .gitignore 与 release audit 双重排除。

8. 开源与引用

代码采用 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