Blame for preference_refinement/README.md

# Preference Refinement Pipeline

本文档记录当前 RelationAdapter refinement 的实际数据、训练方法、实验结果和下一轮扩展方案。文中将原始 text-decoupled LoRA 简称为 **TD**，新加入的 refinement LoRA 简称为 **RF**。

## 1. 当前目标

给定同一关系编辑条件下的 best--worst pair，训练一个轻量 RF LoRA，使模型：

1. 相比冻结 TD 更偏好 best、排斥真实生成出的 worst；
2. 保持 TD 已有的 source identity、构图、纹理和清晰度；
3. 推理时仍然只运行一个合并后的模型，不增加 diffusion steps；
4. 能够与 TD baseline 使用相同 case、相同 seed 做严格前后对比。

## 2. TD baseline

当前 1024、无文本 TD checkpoint：

```text
data/refinement_assets/models/Orannue_resubmit/
  relation252k_rope_1024_no_text5/iteration-40000.safetensors
```

训练 RF 时：

```text
frozen FLUX.1-Kontext-dev backbone
  + merged and frozen TD LoRA
  + zero-initialized trainable RF LoRA
```

关闭 RF adapter 时模型严格退化为 TD；只有 RF LoRA 参数参与反向传播。

## 3. 当前 candidate 数据

### 3.1 Condition 采样

Relation252K 官方训练划分包含 220 个 edit group。当前每个 group 随机选取 5 个不同的 demo/query 组合：

```text
220 groups x 5 conditions = 1,100 conditions
```

一个 condition 包含：

```text
cond1 + cond2 + source + GT target
```

构建脚本：

```text
DiffSynth-Studio/tools/refinement/build_relation252k_refinement_multi.py
```

### 3.2 TD 自采样

每个 condition 使用 TD 生成 5 个固定 seed：

```text
1,100 conditions x 5 seeds = 5,500 TD candidates
```

合并后的 manifest：

```text
data/refinement_candidates/rope1024_refinement_1100_5seed/generation.json
```

所有候选均为空文本推理。生成图是 2x2 grid，真正 result 位于右下角；排序、构建训练 pair 和评估时都只裁剪右下角。

## 4. Best--worst 排序

### 4.1 候选集合

对于每个 condition：

- best 从 `GT + 5 TD candidates` 中选择；
- worst 只从 5 个 TD candidates 中选择；
- GT 同时作为一个候选和 GT-direction scoring reference；
- worst 不允许选择 GT。

### 4.2 自动指标

CLIP condition edit direction：

$$
d_{\mathrm{cond}}
=\operatorname{norm}(E_{\mathrm{CLIP}}(\mathrm{cond2})-E_{\mathrm{CLIP}}(\mathrm{cond1})),
$$

$$
d_{\mathrm{result}}
=\operatorname{norm}(E_{\mathrm{CLIP}}(y)-E_{\mathrm{CLIP}}(\mathrm{source})),
$$

$$
s_{\mathrm{demo}}=d_{\mathrm{result}}^T d_{\mathrm{cond}}.
$$

另外计算：

- CLIP GT direction：candidate 相对 source 的变化是否接近 GT 相对 source 的变化；
- DINO preservation：candidate 与 source 的结构/身份相似度。

三个分数先在同一个 condition 的候选内部转换为 rank，再组合：

$$
s=0.55s_{\mathrm{demo-rank}}
 +0.30s_{\mathrm{GT-rank}}
 +0.15s_{\mathrm{preservation-rank}}.
$$

### 4.3 当前自动通过条件

一个 pair 被称为自动高置信，仅表示它不需要进入当前 review queue，必须同时满足：

1. 三个独立指标中至少两个同意所选 best；
2. 三个独立指标中至少两个同意所选 worst；
3. best 与 worst 的 combined rank margin 不小于 0.25。

这不是人工正确性保证，也不应在论文中描述为人工标注。

当前结果：

| 项目 | 数量 |
|---|---:|
| 全部 conditions | 1,100 |
| 自动通过 pairs | 512 |
| 进入 review queue | 588 |
| 自动通过 pair 覆盖的 groups | 198 / 220 |
| GT best + TD worst | 498 |
| TD best + TD worst | 14 |

训练 pair manifest：

```text
data/refinement_pairs/rope1024_refinement_1100_highconf/residual_pairs.json
```

## 5. 旧 residual RF

旧方法在同一个 noised worst latent 上回归固定 latent residual：

$$
\Delta v
=v_{\mathrm{TD+RF}}-\operatorname{sg}(v_{\mathrm{TD}}),
$$

$$
\mathcal L_{\mathrm{residual}}
=\left\|\Delta v-\gamma(z_0^w-z_0^b)\right\|_2^2.
$$

