# KV-prune 与上游 vLLM 的集成说明

本文说明：**剪枝/压缩（Compactor）功能**在「官网 vLLM 主仓库」里改动了哪些位置、是否只有少量文件、以及随 vLLM 版本升级时如何预期合并成本。

## 1. 是否「仅仅」改了少数几个脚本？

**核心运行时接线**确实集中在少数几个**非** `vllm/kvprune/` 下的文件；功能主体在 `vllm/kvprune/` 包内独立维护。

| 路径 | 作用简述 |
|------|-----------|
| `vllm/env_override.py` | 在 `import vllm` 最早阶段设置与 kvprune 相关的默认环境变量（如 v1 多进程默认、压缩默认开关、可选释放 v1 KV 等）。 |
| `vllm/__init__.py` | 对外导出 `CompressionParams`（懒加载至 `vllm.kvprune.integration.compression_params`）。 |
| `vllm/entrypoints/llm.py` | `kvprune_compression` 参数、`generate(..., compression=...)`、v1 `enforce_eager` / `num_gpu_blocks_override` 策略、懒加载 compactor、委托 `compressed_generate`。 |
| `vllm/v1/worker/gpu_worker.py` | `kvprune_v1_compressed_generate`：供 `collective_rpc` 调用的 TP 多卡压缩生成入口。 |
| `tests/conftest.py` | 测试在导入 vLLM 前覆盖部分 `VLLM_KVPRUNE_*` 默认值，避免全量测试默认走压缩路径。 |
| `vllm\vllm\envs.py` | envs.py 中对 VLLM_KVPRUNE_* 的集中注册  |

**此外（可选/示例，非引擎必需）：**

- `examples/offline_inference/` 下若干 `*kvprune*` 示例脚本：演示用法，不参与核心引擎加载。

**结论：**  
- **「官网 vLLM 主包」里与 kvprune 强相关的改动，主要就是上表 4 个文件 + 测试根配置**（若把测试也算进「集成面」，共 5 处常见提法）。  
- **算法、Compactor、TP 内嵌 runner 等**均在 `vllm/kvprune/`（及该目录下的 `integration/`）中，与上游 diff 相对隔离。

## 2. 随 vLLM 版本更新，是否「很容易」同步剪枝压缩功能？

**相对容易的部分：**

- **集成面小**：合并冲突主要出现在上述少数文件，而不是遍布整个 executor / attention / model 层。
- **逻辑内聚**：大量代码在 `vllm/kvprune/`，可整体移植或 `git` 三方合并时以子树为主处理。

**仍需人工跟进的点（不能假设「自动无痛」）：**

- **`entrypoints/llm.py` 属于高频变更文件**：上游每次大版本可能重构 `LLM` 构造参数、`generate` 签名或引擎初始化；需要**逐次解决冲突**并回归压缩路径。
- **`v1/worker/gpu_worker.py`** 同样会随 executor / RPC 接口变动；`collective_rpc` 方法名或 worker 基类若有变化，需对齐。
- **`env_override.py`** 若上游调整导入顺序或新增全局默认环境变量，需避免覆盖冲突或行为打架。
- **vLLM v1 内部 API**（如 `worker.get_model()`、`vllm_config` 结构）若变更，`vllm/kvprune/integration/*` 也可能要跟着改——这类改动**不在**「仅 5 个文件」里，但仍是**集成层**维护成本。

**建议同步流程（简版）：**

1. 在新上游 tag 上先合并/应用 `vllm/kvprune/` 目录。  
2. 再手动合并上述 4 个主包文件 + `tests/conftest.py`。  
3. 跑与 kvprune 相关的测试与至少一条离线 `compression` 示例。  
4. 关注发行说明中 `LLM`、`EngineArgs`、`gpu_worker`、多进程默认的破坏性变更。

## 3. 与「深度改内核」方案的区别

当前设计**没有**在 `model_executor` 的统一注意力路径上大规模插入 kvprune 钩子（相关辅助逻辑主要在 `vllm/kvprune` 内部）。因此：

- **上游同步时**，通常不必与 FlashAttention / 每层模型代码逐文件对打；  
- **代价是**：功能边界以「共享权重 + compactor 引擎 + 可选 TP RPC」为主，与「原生 KV 算子级一体化」的改动面不同。

---

## 4. 目录重建说明（与 `compactor-vllm` 对齐）

`vllm/kvprune/` 以 `vllm/compactor-vllm/src/compactor_vllm/` 为算法与内核基线整体迁入（`compactor_vllm` → `vllm.kvprune`），再叠加上游集成层：

- **集成**：`integration/*`（`compressed_generate`、`compactor_shared`、`config_adapter`、`v1_tp_runner`、`weight_tie` 等）仍负责「同 `LLM.generate` 前端、双后端」。
- **TP / 调度**：`core/model_runner.py`、`utils/tp_utils.py`、`utils/tp_collectives.py`、`utils/kv_dist.py` 等保留 vLLM 内嵌 TP 与 `collective_rpc` 路径。
- **三种 attention 模式**：`config/engine_config.py` 的 `KvpruneAttentionSchedule` + `integration/config_adapter.py` 的环境变量解析；`layers/attention.py` + `attention/fa_paged_bridge.py` 实现 `fa_triton` / `pdtriton` / `pdfa`。

临时备份目录 `vllm/kvprune_legacy_save/` 可在确认无误后手动删除。

---

*文档随仓库维护；若集成文件列表有增删，请同步更新本节表格。*
