AI Phase 05 — Inference / Local AI / Hardware(Day 41–50)

100-Day AI Knowledge Challenge

AI Phase 05 — Inference / Local AI / Hardware(Day 41–50)

這 10 天要補的是 application-level 工程師最容易漏掉的一塊:API 後面的 model 到底怎麼被 serve。能講清楚 quantization、KV cache、batching、concurrency、throughput、GPU memory,才會跟「只會呼叫 LLM API 的 developer」拉開差距1。核心 mental model 是 Model ≠ Runtime ≠ Server ≠ API ≠ Application,Day 41 先把這五層分開,之後每一天都在回答「這個問題發生在哪一層」2。

主線是 vLLM 官方文件(Read → Run → Benchmark,不用讀完每一頁);搭配 Ollama 官方文件與 llama.cpp 兩條「在自己電腦跑」的路線,以及 Hugging Face 的 GGUF、KV cache、continuous batching 文件。總綱把 DeepLearning.AI 的 vLLM/SGLang 推論短課列為搭配資源,但 2026-10-16 查證時課程列表頁沒有看到這兩門(只看到一門 Cerebras 推論課與一個 Compression and Quantization 分類),所以本 Phase 只引用實際查到的 Quantization Fundamentals with Hugging Face,放在 Day 43 的 Companion3。

總綱第 4 節的重疊對照表沒有列 Phase 05,所以這個 Phase 沒有需要引用 Backend 課程的重疊日4。

兩條 serving 路線貫穿全 Phase5:

Model → Ollama / llama.cpp → Local API → Your backend
Model → vLLM → OpenAI-compatible API → Your backend

Phase 驗收是 Project 1(Local LLM Serving):Model → llama.cpp / vLLM → API → Backend,並附 hardware、quantization、latency、throughput、memory 的實測數據6。對應關係:Day 41–45 是概念與估算(硬體、量化、KV cache、batching),Day 46–48 是三個 runtime 各跑一次,Day 49 是量測方法,Day 50 把前面的數據組成 Project 1。

這個 Phase 的硬體現實: vLLM 的 Quickstart 以 NVIDIA CUDA 為主要安裝路徑;CPU 路徑在 Apple silicon 上沒有預建 wheel、要從原始碼建置,頁面標註為實驗性(見 Day 48)。如果你只有 Mac 或沒有 GPU,Project 1 以 Ollama 或 llama.cpp 為主路線即可,Day 48 改做「讀懂 vLLM 的設定並在 notes 寫出預期差異」,需要實跑時再借用雲端 GPU,並在實測表標明環境。下面所有帶數字的實作輸出,只有純 Python 的估算與模擬是教材作者實際跑過的;Ollama、llama.cpp、vLLM 的指令輸出以你機器上的結果為準。

本 Phase 的 Python 程式碼只用標準函式庫(不需要 pip install 任何東西);Day 44 的設定值請從你選的 model 的 config.json 取得。

Day 41 — Model ≠ Runtime ≠ Server ≠ API ≠ Application

今天要回答的問題

當你的 backend 呼叫 /v1/chat/completions,從那一行 HTTP 請求到 GPU 上的矩陣運算,中間經過哪幾層?每一層各自負責什麼?

主教材(Core)

  • vLLM 文件 — Quickstart(Offline Batched Inference 與 Online Serving 兩節,只讀不裝),預估 25 分鐘
  • vLLM 文件 — Online Serving(OpenAI-Compatible Server 一節與支援的 API 清單),預估 20 分鐘
  • Ollama 文件 — Quickstart(Run a model locally 一節),預估 15 分鐘
  • 實作,預估 45 分鐘

搭配(Companion,選讀)

  • Ollama 文件 — API introduction(Base URLs 一節),對照「原生 API」與「OpenAI 相容 API」是兩個不同的 URL 前綴;預估 10 分鐘

讀的時候抓這幾個重點

  • Model 只是一組 weight 檔案。 它自己不會監聽任何 port,也不知道什麼是 HTTP。Hugging Face 上下載的 safetensors 或 GGUF 檔案就是 model。
  • Runtime 負責把 weight 載進記憶體並做運算。 vLLM Quickstart 的 Offline Batched Inference 一節直接在 Python 裡 LLM(model=...) 然後 llm.generate(...),沒有任何 server,這正是「runtime 不等於 server」的最好證據。
  • Server 把 runtime 包成網路服務。 同一頁的 Online Serving 一節用 vllm serve <model> 啟動 server,預設在 http://localhost:8000,並且提供 OpenAI 相容的 /v1/models、/v1/completions、/v1/chat/completions。Ollama 則是 ollama serve,本機預設 port 是 11434。
  • API 是契約,不是實作。 兩家都提供 OpenAI 相容的路徑,所以你的 backend 只要換 base_url 就能切換 runtime。最容易誤會的是「相容」不等於「完全一樣」:Ollama 的 OpenAI 相容頁面明列了不支援的欄位(例如 chat completions 的 logprobs、tool_choice、n),換 runtime 前要先查這張清單。

實作

不用安裝任何東西,先用文字把五層畫出來。在 notes.md 建立下面這張表,並用 Quickstart 頁面的實際內容填完「對應到的東西」與「這一層出問題時的症狀」兩欄:

層它是什麼對應到的東西(vLLM 路線 / Ollama 路線)這一層出問題時的症狀
Modelweight 檔案
Runtime載入 weight、做運算
Server把 runtime 變成網路服務
API請求/回應的契約
Application你的 backend