512-pair 实验配置：

```text
learning rate: 2e-5
steps: 1,000
RF rank: 32
residual strength: 0.2
anchor: 0
```

旧方法能够增强部分编辑，但由于 498/512 的 best 是 GT，`worst - GT` latent 差包含编辑以外的纹理、光照、构图和随机生成差异。直接 MSE 回归这些完整差异会产生平均化和模糊。

旧 RF 的较好推理折中为 `step 1000 / RF scale 0.5`：

| 指标 | 相对 TD 的变化 |
|---|---:|
| combined edit score | +0.0128 |
| DINO preservation | -0.0237 |
| edge sharpness | -13.8% |

因此仅降低 RF inference scale 可以减轻模糊，但不能解决旧 objective 的根本问题。

## 6. 当前 preference RF

训练入口：

```text
DiffSynth-Studio/examples/flux/model_training/
  train_finetune_preference_refinement_rope1024.py
```

### 6.1 Same-noise pair

对同一个 best--worst pair，采样相同 timestep 和相同 noise：

$$
z_t^b=(1-\sigma_t)z_0^b+\sigma_t\epsilon,
$$

$$
z_t^w=(1-\sigma_t)z_0^w+\sigma_t\epsilon.
$$

分别计算 TD+RF 和冻结 TD 对 best/worst 的 flow-matching MSE：

$$
\ell_\theta^b,\ \ell_\theta^w,
\qquad
\ell_{\mathrm{TD}}^b,\ \ell_{\mathrm{TD}}^w.
$$

相对 preference margin 为：

$$
m=
(\ell_\theta^w-\ell_\theta^b)
-(\ell_{\mathrm{TD}}^w-\ell_{\mathrm{TD}}^b).
$$

Preference loss：

$$
\mathcal L_{\mathrm{pref}}
=-\log\sigma\left(\frac{\beta}{2}w_t m\right).
$$

它只要求 TD+RF 相比冻结 TD 更偏好 best，不要求输出逐像素或逐 latent 拟合 GT。

### 6.2 TD anchor

对 best 和 worst 两条输入都约束 RF 不要过度偏离 TD：

$$
\mathcal L_{\mathrm{anchor}}
=\frac{w_t}{2}
\left(
\|v_\theta^b-v_{\mathrm{TD}}^b\|_2^2
+\|v_\theta^w-v_{\mathrm{TD}}^w\|_2^2
\right).
$$

当前总 loss：

$$
\boxed{
\mathcal L
=\mathcal L_{\mathrm{pref}}
+\lambda_{\mathrm{anchor}}\mathcal L_{\mathrm{anchor}}
}
$$

代码支持额外的 best SFT loss，但当前设置为 0，避免再次引入 GT 整图回归：

```text
preference_best_weight = 0
```

### 6.3 已运行配置

```text
pairs: 512
learning rate: 5e-6
beta: 1.0
anchor weight: 0.05
best SFT weight: 0
RF rank: 32
GPUs: 2
training steps: 500
checkpoint interval: 100
```

训练 Job `12369888` 已完成。单卡真实 loss smoke 的峰值显存为 42.56 GiB；正式训练只保存 RF LoRA。

## 7. 当前 preference RF 结果

相同 seed 的 10-case 初步验证结果：

| 方法 | combined edit | DINO preservation | edge sharpness |
|---|---:|---:|---:|
| 旧 residual RF 最佳点 | +0.0128 | -0.0237 | -13.8% |
| Preference RF step 200 | +0.0285 | -0.0140 | +9.5% |
| Preference RF step 300 | +0.0429 | -0.0347 | +27.7% |

当前选择 **step 200**：

- 编辑增益高于旧 RF；
- source preservation 损失小于旧 RF；
- 没有旧 residual MSE 的整体模糊；
- step 300 开始明显变得激进；
- step 400--500 出现高频描边和崩坏，不能使用。

这说明 preference objective 有效，但当前 `beta=1.0 / anchor=0.05` 的稳定训练窗口较窄，必须 early stop。下一轮可尝试降低 beta 或提高 anchor，使 200 steps 之后不再快速发散。

HF 前后对比：

```text
https://huggingface.co/Orannue/resubmit/tree/main/
rope1024_preference_rf_beta1_anchor005_step200_before_after
```

## 8. 当前 512 pairs 是否足够

### 8.1 足够的部分

512 pairs 已足够用于：

- 验证 preference loss 能否正常工作；
- 对比旧 residual MSE 与 preference RF；
- 发现合理的 checkpoint 和超参数趋势；
- 证明 hard negative 对编辑增强有训练信号。

### 8.2 不足的部分

512 pairs 还不足以作为最终正式 refinement 数据：

