# MambaGate HistX · Board49

时序图 100-candidate 重排（MRR）· Jittor 实现
沃信2.0 · Educoder Jittor-7 赛道一 · 封榜第 49 · dig+RRF ≈ 1.3708

相对 board46：阶段一 avg20 不变；阶段二主交改为 dig+RRF（fuse_final）。

详细复现：docs/REPRO.md · 封榜锁定：docs/FINAL_RANK49.md · 超参：configs/

---

1. 环境安装

• Python 3.8–3.10（建议；Jittor 对该区间支持较好）
• 需可用 GPU 时，按 Jittor 文档 配置 CUDA

pip install -r requirements.txt

核心依赖：jittor>=1.3.8、numpy、pandas、tqdm、numba。

---

2. 数据准备

官方比赛数据需自行从赛事平台获取（本仓库不提交原始数据集）。放到：

data/
├── dataset1/train.csv
├── dataset1/test.csv
├── dataset2/train.csv
└── dataset2/test.csv

数据根目录配置（任选其一）：

方式	示例
命令行	--data_dir data 或 --data_dir <官方数据根>
环境变量	BOARD46_DATA_DIR=<路径>

可选入库（跳过重训时用）：data/ensemble_avg20/、data/experts/、data/valhot_scores/ —— 见 data/README.md。
封榜 AEF 素材：WOXIN_AEF 或 docs/GITLINK_RELEASE.md。

若 *.npy / 专家 CSV 只有约 133 字节，仍是 Git LFS 指针（sync 会标 LFS）。本目录无 .git 时：python -u tools/hydrate_from_board46.py，dig 增量与 AEF 需从 GitLink 拉取实体。

---

3. 训练

默认超参见 configs/（如 stage1_pairfeat20.yaml、stage2_*.yaml）。种子列表：artifacts_pairfeat20.txt。

# 阶段一：pairfeat × 20-seed → avg20（与 board46 相同）
python -u scripts/stage1_train_baseline.py --data_dir data

# 阶段二：专家（specialist / markov / hardneg / d2）
python -u scripts/stage2_train_experts.py --all --data_dir data

已有合法 data/ensemble_avg20 时可跳过阶段一，直接训专家或融合。

---

4. 评测 / 推理

融合与打包（默认读入库 avg20 / experts / valhot / AEF，无需再传 ckpt）：

# 封榜主交 dig+RRF → result_final_dig_rrf.zip
python -u scripts/run_repro.py --skip-20seed --pack final

# 或显式融合入口
python -u scripts/stage2_fuse.py              # 默认 dig+RRF
python -u scripts/stage2_fuse.py --stable     # margin 辅包

权重默认落在本仓 outputs_* / 入库指针；路径解析见 src/rule_expert/paths.py。
Windows 可用：run_repro.bat --skip-20seed --pack final。

---

5. 结果说明

项	说明
指标	榜分 ≈ **MRR(dataset1) + MRR(dataset2)**；每 query 在 100 候选中排序，真值在列 0
本地门控	val-hot 上相对 avg20 的 Δ；avg20 baseline sum ≈ 1.4297
封榜板分	dig+RRF ≈ 1.3708（第 49）；末交 ASYM75 ≈ 1.37085
提交物	zip 根目录仅 dataset1.csv、dataset2.csv，每行 100 维概率

本地 val-hot 与线上板分不可直接比绝对值（分布不同）；以相对 avg20 的 Δ 与锁定配方对照为准。详见 docs/FINAL_RANK49.md。

勿交 result_router_*（本地虚高、榜跌）。见 docs/LESSON_ROUTER_OVERFIT.md。

---

目录结构

configs/     # 训练/融合超参记录
src/         # 模型 / 数据 / 训练 / 融合 / rule_expert / valhot
scripts/     # 推荐入口（stage1_* · stage2_* · run_repro）
tools/       # 数据处理与旧实验脚本
data/        # 仅说明 + 可选入库指针（不放大文件）
docs/        # 复现与封榜文档
outputs/     # 日志 / 权重 / 结果（gitignore，默认不提交）

阶段	推荐入口	旧 shim
一	scripts/stage1_train_baseline.py	run_20seed_pairfeat.py
二专家	scripts/stage2_train_experts.py	分项 train 脚本
二融合	scripts/run_repro.py / stage2_fuse.py	根目录 run_repro.py

阶段一  pairfeat × 20-seed → avg20
           │
阶段二  专家 + dig+RRF（主）/ margin（辅）→ 提交 zip

---

Jittor 纯度

训练与推理：import jittor（权重 *.pkl）。融合：numpy。
详见 docs/JITTOR_ONLY.md。

---

更多文档

文档	内容
docs/REPRO.md	完整复现命令
docs/PAIRFEAT20_TRAINING.md	20-seed 训练
docs/FRAMEWORK_PARITY.md	与 PyTorch 板对齐
ARTIFACTS.md	产物说明
docs/LOGIC.md	算法脉络