接著寫一段 5 行以內的流程:你的 backend 送出一次 chat 請求,依序經過哪些層。預期:每一欄都有具體內容,不能只寫「vLLM」或「Ollama」這種籠統的名字。

過關標準

  • 能回答:「vLLM 的 offline inference 與 vllm serve 差在哪一層?」
  • 能回答:為什麼 backend 換 runtime 時,只改 base_url 還不一定夠?
  • 產出:notes.md 裡填完的五層表與 5 行流程
  1. 依 AI 課程線總綱(curriculum/ai/00-master-curriculum.md)第 10 節「Phase 05 — Inference / Local AI / Hardware」的目標
  2. 依總綱第 10 節「實作」最後一句:這個實驗會讓你真正理解 Model ≠ Runtime ≠ Server ≠ API ≠ Application
  3. 依總綱第 10 節的主線與搭配,以及第 17 節資源總表
  4. 依總綱第 4 節跟 Backend 課程的重疊對照表(表中沒有 Phase 05)
  5. 依總綱第 10 節「實作」的兩條流程
  6. 依總綱第 10 節「驗收 → Project 1:Local LLM Serving」

Day 42 — 硬體與記憶體:model 放得下嗎?

今天要回答的問題

一個 8B 參數的 model,用不同精度存放要多少記憶體?為什麼「放得下 weight」還不代表「跑得動」?

主教材(Core)

  • llama.cpp 文件 — llama-quantize README(Memory/Disk Requirements 一節的 Llama-3.1-8B 量測表:quant、bits/weight、size、prompt t/s、generation t/s),預估 25 分鐘
  • llama.cpp 文件 — README 的 Supported backends(只看清單:Metal、CUDA、HIP、Vulkan、SYCL 等),預估 10 分鐘
  • 實作,預估 60 分鐘

搭配(Companion,選讀)

  • vLLM 文件 — Installation(各硬體平台清單,含 GPU、CPU、Apple silicon),預估 10 分鐘

讀的時候抓這幾個重點

  • Weight 的大小 ≈ 參數量 × 每個參數的 bit 數 ÷ 8。 量測表把這件事寫成 bits/weight 與 size 兩欄,你可以用其中一列反推參數量,再驗證其他列。這個估算是整個 Phase 最常用的一條公式。
  • 量化後的 bits/weight 不是整數。 例如表中 Q4_K_M 約 4.89 bits/weight,而不是 4,因為每個 block 還要存 scale 等額外資訊。看到「4-bit」就當成剛好 4 bit 算,會低估記憶體。
  • 表中的速度欄是該頁作者的機器量到的,不是你的。 它的用途是讓你看趨勢:同一個 model,bits 變少,generation 速度通常變快(因為每個 token 要搬的 weight 變少)。你的數字要自己量(Day 47、49)。
  • Weight 只是記憶體的一部分。 執行時還要放 KV cache 與 activation,這是 Day 44 的主題。今天只算 weight,並且在 notes 裡明確寫「這不含 KV cache」。

實作

用表中的數字驗證公式(純標準函式庫即可):

# (quant, bits_per_weight, size_GiB):llama.cpp tools/quantize README,Llama-3.1-8B 量測表
rows = [("Q2_K", 3.1593, 2.95), ("Q4_K_M", 4.8944, 4.58), ("Q6_K", 6.5633, 6.14),
        ("Q8_0", 8.5008, 7.95), ("F16", 16.0005, 14.96)]
GiB = 1024 ** 3
bpw_f16, size_f16 = rows[-1][1], rows[-1][2]
params = size_f16 * GiB * 8 / bpw_f16          # 用 F16 這列反推參數量
print(f"implied params: {params/1e9:.2f} B")
print(f"{'quant':8} {'bpw':>8} {'README GiB':>11} {'calc GiB':>9}")
for name, bpw, gib in rows:
    print(f"{name:8} {bpw:8.4f} {gib:11.2f} {params*bpw/8/GiB:9.2f}")

預期(教材作者實跑結果):印出 implied params: 8.03 B,且每一列的 calc GiB 與 README GiB 在小數第二位相同。

然後寫你自己的機器卡:在 notes.md 記下你的機型、記憶體(Apple silicon 是統一記憶體;有獨立 GPU 就記 VRAM)、可用的 backend(Metal/CUDA/只有 CPU)。最後把公式套到「你想跑的 model」:參數量 × 兩種量化的 bits/weight,算出 weight 大小,並判斷你的機器放不放得下,同時預留給 KV cache 的空間(先寫「待 Day 44 補」)。

過關標準

  • 能回答:8B 參數的 model 在 F16 與 Q4_K_M 下,weight 各約多大?怎麼算的?
  • 能回答:為什麼 bits/weight 不是剛好 4?
  • 產出:上面程式碼的輸出,加上 notes.md 裡的機器卡與「你的 model 放得下嗎」的計算

Deep Dive(選讀)

  • 讀 llama.cpp 量測表的 prompt t/s 與 generation t/s 兩欄:generation 速度隨 bits 變少而上升(F16 約 29 → Q2_K 約 80 t/s),prompt 速度卻變化不大(約 760~920 t/s)。推測兩者瓶頸為什麼不同,並用 Day 47 的 llama-bench 在自己機器上驗證(Deep Dive 層級)

Day 43 — Quantization 與 GGUF:用精度換記憶體

今天要回答的問題