1. 只覆盖 198/220 groups，22 个 edit group 没有自动通过 pair；
2. 平均每个已覆盖 group 只有约 2.6 pairs；
3. 498/512 的 best 是 GT，positive 类型过于单一；
4. 当前正式前后评估只有 10 cases，且仅来自排序后的前两个 edit group；
5. 自动指标同时参与 pair 选择和当前模型选择，存在 metric overfitting 风险；
6. 588 个 review cases 尚未利用，其中可能包含大量有效 hard negatives。

因此当前结果应称为 **method validation**，不能直接作为最终论文性能结论。

## 9. 推荐的数据扩展顺序

### 9.1 第一优先级：复核现有 588 cases

先对 review queue 做人工或独立视觉 reviewer 复核，而不是立即重新生成全部数据：

- 确认 source identity 是否保持；
- 确认 cond1--cond2 编辑是否在 result 中出现；
- 确认 worst 是否确实是语义失败，而不只是低清晰度；
- 保留具有明确错误模式的 hard negative；
- 拒绝仅因自动指标噪声被选中的 pair。

如果能从 588 cases 中恢复一半，训练集可从 512 增加到约 800 pairs，且无需额外生成成本。

### 9.2 第二优先级：每个现有 condition 增加 seed

当前每个 condition 只有 5 个 TD samples。建议追加 3 个 seed：

```text
1,100 conditions x (5 existing + 3 new) = 8,800 candidates
```

相对当前只需新增：

```text
1,100 x 3 = 3,300 images
```

增加同一 condition 下的 seed 比立即增加 condition 更适合当前目标，因为 preference RF 的主要训练信号来自 hard negative。更多 seed 可以提高找到真实失败样本的概率。

但不能只按当前 CLIP/DINO 组合分数机械选择最差图；候选越多，越容易选到指标 adversarial artifact，因此必须结合视觉 review。

### 9.3 第三优先级：补齐 group 覆盖

针对当前没有自动通过 pair 的 22 个 groups，定向增加 conditions 和 seeds，直到每个 group 至少有 3 个确认可用 pairs。

全 220 groups 的最低平衡目标：

```text
220 groups x 3 accepted pairs = 660 balanced pairs
```

正式训练更建议达到：

```text
1,000--1,500 reviewed or independently verified pairs
```

这是当前项目的工程目标，不是通用理论阈值。训练时还应进行 group-balanced sampling，避免候选多的 group 主导 RF。

### 9.4 第四优先级：增加 conditions

只有在复核 588 cases、追加 seed 和补齐 22 groups 后仍缺少覆盖时，再把每个 group 的 condition 数从 5 提高到 8--10。

直接使用 10 conditions/group、5 seeds 会产生：

```text
220 x 10 x 5 = 11,000 candidates
```

这能扩展 source/query 多样性，但成本高于先给现有 conditions 添加 seed。

## 10. 推荐下一轮正式方案

### 数据

1. 复核 588 review cases；
2. 对 1,100 conditions 追加 3 seeds；
3. 对缺失的 22 groups 定向补样；
4. 构建约 1,000--1,500 个高质量、group-balanced pairs；
5. 单独保留每个 group 的 held-out test case，不参与 pair 选择。

### 训练

建议以当前 step-200 结果为参照，重新从 zero-init RF 开始小规模参数消融：

| 实验 | beta | anchor | 目的 |
|---|---:|---:|---|
| A | 0.5 | 0.05 | 减弱 preference 更新 |
| B | 1.0 | 0.10 | 增强 TD 保持 |
| C | 0.5 | 0.10 | 最保守组合 |

每个实验先训练 300 steps，每 50 steps 保存。只有在 50 个以上、跨 group 的 held-out cases 上确认稳定后，再扩大训练步数。

### 评估

至少同时报告：

- CLIP condition directional score；
- GT directional score；
- DINO source preservation；
- 清晰度/高频 artifact 检查；
- 独立 GPT 或人工视觉评分；
- 相同 seed 的 TD vs TD+RF 前后对比。

模型选择不能只依赖构建 best--worst 数据时使用的同一套自动指标。

## 11. 结论

当前 512-pair preference RF 已证明：相对旧 residual MSE，pairwise preference + TD anchor 能获得更强的编辑增益、更小的 source 损失，并避免整体模糊。

但 512 pairs 和 10-case 验证仍不足以支撑最终模型结论。下一步最有价值的工作不是继续增加训练步数，而是：

1. 复核现有 588 cases；
2. 为当前 1,100 conditions 增加 seed，获得更可靠的 hard negatives；
3. 补齐 22 个缺失 groups；
4. 在更大、跨 group 的 held-out 集合上选择 beta、anchor 和 early-stop step。