# gaolu-4177

**Repository Path**: haobinjun/gaolu-4177

## Basic Information

- **Project Name**: gaolu-4177
- **Description**: AIC 2026 复赛 · 高炉铁次预测（4177）· 码上云开工队交付物（代码+文档，不含权重与提交包）
- **Primary Language**: Unknown
- **License**: Not specified
- **Default Branch**: main
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-10-05
- **Last Updated**: 2026-10-18

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

# 高炉铁次预测（4177）· 复赛交付说明

**参赛团队编号**：AIC-2026-88558114　**队伍名称**：码上云开工　**队长**：韩雨秀
**赛题**：2026 第八届全球校园人工智能算法精英大赛 · 产业命题赛道（AI＋钢铁）· 高炉铁次预测
**数据版本**：`synthetic_round2_v2`　

## 最终成绩（唯一口径 · 截至 2026-10-05 20:00 定榜）

| 项 | 定榜实测值 |
|---|---|
| **最终成绩** | **96.3995** |
| **最终名次** | **第 106 名 / 156 队（前 67.9%）** |
| 分目标成绩 | `wmape_iron = 0.036359`、`wmape_time = 0.035652` |
| 对应提交件 | `round2_v2_L2_tseedC.zip`（2026-10-03 10:01 提交） |
| 奖项档位 | 三等奖（70% 档）· **未进入前 40%，未晋级半决赛** |

**晋级规则**：复赛一、二等奖（前 40%）→ 晋级半决赛；半决赛一、二等奖 → 晋级总决赛。
**档位划分**：15%（一等）／40%（二等）／70%（三等）。
**评分公式**（平台实测校验 10 次以上，零误差）：`Score = 100 × (1 − 0.5×WMAPE_iron − 0.5×WMAPE_time)`

---

## 一、运行环境

| 项 | 要求 |
|---|---|
| 操作系统 | Windows / Linux 均可（实测 Windows 11） |
| Python | **3.10 ~ 3.12**（实测 3.12.5） |
| **GPU（推荐）** | NVIDIA GPU，显存 ≥ 8 GB；需装 **CUDA 版 PyTorch**（见 §2.2） |
| **CPU（可用但慢）** | 必须设环境变量 `TABPFN_ALLOW_CPU_LARGE_DATASET=1`（否则 TabPFN 拒绝 >1000 样本）<br>实测 5 折全流程 **1~2 小时**（GPU 约 8~12 分钟） |
| 内存 | ≥ 16 GB |
| 磁盘 | ≥ 3 GB（依赖约 2.5 GB + 权重 49 MB + 中间产物） |

> ⚠️ **实测踩坑（务必先读）**：`pip install -r requirements.txt` 默认装到 **CPU-only 的 torch**，
> 此时用 `--device cuda` 会直接报 `AssertionError: Torch not compiled with CUDA enabled`。
> **请先按 §2.2 装 CUDA 版 torch。**

## 二、依赖安装

### 2.1 基础依赖

```bash
python -m pip install -r requirements.txt
```

核心：`tabpfn==9.0.0`、`scikit-learn==1.8.0`、`numpy==2.4.6`、`pandas==2.3.3`、`scipy==1.17.1`。

### 2.2 PyTorch（**关键一步**）

```bash
# CUDA 12.4（本机实测）
pip install torch --index-url https://download.pytorch.org/whl/cu124
# CUDA 12.1
# pip install torch --index-url https://download.pytorch.org/whl/cu121
# 纯 CPU 机器
# pip install torch
```

自检：
```bash
python -c "import torch;print(torch.__version__, torch.cuda.is_available())"
# 期望: 2.6.0+cu124 True
```

### 2.3 模型权重

**已随包提供**，无需下载：
`AIC-2026-88558114-模型文件/tabpfn-v2.6-regressor-v2.6_default.ckpt`（49.2 MB）

> 首次运行 TabPFN 时会自动补齐其配套预处理配置到 `~/.cache/tabpfn`（离线环境需预先放置）。

## 三、运行命令

本包提供**两条复现通路**，用途不同，请按需选择：

| 通路 | 脚本 | 复现内容 | 是否逐位一致 |
|---|---|---|---|
| **A. 精确复现** | `verify_submission.py` | **提交的那一组数字**（用包内冻结的组件预测，不重训） | ✅ **逐位一致**（最大差 <1e-6） |
| **B. 从零重训** | `pipeline/run_pipeline.py` | **同一套方法**从头训练得到的结果 | ⚠️ 等价但非逐位（与提交件相关 0.99995/0.99989） |

> **为什么 B 不是逐位一致**：提交时铁次的跨目标特征用的是历史 R5 混合（0.727·t_log21_std + 0.154·t_catlog8 + 0.112·t_v35log16，需 CatBoost 与 TabPFN v3.5 权重），
> 且时长的随机态为 (6,7,8)；而 B 用自身 OOF 作跨目标特征、随机态 (0,1,2)。
> **两者是同一设计的不同实例，指标同级。**

### 3.1 通路 A：精确复现提交件（推荐优先跑这个）

```bash
cd AIC-2026-88558114-代码与数据
python verify_submission.py \
    --model-dir "../AIC-2026-88558114-模型文件" \
    --result    "../AIC-2026-88558114-赛题结果文档/AIC-2026-88558114-赛题结果.csv" \
    --out result_reproduced.csv
```
期望输出：`✅ 逐位一致 —— 提交件可从本包精确重建`

### 3.2 通路 B：从零重训（GPU）

```bash
cd AIC-2026-88558114-代码与数据
python -m pipeline.run_pipeline \
    --data-dir <官方数据包根目录> \
    --ckpt "../AIC-2026-88558114-模型文件/tabpfn-v2.6-regressor-v2.6_default.ckpt" \
    --device cuda --folds 5 --out result.csv
```