量化到底犧牲了什麼?GGUF 檔名裡的 Q4_K_M 是在說什麼?

主教材(Core)

  • Hugging Face Hub 文件 — GGUF(開頭的格式說明、Quantization Types 表,預估 25 分鐘)
  • llama.cpp 文件 — llama-quantize README(Prepare the input GGUF file、Quantize the GGUF 兩節與 Perplexity 相關說明),預估 20 分鐘
  • 實作,預估 60 分鐘

搭配(Companion,選讀)

  • DeepLearning.AI 短課 — Quantization Fundamentals with Hugging Face(Data Types and Sizes、Quantization Theory 兩課),全課約 1 小時 14 分,只挑這兩課;預估 30 分鐘
  • vLLM 文件 — Quantization(頁首說明與支援方法清單),看 vLLM 路線有哪些量化格式;預估 10 分鐘

讀的時候抓這幾個重點

  • GGUF 是「tensor 加 metadata」的單一檔案格式。 Hub 文件的說明是:不同於只存 tensor 的 safetensors,GGUF 同時編碼 tensor 與一組標準化的 metadata,設計目標是載入與儲存快速。所以 llama.cpp 與 Ollama 吃的是 GGUF。
  • 量化名稱可以拆開讀。 以文件的 Quantization Types 表為準:Q4_K 是 4-bit、以 super-block 分組、每個 block 有自己的 scale 與 min;Q8_0 是列在 Legacy 的 8-bit round-to-nearest;IQ 開頭的用到 importance matrix。_M、_S 之類的後綴表頁面沒有逐一解釋,教材不替它補定義,遇到時以 llama-quantize README 的說明為準。
  • 量化的代價是精度損失,要用數字量。 llama-quantize README 說精度損失通常用 perplexity 或 KL divergence 衡量,並提到合適的 imatrix 可以降低損失。注意該頁沒有給各量化類型的 perplexity 數值,所以「Q4 夠用」不能憑頁面下結論,要自己比較同一組 prompt 的輸出。
  • 量化改變的是 weight 的存放方式。 它讓 weight 變小、讓每個 token 要搬的資料變少,但不會自動縮小 KV cache(vLLM 另外有 Quantized KV Cache 這個獨立的功能,見搭配的 Quantization 頁)。這點最容易被搞混。

實作

用你機器上跑得動的小 model,比較兩種量化的檔案大小與同題輸出:

  1. 到 Ollama 的 model library 或 Hugging Face 的 GGUF 篩選頁(hf.co/models?library=gguf)挑一個小型 model(1B~4B),找出它有哪些量化版本可選(各 model 的可用 tag 不同,請在該 model 頁面查,不要憑印象打 tag 名稱)。
  2. 下載兩個不同量化的版本(例如一個 4-bit 類、一個 8-bit 類),記下檔案大小(ollama list 的 SIZE 欄,或 GGUF 檔案本身的大小)。
  3. 用 Day 42 的公式估一次大小,與實際檔案比對,差多少寫進 notes。
  4. 對兩個版本問同樣的 5 個問題(事實題、算術題、中文短文摘要、程式碼題、需要多步推理的題目各一,temperature 設 0),把兩份回答並排貼進 notes.md,標出你看得出差異的地方;看不出差異也要寫「看不出」。

預期:8-bit 類檔案約為 4-bit 類的近兩倍;輸出差異可能很小或沒有,結論以你的觀察為準。

過關標準

  • 能回答:GGUF 與 safetensors 差在哪?
  • 能回答:量化省下的是哪一種記憶體?KV cache 會不會一起變小?
  • 產出:兩個量化版本的大小對照(實際值與公式估算值)、5 題並排回答與你的觀察

Deep Dive(選讀)

  • 讀 llama-quantize README 的 Convert a Hugging Face model to GGUF 與 Quantize 兩段指令,自己把一個小 model 從 Hugging Face 轉成 GGUF 再量化(Deep Dive 層級,需要自行建置 llama.cpp 工具)

Day 44 — KV cache:長 context 與多人同時用為什麼吃記憶體

今天要回答的問題

KV cache 是什麼?它的大小怎麼估?為什麼 context 一長、同時請求一多,GPU 記憶體就先爆在這裡?

主教材(Core)

  • Hugging Face Transformers 文件 — Cache strategies(開頭說明與 Default cache、Cache offloading、Quantized cache 三節),預估 30 分鐘
  • Hugging Face 部落格 — Continuous batching from first principles(Attention 與 KV cache 兩段),預估 15 分鐘
  • 實作,預估 45 分鐘

搭配(Companion,選讀)

  • Ollama 文件 — Context length(預設值依 VRAM 而定、OLLAMA_CONTEXT_LENGTH、用 ollama ps 查 CONTEXT),預估 10 分鐘

讀的時候抓這幾個重點

  • KV cache 存的是過去每個 token 的 key/value 向量。 自回歸生成每一步都要用到前面所有 token 的 K、V,這些不會變,所以存起來重複用,就不用每一步重算。它用記憶體換掉重複的運算。
  • 它隨序列長度線性成長。 Transformers 文件的 Default cache 一節說 DynamicCache 會隨生成過程一路長大;部落格也寫它的代價是記憶體隨序列長度增加。這就是為什麼同一個 model,context 開到 32k 會比 4k 吃掉多得多的記憶體。
  • 每多一個同時進行的請求,就多一份 KV cache。 Weight 是所有請求共用的,KV cache 不是。Day 45 的 batching 與 vLLM 的 PagedAttention 都是在處理這個問題。
  • 有三種省記憶體的路:offload、quantize、縮短 context。 Transformers 文件對照了 offloaded 與 quantized cache,並且都警告會用速度換記憶體,短 context 又有足夠 GPU 記憶體時 quantized cache 甚至可能讓延遲變差。Ollama 的預設 context 長度會隨 VRAM 變動,頁面的預設值是少於 24 GiB VRAM 為 4k tokens——所以「為什麼我的長 prompt 被截掉」要先查這個設定。

