add indexer-topk capture (V3.2 NSA + infra)

[hnyls2002]

Stacked on #24403. Adds the IndexerTopkCapturer (built on BaseTopkCapturer from #24403) and wires V3.2 NSA models as the first producer.

API

• Server flag: --enable-return-indexer-topk (default off)
• Per-request flag: return_indexer_topk: bool on GenerateReqInput
• Response: meta_info["indexer_topk"] is a base64-encoded int32 tensor of shape (seqlen, num_indexer_layers, index_topk)

Activation gating — model_config.get_num_indexer_layers(hf_text_config):

• NSA models (V3.2 family) → num_hidden_layers (one indexer per transformer layer)
• Other architectures → reads num_indexer_layers directly off hf_text_config, default 0
• 0 → capturer stays None, flag is a logged no-op

Producer wiring (CUDA)

• Indexer.forward_cuda (NSA): _maybe_capture_topk at every return point.
• forward_mla.py skip_topk reuse paths: explicit capture call so the reused layer's slot reflects the indices actually in use.
• NPU path is left for follow-up.

Stack

• Base: lsyin/routed-experts-cleanup (consolidate routed-experts capturer onto reusable base #24403)
• This PR adds only the indexer-specific feature on top — no overlap with the cleanup.

[gemini-code-assist]

Code Review

This pull request implements a framework for capturing and returning top-k indices from indexer layers, including new base classes for device and host caching and integration throughout the request lifecycle. Key feedback includes correcting a redundant method override in IndexerTopkCapturer that bypasses necessary data parallelism logic, fixing an off-by-one error and redundant tensor cloning during sequence indexing, and resolving a type hint inconsistency where the output was incorrectly typed as a list of integers instead of a base64-encoded string. Additionally, recommendations were made to improve code robustness and idiomaticity by replacing assertions with explicit exceptions, substituting magic numbers with named constants, and using native PyTorch methods for tensor metadata.

[fzyzcjy]

LGTM since this looks like naive copy-pasting my code and introduces no risk. EDIT: hear there are some cleanup which are reasonable. I originally wanted to do abstractions but heard @ocss884 was doing refactor on main, thus implemented a naive version to avoid I abstract once and he abstract once and get conflcits

[zianglih]

Hi, have you tried end-to-end runs? I previously implemented similar things #16881 but gave up since this information is larger than kv cache so capturing and returning via endpoint is not practical.

For V3.2, 61 layers x 2048 x 4 bytes = 488kb per token.

For V4, 30 layers x 1024 x 4 bytes = 120kb per compressed token.

[hnyls2002]

/rerun-test test_return_indexer_topk.py test_return_routed_experts.py test_deepseek_v32_indexcache.py

[github-actions]

✅ 8-gpu-h200 (2 tests): View workflow run

cd test/ && python3 registered/8-gpu-models/test_return_indexer_topk.py
cd test/ && python3 registered/8-gpu-models/test_deepseek_v32_indexcache.py

✅ 2-gpu-h100 (1 test): View workflow run

cd test/ && python3 registered/rl/test_return_routed_experts.py

[hnyls2002]

@zianglih Thanks for this feedback. Yeah, the current implementation is limited by the large amount of information in the host cache. The current PR unblocks the dsv4 rebase, and you can use --max-total-tokens to keep the buffer manageable for now. In the future, we can still improve this.

cc @yueming-yuan @fzyzcjy

[hnyls2002]

/rerun-test test_return_indexer_topk.py

[github-actions]

✅ 8-gpu-h200 (1 test): View workflow run

cd test/ && python3 registered/8-gpu-models/test_return_indexer_topk.py

[hnyls2002]

/tag-and-rerun-ci