-----------------------------------

Acquista i software ArcGIS tramite Studio A&T srl, rivenditore autorizzato dei prodotti Esri.

I migliori software GIS, il miglior supporto tecnico!

I migliori software GIS, il miglior supporto tecnico!
Azienda operante nel settore GIS dal 2001, specializzata nell’utilizzo della tecnologia ArcGIS e aderente ai programmi Esri Italia Business Network ed Esri Partner Network

-----------------------------------



Visualizzazione post con etichetta vLLM. Mostra tutti i post
Visualizzazione post con etichetta vLLM. Mostra tutti i post

mercoledì 28 ottobre 2026

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.

venerdì 23 ottobre 2026

Cache Engineering for AI Agents

NICOGIS TECH WEEKLY · DEEP DIVE · 23 OTTOBRE 2026

Cache Engineering for AI Agents: KV Cache, Position Encoding, Prefill Optimization e Inference Serving

Un agente che esegue centinaia di tool call non consuma risorse soltanto quando genera token. Ogni osservazione allunga la traiettoria, può aumentare lo stato di attenzione da conservare e rende più costoso il successivo prefill. Il problema diventa: quale stato computazionale conservare, riutilizzare, eliminare o riposizionare senza compromettere la correttezza?

Questo deep dive parte dalla matematica dei transformer, analizza il paper Cache Engineering for Agents e arriva a un laboratorio riproducibile con vLLM e C#/.NET 10. Distingueremo rigorosamente il prefix caching già disponibile nei server di inferenza dalle operazioni sperimentali drop e repos proposte da AKV.

1. La traiettoria di un agente è diversa da una chat

In una chat tradizionale il contesto aumenta con messaggi relativamente brevi. In un agente, una singola tool response può introdurre migliaia di token: log, file sorgente, risultati di ricerca, JSON, documenti. Un ciclo LLM → tool → observation → LLM ripetuto decine o centinaia di volte amplifica il problema.

System + task + tools
        |
        v
     Agent LLM ----> Tool A ----> Observation A
        |                            |
        +----------------------------+
        |
        +-------------> Tool B ----> Observation B
        |                            |
        +----------------------------+
        |
        v
   Next prefill / decode

È necessario separare quattro grandezze: token della cronologia logica, token realmente elaborati durante il prefill, byte di KV cache allocati in GPU e byte trasferiti fra GPU, CPU e storage. Una API commerciale può fatturare token cached senza esporre la KV cache fisica. Un inference server self-hosted può riutilizzare blocchi KV senza cambiare il testo del prompt.

2. KV cache: matematica e dimensionamento

In un transformer autoregressivo, per ogni layer si calcolano le proiezioni Q = XWq, K = XWk e V = XWv. La self-attention causale è, schematicamente, softmax(QKᵀ / sqrt(d) + mask) V. Durante il decode i token precedenti non cambiano: ricalcolarne ogni volta key e value sarebbe uno spreco. La KV cache conserva queste rappresentazioni per riutilizzarle.

Per L layer, Hkv KV head, dimensione D per head, N token e B byte per elemento, una stima è:

M_KV ≈ 2 × L × Hkv × D × N × B

Il fattore due rappresenta K e V. Consideriamo 32 layer, 8 KV head, dimensione 128, BF16 (2 byte), 32.768 token:

2 × 32 × 8 × 128 × 32768 × 2
= 4,294,967,296 byte ≈ 4 GiB per sequenza

Otto sequenze indipendenti di quella lunghezza richiederebbero circa 32 GiB di sola KV cache, prima di pesi del modello, buffer, frammentazione e altre allocazioni. GQA e MQA riducono il numero di KV head; la quantizzazione KV riduce i byte per elemento ma introduce vincoli di precisione e compatibilità. La dimensione massima di contesto pubblicizzata dal modello non coincide con la capacità di servire contemporaneamente molte richieste a quella lunghezza.

