# PR #6356 完整报告

- 仓库：`verl-project/verl`
- 标题：[fsdp, ckpt] chore: fold drop_tied_target_keys into top-level import
- 合并时间：2026-05-15 10:40
- 原文链接：http://prhub.com.cn/verl-project/verl/pull/6356

---

# 执行摘要

- 一句话：清理 drop_tied_target_keys 导入别名
- 推荐动作：值得快速合并，作为 #6334 的清理。对于关注代码整洁和导入规范的团队，此 PR 展示了如何及时处理 review 反馈中的遗留问题。

# 功能与动机

PR body 说明：这是对 #6334 的跟进，根据 @wuxibin89 的 review 意见。合并后的版本在两个文件中都留下了一个独立的 late-import + 别名块：
```python
from verl.utils.transformers_compat import drop_tied_target_keys as _drop_tied_target_keys

```
这个 `_drop_tied_target_keys` 别名只是向后兼容的脚手架，但该符号在合并树中从未存在过——#6334 之前没有文件公开导出它，因此没有其他代码会导入它。删除别名，将辅助函数折叠到现有的顶层 import 行中，并在调用点使用公开名称，简化了导入结构。

# 实现拆解

1. **verl/model_merger/base_model_merger.py**：
 - 将 `from verl.utils.transformers_compat import get_auto_model_for_vision2seq` 扩展为 `from verl.utils.transformers_compat import drop_tied_target_keys, get_auto_model_for_vision2seq`，直接导入 `drop_tied_target_keys`。
 - 删除 late-import 别名块：`from verl.utils.transformers_compat import drop_tied_target_keys as _drop_tied_target_keys # noqa: E402`。
 - 在 `save_hf_model_and_tokenizer` 方法中将 `_drop_tied_target_keys(...)` 调用改为 `drop_tied_target_keys(...)`。
2. **verl/utils/checkpoint/fsdp_checkpoint_manager.py**：
 - 同样将 import 行扩展为直接导入 `drop_tied_target_keys`。
 - 删除 late-import 别名块。
 - 在 `save_checkpoint` 方法中将 `_drop_tied_target_keys(...)` 调用改为 `drop_tied_target_keys(...)`。

该 PR 不涉及测试、配置或部署配套变更，仅做导入和调用名称的简化。

关键文件：
- `verl/model_merger/base_model_merger.py`（模块 模型合并；类别 source；类型 refactor；符号 drop_tied_target_keys, save_hf_model_and_tokenizer）: 移除了 `_drop_tied_target_keys` 别名导入，改为顶层直接导入 `drop_tied_target_keys`，并在调用点更新。清理了 #6334 遗留的向后兼容脚手架。
- `verl/utils/checkpoint/fsdp_checkpoint_manager.py`（模块 检查点管理；类别 source；类型 refactor；符号 drop_tied_target_keys, FSDPCheckpointManager.save_checkpoint）: 与 base_model_merger.py 相同的清理：移除 late-import 别名块，改为顶层直接导入 `drop_tied_target_keys`，并在 `save_checkpoint` 方法中更新调用。

关键符号：drop_tied_target_keys, save_hf_model_and_tokenizer, save_checkpoint

## 关键源码片段

### `verl/model_merger/base_model_merger.py`

移除了 `_drop_tied_target_keys` 别名导入，改为顶层直接导入 `drop_tied_target_keys`，并在调用点更新。清理了 #6334 遗留的向后兼容脚手架。

```python
# base_model_merger.py (head 版本 )
from verl.utils.transformers_compat import drop_tied_target_keys, get_auto_model_for_vision2seq

class BaseModelMerger:
    def save_hf_model_and_tokenizer(self, state_dict: dict[str, torch.Tensor]):
        # ... 省略中间代码 ...
        # 直接在调用点使用公开名称，不再用 _drop_tied_target_keys 别名
        drop_tied_target_keys(state_dict, model, self.model_config)
        model.save_pretrained(self.config.target_dir, state_dict=state_dict)

```

### `verl/utils/checkpoint/fsdp_checkpoint_manager.py`

与 base_model_merger.py 相同的清理：移除 late-import 别名块，改为顶层直接导入 `drop_tied_target_keys`，并在 `save_checkpoint` 方法中更新调用。

```python
# fsdp_checkpoint_manager.py (head 版本 )
from verl.utils.transformers_compat import drop_tied_target_keys, get_auto_model_for_vision2seq

class FSDPCheckpointManager(BaseCheckpointManager):
    def save_checkpoint(self, ...):
        # ... 省略中间代码 ...
        # 直接在调用点使用公开名称，不再用 _drop_tied_target_keys 别名
        drop_tied_target_keys(state_dict, save_model, model_config)
        save_model.save_pretrained(hf_local_path, state_dict=state_dict)

```

# 评论区精华

无 review 评论。PR 由 @wuxibin89 批准，@gemini-code-assist[bot] 发表了自动化评论表示无反馈。

- 暂无高价值评论线程

# 风险与影响

- 风险：风险极低。变更仅为导入别名和调用名称的简化，不涉及行为改动。但需确认所有依赖这两个模块中 `drop_tied_target_keys` 的调用方都已同步更新。根据 PR body 的 smoke check，`from verl.model_merger.base_model_merger import drop_tied_target_keys` 和 `from verl.utils.checkpoint.fsdp_checkpoint_manager import drop_tied_target_keys` 都能正确解析到同一函数。由于该符号在 #6334 之前从未公开导出，因此不存在外部使用者。
- 影响：影响范围仅限于两个文件中的导入和调用方式，对运行时行为无影响。开发者现在可以直接使用 `drop_tied_target_keys` 而非 `_drop_tied_target_keys` 别名，使代码更清晰。
- 风险标记：无行为变更

# 关联脉络

- PR #6334 [fsdp, ckpt] fix: drop tied target keys before HF save_pretrained: 本 PR 是 #6334 的后续清理，移除了 #6334 中遗留的向后兼容别名。