實作

先用公式算(K 和 V 各一份,所以前面有個 2):

def kv_bytes(layers, kv_heads, head_dim, tokens, batch=1, dtype_bytes=2):
    return 2 * layers * kv_heads * head_dim * tokens * batch * dtype_bytes

GiB = 1024 ** 3
# 範例:GQA 設定的 8B 級 model;請換成你的 model 的 config.json 數值
layers, kv_heads, head_dim = 32, 8, 128
print(f"KV per token: {kv_bytes(layers, kv_heads, head_dim, 1)/1024:.0f} KiB")
for tokens in (1_000, 8_000, 32_000):
    for batch in (1, 8):
        print(f"tokens={tokens:>6} batch={batch}: "
              f"{kv_bytes(layers, kv_heads, head_dim, tokens, batch)/GiB:6.2f} GiB")
print("kv_heads=32(沒有 GQA), 8k tokens, batch 1:",
      f"{kv_bytes(layers, 32, head_dim, 8000)/GiB:.2f} GiB")

預期(教材作者實跑結果):KV per token: 128 KiB;8k tokens × batch 1 約 0.98 GiB,32k tokens × batch 8 約 31.25 GiB;沒有 GQA(kv_heads=32)同樣 8k tokens 約 3.91 GiB,是 GQA 版本的 4 倍。

接著在 notes.md:(1)到你選的 model 的 Hugging Face 頁面讀 config.json,找出 num_hidden_layers、num_key_value_heads、hidden_size 與 num_attention_heads(head_dim 通常是後兩者相除;若 config 有明確的 head_dim 欄位以它為準),套進公式;(2)用 Day 42 的 weight 大小加上 KV cache,算出你的機器在 context 8k、同時 1 個與 4 個請求時的總需求。公式假設 fp16 的 cache,若 runtime 另外設定 KV cache 量化,數字會不同,要在 notes 註明。

過關標準

  • 能回答:KV cache 大小由哪四個因素決定?哪一個是你在部署時能直接調整的?
  • 能回答:為什麼「weight 放得下」不代表「能服務 10 個同時請求」?
  • 產出:上面程式碼的輸出,加上你的 model 套用 config 數值後的計算(context 8k,1 個與 4 個請求)

Day 45 — Batching 與 PagedAttention:GPU 怎麼同時服務很多人

今天要回答的問題

為什麼 vLLM 這類 server 的吞吐量可以比一次處理一個請求高這麼多?continuous batching 與 PagedAttention 各解決什麼問題?

主教材(Core)

搭配(Companion,選讀)

讀的時候抓這幾個重點

  • 傳統做法浪費大量 KV cache 記憶體。 vLLM 部落格指出既有系統因為碎片與過度預留,浪費 60%~80% 的記憶體。這是部落格自己的量測,教材只拿來說明「問題在哪」,不是普遍數字。
  • PagedAttention 借用作業系統的分頁。 每個序列的 KV cache 被切成固定大小的 block,邏輯上連續、實體上不必連續,由 block table 對應,按需配置;部落格說浪費只發生在每個序列的最後一個 block。序列之間還能共用 block(例如 parallel sampling),靠 reference count 與 copy-on-write 保持安全。
  • Continuous batching 是把「完成的請求立刻換成等待中的請求」。 部落格的 Dynamic scheduling 一段說,請求一結束就移出 batch、馬上補進新的,而不是等整批一起做完。搭配 ragged batching(不補 padding)與 chunked prefill(長 prompt 切塊),prefill 與 decode 可以放在同一個 batch。
  • 調校是 TTFT 與吞吐量的取捨。 vLLM 優化頁說,max_num_batched_tokens 設小一點有利 inter-token latency,設大一點有利 time to first token 與吞吐量;KV cache 放不下時 vLLM 會 preempt 並稍後重算,可能拉高延遲。這些是 Day 49 量測時要觀察的旋鈕。

實作

不用 GPU:寫一個玩具排程器,量化「靜態 batch」與「continuous batching」的差別。每個請求要生成的 token 數不同,一次最多同時處理 B 個,每一步每個請求產生 1 個 token:

import random

random.seed(0)
lens = [random.choice([8, 16, 32, 64, 128]) for _ in range(32)]   # 每個請求要生成幾個 token
B = 8                                                              # 同時最多幾個

def static_steps(lens):
    # 一批 B 個一起做,等最長的做完才換下一批
    return sum(max(lens[i:i + B]) for i in range(0, len(lens), B))

def continuous_steps(lens):
    queue, active, steps = list(lens), [], 0
    while queue or active:
        while queue and len(active) < B:      # 有空位就立刻補
            active.append(queue.pop(0))
        steps += 1
        active = [x - 1 for x in active if x - 1 > 0]
    return steps

total = sum(lens)
s, c = static_steps(lens), continuous_steps(lens)
print("tokens", total, "static steps", s, "continuous steps", c)
print("slot utilisation static %.2f continuous %.2f" % (total / (s * B), total / (c * B)))

