Skip to content

[None][fix] Make auto host tier sizing rank-aware in KVCacheManagerV2 - #16106

Merged
eopXD merged 4 commits into
NVIDIA:mainfrom
erictsai-nv:fix/kvv2-rank-aware-host-tier
Jul 22, 2026
Merged

[None][fix] Make auto host tier sizing rank-aware in KVCacheManagerV2#16106
eopXD merged 4 commits into
NVIDIA:mainfrom
erictsai-nv:fix/kvv2-rank-aware-host-tier

Conversation

@erictsai-nv

@erictsai-nv erictsai-nv commented Jul 8, 2026

Copy link
Copy Markdown
Contributor

Summary by CodeRabbit

  • Bug Fixes
    • Improved automatic host cache sizing so it better accounts for machines with multiple colocated ranks.
    • Made host memory allocation more reliable by preventing invalid or non-positive quota results.
    • Enhanced runtime logs to show the rank count and memory values used in sizing decisions.

Description

When kv_cache_config.host_cache_size is not set, KVCacheManagerV2
auto-provisions a host cache tier per rank, capped at 50% of the node's
available memory. The cap is computed by each rank independently from the
same node-level reading, so N co-located ranks can collectively reserve up
to N x 50% of node memory.

Observed on GB300 NVL72 (DSR1 FP4 disagg, decode TP16 = 4 nodes x 4 GPUs,
~173 GiB device quota, 975 GiB node RAM): the 4 ranks on each node each
provisioned a 161-173 GiB host tier (~650 GiB total vs ~440 GiB available),
and decode workers were reliably OOM-killed during engine init (6/6
reproductions). The same config with the v1 manager runs fine.

Fix: count ranks sharing the physical node (hostname allgather via the
existing Distributed helper, falling back to mapping.gpus_per_node) and
divide the available-memory cap by that count. Explicitly-set
host_cache_size is unaffected.

Test Coverage

Manually validated on GB300 NVL72 with the previously-failing config:

  • local_ranks=4 detected correctly; host tier reduced to ~55 GiB per
    rank; 4/4 runs completed 43010/43010 requests with zero oom_kill events
    (previously 6/6 OOM).

PR Checklist

Please review the following before submitting your PR:

  • PR description clearly explains what and why. If using CodeRabbit's summary, please make sure it makes sense.

  • PR Follows TRT-LLM CODING GUIDELINES to the best of your knowledge.

  • Test cases are provided for new code paths (see test instructions)

  • If PR introduces API changes, an appropriate PR label is added - either api-compatible or api-breaking. For api-breaking, include BREAKING in the PR title.

  • Any new dependencies have been scanned for license and vulnerabilities

  • CODEOWNERS updated if ownership changes

  • Documentation updated as needed

  • Update tava architecture diagram if there is a significant design change in PR.

  • The reviewers assigned automatically/manually are appropriate for the PR.

  • Please check this after reviewing the above items as appropriate for this PR.

GitHub Bot Help

To see a list of available CI bot commands, please comment /bot help.

@erictsai-nv
erictsai-nv marked this pull request as ready for review July 9, 2026 09:28
@erictsai-nv
erictsai-nv requested a review from a team as a code owner July 9, 2026 09:28
@coderabbitai

coderabbitai Bot commented Jul 9, 2026

Copy link
Copy Markdown
Contributor

Review Change Stack

📝 Walkthrough

Walkthrough

Host-tier quota sizing in KVCacheManagerV2 is updated to be rank-aware within a physical node by determining co-located ranks via hostname allgather with fallback logic, scaling the memory-based quota candidate accordingly, and guarding against non-positive results.

Changes

Host Tier Quota Sizing

Layer / File(s) Summary
Rank-aware quota sizing
tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py
Computes local_ranks via hostname allgather (falling back to mapping.gpus_per_node then 1 on failure), scales the memory-based host quota candidate by mem_available / local_ranks * 0.5, forces host_quota to at least quota when non-positive, and updates the log message to include local_ranks and host memory used.

Estimated code review effort: 2 (Simple) | ~10 minutes

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Title check ✅ Passed The title is specific, concise, and accurately summarizes the main change to KVCacheManagerV2.
Description check ✅ Passed The description includes the required sections and clearly explains the issue, fix, test coverage, and checklist.
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.
✨ 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: 2

