系列第 4 篇（共 4 篇）｜難度：L3-熟練
前置知識：已讀第 1、2、3 篇，熟悉 KV Cache、PagedAttention 與 vLLM 調參

一句話說明

LMCache 就是「KV Cache 的外接倉庫」：把算過的前綴（system prompt、RAG 文件、對話歷史）的 KV Cache 存到 CPU 記憶體、本地磁碟甚至遠端，下次遇到一樣的前綴就直接搬回來用，不用重算，TTFT（第一個 token 出來的時間）直接砍掉一大截。

如果你是用 AI 幫你接 vLLM 的 Vibe Coder，這篇教你看懂 AI 產的設定檔在幹嘛、怎麼確認快取真的有命中、哪些坑要盯著。

先搞懂問題：為什麼要快取 KV Cache

回顧一下前幾篇：模型每收到一段 prompt，會把每個 token 算成一堆中間狀態（就是 KV Cache）存在 GPU 顯存裡，後面生成才用得到。

問題來了——很多請求的「開頭」其實一模一樣：

請求 A: [3000 字的 system prompt] + 「幫我寫一封信」
請求 B: [3000 字的 system prompt] + 「幫我翻譯這段」
請求 C: [3000 字的 system prompt] + 「總結一下重點」
Code language: CSS (css)

這 3000 字的 system prompt，每一次請求都要重新算一遍 KV Cache。這叫 prefill（預填充），是 TTFT 的主要成本。前綴越長，使用者等越久。

RAG 更誇張：你把同一份文件塞進 context 問十個問題，那份文件的 KV Cache 就被白算了十次。多輪對話也一樣，第 5 輪要把前 4 輪的歷史全部重算。

核心洞察：相同的前綴 → 相同的 KV Cache → 應該只算一次。

第一層：vLLM 內建的 Automatic Prefix Caching

vLLM 自己就有一個輕量版解法，一個 flag 就開：

vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --enable-prefix-caching

這在幹嘛：開啟後，vLLM 會記住「已經算過的前綴」對應的 KV Cache block（還記得第 2 篇 PagedAttention 把 KV Cache 切成一塊塊 block 嗎？就是那個）。下一個請求如果開頭 token 完全一樣，就直接重用那些 block，跳過重算。

新版 vLLM（0.6+）的 V1 引擎預設就開 prefix caching，你可能連 flag 都不用加。看到 AI 沒加這個 flag 別急著說它漏了，先確認版本。

但它有個天花板：這些重用的 block 只活在 GPU 顯存裡。顯存很貴很小，一旦裝不下就會被擠掉（evict）。所以：

• 前綴多到 GPU 放不下 → 舊的被踢掉 → 下次又要重算
• vLLM 重啟 → 快取全沒了 → 重頭來過
• 多台機器 → 各自為政，A 機器算過的 B 機器用不到

這就是 LMCache 要補的洞。

第二層：LMCache 是什麼

LMCache 是一個外掛的 KV Cache 分層儲存系統。它把 GPU 放不下的 KV Cache「卸載（offload）」到更大更便宜的地方：

        快              →              慢
        小              →              大
  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌──────────┐
  │   GPU     │  │   CPU     │  │  本地磁碟  │  │  遠端     │
  │  顯存     │  │  記憶體    │  │  (SSD)    │  │ (Redis等) │
  └──────────┘  └──────────┘  └──────────┘  └──────────┘
   vLLM 原生      ← LMCache 幫你多接的這幾層 →

用白話講：GPU 顯存像你桌上的一小塊空間，只放最常用的東西；LMCache 幫你多開了抽屜（CPU）、櫃子（磁碟）、甚至倉庫（遠端），東西放不下就往外挪，要用再拿回來。就算「拿回來」也比「重新算一遍」快得多。

它帶來三個 GPU 原生做不到的能力：