預期(教材作者實跑結果,seed(0)):tokens 1736 static steps 512 continuous steps 272,slot 使用率 static 0.42、continuous 0.80。

這是玩具模型,只模擬「長度不一導致等待」,沒有模擬 prefill、記憶體或真實的 GPU 排程,結果只用來建立直覺。接著改兩個地方並記錄結果:把 B 改成 4 和 16;把所有長度改成都一樣(例如全部 32)。在 notes.md 寫下兩組發現,並解釋為什麼長度全部一樣時兩者就沒差別。

過關標準

  • 能回答:靜態 batch 為什麼會讓 GPU 閒置?continuous batching 怎麼解決?
  • 能回答:PagedAttention 針對的是哪一種浪費?它跟 continuous batching 是同一件事嗎?
  • 產出:上面程式碼的輸出,加上 B 改成 4、16 以及長度全部相同的三組結果與你的解釋

Deep Dive(選讀)

  • 讀 vLLM 設計文件 Paged Attention(頁首標示為基於原始 vLLM 論文的歷史文件),看 block、block size 與 key/value cache 在記憶體中的排列(Deep Dive 層級)

Day 46 — Ollama:本機 server 接上自己的 backend

今天要回答的問題

怎麼在自己電腦跑起一個 model,並讓自己的 backend 用 OpenAI 相容的方式呼叫它,還能量到第一個 token 的時間?

主教材(Core)

  • Ollama 文件 — OpenAI compatibility(Local server usage 與 Supported Endpoints、Unsupported Features 三節),預估 20 分鐘
  • Ollama 文件 — Context length(Setting context length、Check allocated context length 兩節),預估 10 分鐘
  • 實作,預估 80 分鐘

搭配(Companion,選讀)

  • Ollama 文件 — API introduction,看原生 API(/api/chat)與 OpenAI 相容 API(/v1)的 Base URL 差異;預估 10 分鐘

讀的時候抓這幾個重點

  • Ollama 是 runtime 加 server 加 model 管理。 ollama run <model> 會在需要時下載 model 並開聊天;server 預設在 http://localhost:11434。你可以把它想成「Day 41 那張表的 Runtime 與 Server 兩層被包在一起」。
  • 相容層是你的 backend 與 runtime 之間的接縫。 本機用 OpenAI client 時 base_url 設 http://localhost:11434/v1/,api_key 必填但會被忽略。支援 chat completions、completions、models、embeddings 與 responses(responses 只支援非 stateful)。
  • 不支援的欄位是換 runtime 時的地雷。 頁面列出 chat completions 不支援 logprobs、tool_choice、logit_bias、n 等。你的 backend 如果用到這些,換到 Ollama 會悄悄行為不同或報錯,需要先對照。
  • Context 預設值可能比你以為的小。 它依 VRAM 而定,少於 24 GiB 時預設 4k tokens;ollama ps 會顯示 loaded model 的 PROCESSOR(GPU/CPU 比例)與 CONTEXT。如果 PROCESSOR 顯示有一部分在 CPU,代表 model 沒完全放進 GPU 記憶體,速度會明顯下降。

實作

  1. 安裝並啟動 Ollama(見 Quickstart),ollama run <你在 Day 43 選的 model> 確認能聊天,結束後用 ollama ps 記下 PROCESSOR 與 CONTEXT。
  2. 用標準函式庫寫一個 streaming client,量首 token 時間(TTFT)、總時間與輸出片段數(SSE 一個 data: 片段約等於一個 token,這是近似值):
import json, time, urllib.request

BASE = "http://localhost:11434/v1"       # Ollama;Day 47、48 換成 llama.cpp、vLLM 的位址即可
MODEL = "<你的 model 名稱>"                # ollama list 看到的名字

def one(prompt, max_tokens=64):
    req = urllib.request.Request(
        BASE + "/chat/completions",
        data=json.dumps({"model": MODEL, "stream": True, "max_tokens": max_tokens,
                         "messages": [{"role": "user", "content": prompt}]}).encode(),
        headers={"Content-Type": "application/json", "Authorization": "Bearer none"})
    t0, ttft, chunks = time.perf_counter(), None, 0
    with urllib.request.urlopen(req) as r:
        for raw in r:
            line = raw.decode().strip()
            if not line.startswith("data: ") or line == "data: [DONE]":
                continue
            choices = json.loads(line[6:]).get("choices") or [{}]
            if choices[0].get("delta", {}).get("content"):
                chunks += 1
                if ttft is None:
                    ttft = time.perf_counter() - t0
    return ttft, time.perf_counter() - t0, chunks

for p in ["用一句話解釋 KV cache。", "寫一個 Python 的 fibonacci 函式。"]:
    ttft, total, chunks = one(p)
    print(f"ttft={ttft:.3f}s total={total:.3f}s chunks={chunks}")

預期:每個 prompt 印一行 ttft=... total=... chunks=...,數值以你的機器為準。教材作者用一個本機模擬的 SSE stub server 驗證過這段 client 的解析邏輯(stub 以固定間隔送出 data: 片段),沒有對真的 Ollama 跑過,所以第一次跑若遇到欄位差異,請對照 OpenAI compatibility 頁面的 streaming 說明修正,並把差異記進 notes。

  1. 用這個 client 取代 backend 裡呼叫雲端 API 的那一行(只改 base_url 與 model 名稱),確認 backend 能拿到回答。記下「沒改的」與「不得不改的」各有哪些。