3. Prefill e decode: due workload differenti

FaseAttivitàCollo di bottiglia tipicoMetriche
PrefillElabora il prompt e costruisce KVCompute e lunghezza inputPrefill latency, TTFT
DecodeGenera token incrementaliBandwidth, letture KV, batchingITL, output token/s
SchedulerDistribuisce risorse fra richiesteMemoria, queueing, preemptionP95/P99, queue time

Il Time to First Token osservato dal client include rete, eventuale coda, prefill e prima emissione. Ridurre il prefill può migliorare il TTFT senza incidere proporzionalmente sulla durata totale di una risposta lunga. Il continuous batching permette di introdurre nuove richieste mentre altre sono in decode; il chunked prefill suddivide prompt lunghi per condividere meglio la GPU.

4. RoPE: perché eliminare token non risolve il problema delle posizioni

Le Rotary Position Embeddings (RoPE) codificano la posizione ruotando query e key: q′p = R(p)qp e k′p = R(p)kp. Per ogni coppia di coordinate, R(p) è una rotazione il cui angolo dipende dalla posizione e dalla frequenza. Il prodotto scalare fra query e key incorpora così una relazione posizionale.

Supponiamo di avere una traiettoria di 100.000 token e di eliminare dalla cache gli stati di 80.000 token intermedi. La cache attiva è più piccola, ma le posizioni dei token rimasti possono essere ancora molto elevate. Indice logico della traiettoria, numero di elementi KV attivi e indice RoPE non sono la stessa cosa.

Nel caso RoPE standard, un key già ruotato alla posizione p può essere idealmente trasportato alla posizione q applicando:

k′q = R(q) · R(p)^(-1) · k′p

È una proprietà della composizione delle rotazioni. Non implica però che un runtime generico possa spostare arbitrariamente tutti gli stati KV senza conseguenze: gli hidden state dipendono dalle informazioni che erano visibili quando sono stati calcolati, e varianti di RoPE possono avere requisiti differenti.

Errore concettuale frequente: ricollocare un key nella dimensione posizionale non equivale a ricalcolare il token con una storia di attenzione diversa.

5. Prefix caching e PagedAttention non sono sinonimi

Il prefix caching evita di ripetere il prefill quando due richieste condividono lo stesso prefisso tokenizzato. È particolarmente efficace con system prompt, istruzioni sugli strumenti e documenti statici. La somiglianza semantica non basta: serve l'identità dei token e degli altri fattori rilevanti per la cache.

Request A: [system][tools][document][question A]
Request B: [system][tools][document][question B]
            +----- shared prefix -----+
                     cached KV

In vLLM l'Automatic Prefix Caching usa hash dei blocchi che dipendono dai token e dal prefisso precedente. La gestione comprende reference count ed eviction. La documentazione descrive anche un cache_salt opzionale per isolare gruppi di fiducia, riducendo il rischio di canali laterali temporali fra tenant.

PagedAttention affronta invece l'allocazione: divide la KV cache in blocchi fisici non necessariamente contigui, mappati a una sequenza logica. Riduce sprechi di memoria e facilita la condivisione. Prefix caching è una tecnica di riutilizzo; PagedAttention è una tecnica di gestione della memoria. Possono essere combinate.

SGLang utilizza strutture radix per il riuso dei prefissi. Nei modelli ibridi, che combinano full attention, sliding-window attention e stati ricorrenti, la semantica del riuso cambia a seconda della componente: un checkpoint ricorrente non è intercambiabile con un normale blocco KV.

6. Il paper Cache Engineering for Agents: append, drop, repos

Il lavoro Cache Engineering for Agents propone di gestire la cache direttamente, senza riscrivere continuamente la traiettoria testuale dell'agente. Le operazioni fondamentali sono:

