【LMCache 入門到實戰】系列 #02（共 4 篇）｜難度：L2-進階

第 1 篇我們搞懂了 LMCache 是幹嘛的：它把 vLLM 算過的 KV Cache 存下來重複使用， 讓「同樣的前綴不用重算第二次」，省下第一個 token 的等待時間（TTFT）。

這篇要動手了。但你八成是叫 AI 幫你把環境架起來、把 vLLM 的啟動指令生出來—— 所以這篇的重點不是要你背指令，而是教你看懂 AI 交出來的安裝步驟和啟動設定、實際跑一次、確認 cache 是真的有生效。

因為這裡最容易出的坑是：跑起來了、也有輸出，但 LMCache 根本沒被載入，你以為在省時間其實一秒都沒省。

一句話說明

安裝 LMCache = 裝一個 Python 套件（lmcache）； 與 vLLM 整合 = 在啟動 vLLM 時，透過一個叫 KV Connector 的設定，告訴 vLLM「算完的 KV Cache 交給 LMCache 保管」。

你不用改任何模型程式碼，整合幾乎都是啟動時的設定。所以看懂設定，就看懂了八成。

環境需求：先對版本，不然全白搭

LMCache 對環境很挑，這是新手最常卡的地方。動手前先確認四件事：

最關鍵、也最常爆的是最後一項。LMCache 是「掛」在 vLLM 上跑的， vLLM 的 KV Connector 介面改版很勤，版本沒對上，connector 就載不起來。

🚩 先記住這個紅旗：等一下如果你看到 log 裡有 KeyError、connector not found、
或 AttributeError 之類的字，八成就是 vLLM 跟 LMCache 版本不合。

最小安裝：兩行指令

AI 最常交給你的安裝步驟長這樣：

# 建議先開一個乾淨的虛擬環境（避免污染系統 Python）
uv venv && source .venv/bin/activate

# 安裝 vLLM 和 LMCache
uv pip install vllm
uv pip install lmcache
Code language: PHP (php)

逐行翻譯：

• uv venv → 開一個獨立的 Python 環境，套件裝在這個資料夾裡，不會弄髒系統。
• uv pip install vllm → 裝推論引擎 vLLM（會一起拉進 PyTorch、CUDA 相關的一大包）。
• uv pip install lmcache → 裝 LMCache 本體。

📌 知道就好：有些教學會叫你用 pip 而不是 uv pip，效果一樣，uv 只是比較快。
也有人一行 pip install "vllm[lmcache]" 一次裝好，但**分開裝比較好抓版本問題**。

裝完先驗一下有沒有真的裝進去：

python -c "import lmcache; print(lmcache.__version__)"
python -c "import vllm; print(vllm.__version__)"
Code language: JavaScript (javascript)

兩行都印出版本號 = 套件本身沒問題。印不出來、報 ModuleNotFoundError = 沒裝成功，別往下走。

最小可運行範例：讓 vLLM 帶上 LMCache 跑起來

整合的核心只有一件事：啟動 vLLM 時，多給它一個 KV Connector 設定。 AI 最常給你的是這種「環境變數 + 啟動指令」的組合：

# 1. 用環境變數指定 LMCache 的設定檔
export LMCACHE_CONFIG_FILE="lmcache_config.yaml"

# 2. 啟動 vLLM，並掛上 LMCache 這個 KV connector
vllm serve meta-llama/Llama-3.1-8B-Instruct \
  --kv-transfer-config \
  '{"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}'
Code language: PHP (php)

這段是整篇最重要的部分，逐行拆給你看：

• vllm serve meta-llama/Llama-3.1-8B-Instruct
• --kv-transfer-config '...'
• "kv_connector":"LMCacheConnectorV1"
• "kv_role":"kv_both"
• export LMCACHE_CONFIG_FILE=...

翻成白話就是：

「啟動 Llama-3.1-8B 這個模型，
KV Cache 的存取交給 LMCache 處理，
LMCache 的細節設定在 lmcache_config.yaml 裡。」