過關標準

  • 能回答:Ollama 的原生 API 與 OpenAI 相容 API 的 Base URL 各是什麼?
  • 能回答:ollama ps 的 PROCESSOR 若不是 100% GPU,代表什麼?對速度有什麼影響?
  • 產出:ollama ps 的輸出、上面 client 對兩個 prompt 的 TTFT 與總時間、backend 換 base_url 的改動清單

Day 47 — llama.cpp:自己控制 GGUF、GPU offload 與基準測試

今天要回答的問題

直接用 llama.cpp 跑 GGUF,可以調哪些旋鈕?怎麼量出你這台機器的 prompt 處理與生成速度?

主教材(Core)

  • llama.cpp — README(Quick start:安裝方式與 -hf 直接從 Hugging Face 載入;Supported backends),預估 15 分鐘
  • llama.cpp — llama-server README(Common params 的 -m、-c、-ngl、-np、-cb、-fa;OpenAI-compatible API Endpoints;--metrics),預估 30 分鐘
  • llama.cpp — llama-bench README(pp、tg 的定義與 -p、-n、-ngl、-r、-o),預估 15 分鐘
  • 實作,預估 50 分鐘

搭配(Companion,選讀)

  • Hugging Face Hub 文件 — GGUF,回頭看 llama.cpp 與 Ollama 如何共用同一種檔案格式;預估 10 分鐘

讀的時候抓這幾個重點

  • llama.cpp 是一個 C/C++ 推論引擎,支援很多 backend。 README 列出 Metal、CUDA、HIP、Vulkan、SYCL 等。這代表同一份程式可以在 Mac、NVIDIA、AMD 上跑,但你拿到的 binary 是用哪個 backend 編的會決定它能不能用你的 GPU。
  • -ngl(GPU layers)決定有幾層放進 GPU 記憶體。 這是 Day 42 那題「放得下嗎」的實際旋鈕:放不下就少放幾層,剩下的在 CPU 跑,速度會掉。llama-server README 寫預設為 auto,llama-bench 的預設是 -1。
  • llama-bench 把速度分成 pp 與 tg 兩種。 pp 是 prompt processing(讀 prompt,由 -p 設長度,預設 512),tg 是 text generation(逐 token 生成,由 -n 設長度,預設 128)。兩者瓶頸不同:pp 偏重運算,tg 偏重記憶體頻寬。後者是 Day 42 表中量化後 generation 速度上升的原因。這句因果是教材對頁面數據的解讀,不是頁面的原文。
  • llama-server 提供 OpenAI 相容路徑與監控端點。 有 /v1/chat/completions、/health、/slots,以及要加 --metrics 才開啟的 /metrics(Prometheus 格式)。README 同時聲明不對 OpenAI 規格作強相容保證,所以 Day 46 的 client 換過來之後仍要自己驗證。

實作

README 的 Quick start 寫的安裝方式與指令名稱(2026-10-16 查證時是 llama cli/llama serve;較舊版本與自行建置的是 llama-cli/llama-server)可能因版本而異,以你安裝後的 --help 為準。另外 README 對預設 port 的說法(查證時寫 127.0.0.1:9931)請不要直接信:下面一律明確指定 --port。

  1. 依 README 安裝 llama.cpp,確認工具可執行。
  2. 用 Day 43 下載的 GGUF(或 README 示範的 -hf 方式)啟動 server:
llama-server -m <你的.gguf> -c 4096 -ngl 99 --port 8080 --metrics
  1. 把 Day 46 的 client 的 BASE 改成 http://127.0.0.1:8080/v1,MODEL 隨意填(單一 model 的 server 通常不看這欄,若報錯就以 /v1/models 回傳的名稱為準),跑同樣兩個 prompt,與 Day 46 的 TTFT、總時間並排記錄。
  2. 用 llama-bench 量 pp 與 tg:
llama-bench -m <你的.gguf> -p 512 -n 128 -ngl 99 -r 3

預期:輸出表格有 model、size、params、backend、ngl、test(pp512/tg128)與 t/s 欄;backend 欄應顯示你預期的 Metal/CUDA 等。若 backend 顯示 CPU,代表這份 binary 沒用到你的 GPU,在 notes 記下原因。

  1. 再跑一次把 -ngl 改成 0,記錄 t/s 差多少。

過關標準

  • 能回答:pp 與 tg 各量什麼?為什麼量化後 tg 通常比較快?
  • 能回答:-ngl 0 與 -ngl 99 的差別是什麼?你的實測差了多少?
  • 產出:llama-bench 兩次(-ngl 99/-ngl 0)的輸出表格、llama-server 與 Ollama 的 TTFT 對照

Deep Dive(選讀)

  • 加 --metrics 後 curl 一次 /metrics,找出 prompt/生成 token 的計數與處理中請求數對應哪些欄位(Deep Dive 層級)

Day 48 — vLLM:OpenAI 相容的高吞吐 server

今天要回答的問題

vllm serve 一行背後做了什麼?它跟 Day 46、47 的本機 runtime 在定位上差在哪?

主教材(Core)

  • vLLM 文件 — Quickstart(Installation、Online Serving 兩節,含 vllm serve、/v1/models、/v1/chat/completions 的 curl 範例),預估 25 分鐘
  • vLLM 文件 — Online Serving(支援的 API 清單、/metrics、/load),預估 20 分鐘
  • vLLM 文件 — CPU 安裝頁(Apple Silicon 一節與注意事項),預估 10 分鐘
  • 實作,預估 60 分鐘