OperazioneEffettoObiettivo
append(x)Aggiunge KV dei nuovi tokenProseguire l'esecuzione
drop(P)Esclude selettivamente KV dalla futura attenzioneRidurre contesto attivo e memoria
reposModifica gli encoding posizionali dei key conservatiCompattare le posizioni senza re-prefill completo

La differenza rispetto alla summarization è decisiva. Se si sostituisce un tratto del prompt con un riassunto, il prefisso cambia e può essere necessario ricalcolare stati successivi. Se il runtime supporta drop, può escludere porzioni della cache dalle attenzioni future senza necessariamente rigenerare gli stati conservati.

Context engineering:
[A][B][C][D][E] -> summarize -> [A][S][E]
                              prefix modified / possible re-prefill

Cache engineering:
[A][B][C][D][E] -> drop KV(B,C,D) -> active [A][E]
                              retained states may be reused
                  -> repos -> adjusted position encodings

Negli esperimenti degli autori, la policy tool-response rolling-drop ottiene +1,7 punti di score medio e −27,7% di costo medio rispetto alla summarization a soglia. AKV riporta fino a 1,2× di throughput di output e fino a 1,5× di miglioramento relativo della latenza P95 nel proprio setup. Sono risultati sperimentali specifici, non prestazioni garantite di qualsiasi inference server.

7. History dependence: stessi token, cache diversa

Questo è il passaggio più sottile del paper. Immaginiamo due richieste che contengono gli stessi token A, B e C. Nel primo caso C è stato elaborato quando B era visibile; nel secondo B era già stato escluso con drop. Il vettore KV di C può essere diverso perché è diversa la storia dell'attenzione. Di conseguenza la sola identità dei token non determina più lo stato della cache.

Il serving engine AKV, costruito su SGLang, utilizza una struttura radix estesa con nodi che rappresentano le operazioni di drop, gestione dell'eviction consapevole dei riferimenti e segment-batch attention per ricostruire stati coerenti. Il riposizionamento richiede inoltre versioni dei key con encoding posizionali appropriati. È un problema di provenienza dello stato, non semplicemente di cache hit.

8. Inference serving: scheduling, eviction e offloading

TecnicaBeneficioTrade-off
Prefix cachingEvita prefill duplicatoMemoria per blocchi riutilizzabili
PagedAttentionRiduce frammentazioneGestione tabelle di blocchi
Chunked prefillMigliora coesistenza con decodeScheduling più complesso
KV quantizationMeno byte/tokenPossibili effetti numerici
CPU offloadingMaggiore capacità effettivaTrasferimenti e latenza
Disaggregated prefill/decodeWorker specializzatiTrasferimento KV fra worker
AKV drop/reposControllo del contesto attivoRuntime specializzato e semantica complessa

In un sistema disaggregato il costo di trasferimento della KV cache può diventare di primo ordine. Un risparmio nel calcolo non garantisce quindi un miglioramento end-to-end. Occorre misurare anche traffico GPU-GPU, GPU-CPU, congestione di rete, code e preemption.

9. Laboratorio: vLLM e client C#/.NET 10

Obiettivo: confrontare richieste con prefisso invariato e prefisso variabile, misurando TTFT e latenza totale. Il laboratorio verifica il prefix caching standard di vLLM, non implementa le operazioni AKV drop/repos. Per replicare AKV è necessario il repository degli autori e l'infrastruttura SGLang modificata.

9.1 Prerequisiti e server

Occorrono una GPU NVIDIA supportata, ambiente CUDA/driver compatibile, vLLM e .NET SDK 10. Il modello seguente è relativamente piccolo ma richiede comunque VRAM adeguata. Verificare le opzioni effettive con vllm serve --help, perché possono cambiare fra versioni.

vllm serve Qwen/Qwen2.5-1.5B-Instruct \
  --host 0.0.0.0 --port 8000 \
  --enable-prefix-caching --max-model-len 8192

# In un altro terminale:
dotnet new console -n KvCacheBench --framework net10.0
cd KvCacheBench

