NOTES.md

# 实施与 S0 冒烟要点（给下一执行者/服务器环境）

## 已实现（本地已验证）
- 工程脚手架 + 官方 clone(official/) + git 已提交(5a1afb7)
- tools/*.py 全部 CPU 可跑: clean_images(阈值/去重/可复制到 clean) / tag_categories(7类启发式) /
  build_manifest / split_val(70组隔离) / build_patches(>=20k patch) / download_batch(编排)
  已用合成小图冒烟: 模糊/全黑/过曝/纯色正确剔除, 打标与 patch 构建正常。
- src/*.py 与 scripts/*.py 语法编译通过(py_compile)。

## 必须上 A100 用真实权重验证的点(S0, 1 迭代/配置)
1. scripts/setup_env.sh + scripts/download_weights.sh(Plan A) 后运行 scripts/env_check.py。
2. scripts/run_smoke.sh: train_lora 与 train_stage2 各 1 迭代; 重点核对:
   - Net+halfDecoder 全链装配 forward 形状: LR[1,3,128,128] -> RGB[1,3,512,512]
     (若 shape 报错, 以 official/test.py 官方装配为唯一基准修正 src/common.build_net/assemble_full_student)
   - teacher z0 前向与判别器 dtype/shape 匹配(bf16 + autocast)
   - loss 有限值且可保存 checkpoint、可续训
3. 基线复现: 用官方 net_params_200.pkl + official/test.py 在 RealSR 复现论文量级指标;
   并在 A100 记录 OSEDiff 512 fp16 时延(基准分母)。
4. GDPO 教师: 先 python scripts/probe_gdpo.py <权重路径> 确认键格式; 若格式不兼容,
   按 probe 输出在 src/common.load_gdpo_teacher 补映射, 否则回退 --teacher osediff(默认已支持)。

## 执行顺序(每阶段 gate 见方案 §6)
1. tools 数据构建 B1-B4 -> clean -> tag -> patches>=20k -> manifest -> split_val(70)
2. pack_upload.ps1 上传代码+数据; 服务器下载权重
3. S0 smoke -> S1(LoRA) -> eval_val 选 best -> S2(GDPO蒸馏) -> eval_val 选 best -> S3
4. 每次选点: 用 src/eval_val.py 输出 proxy, 把最优权重软链/复制为
   weight/s1/net_params_BEST.pkl (run_stage2 引用) / weight/s2/net_params_BEST.pkl (run_stage3 引用)
5. 速度: src/latency_test.py; 出图: src/inference_4k.py; 导出: src/export_jit.py; 提交包检查: src/check_submission.py

## 已知待办/说明
- 训练脚本仅在服务器有 torch/权重时可运行; 本地 3050 4G 只做代码与数据开发。
- run_stage1/2/3.sh 里的 net_params_BEST.pkl 为占位名, 按实际 eval 结果更新。
- inference_4k/export_jit 采用“512窗->128->官方4x链->512”的 x1 包装语义;
  若官方评测机 runner 口径不同, 以官方样例 runner 实测为准调整 export_jit.SR512。
- 类别打标为启发式(文件名关键词+亮度/绿色占比), 抽样人工复核后再上传训练。


## 试点批次进度 (B3 NKUSR8K 首 100 张, 2026-09-05)
- raw 100 张(~1.9GB) -> clean 90 张(10 张 aHash 重复剔除; 8K 图质量均达标) -> 已删 raw 释放空间
- 分类: city_view 41 / night_building 26 / plant 23 (skyscraper/shop_street/residential 为 0, 需 4KLSDB/RealSR 等源补充)
- patches: 2998 张 512x512 (city_view 1366 / night_building 866 / plant 766), manifest: data/manifest_train.json
- 人工复核图: data/review/NKUSR8K/*.jpg (每类 20 张拼图)
- 注意: synthetic patch 的 val 划分须按"源图"分组(文件名前缀)而非单 patch, 防同源泄露; 最终 val 主要来自 real pairs。

## 数据集构建进度 (2026-09-05 晚 更新, 本批次完成)
- NKUSR8K 全量 1000 张: 下载 900(跳过试点100) -> 清洗 kept 639 (dup 259/过曝 2) -> 已删 raw(17.9GB 释放)
- 合并 clean_all/NKUSR8K = 729 张(试点90 + 全量639, 4096 长边 jpg, 文件名前缀 NKUSR8K_)
- 启发式分类: night_building 231 / plant 255 / city_view 243 (skyscraper/shop/residential 启发式分不出, 无碍训练)
- 源级 val 划分: 70 源留作 val (split_val_sources.json), train 源 659
- patches: data/patches 23,999 (city 7866/night 7684/plant 8449) + data/patches_val 560 (val 源)
- manifest_train.json: synthetic 23,999 + RealSR 训练对 400; manifest_val.json: synthetic 560 + RealSR 测试对 99
- RealSR 对清单: clean_pairs 配对命名 Canon_001_LR4.png <-> Canon_001_HR.png (build_manifest 已按 scene key 匹配)
- 人工复核拼图: data/review/NKUSR8K_all/{city_view,night_building,plant}.jpg

## 待办
- [ ] DRealSR 训练集: 需人工(百度网盘 osiy / Google Drive 文件夹), 见 data/SOURCES.md; 到手后走 clean_pairs 入 real_pairs
- [ ] 4KLSDB: 默认跳过(稀疏类抽取不划算, 结论见 SOURCES.md); 若需补量可用 tools 的 RangeReader 思路实现 extract_klsdb_rg.py
- [ ] 打包上传: scripts/pack_upload.ps1 (需密码), 服务器 setup_env.sh + download_weights.sh + S0 smoke -> S1/S2/S3
- [ ] 本地清理: 确认后删除 data/clean/NKUSR8K* / data/clean_all(已并入 patches, 仅留存备查)

## 2026-09-05 深夜: CLIP/4KLSDB/稀疏类抓取 进展
- 修正: NKUSR8K 无夜景(CLIP 确认 night_building=0); tag_categories 夜景仅允许文件名关键词, 不再按暗度推断
- CLIP(openai/clip-vit-base-patch32, CPU, transformers5.x 需 .pooler_output) 打标 NKUSR8K 729:
  skyscraper 204 / plant 354 / residential 63 / other_building 41 / storefront 22 / mall 21 / city_view 5, reject 19
- 分类升级为 8 类: night_building / skyscraper / storefront(店铺门牌) / mall(商场外拍) / plant /
  residential / city_view / other_building (tools: clip_filter.py, tag_categories.py)
- 4KLSDB 抽取管线落地(全部本地可跑):
  klsdb_index.py(206 分片 id->shard/rg 索引, ~27min) + klsdb_extract.py(rank 按 caption 评分排序 + extract 按 row-group 拉 hr)
  第一批: 18 row-group, 11.6GB 流量 -> 1060 张 4K 原始 -> clean 802 张(data/clean/4KLSDB_b1)
- 稀疏类原图 URL 抓取(fetch_klsdb_urls.py, 成功率 ~96%): night_building 575 / mall 355 /
  storefront 501 / residential 495 / skyscraper 486 -> 后台逐类清洗中(data/clean/4KLSDB_url/<cls>)
- DRealSR: 用户给的 GDrive 文件夹(1tP5m4k1...)只含 Test_x2/x3/x4.zip(测试集); 训练集在百度网盘 osiy(需登录)
- SSDLite: 本地 Windows torchvision CPU wheel ABI 不兼容(2.7/2.6+cpu 均报 torchvision::nms), 已放弃本地;
  方案: 本地用 CLIP; SSDLite person/物过滤代码留到 A100(Linux+torchvision 正常) 或后续换环境再启用
- 待办: URL 清洗完成 -> CLIP 复核(去 people/indoor/other) -> 全池 pHash 去重 -> 合并 clean_all(带源前缀)
  -> 8 类平衡报表 -> sample_review 拼图人工复核 -> build_patches(>=? 目标 5000-7000 HR 源后 50k+ patch)
  -> 再跑 4KLSDB b2/b3 补量到总池 5000-7000


## 2026-09-06 凌晨: LIU4K v2 引入 + 策略更新
- 4KLSDB 政策: 建筑/风景/花草均可入池(增强鲁棒), 夜景适量即可(不堆量)
- LIU4K v2 (GDrive 1FtVQtY2t_ecuy_gzJqZ-CatqrJBAdq_d): 4 组多段zip(Animal/Building/Street/Mountain),
  只取 Building/Street/Mountain; Building = 400 张高分辨率 PNG(3992x2242~6208x4139, Pexels 建筑图, 10.2GB)
  解压用 NVIDIA App 7-Zip 22.01(自带 7z.exe); 旧 7za 9.20 不支持 spanned zip
- DRealSR: 放弃训练(用户确认); SSDLite: 取消(用户确认); 过滤以 CLIP 为主
- URL 稀疏类清洗后: night_building 409 / storefront 446 / mall 248 / residential 339 / skyscraper 331 (共 1773)
- 4KLSDB b1 CLIP 后 accept 604 (plant172/other_building171/residential124/city_view66/storefront35/skyscraper29/mall6/night1), reject 198
- NKUSR8K CLIP accept 710 (skyscraper204/plant354/residential63/other_building41/storefront22/mall21/city_view5), reject 19
- 新工具: merge_reports.py(多源合并/剔 reject/去重) + download_gdrive_parts.py(分卷断点下载)

## 2026-09-06 凌晨2: 四源合并池(CLIP accept + URL文件夹标签 + reject剔除)
- 池: logs/cat_pool_all.json, 共 3072 张清洗后 HR 原图
  night_building 332 / skyscraper 575 / storefront 445 / mall 252 / plant 540 / residential 526 /
  city_view 102 / other_building 300
- 人工复核拼图: data/review/pool_all/{8类}.jpg (每类 20 张)
- LIU4K Building: 400 PNG(10.2GB) -> clean 320 -> jpg(clean_all/LIU4K) -> CLIP accept 235(reject 85 室内/人像)
- 剩余待补: city_view(102, 目标>=400), mall(252); 总池 3072 -> 目标 5000-7000
- 下一批: 4KLSDB b2/b3(城景/商场/其他建筑加量) + LIU4K Street/Mountain(城市街道/山地风景)

## 2026-09-06 凌晨: 收尾流水线启动(finalize_all.ps1 后台自动链)
- 补量URL抓取: plant 790+383 / city_view 398+240 / other_building 554+259 / storefront 129 / mall 160 (raw)
  (skyscraper/residential 候选枯竭未新增; fetch 去重由 jsonl 断点保证)
- 4KLSDB b2 事故: klsdb_extract 未跳过已用 row-group -> b2 与 b1 完全重复(802/802), 已删 b2 目录;
  已修复 extract 记录 used_rgs.json, 后续 b3 不再重复
- clean_url_vol.ps1 正清洗 5 类 raw(plant/city_view/other_building/storefront/mall)
- finalize_all.ps1(等清洗完): clip_url3(全URL目录) -> merge_reports(cat_pool_final, id去重)
  -> split_pool(70源val) -> build_patches2(train 45k, val 560) -> build_manifest(train/val + RealSR对)
- 产出: logs/cat_pool_final.json / cat_train.json / cat_val.json / data/patches / data/patches_val /
  data/manifest_train.json / data/manifest_val.json / data/README.md