**实测输出**（本机复跑，5 折）：
```
[3/5] 时长模型: OOF WMAPE = 0.03790
[4/5] 铁次模型(乘法分解): OOF WMAPE = 0.03721
[5/5] 已写出 result.csv（322 行，校验通过）
```

### 3.3 通路 B：CPU 运行

```bash
# Windows PowerShell
$env:TABPFN_ALLOW_CPU_LARGE_DATASET=1
# Linux / macOS
export TABPFN_ALLOW_CPU_LARGE_DATASET=1

python -m pipeline.run_pipeline --data-dir <数据包根目录> --ckpt <权重> --device cpu --folds 5 --out result.csv
```
实测 CPU 5 折耗时 **1~2 小时**；只想自检可用 `--folds 2`（约 20~30 分钟）。

### 3.4 对照：演进过程中的 v2 配方（非最终提交件）

```bash
python reproduce_final_v2.py --data-dir <数据包根目录> --ckpt <v2.6权重> \
    --device cuda --folds 5 --out result_v2.csv
```
该脚本复现的是窗口中期配方（加法式跨目标 `i_xT_r5`，平台 96.3888），**保留用于技术报告第 6、18 章的对比**；
若提供 `--ckpt35`（TabPFN v3.5 权重，835 MB，**未随包提供**）则可完整构造 R5 混合特征。

## 四、输入 / 输出目录结构

### 4.1 输入（官方数据包，**不含在本交付包内**）

```
<数据包根目录>/
├─ README.txt
├─ data_dictionary.xlsx
├─ train/
│   ├─ train_samples.csv      2754 条：sample_id, spout_no, tap_iron, tap_time_len
│   └─ train_features.csv     2754 条：sample_id + 21 个数值特征
└─ test/
    ├─ test_samples.csv        322 条：sample_id, spout_no
    ├─ test_features.csv       322 条：sample_id + 21 个数值特征
    └─ result_template.csv     322 条：sample_id（预测列留空）
```

### 4.2 本交付包结构

```
AIC-2026-88558114-码上云开工-复赛-韩雨秀/
├─ README.md                                        ← 本文件
├─ requirements.txt                                 ← 依赖清单
├─ AIC-2026-88558114-技术方案.PDF                     ← 技术报告（47 页 / 43,538 字）
├─ AIC-2026-88558114-模型文件/
│   ├─ tabpfn-v2.6-regressor-v2.6_default.ckpt      ← 基模型权重（49.2 MB）
│   ├─ preprocessors.pkl                            ← 预处理器（标准化器 / logfeat 变换器）
│   ├─ final_components.npz                         ← 最终方案各组件的 OOF 与测试预测
│   └─ 模型文件说明.md
├─ AIC-2026-88558114-代码与数据/
│   ├─ pipeline/                                    ← 模块化算法代码
│   │   ├─ data_io.py       数据读取
│   │   ├─ features.py      特征构建
│   │   ├─ model_io.py      模型加载
│   │   ├─ train.py         模型训练（OOF 交叉拟合 / 全量训练）
│   │   ├─ infer.py         预测推理与合规校验
│   │   └─ run_pipeline.py  主入口（端到端）
│   ├─ reproduce_final_v2.py                        ← 等价的单文件复现脚本
│   ├─ src_final/  src_v2/                          ← 方案全流程研究脚本（31 个）
│   ├─ 代码与数据说明.md
│   └─ 全程复盘.md
└─ AIC-2026-88558114-赛题结果文档/
    ├─ AIC-2026-88558114-赛题结果.csv                 ← 排行榜最高分对应结果（322 行）
    └─ AIC-2026-88558114-赛题结果说明.md
```

### 4.3 输出

运行后在 `--out` 指定路径生成 `result.csv`：

| 列 | 含义 | 约束 |
|---|---|---|
| `sample_id` | 测试样本编号 | 322 个，与 `result_template.csv` 逐行一致 |
| `pred_tap_iron` | 出铁量预测（吨） | 非负有限值 |
| `pred_tap_time_len` | 出铁时长预测（分钟） | 非负有限值 |

脚本会**自动执行合规校验**：行数 322、编号逐行一致、无缺失、非负、无重复；任一不满足即抛异常。

## 五、方案与评分口径

**评分公式**（据平台反馈实测校验 10 次以上，零误差）：
```
Score = 100 × ( 1 − 0.5 × WMAPE_iron − 0.5 × WMAPE_time )
WMAPE = Σ|预测 − 真实| / Σ|真实|        ← 两个分目标各占 50%
```
本方案提交件：`WMAPE_iron = 0.036359`、`WMAPE_time = 0.035652` → **96.3995**。

**最终方案要点**
- 基模型：TabPFN v2.6（在本数据上以 3%~500% 的优势胜过 XGBoost / LightGBM / CatBoost / TabPFN v3 / v3.5 / SVR / KRR / MLP / kNN / ExtraTrees）
- **时长**：偏度前 6 特征 log1p 变换 + 标准化 + log 目标的**单组件**模型（3 随机态平均）
- **铁次**：**乘法分解** `iron = 时长预测 × exp(速率模型输出)`，其中 `速率 = 铁次 / 时长`，速率模型输入为 `[标准化 21 特征, spout_no, 时长预测]`
- 三个关键结论：① 跨目标特征**单向**有效（铁次←时长）②**单组件优于混合** ③ 固定测试集下**抽样优于去噪**

技术细节与全部否证实验见 `AIC-2026-88558114-技术方案.PDF`。