1. 跨會話重用：使用者關掉對話明天再來，前綴 KV Cache 還在磁碟上，不用重算。
2. 容量放大：CPU 記憶體通常是顯存的好幾倍，能快取的前綴多非常多。
3. 跨實例共享（進階）：多個 vLLM 實例可以共用一個遠端 KV Cache 池。

實作：把 LMCache 接上 vLLM

步驟 1：安裝

pip install lmcache

LMCache 對 vLLM 版本很敏感。務必確認兩者版本相容（見官方相容表），版本對不上是最常見的翻車點。

步驟 2：用 KV Connector 接上 vLLM

新版 vLLM 透過 KV Connector 這個插槽機制接外部快取。你會看到 AI 產出類似這樣的啟動指令：

LMCACHE_CONFIG_FILE=lmcache.yaml \
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --enable-prefix-caching \
  --kv-transfer-config \
  '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
Code language: JavaScript (javascript)

逐行翻譯：

步驟 3：LMCache 設定檔（lmcache.yaml）

# 每個 KV chunk 的 token 數，要跟 vLLM 對齊
chunk_size: 256

# 開啟 CPU 記憶體這一層，給它 20GB
local_cpu: true
max_local_cpu_size: 20      # 單位 GB

# 開啟本地磁碟這一層，給它 100GB
local_disk: "file:///tmp/lmcache"
max_local_disk_size: 100    # 單位 GB
Code language: PHP (php)

這份設定在幹嘛：告訴 LMCache「GPU 放不下的 KV Cache，先往 CPU 挪（最多 20GB），CPU 也滿了就寫到磁碟 /tmp/lmcache（最多 100GB）」。

也可以完全用環境變數設定，AI 有時會這樣寫，看到別困惑，是同一件事：

export LMCACHE_CHUNK_SIZE=256
export LMCACHE_LOCAL_CPU=True
export LMCACHE_MAX_LOCAL_CPU_SIZE=20
Code language: JavaScript (javascript)

✅ 必看懂 / 📌 知道就好

✅ 必看懂（判斷 AI 有沒有接對）：
- --enable-prefix-caching 有沒有開
- --kv-transfer-config 裡有沒有 LMCacheConnector
- lmcache.yaml 有沒有真的分配 CPU / 磁碟空間

📌 知道就好（遇到再查）：
- kv_role 的 kv_producer / kv_consumer 拆分（做 P/D 分離才需要）
- chunk_size 怎麼調（預設能跑就先別動）

🕰️ 認得就好（舊寫法，維護舊專案會遇到）：
- LMCacheConnector（V1 之前的舊 connector 名稱）
- 舊版用 --kv-transfer-config 以外的接法

什麼場景值得導入？效益怎麼判斷

LMCache 不是萬靈丹。判斷值不值得，就看一個問題：你的請求前綴重複率高不高？

判斷心法：前綴越長、重複越多、prefill 佔比越高，LMCache 賺越多。反過來，如果你的請求又短又不重複，加了 LMCache 只是徒增複雜度和一層搬運開銷。

一個粗略的直覺：如果一個請求的 TTFT 主要花在算那 3000 字的固定 system prompt 上，LMCache 命中後，TTFT 可能從「秒級」掉到「百毫秒級」。前綴越長，這個差距越誇張。

Vibe Coder 驗收檢查點

AI 幫你接好了說「搞定，快取已啟用」——別信，自己驗。

檢查點 1：確認服務有掛上 LMCache

啟動 vLLM 時看 log，應該有 LMCache 初始化的訊息：

預期看到：LMCache 相關的 init log，例如載入 connector、
         配置 CPU/disk backend 的行。
沒看到 → connector 沒接上，多半是 --kv-transfer-config 寫錯或版本不合。

檢查點 2：跑兩次相同前綴，比 TTFT

這是最實在的驗收——同一個長 prompt 打兩次：

第 1 次請求：冷啟動，要算 KV Cache → TTFT 較高（例如 1.2s）
第 2 次請求：命中快取，直接搬 → TTFT 明顯下降（例如 0.2s）
Code language: CSS (css)

如果第二次沒有明顯變快，就是快取根本沒命中，接的有問題。