9.2 Program.cs completo, senza pacchetti esterni

using System.Diagnostics;
using System.Globalization;
using System.Text;
using System.Text.Json;

var endpoint = Environment.GetEnvironmentVariable("LLM_URL")
    ?? "http://localhost:8000";
var model = Environment.GetEnvironmentVariable("LLM_MODEL")
    ?? "Qwen/Qwen2.5-1.5B-Instruct";

using var http = new HttpClient {
    BaseAddress = new Uri(endpoint.TrimEnd('/') + "/"),
    Timeout = TimeSpan.FromMinutes(5)
};

// Il prefisso lungo rimane identico nei casi A e B.
var shared = string.Join("\n", Enumerable.Range(0, 100)
    .Select(i => $"Regola {i:D3}: descrivi trade-off " +
        "fra KV cache, prefill, decode e scheduling GPU."));

Console.WriteLine("case,iteration,ttft_ms,total_ms,output_chars");
foreach (var testCase in new[] { "A", "B", "C" }) {
    for (int i = 0; i < 14; i++) {
        var prefix = testCase == "C"
            ? $"Variante {i:D4}\n" + shared : shared;
        var payload = new {
            model,
            stream = true,
            temperature = 0,
            max_tokens = 120,
            messages = new object[] {
                new { role = "system", content =
                    "Rispondi in italiano, in modo tecnico e conciso." },
                new { role = "user", content = prefix +
                    $"\n\nSpiega il concetto {i:D2} di KV cache." }
            }
        };
        using var req = new HttpRequestMessage(
            HttpMethod.Post, "v1/chat/completions") {
            Content = new StringContent(JsonSerializer.Serialize(payload),
                Encoding.UTF8, "application/json")
        };
        var watch = 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? ttft = null;
        int chars = 0;
        while (await reader.ReadLineAsync() is { } line) {
            if (!line.StartsWith("data: ", StringComparison.Ordinal))
                continue;
            var data = line[6..];
            if (data == "[DONE]") break;
            using var doc = JsonDocument.Parse(data);
            if (!doc.RootElement.TryGetProperty("choices", out var choices)
                || choices.GetArrayLength() == 0) continue;
            var choice = choices[0];
            if (!choice.TryGetProperty("delta", out var delta)
                || !delta.TryGetProperty("content", out var content)
                || content.ValueKind != JsonValueKind.String) continue;
            var fragment = content.GetString();
            if (string.IsNullOrEmpty(fragment)) continue;
            ttft ??= watch.Elapsed.TotalMilliseconds;
            chars += fragment.Length;
        }
        watch.Stop();
        if (i >= 2) Console.WriteLine(string.Join(",",
            testCase, (i - 2).ToString(),
            ttft?.ToString("F2", CultureInfo.InvariantCulture) ?? "",
            watch.Elapsed.TotalMilliseconds.ToString("F2",
                CultureInfo.InvariantCulture), chars.ToString()));
    }
}

Il programma esegue 2 richieste di warm-up e 12 richieste misurate per ciascun caso. A e B condividono il prefisso; C lo altera prima del blocco comune. Le richieste sono sequenziali per isolare il riuso, quindi non costituiscono un test di concorrenza. L'ordine A-B-C può favorire il warm-up della cache: ripetere i test invertendo l'ordine e riavviando il server fra configurazioni.

9.3 Esecuzione e protocollo

# Linux / macOS
export LLM_URL=http://localhost:8000
export LLM_MODEL=Qwen/Qwen2.5-1.5B-Instruct
dotnet run -c Release > results.csv

# PowerShell
$env:LLM_URL = "http://localhost:8000"
$env:LLM_MODEL = "Qwen/Qwen2.5-1.5B-Instruct"
dotnet run -c Release | Out-File results.csv