搭配(Companion,選讀)

  • vLLM 文件 — Optimization and Tuning(Key Parameters:gpu_memory_utilization、max_num_batched_tokens、max_num_seqs),預估 15 分鐘

讀的時候抓這幾個重點

  • vLLM 的定位是服務多個同時請求。 Day 45 的 continuous batching 與 PagedAttention 是它的核心。Ollama、llama.cpp 擅長「單人在本機跑」,vLLM 擅長「一台機器服務很多人」,這是選型的主軸,不是誰比較好。
  • 啟動方式與相容 API 很簡單。 Quickstart 的指令是 vllm serve <model>,預設在 http://localhost:8000;頁面的 Python 範例用 OpenAI(api_key="EMPTY", base_url="http://localhost:8000/v1")。因此 Day 46 的 client 只要換 BASE 就能用。
  • Online Serving 頁不只有 OpenAI 的路徑。 還列了 Anthropic Messages(/v1/messages)、Cohere、Pooling、Tokenize 等,以及 Prometheus 相容的 /metrics。選 vLLM 等於多得到一組可觀測性端點。
  • 平台限制要先確認。 Quickstart 的安裝主要是 NVIDIA CUDA(也涵蓋 ROCm、TPU 等)。CPU 安裝頁寫 Apple silicon 沒有預建 wheel、需從原始碼建置、標註為實驗性、只支援 FP32 與 FP16,需要 macOS Sonoma 以上與 Xcode 15.4 以上;頁面另提到社群的 vllm-metal plugin 以 MLX 做 Metal GPU 推論。查證時間是 2026-10-16,這類支援狀態變動快,動手前請重讀頁面。

實作

先判斷你屬於哪一種情況:

A. 有 NVIDIA GPU(或租得到雲端 GPU): 依 Quickstart 安裝,啟動並呼叫:

vllm serve <一個放得進你 VRAM 的小型 model,例如 Quickstart 示範的 Qwen/Qwen2.5-1.5B-Instruct>
curl http://localhost:8000/v1/models

把 Day 46 的 client 的 BASE 改成 http://localhost:8000/v1、MODEL 填 /v1/models 回傳的名稱,跑同樣兩個 prompt,記錄 TTFT 與總時間,並 curl http://localhost:8000/metrics 存一份輸出。

B. 只有 Mac 或沒有 GPU: 不強迫自己從原始碼建置實驗性路徑。改做書面比較:在 notes.md 寫一張表,欄是「Ollama/llama.cpp/vLLM」,列是「適合的使用情境、硬體需求、同時請求的處理方式、監控端點、你的 backend 要改的地方」,每一格都要附上對應的文件頁面。並寫明「我沒有實跑 vLLM,原因是 ___」。這個選擇會在 Day 50 的 Project 1 報告裡如實標註。

過關標準

  • 能回答:選 vLLM 而不是 Ollama 的情境是什麼?反過來呢?
  • 能回答:你的機器能不能跑 vLLM?依據是哪個頁面的哪一段?
  • 產出:路徑 A 的 TTFT/總時間與 /metrics 輸出;或路徑 B 的比較表與「沒有實跑」的說明

Day 49 — 量測:latency、throughput、concurrency

今天要回答的問題

怎麼用一致的方法量出「一個人用」的延遲與「很多人用」的吞吐量?TTFT、TPOT、throughput 各是什麼?

主教材(Core)

  • vLLM 文件 — Benchmark CLI(Online Benchmark 與 Offline Throughput Benchmark 兩段;TTFT、TPOT、ITL 與 throughput 的定義),預估 25 分鐘
  • vLLM 文件 — Optimization and Tuning(Preemption、Chunked Prefill 兩節;Day 45 讀過一次,這次帶著「我量到什麼」的問題重讀),預估 15 分鐘
  • 實作,預估 70 分鐘

搭配(Companion,選讀)

  • llama.cpp — llama-bench README,回頭看它的重複次數(-r)與標準差輸出;預估 10 分鐘

讀的時候抓這幾個重點

  • 延遲和吞吐量是兩個不同的問題。 Benchmark CLI 頁面把指標分開:TTFT(送出請求到收到第一個輸出)、TPOT(第一個之後每個輸出 token 的平均時間)、ITL(相鄰輸出之間的間隔)都以 mean、median、P99 呈現;throughput 則是 request throughput(req/s)、output token throughput 與 total token throughput(tok/s)。
  • 看 P99 才看得到壞情況。 平均值會被大量正常請求拉低;使用者感受到的卡頓出現在尾端。只報平均的 benchmark 結果不能拿來判斷「撐不撐得住」。
  • 併發度是第三個維度。 同一台機器在 1 個同時請求與 8 個同時請求下,TTFT 和總吞吐量都不同;Day 45 的 continuous batching 預期是:併發增加,總吞吐量上升,但單一請求的延遲可能變長。要量過才知道你的機器上拐點在哪。
  • 要固定其他條件。 model、量化、context 長度、prompt 與輸出長度、temperature 都要固定,否則比較沒有意義。vLLM 的基準指令用固定的 dataset 與 --num-prompts 就是為了這件事。

實作

延伸 Day 46 的 client,加入併發與統計(仍是標準函式庫)。把下面的 one() 換成 Day 46 的同一個函式,再貼上這段:

