fix(weighter): joint_update_aware follow-ups to #58

[haolpku]

概述

joint_update_aware（#58）的 follow-up：修几处保持行为不变的问题，并补上 #58 没有更新的文档。

默认超参和 solver 的数学都没有改动 —— β / τ / damping 的取值属于需要实验数据支撑的决定，我把相关观察单独写在 #58 的 review comment 里，留给 @tongruiliu 定夺。

改动

1. 取 embedding 时改用 eval 模式

_extract_embeddings 在 no_grad 前向之前无条件调了 model.train()：

was_training = model.training
model.train()          # ← 打开 dropout
try:
    with torch.no_grad():
        outputs = model(...)
finally:
    if not was_training:
        model.eval()

这一步只为取 embedding，不需要训练模式，而 train 模式会打开 dropout，让余弦 Gram 矩阵 S 和效用向量 s 带上随机噪声。同文件的 _compute_eval_target 用的是 model.eval()，两处不一致。改为 eval 模式并在结束后恢复原模式。

本仓库 lora_dropout 默认 0.0，所以当前默认配置下没有实际影响；一旦用户开启 dropout 就会中。

2. 让 anchor 方向 u 可以真正做平均

_compute_eval_target 只取一个 eval batch 求均值，而 target_batch_size 默认是 1 —— 也就是说默认情况下 u 是单个样本的 embedding，而不是 docstring 里写的"eval 集平均句向量"。（对比 adapt_weighter._refresh_anchors 是遍历整个 eval 集。）

新增 target_num_batches：

• 默认 1，行为与之前完全一致
• 设为 0 则遍历整个 eval 集

另外均值改为按样本数加权（sum / count 而非逐 batch 的 mean 再平均），这样末尾不满的那个 batch 不会被当成一个完整 batch 计权。

3. 移除未使用的 seed

seed 被存进 self.seed 但从未读取，且暴露在 components.yaml 里，会让人以为可以控制该组件的随机性。

4. 补文档

#58 只改了 4 个文件，漏了文档；#54（ADAPT）当时是连 skills/how_to_use.md 一起改的。本 PR 补齐同样的位置：

• skills/how_to_use.md：component_name 的 choices、算法表、examples/ 目录说明、运行命令
• README.md / README-zh.md：Data Reweighting 表格

并说明了这个方法与前面几个 pointwise 方法的区别（在全局 batch 上求解、需要 eval_dataset、beta: 0 / objective_mode: align_only 可退化为 pointwise）。

5. 示例配置补 train_step

train_step 默认为 0，所以原示例实际走的是 num_train_epochs，而 loss.yaml / adapt.yaml 都给了 train_step: 500。补上以保持一致。

验证

不依赖 GPU 的等价性检查，全部通过：

检查	结果
shipped 默认下 _solve_weights 的输出	与改动前逐位相同（max abs diff = 0.0）
target_num_batches=1	复现改动前的单 batch u
target_num_batches=0	得到 eval 全集均值（构造数据上手算可核对）
_extract_embeddings 之后的 model.training	仍为 True
从 shipped components.yaml 经 registry 构造组件	成功

另外 py_compile 通过，两个 yaml 均可 yaml.safe_load，CI 的 import check 项在本地等价验证通过。

🤖 Generated with Claude Code