Ripetere con prefix caching abilitato e disabilitato, mantenendo identici modello, precisione, GPU e limiti di contesto. Eseguire più repliche indipendenti, annotare la versione del runtime e acquisire anche le metriche server. Il ttft_ms misura il primo frammento di contenuto nello stream, non il primo byte di rete. output_chars non equivale ai token generati: per token/s usare i contatori del server o un tokenizer compatibile.

10. Metriche e interpretazione corretta

MetricaSignificatoAttenzione
TTFTTempo al primo token visibileInclude rete, coda e prefill
ITL / TPOTTempo fra token successiviDipende dal batching
P50/P95/P99Distribuzione delle latenzeServono campioni sufficienti
Prefix cache hit rateQuota di prefisso riutilizzataDefinizione runtime-specifica
KV cache usagePressione sulla cacheNon è tutta la VRAM usata
Output token/sThroughput di generazioneDistinguere per richiesta e aggregato
Cost per correct taskCosto per task verificatoRichiede un valutatore esterno

vLLM espone metriche Prometheus su /metrics; nomi e disponibilità dipendono dalla versione. Fra le famiglie rilevanti: utilizzo KV, query e hit del prefix cache, richieste attive, TTFT e latenza end-to-end. Un hit rate su finestra temporale va calcolato usando variazioni dei contatori nella stessa finestra, non confrontando valori cumulativi di intervalli differenti.

La metrica decisiva per gli agenti non è il solo costo/token: costo per task completato correttamente. Una policy aggressiva può ridurre il contesto attivo e peggiorare l'accuratezza. La valutazione deve includere task fissi, verificatori deterministici, errori di tool calling e regressioni funzionali.

11. Architettura di produzione: cache non significa memoria durevole

ASP.NET Core / Agent API
          |
    AuthN / AuthZ / Tenant
          |
    Agent Orchestrator ---- Durable state / checkpoint
          |                       |
      Model Gateway        Memory / tool results
          |
    Cache policy + routing
          |
   +------+-------+
   |              |
GPU worker A   GPU worker B
KV cache       KV cache
   |              |
   +------+-------+
          |
 Metrics / tracing / audit

Lo stato durevole dell'agente descrive decisioni, tool call, risultati e checkpoint necessari al recovery. La KV cache è un'accelerazione computazionale, spesso volatile. Se un worker GPU si arresta, l'agente deve poter ripartire dalla traiettoria persistita anche quando tutta la cache è andata persa.

Per il multi-tenant, attenzione al riuso di prefissi fra gruppi di fiducia: differenze di latenza possono rivelare indirettamente informazioni. Isolamento della cache, autorizzazioni e politiche di retention devono essere coerenti. Inoltre una tool response malevola rimane non attendibile anche se è già stata memorizzata nella cache.

12. Conclusioni

Il Cache Engineering sposta l'ottimizzazione degli agenti dal solo testo del prompt allo stato computazionale dell'attenzione. Prefix caching e PagedAttention sono oggi strumenti concreti di ottimizzazione del serving; le operazioni drop e repos di AKV rappresentano una direzione di ricerca più avanzata che richiede un runtime specializzato.

Le tre regole operative sono: misurare separatamente prefill, decode e occupazione KV; non riutilizzare stati senza rispettarne la storia; non confondere mai cache GPU e persistenza dell'agente. Il miglioramento più importante non è il costo per token, ma il costo per task corretto e verificabile.

Fonti tecniche e scientifiche

  1. Cache Engineering for Agents — paper (2026)
  2. AKV — codice degli autori
  3. vLLM — Automatic Prefix Caching
  4. vLLM — documentazione e serving
  5. PagedAttention — Hugging Face
  6. Rotary Embeddings — Hugging Face
  7. Transformers — Cache Explanation
  8. SGLang — Unified Radix Cache

Nota metodologica: i numeri AKV sono risultati sperimentali degli autori. Il laboratorio proposto verifica il prefix caching standard, non replica AKV. Controllare la versione delle CLI e la compatibilità GPU prima dell'esecuzione.