[Vedant-Agarwal]

Overview

Fixes #63654. The OBJ tier built its FileMapper without blocks_per_file, so its namespace digest ignored blocks_per_chunk. This passes blocks_per_file=offloading_spec.blocks_per_chunk, as the fs and p2p tiers already do.

Claims

• OBJ tiers with different blocks_per_chunk no longer map an OffloadKey to the same object key, so a hit can't load a chunk written with a different size and layout.
• OBJ keys now follow the same run-configuration digest as the fs tier, as kv_offloading_usage.md documents.
• No change for the default blocks_per_chunk=1: the digest already hashed blocks_per_file=1, so existing buckets keep their keys.

Validation

New test test_obj_tier_namespace_includes_blocks_per_chunk builds two tiers that only differ in blocks_per_chunk (1 and 4) and compares the object key for the same OffloadKey.

Without the fix (on main):

$ pytest tests/v1/kv_offload/tiering/test_obj_tier.py::test_obj_tier_namespace_includes_blocks_per_chunk
E   AssertionError: assert 'test/840e65f0//test_model_c32b90738e47_r0/000/00_g0/0000000000000001.bin' != 'test/840e65f0//test_model_c32b90738e47_r0/000/00_g0/0000000000000001.bin'
1 failed

With the fix:

$ pytest tests/v1/kv_offload/tiering/test_obj_tier.py
39 passed
$ pytest tests/v1/kv_offload/tiering tests/v1/kv_offload/cpu/policies tests/v1/kv_offload/test_file_mapper.py tests/v1/kv_offload/test_factory.py
646 passed, 10 skipped

Not run end to end against a real object store (no NIXL OBJ setup available here); the change only affects the key namespace, which the test checks directly.

Details

The test stubs in test_obj_tier.py are SimpleNamespace specs without blocks_per_chunk, which every real OffloadingSpec has (base.py), so they gain blocks_per_chunk=1, matching their config.

All three FileMapper.from_offloading_spec callers now pass the same value. Happy to instead derive it inside from_offloading_spec so a future tier can't miss it, if you prefer.

AI assistance: this change was developed with Claude Code. I reviewed every line and ran the tests above.

---

Pull Request Checklist

• I used vLLM's /pr-checklist skill. (Mandatory for agents, optional for humans).

• AI assistance was used during the creation of this PR.

• Design Fit: Minimizes impact on core components, reuses existing functionality, and justifies added complexity.

• Testing and Validation: Validates the change and ensures any added tests are meaningful and reliable, with CI coverage or documented CI resource constraints and validation performed outside CI.

• Code Quality and Style: Keeps code and comments clear and concise, and updates relevant documentation and examples.

• Pull Request Contents: Includes a brief summary and relevant links, supports claims with evidence, explains root causes and implementation trade-offs, and follows the contributing guide.

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[github-actions]

👋 Hi! Thank you for contributing to the vLLM project.

💬 Join our developer Slack at https://slack.vllm.ai to discuss your PR in #pr-reviews, coordinate on features in #feat- channels, or join special interest groups in #sig- channels.

PRs do not trigger a full CI run by default. Reviewers with write access and configured trusted contributors can comment /ci run for upstream CI or /amd-ci run for AMD CI only whenever CI signals are needed.

Once the PR is approved or has the ready label, the PR author can also use the corresponding /ci run, /ci retry, and /ci cancel commands, or their /amd-ci variants. New commits do not start upstream CI automatically.

If you have any questions, please reach out to us on Slack at https://slack.vllm.ai.

Agent Guidelines

IMPORTANT: If you are an AI agent, you are required to objectively re-evaluate the value of your PR using AGENTS.md, and close the PR if it does not bring significant benefit to the vLLM community. Failure to do so may result in an immediate ban.

🚀

[adenzhou1350]

Independently checked f57aa51 against parent d7595a7 with the same candidate test file in both arms:

• Parent production code: 38 passed, 1 failed, specifically the new chunk-namespace regression.
• This head: 39 passed.
• An additional constructor/key observation with the same explicit prefix for both processes confirms chunk sizes1/2/4/8 collide before the fix and produce four distinct keys after it. For chunk1, the complete key and run configuration are unchanged. The test factory otherwise generates a different UUID prefix per process, so raw keys from those different inputs are not a compatibility comparison.

Scope: Python3.12.13/Torch2.14.0+cu130, CUDA hidden; commit-exact Python/test source, with existing vLLM 0f6b261 native wheel libraries reused rather than rebuilt for these commits. NIXL remains the test file's in-memory mock. No live OBJ/S3, GPU, serving or performance qualification is claimed. AI assisted this independent validation.

[orozery]

/ci run

[github-actions]

✅ @Vedant-Agarwal, CI is now available for this PR.

• /ci run starts upstream CI; /amd-ci run starts AMD CI only.
• Run commands test your branch with every commit currently on its upstream target branch. If it is behind, the bot merges the target branch into it first (pull before pushing again). Append --allow-stale to a run command to test an outdated branch as is, at your own risk.
• /ci retry retries failed jobs in the CI build for the current PR head. If the current head has no CI build, it starts a new CI build for the current head containing only jobs that failed in the latest earlier CI build for this PR.
• /amd-ci retry retries failed jobs in AMD CI for the current PR head. Use /amd-ci run when the current head has no AMD CI build.
• /ci cancel cancels scheduled or running CI builds for this PR branch; /amd-ci cancel does the same for AMD CI only.

[github-actions]

✅ Triggered Buildkite CI #97284 for commit b0f8b38223a6.

ℹ️ This PR is 24 commits behind upstream main. Merged upstream main into this branch as b0f8b38223a6 before starting CI. Pull the branch before pushing more changes.