import statistics, concurrent.futures as cf

def pct(sorted_vals, q):
    return sorted_vals[min(len(sorted_vals) - 1, int(q * len(sorted_vals)))]

def run(concurrency, n=16, max_tokens=64):
    t0 = time.perf_counter()
    with cf.ThreadPoolExecutor(concurrency) as ex:
        res = list(ex.map(lambda i: one(f"用兩句話解釋第 {i} 個計算機概念。", max_tokens),
                          range(n)))
    wall = time.perf_counter() - t0
    ttfts = sorted(r[0] for r in res)
    return concurrency, statistics.median(ttfts), pct(ttfts, 0.99), sum(r[2] for r in res) / wall

print("conc  ttft_p50  ttft_p99  out_tok/s")
for c in (1, 2, 4, 8):
    c, p50, p99, tps = run(c)
    print(f"{c:4d} {p50:9.3f} {p99:9.3f} {tps:9.1f}")

預期:印出四列,併發 1、2、4、8 各一列。教材作者用本機模擬的 stub server 驗證過統計邏輯(stub 在併發 1 與 4 下,TTFT 中位數都約 0.1 秒、輸出 token/s 從約 24 變約 90),這只證明程式碼本身沒寫錯;真實 runtime 的曲線形狀(例如併發超過某個值之後 TTFT 暴增)會不一樣,請以實測為準。

然後對你在 Day 46、47(有的話加 48)用過的每個 runtime 各跑一次,每次 n 至少 16,並確認其他條件相同。填這張表(Day 50 要用):

Runtime量化併發TTFT p50TTFT p99out tok/s峰值記憶體

「峰值記憶體」欄:Ollama 用 ollama ps 看載入後的大小,Apple silicon 與 Linux 的觀察方式不同(活動監視器或 nvidia-smi);量不到就寫「未量」,不要估一個數字填上去。

過關標準

  • 能回答:TTFT、TPOT、throughput 各量什麼?為什麼要看 P99?
  • 能回答:併發從 1 增加到 8,你量到 TTFT 與總吞吐量各怎麼變?跟 Day 45 的 continuous batching 預期一致嗎?
  • 產出:完整的實測表(至少 2 個 runtime 或 2 種量化 × 4 種併發)與一段 5 行以內的觀察

Deep Dive(選讀)

  • 在有 GPU 的環境用 vLLM 自帶的 vllm bench serve(見 Benchmark CLI 頁的 Online Benchmark 指令)跑一次,把它報的 TTFT/TPOT/ITL 與你自製 client 量到的值對照,找出定義上的差異(Deep Dive 層級)

Day 50 — Project 1:Local LLM Serving

今天要回答的問題

把前 9 天的東西串起來:從一個 GGUF/model 到你的 backend,整條鏈能不能跑、跑多快、吃多少記憶體,結論是什麼?

主教材(Core)

  • 回頭使用前 9 天已讀的頁面,不新增閱讀。重新翻一次:llama.cpp 的 llama-bench README(Output formats)與 vLLM 的 Benchmark CLI(指標定義),用來統一你報告裡的名詞,預估 15 分鐘
  • 實作,預估 100 分鐘

搭配(Companion,選讀)

  • 重讀 Day 41 的五層表,看你現在能不能把每一層出的問題講得更具體;預估 10 分鐘

讀的時候抓這幾個重點

  • Project 1 要展示的是一條完整的鏈。 Model → llama.cpp / vLLM → API → Backend,並且附上 hardware、quantization、latency、throughput、memory 的實測。重點是「每個數字都有來源與條件」,不是數字多漂亮。
  • 誠實的報告包含「沒量到什麼」。 Day 48 路徑 B、Day 49 沒量到的記憶體欄,都要在報告裡明寫,而不是留空或估一個。
  • 結論要能指導選型。 讀報告的人應該能回答:在這台機器上、這個 model,用哪個 runtime、哪個量化、最多服務幾個同時使用者仍可接受。

實作

在 repo 內開一個 project-1-local-llm-serving/ 資料夾(或你自己的 project repo),放入:

  1. README.md,固定這幾節:- Setup:機型、記憶體或 VRAM、作業系統、runtime 與版本、model 與量化版本、啟動指令(照貼可重現)- Architecture:一張圖或一段文字,寫出 Model → runtime → API → Backend 並標出 Day 41 的五層- Backend 整合:你的 backend 怎麼切換 runtime(base_url/model 名稱的設定位置),以及切換時遇到的不相容欄位- Results:Day 49 的實測表,加上 Day 42 的 weight 估算與 Day 44 的 KV cache 估算對照實際記憶體- Limits:沒量到的、環境限制(例如沒有 vLLM 實測的原因)、已知的誤差來源(SSE 片段數近似 token 數等)- 結論:給出一個明確的建議與依據
  2. 量測用的 client 程式碼與你實際使用的指令。

過關標準

  • 能回答:這台機器的瓶頸是記憶體容量、記憶體頻寬還是運算?依據是哪一個實測數字?
  • 能回答:你的 backend 要從這個 runtime 換到另一個,要改哪些地方?
  • 產出:上面的 README.md 與 client 程式碼,且 Results 表的每個數字都附環境與指令,可以被別人照著重跑

Deep Dive(選讀)

  • 把同一個 model 的 weight 大小、KV cache 與實測的總記憶體畫成一張堆疊長條圖,看估算與實測差在哪(Deep Dive 層級)