Skip to content

[None][fix] disagg: derive KV transfer layer offset from physical slot order - #16429

Merged
lowsfer merged 2 commits into
NVIDIA:mainfrom
lowsfer:disagg-kv-map-physical-order
Jul 18, 2026
Merged

[None][fix] disagg: derive KV transfer layer offset from physical slot order#16429
lowsfer merged 2 commits into
NVIDIA:mainfrom
lowsfer:disagg-kv-map-physical-order

Conversation

@lowsfer

@lowsfer lowsfer commented Jul 15, 2026

Copy link
Copy Markdown
Member

Description

Follow-up to a review comment on #16218 (discussion).

PeerRegistrar.get_kv_map() sorted the pool's global layer ids by global_layer_id before computing each layer's slot offset, relying on the convention that KV-cache managers assign global_layer_id monotonically with the layer's byte offset in the slot. That discards the physical-offset order that get_pool_view_global_layer_ids() already recovers from the V2 pool-view buffer_entries. For a non-monotonic layout (e.g. physical order [5, 3]), a layer is mapped to the wrong slot and the transfer copies the wrong KV bytes.

This was not a regression — the sorted() and the monotonicity assumption pre-existed on main, and under that assumption sorted order equals physical order — so it is fixed here in a dedicated PR rather than in the test-prep change #16218.

What changed

  • Use physical slot order directly in get_kv_map(), dropping sorted() on both branches:
    • INDEXED: get_pool_view_global_layer_ids() — ordered by buffer_entries offsets (the V2 pool-view layout).
    • FLAT: get_global_layer_ids()local_layers packing order, which is the physical order for FLAT pools (previously also wrongly sorted()).
  • Anchor the transfer on the physically-first overlapping layer so .index() yields the true slot offset.
  • Replace the implicit monotonicity invariant with an explicit check: the shared layers must form an aligned, contiguous run of physical slots on both peers; otherwise raise ValueError instead of silently transferring the wrong bytes.
  • Updated the comment/docstring accordingly.

Tests

  • test_peer_registrar_get_kv_map_uses_physical_offset_order: non-monotonic layout [5, 3]; asserts the mapper uses the physical slot offset (1), which the old sorted path got wrong.
  • test_peer_registrar_get_kv_map_rejects_non_contiguous_overlap: verifies the new contiguity guard raises.

Test Coverage

tests/unittest/disaggregated/test_peer.py

PR Checklist

  • Commit message follows the guidelines
  • New/existing tests cover these changes
  • Documentation change (n/a)

Summary by CodeRabbit

  • Bug Fixes

    • Improved KV-cache transfer mapping to follow physical buffer slot order.
    • Added validation to reject misaligned or non-contiguous layer overlaps, preventing invalid transfer mappings.
  • Tests

    • Added coverage for physical slot ordering and invalid contiguous-run alignment scenarios.

@lowsfer
lowsfer requested a review from a team as a code owner July 15, 2026 13:31
@coderabbitai

coderabbitai Bot commented Jul 15, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

PeerRegistrar.get_kv_map now derives offsets from physical KV-cache layout order, validates aligned contiguous overlap runs, and adds tests for physical offset selection and invalid overlap rejection.

Changes

KV map alignment

Layer / File(s) Summary
Physical-order KV map alignment
tensorrt_llm/_torch/disaggregation/native/peer.py
Uses layout-derived layer ordering to compute peer offsets and validates that overlapping layers form matching contiguous runs.
Alignment behavior tests
tests/unittest/disaggregated/test_peer.py
Verifies physical-slot offsets and raises an error for non-contiguous overlap.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: chienchunhung, tabrizian

🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
Title check ✅ Passed The title is concise, specific, and matches the main change to KV transfer offset derivation.
Description check ✅ Passed The description covers the issue, solution, tests, and checklist in the required template structure.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests

Comment @coderabbitai help to get the list of available commands.

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (1)
tests/unittest/disaggregated/test_peer.py (1)

407-456: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Coverage needs follow-up for the other new branches.

Current coverage is insufficient: it only tests INDEXED ordering and local-side non-contiguity. Please add:

  • test_peer_registrar_get_kv_map_uses_physical_offset_order_flat
  • test_peer_registrar_get_kv_map_rejects_peer_non_contiguous_overlap or a reordered peer run case

Run pytest tests/unittest/disaggregated/test_peer.py -k get_kv_map.

As per path instructions, provide concrete test names and state whether TensorRT-LLM test coverage is sufficient.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@tests/unittest/disaggregated/test_peer.py` around lines 407 - 456, Add tests
named test_peer_registrar_get_kv_map_uses_physical_offset_order_flat and
test_peer_registrar_get_kv_map_rejects_peer_non_contiguous_overlap, covering
flat physical ordering and a peer-side non-contiguous or reordered overlap
rejection; keep the existing INDEXED and local-side coverage intact. Run pytest
tests/unittest/disaggregated/test_peer.py -k get_kv_map and state whether
TensorRT-LLM test coverage is sufficient.

Source: Path instructions

🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@tests/unittest/disaggregated/test_peer.py`:
- Line 407: Add return annotations of -> None to both test functions,
test_peer_registrar_get_kv_map_uses_physical_offset_order and the additional
test at the referenced location, without changing their behavior.

---

Nitpick comments:
In `@tests/unittest/disaggregated/test_peer.py`:
- Around line 407-456: Add tests named
test_peer_registrar_get_kv_map_uses_physical_offset_order_flat and
test_peer_registrar_get_kv_map_rejects_peer_non_contiguous_overlap, covering
flat physical ordering and a peer-side non-contiguous or reordered overlap
rejection; keep the existing INDEXED and local-side coverage intact. Run pytest
tests/unittest/disaggregated/test_peer.py -k get_kv_map and state whether
TensorRT-LLM test coverage is sufficient.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Enterprise

