# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## 项目概述

百度商业AI技术创新大赛 (CTI) 2026 — **生成式推荐广告排序推理性能优化**。

目标：给定 GRAB Transformer 模型，在**不改模型结构、不在测试集训练**的前提下，极致优化推理性能。量化/稀疏/剪枝明确允许。

## 环境与常用命令

```powershell
# 激活虚拟环境
.\.venv\Scripts\Activate.ps1

# 本地运行推理（需要 dataset/ 和 ckpt.pt）
.\.venv\Scripts\python.exe 代码\code\infer.py
.\.venv\Scripts\python.exe 代码\code\infer.py --ckpt path/to/ckpt.pt

# AI Studio SDK（下载数据集、提交）
.\.venv\Scripts\aistudio.exe download --dataset <id> --local_dir ./dataset --token <token>
.\.venv\Scripts\aistudio.exe download --model <id> --local_dir . --token <token>

# 打包提交
cd 代码/code && zip -r ../../submit.zip infer.py requirements.txt build_env.sh
```

本地环境仅装 `numpy` + `tqdm` + `aistudio-sdk`（轻量），完整 PyTorch 依赖见 `代码/code/requirements.txt`，训练/推理在服务端跑。

## 代码架构

```
infer.py  (单文件，~730 行，所有逻辑集中于此)
├── 数据加载层
│   ├── _detect_has_clk()          — 检测 CSV 是否有 clk 列
│   ├── load_sample_files()        — 加载 CSV → item_dict + user_seq
│   ├── load_logids_from_file()    — 快速提取文件中所有 logid
│   └── CTRUserDataset(Dataset)    — 按用户组织的 CTR 数据集
│       └── make_collate_fn()      — 将用户样本拼接为 batch（含 slot 特征展开）
├── 模型层
│   ├── RepEncoder                 — Slot-wise Embedding → LayerNorm → Linear
│   │   └── Embedding(5M vocab, 512d) × 28 slots → segment_reduce(sum) → concat
│   ├── TransformerEncoder (8 层)
│   │   ├── QKV Projection → Multi-Head Attention (scaled_dot_product)
│   │   ├── SMoE FFN（8 experts, Top-2 gating, 每层独立）
│   │   └── Pre-LayerNorm + Residual
│   ├── CTRModel                   — RepEncoder + Transformer → Linear → logit
│   │   └── Causal mask: 同一用户的 tokens 因果遮罩，不同用户隔离
│   └── load_model(ckpt_path, device) — 模型构建 + 权重加载入口
├── 推理循环 (main)
│   ├── 数据加载（优先缓存 shard_*.pt）
│   ├── 逐 batch 推理 + 计时（只计 model(batch) 耗时）
│   └── 按 test.csv 顺序写 predict.txt
└── 打分工具
    └── _cal_score() — AUC + PCOC + latency → score_all
```

**模型参数规模**：Embedding 5M×512 + 8 层 Transformer (d_model=512, n_heads=8, dim_ff=1024) × MoE(8 experts) ≈ ~6.5M~11.3M 参数。

## 关键接口（评测系统调用契约）

评测系统通过 `from infer import ...` 加载代码，以下是**必须**对齐的接口（来自 `代码/任务提交接口说明.md`）：

| 接口 | 签名 | 说明 |
|------|------|------|
| `load_sample_files` | `(sample_files_list: List[Path]) -> (item_dict, user_seq)` | 数据加载 |
| `CTRTestSeqDataset` | `(test_logids_ordered, item_dict, user_seq, max_feasign_per_slot, max_ctx_len)` | **必须有 `max_slot_id` 属性** |
| `make_collate_fn` | `(max_slot_id) -> Callable` | DataLoader 的 collate_fn |
| `load_model` | `(ckpt_path: Path) -> (model, device)` | 第一个参数是 Path |
| `move_batch_to_device` | `(batch, device) -> batch` | |
| `model(batch)` | `-> (logits, moe_loss)` | logits 经 sigmoid 后是点击概率 |

**致命不匹配**（baseline `infer.py` 当前存在，提交前必须修复）：
1. 类名 `CTRUserDataset` → 应为 `CTRTestSeqDataset`
2. 构造参数 `pred_logids` → 应为 `test_logids_ordered`，缺少 `max_ctx_len`
3. `load_model(device='cuda:0', ckpt_path=None)` → 应为 `load_model(ckpt_path, device='cuda:0')`（Path 作为第一参数）

## 提交规范

### 压缩包结构
```
submit.zip
├── infer.py              # 必需，实现上述全部接口
├── requirements.txt      # 可选，阿里云 PyPI 镜像安装
└── build_env.sh          # 可选，超时 720s，非 0 退出即失败
```

### 硬约束（任一违反 → 总分 0）
- 推理耗时 < 300s（只计 `model(batch)` 逐 batch 累加）
- AUC ∈ [0.65, 1.0]，PCOC ∈ [0.85, 1.15]
- 压缩包内**不能**有 `dataset/` 或 `ckpt.pt`
- 包后缀只能是 `.zip`/`.tar.gz`/`.tar`，解压后文件在根目录
- 每天最多提交 10 次

### 总分公式
```
score_latency = max(0, (300 - latency) / 300)
score_model   = ((AUC - 0.65) * 1000 + (0.15 - |PCOC - 1|) / 0.15 * 10) / 360
score_all     = score_latency * 70 + score_model * 30
```

## 优化路线图（来自 `推理优化方案.md`）

Baseline 数据：推理 229s，AUC 0.759，PCOC 1.110，得分 25.85。

1. **接口对齐**（必须先做）— 确认能在评测系统跑通（得分 > 0）
2. **FP16 量化** — `model.half()`，Embedding 保留 FP32，预期 229s → ~120s
3. **Flash Attention** — 替换 `scaled_dot_product` 为 `F.scaled_dot_product_attention`，数学等价
4. **torch.compile** — `mode="reduce-overhead"` → `"max-autotune"`，build_env.sh 中预热
5. **数据流优化** — 缓存时预转 FP16 + 预搬到 GPU
6. **MoE 优化** — 统计 expert 负载，合并/移除低频 expert
7. **INT8 量化**（可选）— 精度风险较高，仅在前几步不够时尝试

CUDA Graph 已评估并放弃（batch 形状不固定，不适用）。

每步完成后必须在 AI Studio 提交验证，AUC/PCOC 不达标立即回退。

## 关键文件

| 路径 | 用途 |
|------|------|
| `代码/code/infer.py` | 推理主脚本（提交的核心文件） |
| `代码/code/requirements.txt` | 服务端依赖（torch 2.6.0 + CUDA 12.4） |
| `代码/code/build_env.sh` | 环境构建脚本（目前为空壳） |
| `代码/任务提交接口说明.md` | 官方接口规范 |
| `推理优化方案.md` | 完整优化方案（含合规审查） |
| `论文/GRAB_*.pdf` | GRAB 论文（baseline 模型） |
| `论文/HSTU_*.pdf` | HSTU 论文（架构基础） |
| `.gitignore` | 排除 ckpt.pt, dataset/, *.zip, .venv/ |

## 提交记录

| 日期 | 提交次数 | 得分 | AUC | PCOC | 耗时 | 优化手段 | 备注 |
|------|----------|------|-----|------|------|----------|------|
| 06/12 | 3 | **43.55** | 0.7525 | 1.059 | 152s | 接口对齐 + FP16 量化 | 第 1、2 次因 requirements.txt 异常 |