檢查點 3：看 cache hit 指標 / 日誌

觀察 LMCache 的命中日誌或 vLLM 的 metrics（/metrics 端點）裡跟 prefix cache hit rate 相關的數字。命中率高 = 有在賺；一直是 0 = 白接了。

不確定怎麼看指標？把 log 貼給 AI 問：「這段 vLLM/LMCache 的 log 裡，怎麼判斷 KV Cache 有沒有命中？命中率在哪一行？」

🚩 紅旗：這些地方 AI 特別容易踩

🚩 紅旗 1：只加了 flag 卻沒驗證命中

vllm serve ... --enable-prefix-caching   # AI：「快取已開啟！」
Code language: PHP (php)

開了 flag ≠ 真的有命中。前綴只要差一個 token（連空格、標點都算）就整段 miss。一定要用「檢查點 2」實測 TTFT，不要看到 flag 就收貨。

🚩 紅旗 2：版本沒對就直接裝

pip install lmcache   # 沒指定版本，也沒對照 vLLM 版本
Code language: PHP (php)

LMCache 跟 vLLM 綁很緊，版本不合會出現「connector 載入失敗」或更隱晦的「服務起得來但快取永遠 miss」。看到 AI 沒提版本相容，主動問它：「我的 vLLM 是 x.y.z，這個 LMCache 版本相容嗎？」

🚩 紅旗 3：磁碟快取無上限或塞到系統碟

local_disk: "file:///tmp/lmcache"
# 🚩 沒設 max_local_disk_size，或指到會被清空的 /tmp
Code language: PHP (php)

沒設上限的磁碟快取會把硬碟吃爆；指到 /tmp 可能重開機就沒了，或跟系統搶空間。要確認有 max_local_disk_size，且路徑放在夠大、不會被清的磁碟上。

🚩 紅旗 4：把「記憶體換磁碟」當免費

往磁碟卸載雖然比重算快，但磁碟讀取 KV Cache 也是有延遲的。如果你的 SSD 慢、或前綴其實不長，「從磁碟搬回來」可能沒比「重算」快多少。別預設「多加幾層一定更快」，要用 TTFT 實測。

🚩 紅旗 5：以為快取會自己「更新」

KV Cache 是綁定「模型 + 前綴內容」的。換了模型、改了 system prompt 內容，舊快取就該失效。如果 AI 沒處理快取失效邏輯，你可能吃到「上一版 prompt 算出來的舊快取」。改動前綴後，觀察 TTFT 是否回到冷啟動水準來確認舊快取沒被誤用。

系列總結

四篇走下來，你手上的 vLLM 心智模型應該是這樣的：

1. #01 KV Cache：搞懂為什麼推論會吃顯存、KV Cache 是什麼。
2. #02 PagedAttention：顯存怎麼被切成 block 高效管理、前綴怎麼共享。
3. #03 調參：--gpu-memory-utilization、--max-model-len 這些旋鈕怎麼轉。
4. #04 LMCache（本篇）：把 KV Cache 快取到 GPU 之外，讓重複前綴跨請求、跨會話重用。

作為 Vibe Coder，你不需要自己刻這些系統，但你要能看懂 AI 接的設定、實測驗收、抓出「看起來有開其實沒命中」的假象。這就是把 AI 當成一個超快但偶爾唬爛的工程師時，你這個驗收者該有的手感。

看不懂就這樣問 AI

「用白話解釋這段 vLLM 啟動指令裡的 --kv-transfer-config 在幹嘛，我是 Vibe Coder。」

「我的 vLLM 版本是 ___，要裝哪個版本的 LMCache 才相容？幫我列出對照。」

「幫我寫一個小腳本，對同一個長 prompt 連打兩次，印出兩次的 TTFT，讓我確認 KV Cache 有沒有命中。」

「我的場景是 ___（RAG／長 system prompt／多輪對話），前綴大概 ___ 個 token，導入 LMCache 大概能省多少 TTFT？值得嗎？」