Run ID: fb2df76a-e75e-472f-97f6-70571f7452cf

📥 Commits

Reviewing files that changed from the base of the PR and between 0846183 and cb50d56.

📒 Files selected for processing (2)
  • tensorrt_llm/_torch/disaggregation/native/peer.py
  • tests/unittest/disaggregated/test_peer.py

Comment thread tests/unittest/disaggregated/test_peer.py
@lowsfer
lowsfer requested a review from Shixiaowei02 July 15, 2026 13:51
@lowsfer

lowsfer commented Jul 15, 2026

Copy link
Copy Markdown
Member Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59456 [ run ] triggered by Bot. Commit: cb50d56 Link to invocation

@lowsfer

lowsfer commented Jul 15, 2026

Copy link
Copy Markdown
Member Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59487 [ run ] triggered by Bot. Commit: cb50d56 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59456 [ run ] completed with state ABORTED. Commit: cb50d56

Link to invocation

Comment thread tensorrt_llm/_torch/disaggregation/native/peer.py Outdated
@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59487 [ run ] completed with state SUCCESS. Commit: cb50d56
/LLM/main/L0_MergeRequest_PR pipeline #47946 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

  • Please check the failed tests and fix your PR
  • If you cannot view the failures, ask the CI triggerer to share details
  • Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

@lowsfer

lowsfer commented Jul 16, 2026

Copy link
Copy Markdown
Member Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59638 [ run ] triggered by Bot. Commit: cb50d56 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59638 [ run ] completed with state SUCCESS. Commit: cb50d56
/LLM/main/L0_MergeRequest_PR pipeline #48075 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

  • Please check the failed tests and fix your PR
  • If you cannot view the failures, ask the CI triggerer to share details
  • Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

@lowsfer

lowsfer commented Jul 16, 2026

Copy link
Copy Markdown
Member Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59776 [ run ] triggered by Bot. Commit: cb50d56 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59776 [ run ] completed with state SUCCESS. Commit: cb50d56
/LLM/main/L0_MergeRequest_PR pipeline #48201 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

  • Please check the failed tests and fix your PR
  • If you cannot view the failures, ask the CI triggerer to share details
  • Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

lowsfer added 2 commits July 17, 2026 10:57
…t order

PeerRegistrar.get_kv_map() sorted the pool's global layer ids before computing
each layer's slot offset, relying on the convention that managers assign
global_layer_id monotonically with the layer's byte offset. That discards the
physical-offset order recovered by get_pool_view_global_layer_ids() and, for a
non-monotonic layout, maps a layer to the wrong slot and transfers the wrong
KV bytes.

Use the physical slot order directly (buffer_entries offsets for INDEXED pools,
local_layers packing order for FLAT pools) so a layer's index is its slot
offset, and anchor the transfer on the physically-first overlapping layer.
Replace the implicit monotonicity invariant with an explicit check that the
shared layers form an aligned contiguous slot run on both peers, raising
instead of silently corrupting the transfer.

Add unit tests covering a non-monotonic layout and the non-contiguous-overlap
rejection.

Signed-off-by: Yao Yao <lowsfer@users.noreply.github.com>
Address review nit: branch explicitly on MapperKind.INDEXED instead of
relying on else, and raise ValueError for unexpected mapper kinds.

Signed-off-by: Yao Yao <lowsfer@users.noreply.github.com>
@lowsfer
lowsfer force-pushed the disagg-kv-map-physical-order branch from cb50d56 to d7c7030 Compare July 17, 2026 11:03
@lowsfer

lowsfer commented Jul 17, 2026

Copy link
Copy Markdown
Member Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59968 [ run ] triggered by Bot. Commit: d7c7030 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59968 [ run ] completed with state FAILURE. Commit: d7c7030
/LLM/main/L0_MergeRequest_PR pipeline #48362 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

  • Please check the failed tests and fix your PR
  • If you cannot view the failures, ask the CI triggerer to share details
  • Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

@lowsfer

lowsfer commented Jul 17, 2026

Copy link
Copy Markdown
Member Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59999 [ run ] triggered by Bot. Commit: d7c7030 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59999 [ run ] completed with state FAILURE. Commit: d7c7030
/LLM/main/L0_MergeRequest_PR pipeline #48392 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

  • Please check the failed tests and fix your PR
  • If you cannot view the failures, ask the CI triggerer to share details
  • Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

@lowsfer

lowsfer commented Jul 17, 2026

Copy link
Copy Markdown
Member Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #60027 [ run ] triggered by Bot. Commit: d7c7030 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #60027 [ run ] completed with state FAILURE. Commit: d7c7030
/LLM/main/L0_MergeRequest_PR pipeline #48416 completed with status: 'FAILURE'

CI Report

⚠️ Action Required:

  • Please check the failed tests and fix your PR
  • If you cannot view the failures, ask the CI triggerer to share details
  • Once fixed, request an NVIDIA team member to trigger CI again

CI Agent Failure Analysis

Link to invocation

@lowsfer

lowsfer commented Jul 18, 2026

Copy link
Copy Markdown
Member Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #60086 [ run ] triggered by Bot. Commit: d7c7030 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #60086 [ run ] completed with state SUCCESS. Commit: d7c7030
/LLM/main/L0_MergeRequest_PR pipeline #48473 completed with status: 'SUCCESS'

CI Report

Link to invocation

@lowsfer
lowsfer merged commit 682c38d into NVIDIA:main Jul 18, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants