kanshan/TensorRT-LLMs
1
0
Fork 0
mirror of https://github.com/NVIDIA/TensorRT-LLM.git synced 2026-01-14 06:27:45 +08:00
Code Issues Actions 1 Packages Projects Releases Wiki Activity
fef5a02e7e
TensorRT-LLMs/torch/kv_cache_manager.html
nv-guomingz fef5a02e7e
fix invalid link on torch.md (#2770)
2025-02-11 13:55:43 +08:00

286 lines
21 KiB
HTML
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

<!DOCTYPE html>
<html class="writer-html5" lang="en" data-content_root="../">
<head>
<meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>KV Cache Manager &mdash; tensorrt_llm documentation</title>
<link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />
<link rel="stylesheet" type="text/css" href="../_static/css/theme.css?v=e59714d7" />
<link rel="stylesheet" type="text/css" href="../_static/copybutton.css?v=76b2166b" />
<script src="../_static/jquery.js?v=5d32c60e"></script>
<script src="../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
<script src="../_static/documentation_options.js?v=5929fcd5"></script>
<script src="../_static/doctools.js?v=9bcbadda"></script>
<script src="../_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="../_static/clipboard.min.js?v=a7894cd8"></script>
<script src="../_static/copybutton.js?v=65e89d2a"></script>
<script src="../_static/js/theme.js"></script>
<link rel="index" title="Index" href="../genindex.html" />
<link rel="search" title="Search" href="../search.html" />
</head>
<body class="wy-body-for-nav">
<div class="wy-grid-for-nav">
<nav data-toggle="wy-nav-shift" class="wy-nav-side">
<div class="wy-side-scroll">
<div class="wy-side-nav-search" >
<a href="../index.html" class="icon icon-home">
tensorrt_llm
</a>
<div role="search">
<form id="rtd-search-form" class="wy-form" action="../search.html" method="get">
<input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
<p class="caption" role="heading"><span class="caption-text">Getting Started</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../quick-start-guide.html">Quick Start Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../key-features.html">Key Features</a></li>
<li class="toctree-l1"><a class="reference internal" href="../torch.html">PyTorch Backend</a></li>
<li class="toctree-l1"><a class="reference internal" href="../release-notes.html">Release Notes</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Installation</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../installation/linux.html">Installing on Linux</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation/build-from-source-linux.html">Building from Source Code on Linux</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation/windows.html">Installing on Windows</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation/build-from-source-windows.html">Building from Source Code on Windows</a></li>
<li class="toctree-l1"><a class="reference internal" href="../installation/grace-hopper.html">Installing on Grace Hopper</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">LLM API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../llm-api/index.html">API Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../llm-api/reference.html">API Reference</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">LLM API Examples</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../llm-api-examples/index.html">LLM Examples Introduction</a></li>
<li class="toctree-l1"><a class="reference internal" href="../llm-api-examples/customization.html">Common Customizations</a></li>
<li class="toctree-l1"><a class="reference internal" href="../llm-api-examples/llm_api_examples.html">Examples</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Model Definition API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../python-api/tensorrt_llm.layers.html">Layers</a></li>
<li class="toctree-l1"><a class="reference internal" href="../python-api/tensorrt_llm.functional.html">Functionals</a></li>
<li class="toctree-l1"><a class="reference internal" href="../python-api/tensorrt_llm.models.html">Models</a></li>
<li class="toctree-l1"><a class="reference internal" href="../python-api/tensorrt_llm.plugin.html">Plugin</a></li>
<li class="toctree-l1"><a class="reference internal" href="../python-api/tensorrt_llm.quantization.html">Quantization</a></li>
<li class="toctree-l1"><a class="reference internal" href="../python-api/tensorrt_llm.runtime.html">Runtime</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">C++ API</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../_cpp_gen/executor.html">Executor</a></li>
<li class="toctree-l1"><a class="reference internal" href="../_cpp_gen/runtime.html">Runtime</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Command-Line Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../commands/trtllm-build.html">trtllm-build</a></li>
<li class="toctree-l1"><a class="reference internal" href="../commands/trtllm-serve.html">trtllm-serve</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Architecture</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../architecture/overview.html">TensorRT-LLM Architecture</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/core-concepts.html">Model Definition</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/core-concepts.html#compilation">Compilation</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/core-concepts.html#runtime">Runtime</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/core-concepts.html#multi-gpu-and-multi-node-support">Multi-GPU and Multi-Node Support</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/checkpoint.html">TensorRT-LLM Checkpoint</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/workflow.html">TensorRT-LLM Build Workflow</a></li>
<li class="toctree-l1"><a class="reference internal" href="../architecture/add-model.html">Adding a Model</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Advanced</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../advanced/gpt-attention.html">Multi-Head, Multi-Query, and Group-Query Attention</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/gpt-runtime.html">C++ GPT Runtime</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/executor.html">Executor API</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/graph-rewriting.html">Graph Rewriting Module</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/inference-request.html">Inference Request</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/inference-request.html#responses">Responses</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/lora.html">Run gpt-2b + LoRA using GptManager / cpp runtime</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/expert-parallelism.html">Expert Parallelism in TensorRT-LLM</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/kv-cache-reuse.html">KV cache reuse</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/speculative-decoding.html">Speculative Sampling</a></li>
<li class="toctree-l1"><a class="reference internal" href="../advanced/disaggregated-service.html">Disaggregated-Service (experimental)</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Performance</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../performance/perf-overview.html">Overview</a></li>
<li class="toctree-l1"><a class="reference internal" href="../performance/perf-benchmarking.html">Benchmarking</a></li>
<li class="toctree-l1"><a class="reference internal" href="../performance/performance-tuning-guide/index.html">Performance Tuning Guide</a></li>
<li class="toctree-l1"><a class="reference internal" href="../performance/perf-analysis.html">Performance Analysis</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Reference</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../reference/troubleshooting.html">Troubleshooting</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/support-matrix.html">Support Matrix</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/precision.html">Numerical Precision</a></li>
<li class="toctree-l1"><a class="reference internal" href="../reference/memory.html">Memory Usage of TensorRT-LLM</a></li>
</ul>
<p class="caption" role="heading"><span class="caption-text">Blogs</span></p>
<ul>
<li class="toctree-l1"><a class="reference internal" href="../blogs/H100vsA100.html">H100 has 4.6x A100 Performance in TensorRT-LLM, achieving 10,000 tok/s at 100ms to first token</a></li>
<li class="toctree-l1"><a class="reference internal" href="../blogs/H200launch.html">H200 achieves nearly 12,000 tokens/sec on Llama2-13B with TensorRT-LLM</a></li>
<li class="toctree-l1"><a class="reference internal" href="../blogs/Falcon180B-H200.html">Falcon-180B on a single H200 GPU with INT4 AWQ, and 6.7x faster Llama-70B over A100</a></li>
<li class="toctree-l1"><a class="reference internal" href="../blogs/quantization-in-TRT-LLM.html">Speed up inference with SOTA quantization techniques in TRT-LLM</a></li>
<li class="toctree-l1"><a class="reference internal" href="../blogs/XQA-kernel.html">New XQA-kernel provides 2.4x more Llama-70B throughput within the same latency budget</a></li>
</ul>
</div>
</div>
</nav>
<section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
<i data-toggle="wy-nav-top" class="fa fa-bars"></i>
<a href="../index.html">tensorrt_llm</a>
</nav>
<div class="wy-nav-content">
<div class="rst-content">
<div role="navigation" aria-label="Page navigation">
<ul class="wy-breadcrumbs">
<li><a href="../index.html" class="icon icon-home" aria-label="Home"></a></li>
<li class="breadcrumb-item active">KV Cache Manager</li>
<li class="wy-breadcrumbs-aside">
<a href="../_sources/torch/kv_cache_manager.md.txt" rel="nofollow"> View page source</a>
</li>
</ul>
<hr/>
</div>
<div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
<div itemprop="articleBody">
<section id="kv-cache-manager">
<h1>KV Cache Manager<a class="headerlink" href="#kv-cache-manager" title="Link to this heading"></a></h1>
<p>In Transformer-based models, the KV (Key-Value) Cache is a mechanism used to optimize decoding efficiency, particularly during autoregressive generation tasks.
Since KV Cache requires memory to store, it is also an important resource.
In TensorRT-LLM, KV Cache is managed by the <code class="docutils literal notranslate"><span class="pre">KVCacheManager</span></code>.</p>
<section id="kv-cache-manager-introduction">
<h2>KV Cache Manager Introduction<a class="headerlink" href="#kv-cache-manager-introduction" title="Link to this heading"></a></h2>
<p><code class="docutils literal notranslate"><span class="pre">KVCacheManager</span></code> is a type of resource manager, inheriting from <code class="docutils literal notranslate"><span class="pre">BaseResourceManager</span></code>.
Therefore, it implements the interfaces declared by <code class="docutils literal notranslate"><span class="pre">BaseResourceManager</span></code>.</p>
<p>Note: As the project evolves, these interfaces may change.</p>
</section>
<section id="interfaces">
<h2>Interfaces<a class="headerlink" href="#interfaces" title="Link to this heading"></a></h2>
<p>The interfaces from <code class="docutils literal notranslate"><span class="pre">BaseResourceManager</span></code> include:</p>
<ul class="simple">
<li><p><strong>prepare_resources</strong>: Called at each step before model forward in <code class="docutils literal notranslate"><span class="pre">PyExecutor</span></code> for the current batch.
In <code class="docutils literal notranslate"><span class="pre">KVCacheManager</span></code>, this involves allocating KV Cache memory. This allocation varies depending on the request type.
For requests entering the context phase for the first time, KV Cache needs to be allocated for the entire context.
For requests already in the generation phase, KV Cache is allocated for the upcoming step.
If KV Cache is organized in blocks and free space is available within a block, actual allocation may not occur.</p></li>
<li><p><strong>update_resources</strong>: Called at the end of each step for the current batch to update allocated resources.
For KV Cache, updates may not be necessary, so this function currently performs no operations.
If KV Cache reuse is supported in Python, updates like KV Cache Radix Tree management occurs here.</p></li>
<li><p><strong>free_resources</strong>: Called when a request finishes to free the resources allocated for that request.
For KV Cache, if reuse is not enabled, the KV Cache memory used by the request should be recycled.
In the C++ binding implementation, this might involve calling the binding’s <code class="docutils literal notranslate"><span class="pre">remove_sequence</span></code> method to free the KV Cache memory related to that request.</p></li>
</ul>
<p>There are also two interfaces designed for <code class="docutils literal notranslate"><span class="pre">CapacityScheduler</span></code>:</p>
<ul class="simple">
<li><p><strong>get_max_resource_count</strong>: Queries the maximum number of resources available. For <code class="docutils literal notranslate"><span class="pre">KVCacheManager</span></code>, this is usually the maximum number of KV Cache blocks.</p></li>
<li><p><strong>get_needed_resource_to_completion</strong>: Computes the resources needed for a single request to complete.
<code class="docutils literal notranslate"><span class="pre">CapacityScheduler</span></code> uses this to sum up the total resources needed and determine if new requests can be accommodated.</p></li>
</ul>
<p>In addition to the <code class="docutils literal notranslate"><span class="pre">BaseResourceManager</span></code> interfaces, <code class="docutils literal notranslate"><span class="pre">KVCacheManager</span></code> has interfaces related to the <code class="docutils literal notranslate"><span class="pre">ModelEngine</span></code> in use.
For <code class="docutils literal notranslate"><span class="pre">PyTorchModelEngine</span></code>, common interfaces include:</p>
<ul class="simple">
<li><p><strong>get_batch_cache_indices</strong>: Takes a list of <code class="docutils literal notranslate"><span class="pre">LlmRequest</span></code> and returns a <code class="docutils literal notranslate"><span class="pre">Dict[List[int]]</span></code>, indicating the block IDs for each request.</p></li>
<li><p><strong>get_buffers</strong>: Returns the buffer of the KV Cache pool for a given layer, used by the attention backend. The shape might be [<code class="docutils literal notranslate"><span class="pre">num_blocks</span></code>, 2, <code class="docutils literal notranslate"><span class="pre">num_tokens_per_block</span></code>, <code class="docutils literal notranslate"><span class="pre">num_kv_heads</span></code>, <code class="docutils literal notranslate"><span class="pre">head_dim</span></code>].</p></li>
<li><p><strong>get_num_free_blocks</strong>: Returns the number of free blocks available for allocation.</p></li>
</ul>
<p>There are also interfaces for warming up <code class="docutils literal notranslate"><span class="pre">PyTorchModelEngine</span></code>, especially when using CUDA graphs:</p>
<ul class="simple">
<li><p><strong>add_padding_request</strong>: Adds a sequence of context length 1 to KV Cache as a warmup request.
This is optional if CUDA Graph is not used in your proof of concept.</p></li>
</ul>
</section>
<section id="customize-kv-cache-manager">
<h2>Customize KV Cache Manager<a class="headerlink" href="#customize-kv-cache-manager" title="Link to this heading"></a></h2>
<p>To customize <code class="docutils literal notranslate"><span class="pre">KVCacheManager</span></code>, implement all the necessary interfaces.
Then, integrate it into the <code class="docutils literal notranslate"><span class="pre">PyExecutor</span></code>. For the PyTorch backend, the relevant code is in <a class="reference download internal" download="" href="../_downloads/7bf66a65dff8703efe2c82828509f35d/pytorch_model_registry.py"><span class="xref download myst">pytorch_model_registry.py</span></a>.
In the <code class="docutils literal notranslate"><span class="pre">create_pytorch_model_based_executor</span></code> function, the <code class="docutils literal notranslate"><span class="pre">KVCacheManager</span></code> is instantiated as follows:</p>
<div class="highlight-python notranslate"><div class="highlight"><pre><span></span> <span class="n">kv_cache_manager</span> <span class="o">=</span> <span class="n">KVCacheManager</span><span class="p">(</span>
<span class="n">executor_config</span><span class="o">.</span><span class="n">kv_cache_config</span><span class="p">,</span>
<span class="n">tensorrt_llm</span><span class="o">.</span><span class="n">bindings</span><span class="o">.</span><span class="n">internal</span><span class="o">.</span><span class="n">batch_manager</span><span class="o">.</span><span class="n">CacheType</span><span class="o">.</span><span class="n">SELF</span><span class="p">,</span>
<span class="n">model_engine</span><span class="o">.</span><span class="n">model</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">num_hidden_layers</span><span class="p">,</span>
<span class="n">model_engine</span><span class="o">.</span><span class="n">model</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">num_attention_heads</span><span class="p">,</span>
<span class="n">model_engine</span><span class="o">.</span><span class="n">model</span><span class="o">.</span><span class="n">config</span><span class="o">.</span><span class="n">num_key_value_heads</span><span class="p">,</span>
<span class="n">head_dim</span><span class="p">,</span>
<span class="n">tokens_per_block</span><span class="p">,</span>
<span class="n">max_seq_len</span><span class="p">,</span>
<span class="n">max_num_requests</span><span class="p">,</span>
<span class="n">mapping</span><span class="p">,</span>
<span class="n">dtype</span><span class="o">=</span><span class="n">kv_cache_dtype</span><span class="p">,</span>
<span class="p">)</span>
</pre></div>
</div>
<p>For local testing or proof of concept, update these lines to use your implementation.
Then, test it to ensure the <code class="docutils literal notranslate"><span class="pre">PyExecutor</span></code> runs with your customized <code class="docutils literal notranslate"><span class="pre">KVCacheManager</span></code>.</p>
</section>
</section>
</div>
</div>
<footer>
<hr/>
<div role="contentinfo">
<jinja2.runtime.BlockReference object at 0x7f96d13ddac0>
<div class="footer">
<p>
Copyright © 2024 NVIDIA Corporation
</p>
<p>
<a class="Link" href="https://www.nvidia.com/en-us/about-nvidia/privacy-policy/" target="_blank" rel="noopener"
data-cms-ai="0">Privacy Policy</a> |
<a class="Link" href="https://www.nvidia.com/en-us/about-nvidia/privacy-center/" target="_blank" rel="noopener"
data-cms-ai="0">Manage My Privacy</a> |
<a class="Link" href="https://www.nvidia.com/en-us/preferences/start/" target="_blank" rel="noopener"
data-cms-ai="0">Do Not Sell or Share My Data</a> |
<a class="Link" href="https://www.nvidia.com/en-us/about-nvidia/terms-of-service/" target="_blank"
rel="noopener" data-cms-ai="0">Terms of Service</a> |
<a class="Link" href="https://www.nvidia.com/en-us/about-nvidia/accessibility/" target="_blank" rel="noopener"
data-cms-ai="0">Accessibility</a> |
<a class="Link" href="https://www.nvidia.com/en-us/about-nvidia/company-policies/" target="_blank"
rel="noopener" data-cms-ai="0">Corporate Policies</a> |
<a class="Link" href="https://www.nvidia.com/en-us/product-security/" target="_blank" rel="noopener"
data-cms-ai="0">Product Security</a> |
<a class="Link" href="https://www.nvidia.com/en-us/contact/" target="_blank" rel="noopener"
data-cms-ai="0">Contact</a>
</p>
</div>
</div>
</footer>
</div>
</div>
</section>
</div>
<script>
jQuery(function () {
SphinxRtdTheme.Navigation.enable(true);
});
</script>
</body>
</html>
Reference in New Issue View Git Blame Copy Permalink