設定檔逐行翻譯：lmcache_config.yaml

上面那個 yaml 檔，入門版長這樣，每一行都值得認得：

# lmcache_config.yaml
chunk_size: 256          # 每個 KV cache「切塊」的大小（token 數）
local_cpu: true          # 把 KV cache 存一份在 CPU 記憶體（RAM）
max_local_cpu_size: 5.0  # CPU 快取最多用 5 GB
Code language: PHP (php)

對照翻譯：

📌 知道就好：chunk_size 影響「命中的精細度」。太大 → 前綴要一模一樣才命中；
太小 → 比對開銷變多。**入門階段用預設 256，先讓它動起來再說。**

還有一層你會聽到的是「儲存後端」——快取除了放本機 CPU/GPU，還能放遠端（例如另一台機器、Redis）。 入門只要知道：先用 local_cpu 這種本機快取，遠端後端是後面篇章的事。

常見變化：AI 可能怎麼寫

同樣是「啟用 LMCache」，AI 給你的寫法可能長得不太一樣，認得就好：

變化 1：全部塞進環境變數，不用 yaml 檔

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

→ 跟 yaml 檔等價，只是改用環境變數設定。適合寫在啟動腳本裡。

變化 2：舊版的 connector 名稱

# 🕰️ 認得就好：舊教學會看到這種寫法
--kv-transfer-config '{"kv_connector":"LMCacheConnector", ...}'
Code language: PHP (php)

→ 注意結尾沒有 V1。這是舊介面。如果你照抄舊教學卻用新版 vLLM，很可能載不起來。 以官方目前文件的 LMCacheConnectorV1 為準。

變化 3：用 Python 直接跑（不走 vllm serve 指令）

from vllm import LLM
from vllm.config import KVTransferConfig

llm = LLM(
    model="meta-llama/Llama-3.1-8B-Instruct",
    kv_transfer_config=KVTransferConfig(
        kv_connector="LMCacheConnectorV1",
        kv_role="kv_both",
    ),
)
Code language: JavaScript (javascript)

→ 跟指令列版本做的事一樣，只是寫在 Python 裡。設定的鍵名（kv_connector、kv_role）完全一致。

驗收：怎麼確認 cache 真的生效？（這段最重要）

跑起來 ≠ 有效。 LMCache 最陰的地方是：就算它根本沒載入，vLLM 照樣正常回答，你完全看不出來。 所以一定要主動驗證。方法是發兩次一樣的請求，看第二次有沒有變快。

第一步，開好伺服器後，連續打兩次內容相同的請求：

# 送一段長 prompt，記錄回應時間；同一個 prompt 再送一次
curl http://localhost:8000/v1/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"meta-llama/Llama-3.1-8B-Instruct","prompt":"<貼一段很長的固定文字>","max_tokens":10}'
Code language: PHP (php)

第二步，看 vLLM 伺服器那側的 log。有生效的話會看到 LMCache 印出類似這樣的訊息：

LMCache INFO: Reqid: ... , Store KV cache ...   # 第一次：把 cache 存起來
LMCache INFO: Reqid: ... , Retrieve KV cache ... hit tokens: 512   # 第二次：命中！讀到 512 個 token
Code language: PHP (php)

判讀重點：

• 看到 Retrieve 且 hit tokens 大於 0 → cache 命中了，成功。
• 只有 Store 沒有 Retrieve、或 hit tokens: 0 → 沒命中，往下看紅旗排查。
• log 裡完全沒有任何 LMCache 字樣 → connector 根本沒載入（最常見的假成功）。

第三步（進階一點），觀察 TTFT（Time To First Token，第一個 token 多久吐出來）。 第二次相同請求的 TTFT 應該明顯低於第一次——這就是 LMCache 幫你省下的時間。

🚩 紅旗：看到這些要警覺

🟡 紅旗 1：log 裡完全沒有 LMCache 字樣

