vllm - 💡(How to fix) Fix prompt_tokens_details.cached_tokens always reports prompt_tokens - 1 in disaggregated prefill/decode mode

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

Code Example

Your output of `python collect_env.py` here

---

## Summary
                                                                                                     
  When running vLLM in disaggregated prefill/decode mode with `--enable-prompt-tokens-details`, the  
  `usage.prompt_tokens_details.cached_tokens` value is always reported as `prompt_tokens - 1`,       
  regardless of whether any prefix cache hit actually occurred.                                      
                  
  This happens even on the very first request with a unique prompt that cannot possibly have a prefix
   cache hit.
                                                                                                     
  ## Expected behavior

  `cached_tokens` should reflect actual **prefix cache hits from prior requests** — matching the     
  OpenAI API semantics for this field. For a cold request with no prior matching prefix,
  `cached_tokens` should be `0` (or at most a small constant if the cache contains a system-prompt   
  prefix).
RAW_BUFFERClick to expand / collapse

Your current environment

<details> <summary>The output of <code>python collect_env.py</code></summary>
Your output of `python collect_env.py` here
</details>

Deployment: disaggregated prefill/decode (PD)

🐛 Describe the bug

  ## Summary
                                                                                                     
  When running vLLM in disaggregated prefill/decode mode with `--enable-prompt-tokens-details`, the  
  `usage.prompt_tokens_details.cached_tokens` value is always reported as `prompt_tokens - 1`,       
  regardless of whether any prefix cache hit actually occurred.                                      
                  
  This happens even on the very first request with a unique prompt that cannot possibly have a prefix
   cache hit.
                                                                                                     
  ## Expected behavior

  `cached_tokens` should reflect actual **prefix cache hits from prior requests** — matching the     
  OpenAI API semantics for this field. For a cold request with no prior matching prefix,
  `cached_tokens` should be `0` (or at most a small constant if the cache contains a system-prompt   
  prefix).

Reproduction

  1. Deploy vLLM in disaggregated PD mode (one prefill instance, one decode instance, KV-transfer
    enabled).
  2. Pass --enable-prompt-tokens-details to both instances.
  3. Send a chat/completions request with a fresh, unique prompt directly to the decode worker (bypassing any router/proxy).
  4. Inspect usage.prompt_tokens_details.cached_tokens in the response.

Observed: cached_tokens == prompt_tokens - 1 on every request.
Expected: cached_tokens == 0 for a cold prompt.

Before submitting a new issue...

  • Make sure you already searched for relevant issues, and asked the chatbot living at the bottom right corner of the documentation page, which can answer lots of frequently asked questions.

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING