KV Cache Engineering for LLM Inference

La KV cache è diventata una risorsa di sistema, non un dettaglio del Transformer

Il costo dell’inferenza autoregressiva non dipende soltanto dai FLOP del modello. A parità di pesi, tokenizer e qualità della generazione, il serving può passare da una buona latenza interattiva a un p99 inutilizzabile per effetto di occupazione HBM, frammentazione dei blocchi, scheduling, interferenza tra prefill e decode, riuso dei prefissi e trasferimento delle cache fra GPU. Questa analisi attraversa l’intero percorso: tensori K/V → gestione paginata → hashing → sicurezza multi-tenant → osservabilità → deployment .NET e Azure.

Perimetro tecnico. I calcoli di memoria riportati sono modelli analitici esplicitamente parametrizzati, non benchmark. Le opzioni vLLM sono legate alla documentazione corrente: prima di usarle in produzione occorre fissare la versione del container e verificare la CLI di quella release.

1. Internals: cosa viene conservato per ogni token

In un decoder-only Transformer, a ogni layer il token produce query, key e value. Durante la generazione la query del nuovo token deve attendere alle key e value dei token precedenti. Conservare K e V evita di ricalcolarli a ogni passo: il compute risparmiato viene scambiato con capacità e bandwidth di memoria. Le query dei token passati non devono essere conservate per la normale attenzione causale.

Per layer e token:
K: [n_kv_heads, head_dim]  V: [n_kv_heads, head_dim]

KV_bytes_per_token = 2 * n_layers * n_kv_heads * head_dim * bytes_per_element
KV_bytes_sequence = KV_bytes_per_token * sequence_length

Esempio puramente parametrico:
32 layer, 8 KV heads, dimensione 128, BF16 (2 byte)
= 2 * 32 * 8 * 128 * 2 = 131072 byte/token = 128 KiB/token
8192 token = 1 GiB di KV cache per sequenza (senza overhead).

Con Grouped Query Attention (GQA) più query head condividono lo stesso insieme di KV head: nel modello sopra conta n_kv_heads, non il numero di query head. La formula non copre architetture ibride, sliding-window, compressione, quantizzazione KV o strategie di allocazione speciali: in questi casi serve la configurazione reale del modello e del serving engine.

Analisi. La quantizzazione dei pesi e quella della KV cache risolvono due problemi differenti. Ridurre i pesi può consentire di caricare il modello; ridurre i byte per elemento della cache può aumentare il numero di sequenze concorrenti o il contesto effettivamente servibile. Il guadagno va però validato contro kernel disponibili, precisione numerica e bandwidth.

2. PagedAttention: indirizzamento logico e fisico

Il lavoro originale di Kwon et al. (SOSP 2023) introduce PagedAttention per evitare che una cache di lunghezza variabile debba occupare un grande segmento fisico contiguo. Il runtime spezza la sequenza in blocchi logici di dimensione fissa e li mappa su blocchi fisici anche non adiacenti. La block table svolge un ruolo concettualmente simile alla page table di un sistema operativo, pur non essendo una mappatura MMU della CPU.

Sequenza A, blocchi logici: [L0] [L1] [L2] [L3]
Block table A:          [ 7] [31] [ 4] [22]
Pool fisico GPU: ... [4] ... [7] ... [22] ... [31] ...

Sequenza B con prefisso condiviso:
Block table B:          [ 7] [31] [15]
                              ^
                   divergenza dopo prefisso

Il beneficio non è un’accelerazione magica del kernel di attenzione: è una gestione della memoria che riduce frammentazione e duplicazione e rende possibile mantenere più richieste attive. Il blocco finale può avere spazio inutilizzato; per questo la granularità dei blocchi è un trade-off fra frammentazione interna, dimensione delle tabelle e overhead del kernel. Il paper riporta miglioramenti di throughput in specifici confronti sperimentali, che non vanno trasferiti automaticamente a modelli o GPU odierni.

Failure mode. Se una richiesta lunga occupa molti blocchi, la pressione sulla pool può causare eviction di blocchi riutilizzabili o preemption di altre richieste. La latenza può quindi peggiorare anche quando il modello è già interamente residente in VRAM.

Fonte primaria: Paper PagedAttention, SOSP 2023; vLLM: design del KV block manager.

3. Prefix hashing: l’identità della cache è una catena

Automatic Prefix Caching (APC) permette di riutilizzare blocchi KV già calcolati quando un’altra richiesta condivide lo stesso prefisso di token. Non basta che due stringhe siano simili: contano token ID, ordine, modello, template, eventuali componenti multimodali e metadati che partecipano all’identità del blocco. Una cache hit non evita il lavoro di decode dei nuovi token.

H0 = HASH(parent = null, block_tokens_0, extra_hashes_0)
H1 = HASH(parent = H0,   block_tokens_1, extra_hashes_1)
H2 = HASH(parent = H1,   block_tokens_2, extra_hashes_2)

Prompt A: [system][policy][document A][question A]
Prompt B: [system][policy][document B][question B]
                  ^ prefisso condivisibile

Prompt C: [timestamp variabile][system][policy]...
           ^ rompe subito il prefisso condiviso

In vLLM l’algoritmo di hashing configurabile comprende sha256 (serializzazione Python pickle) e sha256_cbor (canonical CBOR). La variante CBOR è adatta quando serve riproducibilità cross-language, ma un hash SHA-256 calcolato in C# su una stringa JSON non equivale all’hash interno dei blocchi vLLM. È necessario riprodurre esattamente schema, serializzazione, tokenizzazione e metadati: l’esempio C# successivo usa un hash di policy, non simula l’algoritmo interno di vLLM.

Analisi di progettazione del prompt. Spostare istruzioni stabili, schemi tool e documentazione condivisa all’inizio del contesto può aumentare il riuso; inserire identificatori di richiesta, timestamp e contenuti personali prima del prefisso comune lo distrugge. La convenienza dipende però dal numero di richieste, dalla residency della cache e dalla sua politica di eviction.

Fonte primaria: vLLM Automatic Prefix Caching; Configurazione degli algoritmi hash.

4. Tenant isolation: cache salt non significa sandbox

Il riuso della cache crea un canale laterale: un client può confrontare i tempi di prefill per dedurre se un prefisso ipotizzato sia già stato elaborato. vLLM documenta il rischio di timing e offre cache_salt, inserito nell’hash iniziale per impedire la condivisione tra trust group con salt differenti. È una mitigazione mirata, non un confine generale di sicurezza. La documentazione vLLM precisa che tenant nello stesso processo condividono scheduler e cache.

IDENTITY PROVIDER → ASP.NET CORE GATEWAY
                           │
                           ├── authenticate tenant
                           ├── authorize model + quota
                           ├── derive server-side cache salt
                           ├── reject client-supplied salt
                           └── route to isolated inference pool
                                       │
                            vLLM instance / trust group

Un gateway non deve fidarsi di X-Tenant-Id o di un salt fornito liberamente dal client. L’identità del tenant deve derivare da credenziali validate, e il salt deve essere generato dal server. Se è necessario isolamento forte di dati e prestazioni, usare istanze separate per tenant o gruppi di fiducia, con risorse e rete segmentate; considerare anche log, metriche, checkpoint e dati temporanei.

5. C#/.NET 10: derivazione di un salt server-side

L’esempio seguente produce un salt pseudonimo stabile per un tenant usando HMAC-SHA256 e un segreto applicativo. È utile per separare trust group senza esporre identificatori direttamente al backend; non è un’implementazione del prefix hash di vLLM. La rotazione del segreto invalida la possibilità di riuso tra vecchi e nuovi salt. Non usare una chiave incorporata nel sorgente.

using System.Security.Cryptography;
using System.Text;

static string DeriveCacheSalt(string tenantId, byte[] secret)
{
    if (string.IsNullOrWhiteSpace(tenantId))
        throw new ArgumentException("Missing tenant", nameof(tenantId));

    byte[] message = Encoding.UTF8.GetBytes("kv-cache/v1/" + tenantId);
    byte[] digest = HMACSHA256.HashData(secret, message);
    return Convert.ToHexString(digest);
}

// secret: 32+ random bytes from Key Vault / environment; not in source.
// tenantId: obtained from a validated identity token.
// Forward cache_salt to a vLLM release supporting this request field.

Il rate limiting applicativo deve essere partizionato per identità verificata; inoltre è opportuno imporre limiti separati su token di input, token di output, richieste simultanee e durata massima. Un semplice limite in richieste/minuto non controlla il consumo di HBM: una richiesta da 100.000 token può pesare più di centinaia di richieste corte.

Fonte primaria: vLLM Security: multi-tenancy e timing; ASP.NET Core rate limiting.

6. TTFT, ITL, TPOT e p99: misurare la qualità del servizio

TTFT (Time To First Token) misura la latenza fino al primo token prodotto; lato client include rete, gateway, code, tokenizzazione e trasporto del primo evento. ITL (Inter-Token Latency) misura l’intervallo fra token successivi; TPOT è spesso usato per descrivere il tempo medio per token di output, ma le definizioni operative possono differire. Un evento SSE non corrisponde necessariamente a un token: può contenere più token, un frammento testuale o solo metadati. Occorre quindi distinguere first SSE byte, first non-empty content delta e TTFT misurato dal motore.

End-to-end latency ≈ gateway + queue + prefill + decode + transport

TTFT_client = t(first content delta) - t(request start)
ITL_engine  = t(token_i) - t(token_i-1)
Goodput     = successful requests satisfying TTFT/ITL SLO per second

SLO di esempio (NON benchmark):
TTFT p99 < soglia concordata
ITL  p99 < soglia concordata
Error rate < soglia concordata

La media è insufficiente: un sistema può mantenere throughput elevato e peggiorare drasticamente la tail latency sotto carico. Segmentare le distribuzioni per lunghezza del prompt, output richiesto, tenant, modello, cache hit/miss e livello di concorrenza. Confrontare percentile per richiesta e percentile per token senza dichiararne il denominatore produce conclusioni scorrette.

Le metriche Prometheus di vLLM includono istogrammi di TTFT, inter-token latency, queue time e segnali relativi a utilizzo della KV cache e prefix caching; nomi e disponibilità possono evolvere fra versioni. Evitare etichette ad alta cardinalità come request ID, testo del prompt o tenant ID grezzo.

Fonte primaria: vLLM Production Metrics; Metriche per richiesta.

7. Laboratorio C#: streaming SSE e percentile end-to-end

Il client seguente usa soltanto librerie .NET 10, legge una risposta Chat Completions in streaming, misura il primo delta.content non vuoto e calcola i percentili di una serie di richieste. Il codice non pretende di misurare ITL token-level: l’API SSE espone chunk, non una garanzia di un evento per token. Per il test usare un modello e un endpoint locali configurati via variabili d’ambiente; nessuna credenziale è hardcoded.

// dotnet new console -f net10.0 -n KvLatencyLab
// Program.cs
using System.Diagnostics;
using System.Net.Http.Headers;
using System.Text;
using System.Text.Json;

string endpoint = Environment.GetEnvironmentVariable("LLM_ENDPOINT")
    ?? "http://localhost:8000/v1/chat/completions";
string model = Environment.GetEnvironmentVariable("LLM_MODEL")
    ?? throw new InvalidOperationException("Set LLM_MODEL");
string? apiKey = Environment.GetEnvironmentVariable("LLM_API_KEY");

using var http = new HttpClient { Timeout = TimeSpan.FromMinutes(5) };
if (!string.IsNullOrEmpty(apiKey))
    http.DefaultRequestHeaders.Authorization =
        new AuthenticationHeaderValue("Bearer", apiKey);

var samples = new List<(double firstContentMs, double totalMs)>();
for (int n = 0; n < 20; n++)
{
    var payload = new
    {
        model,
        stream = true,
        max_tokens = 96,
        temperature = 0,
        messages = new[] { new { role = "user", content =
            "Explain KV cache block tables in three technical paragraphs." } }
    };
    using var req = new HttpRequestMessage(HttpMethod.Post, endpoint)
    {
        Content = new StringContent(JsonSerializer.Serialize(payload),
            Encoding.UTF8, "application/json")
    };
    var sw = Stopwatch.StartNew();
    using var res = await http.SendAsync(req,
        HttpCompletionOption.ResponseHeadersRead);
    res.EnsureSuccessStatusCode();
    await using var stream = await res.Content.ReadAsStreamAsync();
    using var reader = new StreamReader(stream);
    double? first = null;
    while (await reader.ReadLineAsync() is { } line)
    {
        if (!line.StartsWith("data: ", StringComparison.Ordinal)) continue;
        string json = line[6..];
        if (json == "[DONE]") break;
        using var doc = JsonDocument.Parse(json);
        var choices = doc.RootElement.GetProperty("choices");
        if (choices.GetArrayLength() == 0) continue;
        var delta = choices[0].GetProperty("delta");
        if (delta.TryGetProperty("content", out var content) &&
            content.ValueKind == JsonValueKind.String &&
            !string.IsNullOrEmpty(content.GetString()))
            first ??= sw.Elapsed.TotalMilliseconds;
    }
    if (first is not null)
        samples.Add((first.Value, sw.Elapsed.TotalMilliseconds));
}
static double P(double[] xs, double q)
{
    Array.Sort(xs);
    double index = (xs.Length - 1) * q;
    int lo = (int)Math.Floor(index), hi = (int)Math.Ceiling(index);
    return xs[lo] + (xs[hi] - xs[lo]) * (index - lo);
}
if (samples.Count == 0) throw new Exception("No content deltas");
var ttft = samples.Select(x => x.firstContentMs).ToArray();
Console.WriteLine($"N={ttft.Length} TTFC p50={P(ttft, .50):F1} ms " +
    $"p95={P(ttft, .95):F1} ms p99={P(ttft, .99):F1} ms");
// This is time-to-first-content (TTFC), not engine-measured TTFT.
// Use >=1000 samples and concurrent load for meaningful p99 inference.

Limite statistico. Venti richieste servono a verificare il programma, non a caratterizzare il p99. Per un confronto serio servono warm-up, carico controllato, campioni numerosi, distribuzioni ripetute e intervalli di confidenza. Eseguire A/B con identica lunghezza del prefisso, stessa concorrenza e cache cold/warm; misurare anche le metriche server per separare code e prefill.

8. Prefill/decode disaggregation: separare il compute, pagare il trasferimento

Prefill e decode hanno profili di carico differenti. Il prefill elabora molti token del prompt in parallelo e tende a sfruttare meglio grandi operazioni di calcolo; il decode genera uno o pochi token per step per sequenza e può diventare limitato dal movimento dei pesi e della KV cache. Sullo stesso pool GPU, l’inserimento di prefill lunghi può interferire con la regolarità del decode. La disaggregazione separa le istanze e trasferisce i tensori KV dalla fase prefill alla fase decode.

Client .NET
   │
   ▼
Inference gateway / router
   │
   ├── PREFILL GPU pool: tokenize + compute prompt K/V
   │                         │
   │                    KV transfer
   │                         │
   └── DECODE GPU pool  ◄────┘
              │
         token streaming
              │
           Client

La documentazione vLLM descrive connettori di trasferimento e due istanze distinte; la funzionalità è indicata come sperimentale. La disaggregazione può rendere più controllabile il tail ITL, ma non garantisce automaticamente un TTFT migliore. È necessario confrontarla anche con chunked prefill sullo stesso hardware e con la stessa distribuzione di richieste.

T_disaggregated_TTFT ≈ T_queue_prefill + T_prefill + T_KV_transfer
                       + T_queue_decode + T_first_decode + T_network

T_KV_transfer ≈ KV_bytes / effective_bandwidth + protocol_overhead

Break-even (analisi): il guadagno da minore interferenza
deve superare overhead di routing, trasferimento e coordinamento.

Esempio parametrico: una sequenza con 1 GiB di KV da trasferire su un collegamento con 10 GiB/s effettivi richiede almeno circa 100 ms per la sola trasmissione ideale, senza serializzazione, sincronizzazione, contesa o copie aggiuntive. Non è una misura Azure: la bandwidth realmente disponibile dipende da VM, topologia, connettore, trasporto e dimensione del batch.

Fonte primaria: vLLM Disaggregated Prefilling; Implementazione e configurazioni.

9. Azure: HBM, quota, rete e costo per richiesta conforme allo SLO

Su Azure, una configurazione documentata è la serie NCads H100 v5 con GPU NVIDIA H100 NVL: Standard_NC40ads_H100_v5 espone una GPU con 94 GiB di memoria GPU e 320 GiB RAM di sistema; Standard_NC80adis_H100_v5 due GPU per 188 GiB complessivi e 640 GiB RAM. Disponibilità regionale, quota e prezzo non sono deducibili dalla sola scheda tecnica: vanno verificati sulla sottoscrizione e regione effettiva. Una VM con due GPU non implica che la memoria GPU sia automaticamente un unico spazio indirizzabile da un singolo processo.

Per dimensionare una VM: VRAM_required ≈ model_weights + peak_KV + CUDA_graphs/workspaces + runtime_overhead + safety_margin. Il modello in formato 4-bit non occupa semplicemente parametri × 0,5 byte: scale, metadati, layer non quantizzati e implementazione del kernel possono aggiungere overhead. La quota HBM disponibile alla KV cache va misurata dopo il caricamento reale del modello.

