[Config] Unify indexer cache dtype under attention_config.indexer_kv_dtype

[zyongye]

Purpose

The sparse-attention indexer picked its K-cache dtype through two unrelated knobs:

flag	type	read by
attention_config.use_fp4_indexer_cache	bool	DeepSeek V3.2/V4 only
attention_config.indexer_kv_dtype	enum	MiniMax M3 only

Because each model read only one of them, passing both was accepted and quietly
resolved in favor of the bool on the DeepSeek path. A config asking for an fp8
indexer cache (--attention_config.indexer_kv_dtype fp8) alongside
--attention_config.use_fp4_indexer_cache=True ran MXFP4, with no warning. I hit
exactly this in a local DSV4 recipe whose "fp8 indexer" arm had in fact been
running MXFP4 for its whole history.

This PR makes indexer_kv_dtype the single knob and deprecates
use_fp4_indexer_cache.

Changes

vllm/config/attention.py

• indexer_kv_dtype gains an "auto" default, resolved per model by the new
  resolve_indexer_kv_dtype(default). The old "bf16" default was never
  meaningful for DeepSeek, whose indexer cache is always quantized; "auto"
  means fp8 there and bf16 for M3, preserving both models' current behavior.
• use_fp4_indexer_cache becomes bool | None = None. When set it logs a
  deprecation warning (removal in v0.19) and maps True -> "mxfp4". False is
  a no-op because it already selected the model default. Conflicting values now
  raise instead of one silently winning.
• The deprecated field is excluded from compute_hash, so
  use_fp4_indexer_cache=True and indexer_kv_dtype=mxfp4 share a compile
  cache entry rather than splitting it.

vllm/v1/attention/backends/mla/indexer.py

• New dsa_indexer_uses_fp4(vllm_config) centralizes resolution + validation for
  the DeepSeek path, so the model side and the metadata builder cannot disagree.
  It rejects dtypes the DSA indexer has no kernels for (bf16, nvfp4) instead
  of failing later in kernel selection, and turns the existing Blackwell
  assert into a ValueError so the check survives python -O.

Callers — models/deepseek_v4/attention.py and
models/minimax_m3/nvidia/model.py go through the shared helpers. DSV4 now
validates at model construction too, not only at backend build.

Configs — the two tracked gsm8k eval configs move to
--attention_config.indexer_kv_dtype=mxfp4.

Backward compatibility

--attention_config.use_fp4_indexer_cache=True keeps working and keeps
selecting MXFP4; it just warns. All three CLI spellings were exercised
(--attention_config.indexer_kv_dtype=mxfp4, the deprecated flag, and JSON
--attention-config '{"indexer_kv_dtype": "nvfp4"}').

The one intentional behavior change: a config passing both flags with
different values used to silently take the bool, and now raises. That
combination was always a contradiction; on the DeepSeek path it produced a cache
dtype the config did not ask for.

Not a duplicate

Per the duplicate-work checks in AGENTS.md:

gh pr list --repo vllm-project/vllm --state open --search "indexer_kv_dtype"
gh pr list --repo vllm-project/vllm --state open --search "use_fp4_indexer_cache"
gh pr list --repo vllm-project/vllm --state open --search "deprecate indexer cache"
gh pr list --repo vllm-project/vllm --state open --search "unify indexer dtype attention config"

Nearest open PRs, all adjacent rather than overlapping — none touches
vllm/config/attention.py or unifies the two knobs:

• [Feature] IndexCache for DeepSeek-V4 (validated on V4-Flash-0731, including DSpark on to accelerate on top of  #51209 (IndexCache for DeepSeek-V4) — touches models/deepseek_v4/attention.py,
  the one file in common, but adds a feature; no config-surface change.
• [Minimax-M3] Enable fp8 index cache on the Triton indexer (non-SM100) #47665 (MiniMax-M3 fp8 index cache on the Triton indexer) — consumes
  indexer_kv_dtype, does not change how it is selected.
• [Kernel] MXFP4 indexer cache for GLM-5.2 / DSA (glm_moe_dsa) #48558 (MXFP4 indexer cache for GLM-5.2 / DSA) — kernel + deepseek_v2.py.

If #51209 lands first the overlap is a small context conflict in
DeepseekV4Indexer.__init__, trivially rebasable.

Testing

pre-commit run --files <changed files>          # all hooks pass, incl. mypy
.venv/bin/python -m pytest tests/config/test_config_generation.py \
                          tests/engine/test_arg_utils.py -q
# 98 passed, 1 failed

The single failure is test_config_generation.py::test_ray_runtime_env
(ModuleNotFoundError, ray not installed); confirmed pre-existing by rerunning
it on a clean stash of main.

Config-resolution matrix verified directly (default -> auto; deprecated
True -> mxfp4 + warning; deprecated False -> auto; conflict -> raises;
auto -> fp8/bf16 per model; hashes of the deprecated and new spellings match).

Model evaluation

Real serving run on the DeepSeek path this change is riskiest for — TP8 over
2x GB300 (8 GPUs), DSpark speculative decoding (7 tokens, greedy),
--attention-config.backend FLASHINFER_MLA, --kv-cache-dtype fp8,
cudagraph_mode FULL_DECODE_ONLY, driven by the new flag
--attention_config.indexer_kv_dtype=mxfp4.

Engine log confirms the unified flag drives both consumers to the MXFP4 path:

attention_config=AttentionConfig(..., use_fp4_indexer_cache=None, indexer_kv_dtype='mxfp4', ...)
[attention.py:810] Using MXFP4 indexer cache for Lightning Indexer.
[indexer.py:558] DSA indexer decode path: use_flattening=False supports_varlen=True (next_n=8, use_fp4_cache=True)

aime25, 4 epochs, n=120, 0 request errors, temperature 1.0 / top_p 0.95,
thinking enabled, max_tokens 150000:

metric	value
exact_match	1.0000
pass@4	1.0000

Caveat worth stating plainly: aime25 is saturated for this checkpoint, so this
result confirms the MXFP4 path is intact end-to-end but cannot by itself
distinguish it from fp8 or from the pre-change build. The stronger evidence for
"no behavior change" is that "auto" resolves to each model's previous default
and the resolution matrix above is exhaustive over the flag combinations.

AI assistance

AI assistance (Claude Code) was used for this change. I reviewed every changed
line, ran the tests and the multi-node eval above myself, and can defend the
change end-to-end.

[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.

[zyongye]

/ci run

[github-actions]

✅ Triggered Buildkite CI #84112 for commit b5a2aafdecb4.