# PR #44293 完整报告

- 仓库：`vllm-project/vllm`
- 标题：Nit Changes in Tiered KV Offload
- 合并时间：2026-06-03 12:53
- 原文链接：http://prhub.com.cn/vllm-project/vllm/pull/44293

---

## 执行摘要

本 PR 为 `FileSystemTierManager` 的类文档添加了跨进程 KV 缓存共享的配置说明，同时将两个测试文件移动到更合适的目录。变更极小（8 行新增，0 行删除），无逻辑修改，属于文档改进与代码结构清理。

## 功能与动机

根据 PR body 描述，目的是为 `FileSystemTierManager` 添加文档，告知用户如何启用 KV 缓存的跨进程共享。核心是说明：当多个 vLLM 实例通过共享 PVC 使用同一 `root_dir` 时，必须设置环境变量 `PYTHONHASHSEED` 为固定值（例如 `"0"`），否则每个进程会随机初始化块内容哈希种子 `NONE_HASH`，导致相同 token 内容产生不同的块文件名，从而无法共享。

## 实现拆解

1. **文档补充**：在 `vllm/v1/kv_offload/tiering/fs/manager.py` 的 `FileSystemTierManager` 类文档字符串末尾新增了“Cross-process sharing”段落，清晰解释了跨进程共享的条件和原因。
2. **测试文件移动**：将 `tests/v1/kv_offload/test_fs_tier.py` 和 `tests/v1/kv_offload/test_tiering_offloading.py` 分别移动到 `tests/v1/kv_offload/tiering/` 子目录下，保持与源码模块 `vllm/v1/kv_offload/tiering/fs/` 一致的目录结构。文件内容无任何修改。

### 以下为 `FileSystemTierManager` 类文档的关键部分，新增内容已包含在内：

```python
class FileSystemTierManager(SecondaryTierManager):
    """
    Pure-Python disk-backed secondary tier.

    Read-priority threads service load jobs preferentially; write-priority
    threads service store jobs preferentially. Both groups can drain either
    queue, so neither starves.

    submit_store / submit_load are non-blocking: they enqueue tasks and return.
    get_finished_jobs() polls job completion and returns completed JobResults.

    Cross-process sharing:
        In order to enable KV cache sharing between multiple vLLM instances
        using the same ``root_dir`` (e.g., via a shared PVC) the environment
        variable ``PYTHONHASHSEED`` must be set to the same fixed value
        (e.g., "0") on all instances. Without this, each process initializes
        ``NONE_HASH`` (the chain-hash seed for block content hashes) with
        random bytes, producing different block filenames for identical token
        content.
    """

```

## 评论区精华

无 review 评论。审核者 njhill 直接批准了该 PR。

## 风险与影响

- **风险**：极低。仅文档和文件移动，无逻辑变更。测试文件移动已被验证，CI 通过。
- **影响**：影响范围小。对于使用 `FileSystemTierManager` 进行跨进程 KV 缓存的用户，提供了重要的配置指引；测试目录结构更加一致，便于后续维护。

## 关联脉络

无直接关联的 PR 或 Issue。本 PR 是独立的文档改进和清理工作。