Analisi. Per una prima baseline è spesso più utile una singola istanza GPU con batching e prefix caching misurati che una topologia distribuita prematura. La separazione prefill/decode diventa interessante quando i profili di traffico e la tail latency giustificano il costo aggiuntivo di GPU, rete, coordinamento e operazioni. In un ambiente Azure multi-tenant, separare processi e reti per gruppi di fiducia può essere più importante del massimo cache hit rate.

Il costo va calcolato come € / richiesta completata entro SLO, includendo VM accese durante idle, storage, rete, osservabilità, replica, failure/retry e capacità inutilizzata. Non si riportano prezzi orari perché cambiano per regione, contratto e data.

Fonti primarie: Azure NCads H100 v5 specifications; Azure Pricing Calculator.

10. Architettura .NET: controllo del flusso e osservabilità end-to-end

Un gateway ASP.NET Core davanti a vLLM non dovrebbe essere un proxy HTTP trasparente. È il punto in cui applicare autenticazione, policy dei tenant, token budget, controllo della concorrenza, propagazione della cancellazione, timeout distinti per queue e generation, correlation ID e metriche. La connessione SSE deve mantenere backpressure e terminare il lavoro backend quando il client interrompe la richiesta. Un timeout globale unico può confondere un prefill lento con un decode bloccato.

Ingress / Entra ID
      │
ASP.NET Core .NET 10
  ├── JWT validation / authorization
  ├── tenant-derived cache_salt
  ├── concurrency + token budgets
  ├── ActivitySource / Meter / trace context
  ├── CancellationToken propagation
  └── SSE streaming proxy
      │
   vLLM endpoint(s)
      ├── /v1/chat/completions
      └── /metrics → Prometheus/Grafana

Metriche minime: ingress requests, rejected requests, active requests, queue wait, first-content latency, total duration, response status, token input/output, cache hit rate, KV occupancy, preemption, transfer latency e GPU utilization. Le metriche per tenant devono rispettare la privacy: preferire ID pseudonimi e cardinalità controllata. Per il backend vLLM usare le metriche native, senza confondere misure lato client con i tempi interni del motore.

Technical Takeaways

  1. KV cache è capacità HBM dinamica: senza un budget esplicito di token concorrenti il modello può stare in memoria ma il serving non essere stabile.
  2. PagedAttention gestisce blocchi, APC riusa compute: due ottimizzazioni distinte da misurare separatamente.
  3. La cache è anche una superficie di sicurezza: cache_salt mitiga un canale laterale, non sostituisce l’isolamento tra tenant.
  4. Il p99 è una proprietà del sistema: scheduler, queueing, prompt mix e interferenza contano quanto il kernel GPU.
  5. Disaggregare non è gratuito: i millisecondi di KV transfer possono cancellare i benefici sul TTFT.
  6. .NET è il control plane: identità, quote, streaming, tracing e SLO devono essere indipendenti dal motore di inferenza.

Lab della settimana

  1. Cache cold vs warm. Avviare vLLM con un modello compatibile, eseguire 100+ richieste con prefisso identico e poi con un timestamp all’inizio del prompt. Registrare TTFC lato .NET, TTFT server, prefix-cache hits e KV occupancy. Ripetere dopo warm-up e a diversi livelli di concorrenza. Guida APC.
  2. Isolamento del riuso. In un ambiente di test senza dati sensibili, inviare lo stesso prefisso con due salt distinti e verificare tramite metriche che il riuso avvenga solo nel trust group previsto. Ripetere su processi separati e confrontare la superficie di isolamento, non soltanto la latenza. Security guidance.
  3. Chunked vs disaggregated prefill. Su hardware e workload controllati confrontare una istanza con scheduling misto e due istanze con KV transfer. Registrare TTFT p50/p95/p99, ITL p99, goodput, bytes trasferiti e costo orario. Usare gli esempi della release vLLM installata, perché i connector sono sperimentali. Documentazione disaggregated prefill.

Conclusione — Valutazione architetturale. L’inferenza LLM su scala non è semplicemente l’esecuzione di un modello: è la gestione concorrente di una gerarchia di memoria sensibile al contenuto, di un sistema di code e di una rete che sposta stato tra acceleratori. La KV cache è il punto in cui performance, sicurezza e architettura distribuita smettono di essere problemi separati.

Commenti