症狀：vLLM 跑得好好的，但整份 log 搜不到 LMCache。 意思：connector 沒載入，你以為在用快取，其實一秒都沒省。這是最常見的「假成功」。 怎麼發現：grep -i lmcache vllm.log，什麼都沒有就中了。 跟 AI 這樣說：「vLLM 有起來但 log 完全沒有 LMCache 訊息，幫我檢查 --kv-transfer-config 的 connector 名稱和我的 vLLM 版本是否相容。」

🟡 紅旗 2：版本不相容導致 connector 載入失敗

症狀：啟動時報 KeyError: 'LMCacheConnectorV1'、AttributeError、或 connector not found。 意思：vLLM 跟 LMCache 版本對不上，介面兜不起來。 跟 AI 這樣說：「我的 vLLM 是 <版本>、LMCache 是 <版本>（pip show vllm lmcache 的結果貼上），這兩個版本相容嗎？該用哪個 connector 名稱？」

🟡 紅旗 3：cache 永遠 miss（hit tokens: 0）

症狀：LMCache 有載入、也有 Store，但第二次請求還是 hit tokens: 0。 常見原因：兩次 prompt 其實不完全一樣（多了空白、時間戳、隨機 ID），或 prompt 比一個 chunk_size 還短根本存不進去。 驗收動作：先確定兩次送的 prompt 是逐字相同且夠長（至少超過一個 chunk）。 跟 AI 這樣說：「我送兩次相同 prompt 但 hit tokens 一直是 0，幫我檢查 prompt 是否完全一致、以及是否超過 chunk_size。」

🟡 紅旗 4：把金鑰或路徑寫死在啟動指令裡

export HF_TOKEN="hf_abcd1234..."   # 🚩 token 直接寫在指令/腳本裡
Code language: PHP (php)

為什麼危險：腳本一進 git 或貼給別人，Hugging Face token 就外洩了。 跟 AI 這樣說：「把 HF_TOKEN 改成從環境變數或 .env 讀，不要寫死在啟動腳本裡。」

Vibe Coder 驗收檢查點

按順序做，每一步都有明確的預期結果：

• [ ] 套件裝好：python -c "import lmcache, vllm; print(lmcache.__version__, vllm.__version__)"
• [ ] 版本相容：把上面兩個版本號貼給 AI 問「這兩個版本的 LMCache 和 vLLM 相容嗎？」
• [ ] 伺服器起得來：vllm serve ... 帶上 --kv-transfer-config 後，log 出現 LMCache INFO（而不是報錯）。
• [ ] cache 真的命中：連送兩次逐字相同的長 prompt，第二次的 log 出現 Retrieve 且 hit tokens > 0。
• [ ] 速度真的變快：第二次相同請求的 TTFT 明顯低於第一次。

四項全過，才算真的「整合成功」，不是「跑起來」就算。

看不懂就這樣問 AI

「我用 vllm serve 加了 --kv-transfer-config 啟動 LMCache，
但不確定有沒有生效。這是我的啟動指令和一段 log（貼上），
幫我判斷 LMCache 有沒有真的載入、cache 有沒有命中，一步步告訴我怎麼確認。」

「用白話解釋 {"kv_connector":"LMCacheConnectorV1","kv_role":"kv_both"}
這段設定每個欄位在幹嘛，我是第一次用 LMCache。」

小結

這篇你學到的不是「背啟動指令」，而是三個判斷力：

1. 裝之前先對版本——vLLM 跟 LMCache 版本不合，後面全白搭。
2. 整合的核心是 --kv-transfer-config——看懂這個 JSON 就看懂了整合。
3. 跑起來 ≠ 生效——一定要用「送兩次相同 prompt、看 log 有沒有 Retrieve / hit tokens」來驗收。

下一篇（#03）我們會把設定調得更講究：chunk_size 怎麼影響命中率、CPU/GPU 快取怎麼分層、 以及把快取放到遠端後端，讓多個 vLLM 實例共用同一份 KV Cache。