🤖 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 `@tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py`:
- Around line 875-887: The fallback in KV cache manager v2 host sizing is
reintroducing the host OOM risk by resetting a nonpositive host_quota back to
quota. In kv_cache_manager_v2.py, update the auto-sizing logic around
candidates/host_quota so that a computed host_quota of 0 or less is left
unchanged and allowed to skip host tier creation via the downstream host tier
check, rather than falling back to the full quota. Keep the existing sizing path
and logger.info context intact, but remove the unsafe quota fallback in the host
quota calculation.
- Around line 844-864: The hostname allgather in kv_cache_manager_v2’s
local_ranks sizing logic is swallowing real distributed failures, which can
leave other ranks stuck in the collective. Update the logic around
Distributed.get(mapping).allgather(socket.gethostname()) so exceptions are not
broadly caught; either let the error propagate or restructure the fallback to
occur only outside the collective. Keep the rank-aware sizing behavior in place,
but avoid masking failures in this block.
🪄 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: 3dd1084e-1f1c-4bec-95bf-000868d376dd

📥 Commits

Reviewing files that changed from the base of the PR and between 8c1b230 and daeb05a.

📒 Files selected for processing (1)
  • tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py

Comment thread tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py Outdated
Comment thread tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py Outdated
@erictsai-nv erictsai-nv removed their assignment Jul 9, 2026
…ric fallback

Signed-off-by: Eric Tsai <ertsai@nvidia.com>

@eopXD eopXD left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

Looks good to me with slight comments.

A unit test coverage would be good to validate your change.

Comment thread tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py Outdated
Comment thread tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py Outdated
…t tests

Signed-off-by: Eric Tsai <ertsai@nvidia.com>
@eopXD

eopXD commented Jul 10, 2026

Copy link
Copy Markdown
Collaborator

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #58669 [ run ] triggered by Bot. Commit: 4d0a2d9 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #58669 [ run ] completed with state SUCCESS. Commit: 4d0a2d9
/LLM/main/L0_MergeRequest_PR pipeline #47255 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

@erictsai-nv

Copy link
Copy Markdown
Contributor Author

/bot run --disable-fail-fast

1 similar comment
@nvpohanh

Copy link
Copy Markdown
Collaborator

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #58870 [ run ] triggered by Bot. Commit: 4d0a2d9 Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #58870 [ run ] completed with state SUCCESS. Commit: 4d0a2d9
/LLM/main/L0_MergeRequest_PR pipeline #47416 completed with status: 'SUCCESS'

CI Report

Link to invocation

@nvpohanh
nvpohanh requested review from a team, lori-ren and tongyuantongyu July 16, 2026 08:50
Comment thread tensorrt_llm/_torch/pyexecutor/kv_cache_manager_v2.py Outdated

@QiJune QiJune left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

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

LGTM

… rank discovery

Signed-off-by: Eric Tsai <ertsai@nvidia.com>
@erictsai-nv

Copy link
Copy Markdown
Contributor Author

/bot run --disable-fail-fast

1 similar comment
@nvpohanh

Copy link
Copy Markdown
Collaborator

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59894 [ run ] triggered by Bot. Commit: e1c95ef Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #59894 [ run ] completed with state FAILURE. Commit: e1c95ef
/LLM/main/L0_MergeRequest_PR pipeline #48295 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

@erictsai-nv

Copy link
Copy Markdown
Contributor Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #60216 [ run ] triggered by Bot. Commit: e1c95ef Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #60216 [ run ] completed with state SUCCESS. Commit: e1c95ef
/LLM/main/L0_MergeRequest_PR pipeline #48583 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

@erictsai-nv

Copy link
Copy Markdown
Contributor Author

/bot run --disable-fail-fast

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #60289 [ run ] triggered by Bot. Commit: e1c95ef Link to invocation

@tensorrt-cicd

Copy link
Copy Markdown
Collaborator

PR_Github #60289 [ run ] completed with state SUCCESS. Commit: e1c95ef
/LLM/main/L0_MergeRequest_PR pipeline #48642 completed with status: 'SUCCESS'

CI Report

Link to invocation

@eopXD
eopXD merged commit 128d020 into NVIDIA:main Jul 22, 2026
7 checks passed
yuanjingx87 pushed a commit to yuanjingx87/TensorRT-LLM that referenced this pull request Jul 26, 2026
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.

5 participants