Memory on Tarragon

Agent Memory

Tue, 12 May 2026 00:00:00 +0000

Agent memory 的核心概念是「agent 在 context window 之外管理長期狀態的設計」、把使用者偏好、過去任務、知識、操作流程等持久化、跨 session 重用。借鑒人類認知科學的五個層次：working memory（context 本身）、short-term（session scratchpad）、long-term episodic（過去事件）、long-term semantic（事實 / 知識）、long-term procedural（流程 / 技能）。

概念位置

五個層次的對比：

層	範圍	存放位置	典型內容
Working memory	當前 query / forward pass	Context window 本身	當下對話、tool result、reasoning trace
Short-term / session memory	單一 session（小時級）	Scratchpad 物件 / prompt cache	Session 內累積的中間結果、用過的策略
Long-term episodic memory	跨 session（永久）	DB / vector store / file system	「上週 alice 問過 X」「上個 sprint 解過 Y bug」
Long-term semantic memory	跨 session（永久）	DB / vector store / KG	「user 偏好 markdown 輸出」「專案用 React 18」「Python 3.11」
Long-term procedural memory	跨 session（永久）	Skill registry / playbook	「跑測試前先 npm install」「commit 前要 lint」

跟其他相關概念的關係：

概念	跟 agent memory 的關係
RAG	Long-term semantic memory 的常見實作（vector store retrieval）
Context window	Working memory 的物理上限
System prompt	把 semantic / procedural memory 編碼進 scaffold 的方式
Subagent	用 subagent 分隔不同 specialty 的 memory

設計責任

讀 agent paper / 設計 / framework docs 看到「agent memory」「memory store」「mem0 / Letta」「episodic / semantic memory」就是這 framing。寫 code 場景的判讀：

不是每個 agent 都需要五個層次都用：autocomplete 只要 working memory；對話 IDE assistant 多用 working + session；長期 coding agent 才需要 long-term
Long-term memory 的兩條實作路線：(a) retrieval-on-demand（vector store + similarity search、見 RAG）、(b) injection-on-startup（把關鍵 memory 編進 system prompt、適合小量穩定的 procedural）
失敗模式：memory drift（舊 memory 過時但仍被 retrieve）、PII 寫入（user 不知情下被存）、context 污染（不相關 memory 被 inject 進 working）、跟 hallucination 互相 boost
跟 4.19 agent memory 章節的關係：本卡是分類定義、章節是工程實務（寫入時機、retrieval 設計、失敗模式緩解）

MoE CPU 卸載

Tue, 12 May 2026 00:00:00 +0000

MoE CPU 卸載的核心概念是「Mixture-of-Experts 模型每個 token 只啟用少數專家、把不活躍的專家權重留在系統 RAM、用到再走 PCIe 拉回 GPU」。它讓 16GB VRAM 卡能載入 30B / 70B 等級的 MoE 模型、是獨立 GPU 場景相對統一記憶體場景多出的工程選項。

概念位置

MoE 卸載屬於「推論時的權重位置管理」、跟量化屬於「權重精度壓縮」是兩個獨立維度、可以疊加（如 30B MoE Q4 + 卸載部分層、模型精度跟記憶體位置同時被處理）。它跟 KV cache 量化是 PC 場景常一起使用的兩個工具：卸載騰出 VRAM、KV cache 量化讓騰出的 VRAM 拿去開大 context window。

在 llama.cpp 中、對應的旗標是 --n-cpu-moe 、把 N 層的 MoE 專家權重保留在 CPU 記憶體。例如 --n-cpu-moe 30 表示 30 層的專家層留 RAM、其餘走 GPU。

可觀察訊號與例子

以 Qwen3-30B-A3B Q4_K_M（模型體積 10 GB 級、active parameter 約 3B 等級）為例、不同卸載策略下記憶體分布與生字速度的相對方向（具體數值依驅動、CUDA backend、模型版本、PCIe 版本變化、本表用於說明趨勢、不是嚴格 benchmark）：

配置	卸載策略	VRAM 佔用方向	RAM 佔用方向	生字速度方向（同卡比較）
全載 VRAM	`--n-cpu-moe 0`	接近 VRAM 上限	系統正常	上限取決於 VRAM 頻寬
中度卸載	`--n-cpu-moe ~20`	顯著下降	上升至 10 GB 級	較全載小幅下降
重度卸載	`--n-cpu-moe ~30`	大幅下降	上升較多	較全載明顯下降
極限卸載	`--n-cpu-moe ~40`	接近最低	上升最多	較全載大幅下降

事實查核註：上表是趨勢示意、不是經本文系統實測的數值。實際數值依顯卡型號、PCIe 版本、CUDA backend、GGUF 量化版本、-ngl 設定、context 長度與 batch size 變化、建議用 llama-bench 或實際工作流校準。

社群常見的觀察是：MoE 卸載對生字速度的衰減幅度、相對於「Dense 模型把同樣比例的層卸載到 CPU」較小、原因是 MoE 每 token 只啟用少數專家、PCIe 上的權重傳輸量也較少；具體幅度依模型架構（active parameter 比例、專家數）變化。

設計責任

理解 MoE 卸載後、可以解釋三個 PC 場景的現象：16GB VRAM 卡能載入 30B 級 MoE 模型（透過部分卸載而非全載 VRAM）、PC 場景 64GB RAM 相對 32GB 在 MoE 卸載空間上明顯更寬裕（可卸載更多層）、Mac 統一記憶體場景較少需要「卸載」這個概念（VRAM 跟 RAM 共用、不需要在兩個區域之間搬資料）。

設定 PC 推論伺服器時、卸載層數通常跟 KV cache 量化、context 長度、併發數一起調：先估算想開的 context 長度、扣掉 KV cache 體積算出 VRAM 餘量、再選卸載層數讓模型剛好放得進。詳見 5.0 VRAM + RAM 分層預算。

VRAM

Tue, 12 May 2026 00:00:00 +0000

VRAM（Video RAM）的核心概念是「顯卡晶片上的高速記憶體、跟系統主機板上的 RAM 是物理上獨立的兩塊預算」。獨立 GPU 場景下、模型權重要載入 VRAM 才能用 GPU 高速計算；VRAM 容量直接決定能跑多大模型。跟 Apple Silicon 的統一記憶體不同、PC 上 VRAM 跟系統 RAM 兩塊預算要分開規劃。

概念位置

VRAM 同時影響「能載入什麼」跟「跑多快」兩個維度：

容量（GB）：決定能放多少模型權重 + KV cache + 推論中間結果。容量不夠則跑不起來、需透過 MoE CPU 卸載把部分權重放系統 RAM。
頻寬（GB/s）：影響每 token 生成速度上限、見 memory bandwidth 卡片。

常見消費級 GPU 的 VRAM 規格（廠商標稱、依世代與型號變化）：

GPU	VRAM 容量	VRAM 類型
RTX 5060 / 4060	8GB	GDDR6/7
RTX 5060 Ti / 4060 Ti	16GB	GDDR6/7
RTX 5070 Ti / 4070 Ti	16GB	GDDR6/7
RTX 4090	24GB	GDDR6X
RTX 5090	32GB	GDDR7

VRAM 容量是選 GPU 跑本地 LLM 的第一決策軸、頻寬是第二決策軸。同容量下、頻寬接近 2 倍的卡（如 5070 Ti 對 5060 Ti）生字速度差異明顯。

事實查核註：上表是 2026 年 5 月主流消費級 NVIDIA GPU 規格的數量級對照、實際 VRAM 容量、頻寬、GDDR 版本依特定型號、廠商 / SKU、製造時間變化、引用前以 NVIDIA 官方規格頁為準。

設計責任

理解 VRAM 後可以解釋三個現象：為什麼同樣 16GB 容量、不同卡的生字速度差很多（頻寬不同）；為什麼 MoE 模型在 16GB VRAM 上跑得了 30B 級模型（透過卸載）；為什麼 PCIe 頻寬在 PC 場景影響 MoE 卸載的速度（系統 RAM 跟 VRAM 之間的橋）。

選 PC 規劃本地 LLM 時、VRAM 容量決定能跑的模型上限、VRAM 頻寬決定生字速度上限、系統 RAM 容量決定 MoE 卸載空間。詳見 5.0 VRAM + RAM 分層預算。

3.1 GC 與 memory limit

Wed, 22 Apr 2026 00:00:00 +0000

GC 與 memory limit 的核心關係是：Go runtime 會根據 heap 成長決定何時執行 GC，而 memory limit 讓 runtime 有一個軟性記憶體目標。Memory limit 不是硬性上限，也不是 leak 修復工具；它是讓 runtime 更早回應記憶體壓力的控制訊號。

本章目標

學完本章後，你將能夠：

理解 heap growth、GOGC 與 GC 頻率的關係
判斷 debug.SetMemoryLimit 能解決什麼、不能解決什麼
從環境變數設定服務 memory limit
用 runtime metrics 觀察調整效果
分辨 GC 壓力、長期保留與真正 leak

【觀察】長時間服務的記憶體問題通常是趨勢問題

記憶體診斷的核心觀察是趨勢。Heap 是否持續上升、GC 後是否下降、goroutine 是否增加、某個操作後是否留下無法回收的資料，這些都比「現在用了多少 MB」更重要。

常見現象：

啟動後 heap 穩定在某個區間：通常正常。
每次高峰後 heap 都能下降：可能是短暫配置。
GC 後 heap 仍持續上升：可能有長期保留或 leak。
GC 次數快速增加且 CPU 升高：可能是 allocation 壓力。
goroutine 與 heap 同時增加：可能是 goroutine leak 或 send buffer 堆積。

Memory limit 可以幫 runtime 更積極控制 heap，但不能替代趨勢判讀。

【判讀】GC 控制的是 heap 成長

Go GC 的核心目標是回收不再被引用的 heap 物件。Runtime 會根據 GOGC 控制下一次 GC 觸發點。

1GOGC=100 go run ./cmd/server

GOGC=100 大致表示 heap 在上次 GC 後成長約 100% 時觸發下一次 GC。數字越小，GC 越頻繁，記憶體通常較低但 CPU 成本較高；數字越大，GC 較少，記憶體通常較高但 CPU 成本較低。

這是取捨，不是調大或調小就一定更好。CPU 緊繃的服務可能不能承受過低 GOGC；記憶體緊繃的服務可能不能承受過高 GOGC。

【判讀】memory limit 是 runtime 軟目標

debug.SetMemoryLimit 的核心用途是告訴 Go runtime 希望整體記憶體使用量靠近某個目標。當 runtime 接近目標時，會更積極回收 heap。

1func configureRuntime() {
2    const limit = 512 << 20 // 512 MiB
3    debug.SetMemoryLimit(limit)
4}

這不是作業系統層級的硬限制。程式仍可能短暫超過這個值，特別是有大量非 Go heap 記憶體、cgo、mmap、大型 byte slice 尖峰或外部 library 配置時。

Memory limit 適合容器、桌面常駐服務、背景 worker、WebSocket server 這類需要避免吃掉過多資源的服務。若部署平台已有 memory limit，Go runtime 的 limit 通常應略低於平台限制，留給非 Go heap 與系統開銷。

【執行】設定值應來自部署環境

Memory limit 的核心配置原則是由部署環境決定，而不是寫死在 library 裡。應用入口可以讀取環境變數，解析後設定 runtime。

 1func ConfigureMemoryLimitFromEnv() error {
 2    raw := os.Getenv("APP_MEMORY_LIMIT_MB")
 3    if raw == "" {
 4        return nil
 5    }
 6
 7    mb, err := strconv.Atoi(raw)
 8    if err != nil {
 9        return fmt.Errorf("parse APP_MEMORY_LIMIT_MB: %w", err)
10    }
11
12    if mb <= 0 {
13        return fmt.Errorf("APP_MEMORY_LIMIT_MB must be positive")
14    }
15
16    debug.SetMemoryLimit(int64(mb) << 20)
17    return nil
18}

錯誤應在啟動時明確失敗。服務若用錯誤設定悄悄運行，後續記憶體行為會很難解釋。

【策略】runtime metrics 用來看調整是否有效

Runtime metrics 的核心用途是驗證調整效果。只改 GOGC 或 memory limit，不看 heap 與 GC 趨勢，容易變成憑感覺調參。

簡單方式可以用 runtime.ReadMemStats：

1func ReadHeapAlloc() uint64 {
2    var stats runtime.MemStats
3    runtime.ReadMemStats(&stats)
4    return stats.HeapAlloc
5}

較完整的服務可以使用 runtime/metrics：

1func ReadRuntimeSamples() []metrics.Sample {
2    samples := []metrics.Sample{
3        {Name: "/memory/classes/heap/objects:bytes"},
4        {Name: "/gc/cycles/total:gc-cycles"},
5        {Name: "/sched/goroutines:goroutines"},
6    }
7    metrics.Read(samples)
8    return samples
9}

觀察時要看趨勢：調整後 heap 峰值是否下降、GC 次數是否合理、CPU 是否上升、goroutine 是否仍持續增加。

【判讀】memory limit 不能修正仍被引用的資料

Memory limit 的核心邊界是它只能影響 GC 行為，不能讓仍被引用的物件消失。若程式把資料一直留在 map、slice、cache、goroutine 或 send buffer 裡，GC 不能回收。

1var cache = map[string][]byte{}
2
3func SavePayload(id string, payload []byte) {
4    cache[id] = payload
5}

如果 cache 沒有大小限制、TTL 或刪除策略，memory limit 只會讓 GC 更常跑，但資料仍被 cache 引用。真正修正是設計 cache 淘汰、分頁、快照大小限制或資料釋放路徑。

因此遇到 heap 持續上升時，下一步是用 pprof 確認誰保留了記憶體。

【策略】判斷是 GC 壓力還是長期保留

記憶體問題的核心分流是：物件被大量配置但很快回收，還是物件被長期保留。

現象	可能問題	下一步
`alloc_space` 高，`inuse_space` 不高	短命配置多，GC 壓力大	找熱路徑 allocation
`inuse_space` 持續上升	長期保留或 leak	看 heap profile retainers
goroutine 數量同步上升	goroutine leak 或 queue 堆積	看 goroutine profile
GC 次數暴增但 heap 仍高	memory limit 壓力或資料保留	檢查 cache/map/buffer

這個分流會決定後續工具。GC 參數能緩解壓力，但保留資料要回到資料結構與 lifecycle 修。

【測試】runtime 設定函式可以獨立測解析

Runtime 本身不需要在單元測試中反覆調參。應把環境解析邏輯獨立出來，測試輸入與錯誤即可。

 1func ParseMemoryLimitMB(raw string) (int64, error) {
 2    if raw == "" {
 3        return 0, nil
 4    }
 5    mb, err := strconv.Atoi(raw)
 6    if err != nil {
 7        return 0, fmt.Errorf("parse memory limit: %w", err)
 8    }
 9    if mb <= 0 {
10        return 0, fmt.Errorf("memory limit must be positive")
11    }
12    return int64(mb) << 20, nil
13}

測試：

1func TestParseMemoryLimitMB(t *testing.T) {
2    got, err := ParseMemoryLimitMB("512")
3    if err != nil {
4        t.Fatalf("parse memory limit: %v", err)
5    }
6    if got != 512<<20 {
7        t.Fatalf("limit = %d, want %d", got, int64(512<<20))
8    }
9}

這讓設定邏輯可測，而不需要在每個測試中真的改 runtime 狀態。

本章不處理

本章先處理單一 Go process 如何判讀 heap、GC 與 memory limit；平台 OOM 與部署合約，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 runtime 壓力、allocation 與 pprof 診斷；如果你要先回看語言教材，可以讀：

小結

GC 控制 heap 回收節奏，memory limit 給 runtime 一個記憶體軟目標。合理設定能降低長時間服務的資源風險，但不能修正 cache、map、slice、goroutine 或 buffer 長期持有資料。診斷時先看趨勢，再用 pprof 區分 GC 壓力與長期保留。

3.1 PyObject 與物件模型

Tue, 20 Jan 2026 00:00:00 +0000

Python 中「一切皆物件」不只是一句口號，而是 CPython 實現的核心設計。理解 PyObject 是深入 Python 內部的第一步。

先備知識

進階系列模組二：元編程
基本的 C 語言知識（結構體、指標）

本章目標

學完本章後，你將能夠：

理解 PyObject 結構
理解參考計數的工作原理
解釋「一切皆物件」的實現方式
觀察物件的記憶體佈局

【原理層】一切皆物件

什麼是「一切皆物件」？

在 Python 中，所有東西都是物件：

 1# 數字是物件
 2x = 42
 3print(type(x))        # 
 4print(x.__class__)    # 
 5print(x.bit_length()) # 6（呼叫方法）
 6
 7# 函式是物件
 8def hello():
 9    pass
10print(type(hello))    # 
11print(hello.__name__) # hello
12
13# 類別是物件
14class MyClass:
15    pass
16print(type(MyClass))  # 
17
18# 甚至 type 本身也是物件
19print(type(type))     #

PyObject 結構

在 C 語言層面，所有 Python 物件都基於 PyObject 結構：

1// CPython 原始碼中的定義（簡化版）
2typedef struct _object {
3    Py_ssize_t ob_refcnt;  // 參考計數
4    PyTypeObject *ob_type; // 型別指標
5} PyObject;

每個 Python 物件在記憶體中至少包含這兩個欄位：

1┌─────────────────────────────────────┐
2│           PyObject                   │
3├─────────────────────────────────────┤
4│  ob_refcnt (參考計數)    8 bytes    │
5│  ob_type   (型別指標)    8 bytes    │
6├─────────────────────────────────────┤
7│  ... 物件特定的資料 ...              │
8└─────────────────────────────────────┘

變長物件：PyVarObject

對於長度可變的物件（如 list、str），使用 PyVarObject：

1typedef struct {
2    PyObject ob_base;
3    Py_ssize_t ob_size;  // 元素數量
4} PyVarObject;

1┌─────────────────────────────────────┐
2│         PyVarObject                  │
3├─────────────────────────────────────┤
4│  ob_refcnt (參考計數)    8 bytes    │
5│  ob_type   (型別指標)    8 bytes    │
6│  ob_size   (元素數量)    8 bytes    │
7├─────────────────────────────────────┤
8│  ... 元素資料 ...                    │
9└─────────────────────────────────────┘

【設計層】參考計數

工作原理

Python 使用參考計數來追蹤物件的使用：

 1import sys
 2
 3a = [1, 2, 3]
 4print(sys.getrefcount(a))  # 2（a 本身 + getrefcount 的參數）
 5
 6b = a  # 增加參考
 7print(sys.getrefcount(a))  # 3
 8
 9del b  # 減少參考
10print(sys.getrefcount(a))  # 2

參考計數的增減時機

 1# 增加參考計數的操作
 2x = obj          # 賦值
 3container.append(obj)  # 加入容器
 4func(obj)        # 作為參數傳遞
 5
 6# 減少參考計數的操作
 7del x            # 刪除變數
 8x = other        # 重新賦值
 9container.remove(obj)  # 從容器移除
10函式返回         # 區域變數離開作用域

參考計數的優缺點

優點	缺點
即時回收	無法處理循環參考
可預測的記憶體使用	每次操作都要更新計數
簡單易理解	多執行緒下需要鎖（GIL 的原因之一）

【實作層】觀察物件

使用 id() 觀察記憶體位址

 1a = [1, 2, 3]
 2b = a
 3c = [1, 2, 3]
 4
 5print(id(a))  # 140234567890112
 6print(id(b))  # 140234567890112（同一物件）
 7print(id(c))  # 140234567890176（不同物件）
 8
 9print(a is b)  # True
10print(a is c)  # False
11print(a == c)  # True（值相等）

小整數快取

CPython 對 -5 到 256 的整數進行快取：

 1a = 256
 2b = 256
 3print(a is b)  # True（同一物件）
 4
 5a = 257
 6b = 257
 7print(a is b)  # False（不同物件）
 8
 9# 但在同一行的情況可能會被編譯器優化
10a, b = 257, 257
11print(a is b)  # True（編譯時優化）

字串駐留（String Interning）

簡單的字串會被自動駐留：

 1a = "hello"
 2b = "hello"
 3print(a is b)  # True（駐留）
 4
 5a = "hello world"
 6b = "hello world"
 7print(a is b)  # False（含空格，不駐留）
 8
 9# 手動駐留
10import sys
11a = sys.intern("hello world")
12b = sys.intern("hello world")
13print(a is b)  # True

使用 ctypes 觀察記憶體

 1import ctypes
 2import sys
 3
 4def get_refcount(obj_id):
 5    """直接從記憶體讀取參考計數"""
 6    return ctypes.c_long.from_address(obj_id).value
 7
 8a = [1, 2, 3]
 9obj_id = id(a)
10
11print(f"sys.getrefcount: {sys.getrefcount(a)}")
12print(f"ctypes 直接讀取: {get_refcount(obj_id)}")
13# 注意：sys.getrefcount 會多 1（因為參數傳遞）

觀察物件大小

 1import sys
 2
 3# 基本物件大小
 4print(sys.getsizeof(None))      # 16
 5print(sys.getsizeof(True))      # 28
 6print(sys.getsizeof(0))         # 28
 7print(sys.getsizeof(1))         # 28
 8print(sys.getsizeof(10**100))   # 72（大整數）
 9
10# 容器大小（不包含元素）
11print(sys.getsizeof([]))        # 56
12print(sys.getsizeof([1, 2, 3])) # 88
13print(sys.getsizeof({}))        # 64
14
15# 注意：getsizeof 不遞迴計算
16nested = [[1, 2], [3, 4]]
17print(sys.getsizeof(nested))    # 只計算外層 list

【深入】PyTypeObject

型別物件的結構

每個型別（int、str、list 等）都是 PyTypeObject 的實例：

 1// 簡化版
 2typedef struct _typeobject {
 3    PyObject_VAR_HEAD
 4    const char *tp_name;       // 型別名稱
 5    Py_ssize_t tp_basicsize;   // 基本大小
 6    Py_ssize_t tp_itemsize;    // 元素大小（變長物件）
 7
 8    // 方法槽（slots）
 9    destructor tp_dealloc;     // 解構函式
10    reprfunc tp_repr;          // __repr__
11    hashfunc tp_hash;          // __hash__
12    // ... 更多方法槽
13} PyTypeObject;

在 Python 中觀察型別資訊

 1# 型別的基本資訊
 2print(int.__name__)       # int
 3print(int.__basicsize__)  # 28（64-bit 系統）
 4
 5# 方法解析順序
 6class A: pass
 7class B(A): pass
 8class C(B): pass
 9
10print(C.__mro__)
11# (, , , )
12
13# 型別的型別
14print(type(int))    # 
15print(type(type))   # （type 是自己的實例）

為什麼 is 比 == 快？

 1# is 只比較記憶體位址（一個指標比較）
 2# == 需要呼叫 __eq__ 方法（可能很複雜）
 3
 4import timeit
 5
 6a = [1, 2, 3]
 7b = a
 8c = [1, 2, 3]
 9
10# is 比較（非常快）
11print(timeit.timeit('a is b', globals=globals(), number=1000000))
12# 約 0.02 秒
13
14# == 比較（需要比較內容）
15print(timeit.timeit('a == c', globals=globals(), number=1000000))
16# 約 0.05 秒

【實戰】效能影響

避免不必要的物件建立

 1# 不好：每次迭代都建立新的 tuple
 2for i in range(1000):
 3    point = (i, i * 2)
 4
 5# 好：如果結構固定，考慮使用 __slots__ 的類別
 6class Point:
 7    __slots__ = ['x', 'y']
 8    def __init__(self, x, y):
 9        self.x = x
10        self.y = y
11
12# 或者使用 namedtuple
13from collections import namedtuple
14Point = namedtuple('Point', ['x', 'y'])

使用物件池

 1# 對於頻繁建立的小物件，考慮重複使用
 2class ObjectPool:
 3    def __init__(self, factory, max_size=100):
 4        self._factory = factory
 5        self._pool = []
 6        self._max_size = max_size
 7
 8    def acquire(self):
 9        if self._pool:
10            return self._pool.pop()
11        return self._factory()
12
13    def release(self, obj):
14        if len(self._pool) < self._max_size:
15            self._pool.append(obj)
16
17# 使用
18pool = ObjectPool(list)
19lst = pool.acquire()
20lst.extend([1, 2, 3])
21# 使用完畢
22lst.clear()
23pool.release(lst)

思考題

為什麼 CPython 選擇 -5 到 256 作為小整數快取的範圍？
如果參考計數是 Python 物件的核心，那多執行緒時會發生什麼問題？
None 是單例，這是如何實現的？

實作練習

寫一個函式，計算一個巢狀資料結構的「真實」記憶體使用量
使用 ctypes 觀察 list 物件的內部結構
實驗不同大小的整數的 is 行為

延伸閱讀

下一章：記憶體管理與垃圾回收

案例：記憶體優化

Wed, 21 Jan 2026 00:00:00 +0000

本案例基於 .claude/lib/config_loader.py 的實際程式碼，展示如何用 __slots__ 和 weakref 優化記憶體使用。

先備知識

問題背景

現有設計

config_loader.py 使用全域字典作為快取，這是一個常見的設計模式：

 1# Global cache variables
 2_agents_config_cache: Optional[dict] = None
 3_quality_rules_cache: Optional[dict] = None
 4
 5def load_agents_config() -> dict:
 6    """
 7    載入代理人配置
 8
 9    使用模組層級變數作為快取，避免重複讀取檔案。
10    """
11    global _agents_config_cache
12    if _agents_config_cache is None:
13        try:
14            _agents_config_cache = load_config("agents")
15        except FileNotFoundError:
16            _agents_config_cache = _get_default_agents_config()
17    return _agents_config_cache
18
19def clear_config_cache() -> None:
20    """清除配置快取（用於測試或配置熱更新）"""
21    global _agents_config_cache, _quality_rules_cache
22    _agents_config_cache = None
23    _quality_rules_cache = None

這種設計簡單直觀，但當系統需要快取更複雜的物件時，會遇到記憶體問題。

記憶體問題

當快取大量物件時：

Python 字典有額外開銷：每個字典需要維護 hash table、keys、values
物件的 __dict__ 佔用記憶體：每個實例都有自己的屬性字典
快取可能導致記憶體洩漏：強引用阻止物件被回收

讓我們用一個更複雜的快取場景來說明問題：

 1import sys
 2
 3class ConfigItem:
 4    """配置項目，模擬複雜的快取物件"""
 5    def __init__(self, key: str, value: str, metadata: dict):
 6        self.key = key
 7        self.value = value
 8        self.metadata = metadata
 9        self.access_count = 0
10        self.last_accessed = None
11
12# Create a config item and measure memory
13item = ConfigItem("database.host", "localhost", {"type": "string"})
14
15# Object size
16print(f"ConfigItem size: {sys.getsizeof(item)} bytes")
17# ConfigItem size: 48 bytes
18
19# But the real cost is in __dict__
20print(f"__dict__ size: {sys.getsizeof(item.__dict__)} bytes")
21# __dict__ size: 184 bytes

當快取數萬個這樣的物件時，記憶體開銷會非常可觀。

進階解決方案

優化目標

減少每個物件的記憶體佔用
避免快取導致的記憶體洩漏
保持 API 不變

實作步驟

步驟 1：使用 `slots` 減少物件大小

__slots__ 告訴 Python 這個類別只會有哪些屬性，讓直譯器可以用更緊湊的方式儲存資料：

 1import sys
 2
 3class ConfigItemWithoutSlots:
 4    """標準類別，使用 __dict__"""
 5    def __init__(self, key: str, value: str, metadata: dict):
 6        self.key = key
 7        self.value = value
 8        self.metadata = metadata
 9        self.access_count = 0
10        self.last_accessed = None
11
12class ConfigItemWithSlots:
13    """使用 __slots__ 優化記憶體"""
14    __slots__ = ['key', 'value', 'metadata', 'access_count', 'last_accessed']
15
16    def __init__(self, key: str, value: str, metadata: dict):
17        self.key = key
18        self.value = value
19        self.metadata = metadata
20        self.access_count = 0
21        self.last_accessed = None
22
23# Compare memory usage
24item_without = ConfigItemWithoutSlots("db.host", "localhost", {"type": "str"})
25item_with = ConfigItemWithSlots("db.host", "localhost", {"type": "str"})
26
27print(f"Without __slots__: {sys.getsizeof(item_without)} bytes")
28print(f"With __slots__:    {sys.getsizeof(item_with)} bytes")
29
30# The real difference is __dict__
31print(f"__dict__ overhead: {sys.getsizeof(item_without.__dict__)} bytes")
32# item_with has no __dict__!
33try:
34    item_with.__dict__
35except AttributeError as e:
36    print(f"No __dict__: {e}")

記憶體結構比較

 1沒有 __slots__:
 2┌──────────────────────────────────┐
 3│ PyObject header         (16 B)   │
 4│ __dict__ 指標            (8 B)   │
 5│ __weakref__ 指標         (8 B)   │
 6│                                  │
 7│ __dict__ (separate object):      │
 8│   - hash table          (64 B)   │
 9│   - keys array          (40 B)   │
10│   - values array        (40 B)   │
11│   - key strings        (~80 B)   │
12│                                  │
13│ Total: ~256 bytes per object     │
14└──────────────────────────────────┘
15
16有 __slots__:
17┌──────────────────────────────────┐
18│ PyObject header         (16 B)   │
19│ key slot                 (8 B)   │
20│ value slot               (8 B)   │
21│ metadata slot            (8 B)   │
22│ access_count slot        (8 B)   │
23│ last_accessed slot       (8 B)   │
24│                                  │
25│ Total: ~56 bytes per object      │
26└──────────────────────────────────┘

大量物件的記憶體節省

 1import sys
 2import tracemalloc
 3
 4def measure_memory(cls, count=10000):
 5    """Measure memory for creating multiple objects"""
 6    tracemalloc.start()
 7
 8    objects = [
 9        cls(f"key_{i}", f"value_{i}", {"index": i})
10        for i in range(count)
11    ]
12
13    current, peak = tracemalloc.get_traced_memory()
14    tracemalloc.stop()
15
16    return current, peak, objects
17
18# Measure both classes
19mem_without, peak_without, _ = measure_memory(ConfigItemWithoutSlots)
20mem_with, peak_with, _ = measure_memory(ConfigItemWithSlots)
21
22print(f"Without __slots__: {mem_without / 1024 / 1024:.2f} MB")
23print(f"With __slots__:    {mem_with / 1024 / 1024:.2f} MB")
24print(f"Savings:           {(mem_without - mem_with) / 1024 / 1024:.2f} MB")
25print(f"Ratio:             {mem_without / mem_with:.1f}x")
26
27# Typical output:
28# Without __slots__: 3.82 MB
29# With __slots__:    1.15 MB
30# Savings:           2.67 MB
31# Ratio:             3.3x

步驟 2：使用 weakref 避免強引用

weakref 讓我們可以引用物件，但不阻止它被垃圾回收：

 1import weakref
 2
 3class CacheableConfig:
 4    """可以被弱引用的配置物件"""
 5    __slots__ = ['key', 'value', '_data', '__weakref__']  # Note: __weakref__ slot
 6
 7    def __init__(self, key: str, value: str):
 8        self.key = key
 9        self.value = value
10        self._data = None
11
12    def __repr__(self):
13        return f"CacheableConfig({self.key!r}, {self.value!r})"
14
15# Create object and weak reference
16config = CacheableConfig("app.name", "MyApp")
17weak_ref = weakref.ref(config)
18
19print(f"Object exists: {weak_ref()}")
20# Object exists: CacheableConfig('app.name', 'MyApp')
21
22# Delete the strong reference
23del config
24
25print(f"After del: {weak_ref()}")
26# After del: None

使用 callback 追蹤物件回收

 1import weakref
 2
 3def on_finalize(ref):
 4    """Callback when object is garbage collected"""
 5    print(f"Object was garbage collected!")
 6
 7config = CacheableConfig("db.port", "5432")
 8weak_ref = weakref.ref(config, on_finalize)
 9
10print("Deleting object...")
11del config
12# Output: Object was garbage collected!

步驟 3：使用 WeakValueDictionary

WeakValueDictionary 是實作自動清理快取的利器：

 1import weakref
 2from typing import Callable, TypeVar, Generic
 3
 4T = TypeVar('T')
 5
 6class WeakCache(Generic[T]):
 7    """
 8    Auto-cleaning cache using weak references.
 9
10    Objects are automatically removed from cache when no strong
11    references exist outside the cache.
12    """
13
14    def __init__(self):
15        self._cache: weakref.WeakValueDictionary[str, T] = (
16            weakref.WeakValueDictionary()
17        )
18        self._hits = 0
19        self._misses = 0
20
21    def get(self, key: str, factory: Callable[[], T]) -> T:
22        """
23        Get item from cache, creating it if necessary.
24
25        Args:
26            key: Cache key
27            factory: Function to create value if not cached
28
29        Returns:
30            Cached or newly created value
31        """
32        value = self._cache.get(key)
33        if value is not None:
34            self._hits += 1
35            return value
36
37        self._misses += 1
38        value = factory()
39        self._cache[key] = value
40        return value
41
42    def __len__(self) -> int:
43        return len(self._cache)
44
45    def stats(self) -> dict:
46        """Return cache statistics"""
47        total = self._hits + self._misses
48        hit_rate = self._hits / total if total > 0 else 0
49        return {
50            "hits": self._hits,
51            "misses": self._misses,
52            "hit_rate": f"{hit_rate:.1%}",
53            "size": len(self._cache),
54        }
55
56# Demo: automatic cleanup
57cache = WeakCache[CacheableConfig]()
58
59# Create and cache object
60config1 = cache.get("app.name", lambda: CacheableConfig("app.name", "MyApp"))
61config2 = cache.get("app.name", lambda: CacheableConfig("app.name", "MyApp"))  # Cache hit
62
63print(f"Cache size: {len(cache)}")  # 1
64print(f"Same object: {config1 is config2}")  # True
65print(f"Stats: {cache.stats()}")  # hits=1, misses=1
66
67# Delete strong reference
68del config1
69del config2
70
71# Object is garbage collected, cache is auto-cleaned
72import gc
73gc.collect()
74
75print(f"Cache size after cleanup: {len(cache)}")  # 0

步驟 4：測量記憶體使用

使用 sys.getsizeof 和 tracemalloc 進行精確測量：

 1import sys
 2import tracemalloc
 3from pympler import asizeof  # pip install pympler
 4
 5def measure_object_size(obj, label="Object"):
 6    """Measure object size using different methods"""
 7
 8    # Basic size (doesn't include referenced objects)
 9    basic = sys.getsizeof(obj)
10
11    # Deep size (includes all referenced objects)
12    # Using pympler for accurate measurement
13    deep = asizeof.asizeof(obj)
14
15    print(f"{label}:")
16    print(f"  sys.getsizeof: {basic:,} bytes")
17    print(f"  pympler deep:  {deep:,} bytes")
18
19    return basic, deep
20
21# Compare different object types
22item_without = ConfigItemWithoutSlots("key", "value", {"a": 1, "b": 2})
23item_with = ConfigItemWithSlots("key", "value", {"a": 1, "b": 2})
24
25measure_object_size(item_without, "Without __slots__")
26measure_object_size(item_with, "With __slots__")
27
28# Using tracemalloc for allocation tracking
29def track_allocations():
30    """Track memory allocations during execution"""
31    tracemalloc.start()
32
33    # Simulate creating many cached objects
34    items = []
35    for i in range(1000):
36        items.append(ConfigItemWithSlots(
37            f"config.item.{i}",
38            f"value_{i}",
39            {"index": i, "active": True}
40        ))
41
42    # Get snapshot
43    snapshot = tracemalloc.take_snapshot()
44    top_stats = snapshot.statistics('lineno')
45
46    print("\nTop 5 memory allocations:")
47    for stat in top_stats[:5]:
48        print(f"  {stat}")
49
50    # Get traced memory
51    current, peak = tracemalloc.get_traced_memory()
52    print(f"\nCurrent memory: {current / 1024:.1f} KB")
53    print(f"Peak memory:    {peak / 1024:.1f} KB")
54
55    tracemalloc.stop()
56    return items
57
58track_allocations()

比較記憶體差異的完整腳本

 1import sys
 2import gc
 3import tracemalloc
 4from dataclasses import dataclass
 5
 6class StandardConfig:
 7    """Standard class with __dict__"""
 8    def __init__(self, key, value, metadata):
 9        self.key = key
10        self.value = value
11        self.metadata = metadata
12        self.hits = 0
13
14class SlottedConfig:
15    """Optimized with __slots__"""
16    __slots__ = ['key', 'value', 'metadata', 'hits']
17
18    def __init__(self, key, value, metadata):
19        self.key = key
20        self.value = value
21        self.metadata = metadata
22        self.hits = 0
23
24@dataclass
25class DataclassConfig:
26    """Using dataclass"""
27    key: str
28    value: str
29    metadata: dict
30    hits: int = 0
31
32@dataclass(slots=True)  # Python 3.10+
33class SlottedDataclass:
34    """Dataclass with __slots__"""
35    key: str
36    value: str
37    metadata: dict
38    hits: int = 0
39
40def benchmark_memory(cls, count=10000, label=""):
41    """Benchmark memory usage for a class"""
42    gc.collect()
43    tracemalloc.start()
44
45    objects = [
46        cls(f"key_{i}", f"value_{i}", {"index": i})
47        for i in range(count)
48    ]
49
50    current, peak = tracemalloc.get_traced_memory()
51    tracemalloc.stop()
52
53    per_object = current / count
54    print(f"{label or cls.__name__:25} | "
55          f"{current/1024:8.1f} KB | "
56          f"{per_object:6.1f} B/obj")
57
58    return objects  # Keep reference to prevent GC
59
60print(f"{'Class':25} | {'Total':>10} | {'Per Object':>10}")
61print("-" * 55)
62
63benchmark_memory(StandardConfig)
64benchmark_memory(SlottedConfig)
65benchmark_memory(DataclassConfig)
66benchmark_memory(SlottedDataclass)
67
68# Typical output:
69# Class                     |      Total |  Per Object
70# -------------------------------------------------------
71# StandardConfig            |   2578.5 KB |  263.6 B/obj
72# SlottedConfig             |    859.4 KB |   87.9 B/obj
73# DataclassConfig           |   2656.3 KB |  271.6 B/obj
74# SlottedDataclass          |    898.4 KB |   91.9 B/obj

完整程式碼

以下是整合所有優化技術的完整實作：

  1"""
  2Memory-optimized configuration cache system.
  3
  4This module demonstrates:
  5- Using __slots__ to reduce object memory footprint
  6- Using weakref for automatic cache cleanup
  7- Using tracemalloc for memory profiling
  8
  9Based on patterns from .claude/lib/config_loader.py
 10"""
 11
 12import weakref
 13import sys
 14import gc
 15import tracemalloc
 16from typing import Any, Callable, Generic, Optional, TypeVar
 17from pathlib import Path
 18from datetime import datetime
 19
 20T = TypeVar('T')
 21
 22class ConfigEntry:
 23    """
 24    Memory-optimized configuration entry.
 25
 26    Uses __slots__ to reduce memory footprint by ~3x compared
 27    to regular classes.
 28    """
 29    __slots__ = [
 30        'key', 'value', 'source', 'loaded_at',
 31        'access_count', '__weakref__'
 32    ]
 33
 34    def __init__(
 35        self,
 36        key: str,
 37        value: Any,
 38        source: Optional[str] = None
 39    ):
 40        self.key = key
 41        self.value = value
 42        self.source = source
 43        self.loaded_at = datetime.now()
 44        self.access_count = 0
 45
 46    def __repr__(self) -> str:
 47        return (
 48            f"ConfigEntry(key={self.key!r}, "
 49            f"value={self.value!r}, "
 50            f"accesses={self.access_count})"
 51        )
 52
 53    def touch(self) -> None:
 54        """Record an access to this entry"""
 55        self.access_count += 1
 56
 57class SmartConfigCache:
 58    """
 59    Smart configuration cache with automatic memory management.
 60
 61    Features:
 62    - Weak references for automatic cleanup
 63    - Memory usage tracking
 64    - Hit/miss statistics
 65    - Optional size limits
 66
 67    Example:
 68        cache = SmartConfigCache(max_size=1000)
 69
 70        # Get or create config
 71        config = cache.get_or_create(
 72            "database.host",
 73            lambda: ConfigEntry("database.host", "localhost", "env")
 74        )
 75
 76        # Check stats
 77        print(cache.stats())
 78    """
 79
 80    def __init__(self, max_size: Optional[int] = None):
 81        """
 82        Initialize the cache.
 83
 84        Args:
 85            max_size: Maximum number of entries. None for unlimited.
 86        """
 87        self._cache: weakref.WeakValueDictionary[str, ConfigEntry] = (
 88            weakref.WeakValueDictionary()
 89        )
 90        self._strong_refs: dict[str, ConfigEntry] = {}  # Keep important items
 91        self._max_size = max_size
 92        self._hits = 0
 93        self._misses = 0
 94        self._evictions = 0
 95
 96    def get(self, key: str) -> Optional[ConfigEntry]:
 97        """
 98        Get entry from cache.
 99
100        Args:
101            key: Configuration key
102
103        Returns:
104            ConfigEntry if found, None otherwise
105        """
106        # Check strong refs first
107        entry = self._strong_refs.get(key)
108        if entry is not None:
109            self._hits += 1
110            entry.touch()
111            return entry
112
113        # Then check weak refs
114        entry = self._cache.get(key)
115        if entry is not None:
116            self._hits += 1
117            entry.touch()
118            return entry
119
120        self._misses += 1
121        return None
122
123    def get_or_create(
124        self,
125        key: str,
126        factory: Callable[[], ConfigEntry],
127        keep_strong: bool = False
128    ) -> ConfigEntry:
129        """
130        Get existing entry or create new one.
131
132        Args:
133            key: Configuration key
134            factory: Function to create entry if not found
135            keep_strong: If True, keep a strong reference (won't auto-cleanup)
136
137        Returns:
138            Existing or newly created ConfigEntry
139        """
140        entry = self.get(key)
141        if entry is not None:
142            return entry
143
144        # Create new entry
145        entry = factory()
146        self._cache[key] = entry
147
148        if keep_strong:
149            self._enforce_size_limit()
150            self._strong_refs[key] = entry
151
152        return entry
153
154    def _enforce_size_limit(self) -> None:
155        """Evict old entries if cache is full"""
156        if self._max_size is None:
157            return
158
159        while len(self._strong_refs) >= self._max_size:
160            # Evict least accessed entry
161            if not self._strong_refs:
162                break
163
164            min_key = min(
165                self._strong_refs.keys(),
166                key=lambda k: self._strong_refs[k].access_count
167            )
168            del self._strong_refs[min_key]
169            self._evictions += 1
170
171    def pin(self, key: str) -> bool:
172        """
173        Pin an entry to prevent automatic cleanup.
174
175        Args:
176            key: Configuration key
177
178        Returns:
179            True if entry was pinned, False if not found
180        """
181        entry = self._cache.get(key)
182        if entry is None:
183            return False
184
185        self._enforce_size_limit()
186        self._strong_refs[key] = entry
187        return True
188
189    def unpin(self, key: str) -> bool:
190        """
191        Unpin an entry to allow automatic cleanup.
192
193        Args:
194            key: Configuration key
195
196        Returns:
197            True if entry was unpinned, False if not found
198        """
199        if key in self._strong_refs:
200            del self._strong_refs[key]
201            return True
202        return False
203
204    def clear(self) -> None:
205        """Clear all cached entries"""
206        self._cache.clear()
207        self._strong_refs.clear()
208
209    def stats(self) -> dict:
210        """
211        Get cache statistics.
212
213        Returns:
214            Dict with hits, misses, hit_rate, size, pinned, evictions
215        """
216        total = self._hits + self._misses
217        hit_rate = self._hits / total if total > 0 else 0.0
218
219        return {
220            "hits": self._hits,
221            "misses": self._misses,
222            "hit_rate": f"{hit_rate:.1%}",
223            "total_size": len(self._cache) + len(self._strong_refs),
224            "weak_refs": len(self._cache),
225            "pinned": len(self._strong_refs),
226            "evictions": self._evictions,
227        }
228
229    def memory_usage(self) -> dict:
230        """
231        Estimate memory usage of cached entries.
232
233        Returns:
234            Dict with entry_count, estimated_bytes, per_entry_bytes
235        """
236        all_entries = list(self._cache.values()) + list(self._strong_refs.values())
237
238        if not all_entries:
239            return {
240                "entry_count": 0,
241                "estimated_bytes": 0,
242                "per_entry_bytes": 0,
243            }
244
245        # Estimate based on first entry
246        sample = all_entries[0]
247        per_entry = sys.getsizeof(sample)
248
249        return {
250            "entry_count": len(all_entries),
251            "estimated_bytes": per_entry * len(all_entries),
252            "per_entry_bytes": per_entry,
253        }
254
255def demo_memory_optimization():
256    """Demonstrate memory optimization techniques"""
257
258    print("=" * 60)
259    print("Memory Optimization Demo")
260    print("=" * 60)
261
262    # Start memory tracking
263    tracemalloc.start()
264    gc.collect()
265    snapshot1 = tracemalloc.take_snapshot()
266
267    # Create cache and populate
268    cache = SmartConfigCache(max_size=100)
269
270    # Simulate loading many configurations
271    entries = []
272    for i in range(1000):
273        entry = cache.get_or_create(
274            f"config.item.{i}",
275            lambda i=i: ConfigEntry(
276                f"config.item.{i}",
277                f"value_{i}",
278                "demo"
279            ),
280            keep_strong=(i < 100)  # Pin first 100
281        )
282        entries.append(entry)
283
284    # Take snapshot after creation
285    gc.collect()
286    snapshot2 = tracemalloc.take_snapshot()
287
288    # Print stats
289    print("\nCache Statistics:")
290    for key, value in cache.stats().items():
291        print(f"  {key}: {value}")
292
293    print("\nMemory Usage:")
294    for key, value in cache.memory_usage().items():
295        print(f"  {key}: {value:,}")
296
297    # Show memory diff
298    diff = snapshot2.compare_to(snapshot1, 'lineno')
299    print("\nTop 5 Memory Allocations:")
300    for stat in diff[:5]:
301        print(f"  {stat}")
302
303    # Demo weak reference cleanup
304    print("\n" + "-" * 60)
305    print("Weak Reference Cleanup Demo")
306    print("-" * 60)
307
308    print(f"Before cleanup - Cache size: {cache.stats()['total_size']}")
309
310    # Delete external references to unpinned entries
311    del entries
312    gc.collect()
313
314    print(f"After cleanup  - Cache size: {cache.stats()['total_size']}")
315    print("(Only pinned entries remain)")
316
317    tracemalloc.stop()
318
319if __name__ == "__main__":
320    demo_memory_optimization()

使用範例

 1from memory_optimized_cache import SmartConfigCache, ConfigEntry
 2
 3# Initialize cache with size limit
 4cache = SmartConfigCache(max_size=1000)
 5
 6# Load configuration
 7def load_database_config():
 8    """Factory function to load database config"""
 9    return ConfigEntry(
10        key="database",
11        value={
12            "host": "localhost",
13            "port": 5432,
14            "name": "myapp"
15        },
16        source="config.yaml"
17    )
18
19# Get or create (with strong reference for important config)
20db_config = cache.get_or_create(
21    "database",
22    load_database_config,
23    keep_strong=True  # Keep in memory
24)
25
26print(f"Database host: {db_config.value['host']}")
27
28# Temporary config (will be auto-cleaned when not referenced)
29temp_config = cache.get_or_create(
30    "temp.setting",
31    lambda: ConfigEntry("temp.setting", "temporary", "runtime")
32)
33
34# Check statistics
35print(cache.stats())
36# {'hits': 0, 'misses': 2, 'hit_rate': '0.0%',
37#  'total_size': 2, 'weak_refs': 1, 'pinned': 1, 'evictions': 0}
38
39# Memory usage
40print(cache.memory_usage())
41# {'entry_count': 2, 'estimated_bytes': 112, 'per_entry_bytes': 56}

設計權衡

`slots` vs 標準類別

面向	標準類別	`__slots__`
記憶體佔用	較多（有 `__dict__`）	較少（節省 ~60-70%）
動態屬性	支援 `obj.new_attr = x`	不支援（除非加 `__dict__`）
繼承	簡單	子類別需要自己的 `__slots__`
弱引用	預設支援	需要加入 `__weakref__` slot
Pickle	直接支援	需要 `__getstate__`/`__setstate__`
多重繼承	正常運作	多個父類別不能都有非空 `__slots__`

強引用 vs 弱引用快取

面向	強引用快取	弱引用快取
記憶體管理	需要手動清理	自動清理
資料保證	資料一定存在	資料可能被回收
適用場景	關鍵配置	暫時性資料
實作複雜度	簡單	稍微複雜

何時使用哪種技術？

 1決策樹：
 2
 3物件數量多嗎？
 4├── 是 → 考慮 __slots__
 5│   └── 需要動態屬性嗎？
 6│       ├── 是 → __slots__ = [..., '__dict__']
 7│       └── 否 → __slots__ = [...]
 8└── 否 → 標準類別即可
 9
10快取可能無限增長嗎？
11├── 是 → 使用 WeakValueDictionary 或 LRU
12└── 否 → 普通字典即可
13
14資料可以被回收嗎？
15├── 是 → weakref
16└── 否 → 強引用

什麼時候該用這個技術？

適合使用

建立大量小物件：如資料點、事件、配置項目
記憶體使用是瓶頸：經過 profiling 確認
快取可能無限增長：如用戶 session、請求資料
長時間運行的服務：如 web server、daemon

不建議使用

物件數量很少：優化效果不明顯
需要動態新增屬性：__slots__ 會限制彈性
過早優化：先確認是否真的有問題
程式碼可讀性優先：標準類別更直觀

優化決策流程

 1# Step 1: Profile first!
 2# Don't optimize until you know where the problem is
 3
 4import tracemalloc
 5
 6tracemalloc.start()
 7# ... run your code ...
 8snapshot = tracemalloc.take_snapshot()
 9top_stats = snapshot.statistics('lineno')
10
11for stat in top_stats[:10]:
12    print(stat)
13
14# Step 2: If memory is the issue, identify the class
15# Look for classes with many instances
16
17import gc
18from collections import Counter
19
20counter = Counter(type(obj).__name__ for obj in gc.get_objects())
21print(counter.most_common(10))
22
23# Step 3: Only then apply __slots__ to hot classes

練習

基礎練習：比較有無 `slots` 的記憶體差異

撰寫一個腳本，比較以下三種類別建立 100,000 個實例的記憶體使用：

 1# Exercise: Complete this benchmark script
 2
 3import sys
 4import tracemalloc
 5from dataclasses import dataclass
 6
 7# 1. Standard class
 8class PointStandard:
 9    def __init__(self, x, y, z):
10        self.x = x
11        self.y = y
12        self.z = z
13
14# 2. Class with __slots__
15class PointSlots:
16    __slots__ = ['x', 'y', 'z']
17    def __init__(self, x, y, z):
18        self.x = x
19        self.y = y
20        self.z = z
21
22# 3. Named tuple
23from collections import namedtuple
24PointNamed = namedtuple('PointNamed', ['x', 'y', 'z'])
25
26# TODO: Write benchmark function
27def benchmark(cls, count=100000):
28    """Measure memory for creating `count` instances"""
29    pass  # Implement this
30
31# TODO: Compare results
32# Expected: PointSlots uses ~3x less memory than PointStandard

進階練習：實作 weakref 快取

建立一個 ImageCache 類別，具有以下功能：

 1# Exercise: Implement ImageCache
 2
 3class ImageCache:
 4    """
 5    Cache for image data with automatic cleanup.
 6
 7    Requirements:
 8    - Use WeakValueDictionary for auto-cleanup
 9    - Track hit/miss statistics
10    - Support maximum size limit
11    - Provide memory usage estimation
12
13    Example usage:
14        cache = ImageCache(max_size=100)
15
16        img = cache.get_or_load("photo.jpg", lambda: load_image("photo.jpg"))
17
18        print(cache.stats())
19        # {'hits': 0, 'misses': 1, 'size': 1}
20    """
21
22    def __init__(self, max_size=None):
23        # TODO: Initialize cache
24        pass
25
26    def get_or_load(self, key, loader):
27        # TODO: Implement get or load logic
28        pass
29
30    def stats(self):
31        # TODO: Return cache statistics
32        pass

挑戰題：用 tracemalloc 追蹤記憶體洩漏

給定以下有記憶體洩漏的程式碼，使用 tracemalloc 找出問題並修復：

 1# Exercise: Find and fix the memory leak
 2
 3class EventHandler:
 4    _handlers = []  # Class variable - potential leak!
 5
 6    def __init__(self, name):
 7        self.name = name
 8        self.callbacks = []
 9        EventHandler._handlers.append(self)  # Leak: strong reference
10
11    def register(self, callback):
12        self.callbacks.append(callback)
13
14    def fire(self, event):
15        for cb in self.callbacks:
16            cb(event)
17
18def process_events():
19    """This function creates handlers but never cleans them up"""
20    for i in range(1000):
21        handler = EventHandler(f"handler_{i}")
22        handler.register(lambda e: print(e))
23        handler.fire(f"event_{i}")
24        # handler goes out of scope but is still in _handlers!
25
26# TODO:
27# 1. Use tracemalloc to measure memory growth
28# 2. Identify the leak
29# 3. Fix EventHandler to use weak references
30# 4. Verify the fix with tracemalloc

延伸閱讀

上一章：效能分析實戰 返回：模組四：CPython 內部機制

3.2 記憶體管理與垃圾回收

Tue, 20 Jan 2026 00:00:00 +0000

Python 的記憶體管理結合了參考計數和分代垃圾回收。理解這些機制有助於寫出更高效的程式碼。

先備知識

3.1 PyObject 與物件模型

本章目標

學完本章後，你將能夠：

理解參考計數的限制
理解分代垃圾回收的原理
使用 __slots__ 優化記憶體
使用 tracemalloc 分析記憶體使用

【原理層】記憶體模型

Stack vs Heap

Python 的記憶體分為兩個主要區域：

 1┌─────────────────────────────────────┐
 2│              Stack                   │
 3│  ┌─────────────────────────────────┐│
 4│  │ 變數名稱 → 指向 Heap 的指標      ││
 5│  │ a ──────→ [指標]                ││
 6│  │ b ──────→ [指標]                ││
 7│  └─────────────────────────────────┘│
 8└─────────────────────────────────────┘
 9                 │
10                 ▼
11┌─────────────────────────────────────┐
12│              Heap                    │
13│  ┌─────────────────────────────────┐│
14│  │ PyObject: [1, 2, 3]             ││
15│  │ PyObject: "hello"               ││
16│  │ PyObject: 42                    ││
17│  └─────────────────────────────────┘│
18└─────────────────────────────────────┘

Stack：儲存變數名稱和指標（參考）
Heap：儲存實際的 Python 物件

Python 的記憶體分配器

CPython 使用分層的記憶體分配器：

 1┌─────────────────────────────────────┐
 2│     Python 物件分配器               │
 3│     (PyObject_Malloc)               │
 4├─────────────────────────────────────┤
 5│     Python 記憶體分配器             │
 6│     (PyMem_Malloc)                  │
 7├─────────────────────────────────────┤
 8│     C 標準函式庫                    │
 9│     (malloc)                        │
10├─────────────────────────────────────┤
11│     作業系統                        │
12└─────────────────────────────────────┘

對於小於 512 bytes 的物件，Python 使用自己的分配器來減少系統呼叫。

【設計層】循環參考問題

參考計數的限制

參考計數無法處理循環參考：

 1import gc
 2
 3class Node:
 4    def __init__(self, name):
 5        self.name = name
 6        self.ref = None
 7
 8# 建立循環參考
 9a = Node("A")
10b = Node("B")
11a.ref = b
12b.ref = a
13
14# 刪除外部參考
15del a
16del b
17
18# 此時 A 和 B 仍互相參考，參考計數都是 1
19# 但它們已經無法被存取了（垃圾）

1刪除前：
2外部 ─→ A ←──→ B ←─ 外部
3        refcnt=2  refcnt=2
4
5刪除後：
6        A ←──→ B
7        refcnt=1  refcnt=1
8        （無法被存取，但參考計數不為 0）

分代垃圾回收

為了解決循環參考，Python 使用分代垃圾回收：

 1import gc
 2
 3# 查看 GC 統計
 4print(gc.get_count())  # (700, 10, 0) - 各代的物件數
 5
 6# 三個世代（Python 3.12 以前）
 7# Generation 0: 新物件
 8# Generation 1: 存活過一次 GC 的物件
 9# Generation 2: 存活過多次 GC 的物件
10
11# Python 3.12+ 改為四個世代
12# Young generation (1 代)
13# Old generations (2 代)
14# Permanent generation (永久)

GC 觸發時機

 1import gc
 2
 3# 查看閾值
 4print(gc.get_threshold())  # (700, 10, 10)
 5
 6# 意義：
 7# - 當 Generation 0 有 700 個物件時，觸發 Gen 0 GC
 8# - 當 Gen 0 GC 執行 10 次後，觸發 Gen 1 GC
 9# - 當 Gen 1 GC 執行 10 次後，觸發 Gen 2 GC
10
11# 手動觸發 GC
12gc.collect()
13
14# 設定閾值
15gc.set_threshold(1000, 15, 15)

【實作層】記憶體優化

使用 slots

__slots__ 可以顯著減少物件的記憶體使用：

 1import sys
 2
 3class WithoutSlots:
 4    def __init__(self, x, y):
 5        self.x = x
 6        self.y = y
 7
 8class WithSlots:
 9    __slots__ = ['x', 'y']
10
11    def __init__(self, x, y):
12        self.x = x
13        self.y = y
14
15obj1 = WithoutSlots(1, 2)
16obj2 = WithSlots(1, 2)
17
18print(sys.getsizeof(obj1))  # 48
19print(sys.getsizeof(obj2))  # 48（但沒有 __dict__）
20
21# 實際差異在 __dict__
22print(sys.getsizeof(obj1.__dict__))  # 104
23# obj2 沒有 __dict__

為什麼 `slots` 省記憶體？

 1沒有 __slots__：
 2┌─────────────────────────┐
 3│ PyObject header (16 B)  │
 4│ __dict__ 指標 (8 B)      │
 5│ __weakref__ 指標 (8 B)   │
 6│ __dict__ → { 'x': 1,    │
 7│              'y': 2 }   │
 8│            （額外 100+ B）│
 9└─────────────────────────┘
10
11有 __slots__：
12┌─────────────────────────┐
13│ PyObject header (16 B)  │
14│ x (8 B)                 │
15│ y (8 B)                 │
16└─────────────────────────┘

slots 的限制

 1class Base:
 2    __slots__ = ['x']
 3
 4class Derived(Base):
 5    __slots__ = ['y']  # 不能與父類別重複
 6
 7    def __init__(self):
 8        self.x = 1
 9        self.y = 2
10        # self.z = 3  # 錯誤！沒有 __dict__
11
12# 如果需要動態屬性，加入 '__dict__'
13class Flexible:
14    __slots__ = ['x', '__dict__']

使用弱參考

弱參考不增加參考計數，適合用於快取：

 1import weakref
 2
 3class ExpensiveObject:
 4    def __init__(self, value):
 5        self.value = value
 6
 7# 建立物件和弱參考
 8obj = ExpensiveObject(42)
 9weak_ref = weakref.ref(obj)
10
11print(weak_ref())  # 
12print(weak_ref().value)  # 42
13
14# 刪除強參考
15del obj
16
17print(weak_ref())  # None（物件已被回收）

使用 WeakValueDictionary 實作快取

 1import weakref
 2
 3class Cache:
 4    def __init__(self):
 5        self._cache = weakref.WeakValueDictionary()
 6
 7    def get(self, key, factory):
 8        value = self._cache.get(key)
 9        if value is None:
10            value = factory()
11            self._cache[key] = value
12        return value
13
14cache = Cache()
15
16def create_expensive():
17    return ExpensiveObject(100)
18
19obj = cache.get('key1', create_expensive)
20# 當 obj 不再被使用時，快取會自動清理

【實作層】記憶體分析工具

使用 tracemalloc

 1import tracemalloc
 2
 3# 開始追蹤
 4tracemalloc.start()
 5
 6# 執行程式碼
 7data = [i ** 2 for i in range(10000)]
 8more_data = {str(i): i for i in range(10000)}
 9
10# 取得記憶體快照
11snapshot = tracemalloc.take_snapshot()
12
13# 顯示前 10 個記憶體使用最多的位置
14top_stats = snapshot.statistics('lineno')
15for stat in top_stats[:10]:
16    print(stat)
17
18# 比較兩個快照
19tracemalloc.start()
20snapshot1 = tracemalloc.take_snapshot()
21
22# 執行更多程式碼
23big_list = list(range(100000))
24
25snapshot2 = tracemalloc.take_snapshot()
26diff = snapshot2.compare_to(snapshot1, 'lineno')
27
28for stat in diff[:5]:
29    print(stat)

使用 gc 模組除錯

 1import gc
 2
 3# 啟用除錯
 4gc.set_debug(gc.DEBUG_LEAK)
 5
 6# 找出無法回收的物件
 7gc.collect()
 8print(gc.garbage)  # 無法回收的物件列表
 9
10# 取得所有被追蹤的物件
11all_objects = gc.get_objects()
12print(f"被追蹤的物件數量: {len(all_objects)}")
13
14# 找出特定類別的實例
15class MyClass:
16    pass
17
18instances = [obj for obj in gc.get_objects() if isinstance(obj, MyClass)]
19print(f"MyClass 實例數量: {len(instances)}")

檢測記憶體洩漏

 1import gc
 2import tracemalloc
 3
 4def find_memory_leak():
 5    tracemalloc.start()
 6
 7    # 記錄初始狀態
 8    gc.collect()
 9    snapshot1 = tracemalloc.take_snapshot()
10
11    # 執行可能洩漏的程式碼
12    for _ in range(1000):
13        suspicious_function()
14
15    # 記錄最終狀態
16    gc.collect()
17    snapshot2 = tracemalloc.take_snapshot()
18
19    # 比較
20    diff = snapshot2.compare_to(snapshot1, 'lineno')
21
22    print("記憶體增長最多的位置：")
23    for stat in diff[:10]:
24        print(stat)

【實戰】常見記憶體問題

問題 1：大量小物件

 1# 不好：建立大量小物件
 2class Point:
 3    def __init__(self, x, y):
 4        self.x = x
 5        self.y = y
 6
 7points = [Point(i, i) for i in range(1000000)]
 8
 9# 好：使用 __slots__
10class Point:
11    __slots__ = ['x', 'y']
12    def __init__(self, x, y):
13        self.x = x
14        self.y = y
15
16# 更好：使用 NumPy（如果是數值資料）
17import numpy as np
18points = np.zeros((1000000, 2))

問題 2：循環參考

 1# 不好：物件間的循環參考
 2class Parent:
 3    def __init__(self):
 4        self.children = []
 5
 6class Child:
 7    def __init__(self, parent):
 8        self.parent = parent
 9        parent.children.append(self)
10
11# 好：使用弱參考
12import weakref
13
14class Child:
15    def __init__(self, parent):
16        self.parent = weakref.ref(parent)
17        parent.children.append(self)

問題 3：全域變數累積

 1# 不好：全域快取無限增長
 2_cache = {}
 3
 4def process(key, value):
 5    if key not in _cache:
 6        _cache[key] = expensive_compute(value)
 7    return _cache[key]
 8
 9# 好：使用 LRU cache
10from functools import lru_cache
11
12@lru_cache(maxsize=1000)
13def process(key, value):
14    return expensive_compute(value)

思考題

為什麼 Python 需要同時使用參考計數和垃圾回收？只用其中一種不行嗎？
__slots__ 為什麼不能用於繼承自內建型別的類別？
在什麼情況下應該手動呼叫 gc.collect()？

實作練習

使用 tracemalloc 分析一個現有程式的記憶體使用
將一個使用大量物件的程式改用 __slots__ 優化
使用 WeakValueDictionary 實作一個自動清理的快取

延伸閱讀

上一章：PyObject 與物件模型 下一章：Bytecode 與虛擬機

1.4 共享狀態與複製邊界

Wed, 22 Apr 2026 00:00:00 +0000

共享狀態的核心規則是同一份可變資料若會被多個 goroutine 存取，就必須有明確 owner 與保護邊界。Map 需要同步，slice 回傳前通常要 copy，可變指標不能隨意暴露，修改行為應集中在擁有狀態的型別內。

本章目標

學完本章後，你將能夠：

判斷哪個型別擁有共享狀態
用 sync.RWMutex 保護 map 與 slice
避免回傳內部 map、slice、pointer
分辨 shallow copy 與 deep copy 的邊界
用測試與 race detector 驗證共享狀態安全性

【觀察】共享狀態風險通常延遲出現

共享狀態的核心風險是錯誤可能只在特定併發時序下出現。單元測試可能通過，本地手動操作也正常，但高流量下會出現 data race、map panic、狀態被外部修改或歷史資料被覆蓋。

反模式示意：

 1type Store struct {
 2    users map[string]User
 3}
 4
 5func (s *Store) Save(user User) {
 6    s.users[user.ID] = user
 7}
 8
 9func (s *Store) Users() map[string]User {
10    return s.users
11}

這個型別有兩個問題：map 沒有同步保護，且 Users 直接暴露內部 map。呼叫端拿到 map 後可以繞過 Store 修改資料。

【判讀】mutex 保護的是狀態不變式

Mutex 的核心責任不是讓程式「不會同時跑」，而是保護某一組資料的不變式。只要讀寫同一份可變資料，就應該由同一個 owner 控制 lock。

 1type UserRepository struct {
 2    mu    sync.RWMutex
 3    users map[string]User
 4}
 5
 6func NewUserRepository() *UserRepository {
 7    return &UserRepository{
 8        users: make(map[string]User),
 9    }
10}

UserRepository 是 users map 的 owner。外部程式不應持有 users 的 reference，也不應知道它用 map、資料庫或其他結構保存。

【執行】所有讀寫都經過 owner method

共享 map 的核心規則是所有讀寫都經過同一組方法。寫入使用 Lock，讀取使用 RLock。

 1func (r *UserRepository) Save(ctx context.Context, user User) error {
 2    r.mu.Lock()
 3    defer r.mu.Unlock()
 4
 5    r.users[user.ID] = user
 6    return nil
 7}
 8
 9func (r *UserRepository) Find(ctx context.Context, id string) (User, bool, error) {
10    r.mu.RLock()
11    defer r.mu.RUnlock()
12
13    user, ok := r.users[id]
14    return user, ok, nil
15}

context.Context 在 memory repository 裡可能用不到，但保留在 method signature 可以讓未來改成資料庫或遠端儲存時支援取消。這是 repository port 常見的演進邊界。

【判讀】回傳內部 map 會破壞 lock

回傳 map 的核心風險是鎖只保護到方法結束。方法回傳後，呼叫端拿到的仍然是同一份 map，任何修改都會繞過 owner。

反模式：

1func (r *UserRepository) UnsafeUsers(ctx context.Context) map[string]User {
2    r.mu.RLock()
3    defer r.mu.RUnlock()
4
5    return r.users
6}

這段程式看起來有加鎖，但鎖釋放後外部仍能修改內部 map：

1users := repo.UnsafeUsers(ctx)
2delete(users, "user_1")

安全做法是回傳 copy：

 1func (r *UserRepository) Users(ctx context.Context) (map[string]User, error) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    result := make(map[string]User, len(r.users))
 6    for id, user := range r.users {
 7        result[id] = user
 8    }
 9    return result, nil
10}

呼叫端可以自由修改 result，不會影響 repository 內部狀態。

【判讀】slice copy 保護的是底層 array

Slice 的核心風險是 slice header 會被複製，但底層 array 可能共享。直接回傳 slice 會讓呼叫端修改 owner 的內部資料。

 1type RecentEvents struct {
 2    mu     sync.RWMutex
 3    events []Event
 4}
 5
 6func (r *RecentEvents) Append(ctx context.Context, event Event) {
 7    r.mu.Lock()
 8    defer r.mu.Unlock()
 9
10    r.events = append(r.events, event)
11}

安全的 list method：

1func (r *RecentEvents) List(ctx context.Context) []Event {
2    r.mu.RLock()
3    defer r.mu.RUnlock()
4
5    result := make([]Event, len(r.events))
6    copy(result, r.events)
7    return result
8}

copy 建立新的底層 array。呼叫端對 result 排序、截斷、append 或修改元素，不會改到 r.events。

【策略】值型別可以 shallow copy，可變欄位需要 deep copy

Copy boundary 的核心判斷是資料裡是否還包含可變 reference。若 struct 只有 string、int、time.Time 這類值型別，shallow copy 通常足夠；若 struct 包含 map、slice 或 pointer，就要考慮 deep copy。

值型別範例：

1type Event struct {
2    ID        string
3    Type      string
4    CreatedAt time.Time
5}

這種 Event 放在 slice 裡，用 copy 複製 slice 通常足夠。

含可變欄位的範例：

1type Event struct {
2    ID       string
3    Type     string
4    Metadata map[string]string
5}

這時只 copy slice 不夠，因為每個 Event.Metadata 仍然指向同一份 map。需要 clone：

 1func CloneEvent(event Event) Event {
 2    cloned := event
 3    if event.Metadata != nil {
 4        cloned.Metadata = make(map[string]string, len(event.Metadata))
 5        for key, value := range event.Metadata {
 6            cloned.Metadata[key] = value
 7        }
 8    }
 9    return cloned
10}

是否需要 deep copy 取決於 API 承諾。如果呼叫端不應修改 repository 內部資料，就要複製所有可變 reference。

【判讀】回傳 pointer 要代表明確修改權

Pointer 回傳的核心語意是呼叫端取得同一份資料的參照。若資料屬於共享狀態，回傳 pointer 通常會破壞 owner 邊界。

容易誤解的 API：

 1func (r *UserRepository) FindPointer(ctx context.Context, id string) (*User, bool) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    user, ok := r.users[id]
 6    if !ok {
 7        return nil, false
 8    }
 9    return &user, true
10}

這段程式回傳的是區域變數 user 的指標，不是 map 內部資料的可修改入口。呼叫端修改這個 pointer，不會保存回 repository。API 看起來像能修改，實際不能，語意不清楚。

更清楚的做法是回傳 value，並提供明確 update method：

 1func (r *UserRepository) UpdateEmail(ctx context.Context, id string, email string) (bool, error) {
 2    r.mu.Lock()
 3    defer r.mu.Unlock()
 4
 5    user, ok := r.users[id]
 6    if !ok {
 7        return false, nil
 8    }
 9
10    user.Email = email
11    r.users[id] = user
12    return true, nil
13}

修改行為集中在 repository 內，lock、驗證與狀態一致性也留在同一個地方。

【策略】mutex 和 channel owner 要按資料形狀選擇

狀態保護的核心選擇是 mutex owner 或 goroutine owner。兩者都符合 Go 的精神，差異在資料存取模式。

方法	適用情境	代價
mutex owner	多個方法需要同步讀寫狀態	要維護 lock 與 copy boundary
goroutine owner	所有修改都能表示成訊息	要設計 command、reply、shutdown

Mutex 版本：

1repo.Save(ctx, user)
2user, ok, err := repo.Find(ctx, id)

Goroutine owner 版本：

1type command struct {
2    kind  string
3    user  User
4    reply chan result
5}

不要為了避免 mutex 而把簡單狀態硬改成複雜訊息系統。也不要在需要嚴格順序與單一事件流時到處加 lock。選擇應該來自資料形狀與讀寫模式。

【測試】copy boundary 要用外部修改驗證

Copy boundary 的測試核心是呼叫 getter 後修改回傳值，再確認 owner 內部資料沒有被改動。

 1func TestUsersReturnsCopy(t *testing.T) {
 2    repo := NewUserRepository()
 3    ctx := context.Background()
 4
 5    if err := repo.Save(ctx, User{ID: "user_1", Email: "a@example.com"}); err != nil {
 6        t.Fatalf("save user: %v", err)
 7    }
 8
 9    users, err := repo.Users(ctx)
10    if err != nil {
11        t.Fatalf("users: %v", err)
12    }
13    delete(users, "user_1")
14
15    _, ok, err := repo.Find(ctx, "user_1")
16    if err != nil {
17        t.Fatalf("find user: %v", err)
18    }
19    if !ok {
20        t.Fatalf("repository should not be modified through returned map")
21    }
22}

Slice copy 也用同樣方式測：

 1func TestEventListReturnsCopy(t *testing.T) {
 2    events := &RecentEvents{}
 3    ctx := context.Background()
 4
 5    events.Append(ctx, Event{ID: "evt_1"})
 6    got := events.List(ctx)
 7    got[0].ID = "changed"
 8
 9    again := events.List(ctx)
10    if again[0].ID != "evt_1" {
11        t.Fatalf("internal event was modified through returned slice")
12    }
13}

這類測試能直接防止未來有人為了「省 copy」而破壞狀態邊界。

【測試】race detector 驗證同步邊界

Race detector 的核心用途是找出未同步的共享記憶體存取。對含有 goroutine、map、slice、repository 的測試，應定期執行：

1go test -race ./...

可以用併發測試增加觸發機率：

 1func TestRepositoryConcurrentAccess(t *testing.T) {
 2    repo := NewUserRepository()
 3    ctx := context.Background()
 4
 5    var wg sync.WaitGroup
 6    for i := 0; i < 100; i++ {
 7        i := i
 8        wg.Add(1)
 9        go func() {
10            defer wg.Done()
11            id := fmt.Sprintf("user_%d", i)
12            _ = repo.Save(ctx, User{ID: id})
13            _, _, _ = repo.Find(ctx, id)
14        }()
15    }
16    wg.Wait()
17}

這個測試本身不一定能證明沒有所有問題，但搭配 -race 可以檢查 repository 方法是否真的包住共享 map。

本章不處理

本章先聚焦單一 Go process 內的共享狀態保護；更外層的資料庫交易、快取一致性與資料複製邊界，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 repository、copy boundary 與 state owner；如果你要先回看語言教材，可以讀：

小結

共享狀態的安全邊界由 owner、lock、copy 與明確修改方法組成。Map/slice 讀寫要經過同一個 owner；getter 不應暴露內部可變資料；含 map、slice、pointer 的 struct 要考慮 deep copy；修改行為應集中在方法內。這些規則能讓長時間運行的 Go 服務避開 data race、外部突變與難以重現的狀態錯誤。

2.4 慢客戶端與 send buffer 管理

Wed, 22 Apr 2026 00:00:00 +0000

慢客戶端管理的核心問題是單一 client 的讀取速度可能低於 server 推送速度。若 send buffer 沒有上限，慢 client 會把訊息堆在記憶體裡；若 hub 使用 blocking send，慢 client 會拖住所有 client。

本章目標

學完本章後，你將能夠：

分辨慢 client 對 hub、write pump、記憶體的影響
用 bounded send channel 限制單一 client 的排隊量
設計 queue full 時的 drop、disconnect、coalesce 策略
在必要時用 byte budget 管理大型 payload
測試 send buffer 滿載與 client unregister 行為

【觀察】慢 client 會把局部問題變成全域問題

慢 client 的核心風險是它不只影響自己。若 hub broadcast 時對每個 client 使用 blocking send，其中一個 client 的 send channel 滿了，hub 就可能卡住，其他 client 也收不到訊息。

反模式：

1func (h *Hub) Broadcast(message ServerMessage) {
2    for client := range h.clients {
3        client.send <- message
4    }
5}

這段程式看起來保證送達，但實際上把整個 hub 的可用性綁在最慢的 client 上。只要一個 client 不讀，所有 broadcast 都可能停住。

【判讀】send channel 是每個 client 的容量邊界

Send channel 的核心責任是作為單一 client 的輸出佇列。它必須有容量上限，否則 server 會替慢 client 無限制保存訊息。

 1const sendBufferSize = 64
 2
 3type Client struct {
 4    id   string
 5    send chan ServerMessage
 6}
 7
 8func NewClient(id string) *Client {
 9    return &Client{
10        id:   id,
11        send: make(chan ServerMessage, sendBufferSize),
12    }
13}

Buffer 的目的只是吸收短暫尖峰，不是讓 client 長期落後。若 client 長期消費速度低於推送速度，任何有限 buffer 都會滿。

【策略】滿載策略取決於訊息語意

慢 client 滿載的核心決策是訊息能不能遺失。不同資料類型需要不同策略。

訊息類型	常見策略	理由
即時狀態 snapshot	可丟棄舊訊息或 coalesce	最新狀態比每個中間狀態重要
action result	優先送達，滿載時可斷線	client 需要知道操作結果
診斷 log stream	可取樣或丟棄	資料量大，通常不是唯一真相
金流、訂單、稽核事件	不應只靠 WebSocket	需要可靠儲存或可重播來源

WebSocket send buffer 不應承擔資料可靠性。若訊息不能遺失，可靠性應放在資料庫、queue 或 event log，WebSocket 只負責即時通知。

【執行】non-blocking send 保護 hub

Hub 的核心保護是 broadcast 時不被單一 client 阻塞。TrySend 可以讓 hub 立即知道該 client 是否已滿載。

1func (c *Client) TrySend(message ServerMessage) bool {
2    select {
3    case c.send <- message:
4        return true
5    default:
6        return false
7    }
8}

Hub 可以把滿載 client 送進 unregister：

 1func (h *Hub) Broadcast(topic string, message ServerMessage) {
 2    for client := range h.clients {
 3        if !client.IsSubscribed(topic) {
 4            continue
 5        }
 6
 7        if ok := client.TrySend(message); !ok {
 8            h.unregister <- client
 9        }
10    }
11}

這種策略犧牲慢 client，保護整體服務。對即時通知服務來說，讓慢 client 重連並重新取得 snapshot，通常比讓所有 client 等它更合理。

【策略】drop newest、drop oldest、disconnect 是不同語意

Queue full 策略的核心差異是保留哪一筆資料，以及是否繼續維持連線。

策略	行為	適用情境
drop newest	新訊息不進 queue	舊訊息仍有價值
drop oldest	移除舊訊息，保留最新	狀態型更新
disconnect	關閉 client，要求重連	client 已明顯跟不上
coalesce	合併多筆更新成一筆	topic 最新狀態可覆蓋

Drop oldest 範例：

 1func (c *Client) TrySendLatest(message ServerMessage) bool {
 2    select {
 3    case c.send <- message:
 4        return true
 5    default:
 6    }
 7
 8    select {
 9    case <-c.send:
10    default:
11    }
12
13    select {
14    case c.send <- message:
15        return true
16    default:
17        return false
18    }
19}

這段程式表示「新狀態比舊狀態重要」。它不適合 action result 或不可遺失事件，因為它會主動丟掉尚未送出的舊訊息。

【策略】byte budget 比 message count 更接近記憶體風險

Message count 的核心限制是每筆訊息大小不同。64 筆小訊息和 64 筆大型 JSON payload 的記憶體成本差很多；當 payload 大小差異明顯時，可以加上 byte budget。

 1type Client struct {
 2    send      chan ServerMessage
 3    sendBytes int64
 4    maxBytes  int64
 5}
 6
 7func (c *Client) TrySend(message ServerMessage) bool {
 8    size := int64(message.Size())
 9    if atomic.AddInt64(&c.sendBytes, size) > c.maxBytes {
10        atomic.AddInt64(&c.sendBytes, -size)
11        return false
12    }
13
14    select {
15    case c.send <- message:
16        return true
17    default:
18        atomic.AddInt64(&c.sendBytes, -size)
19        return false
20    }
21}

Write pump 成功取出並寫出訊息後，必須扣回 byte budget：

1func (c *Client) markSent(message ServerMessage) {
2    atomic.AddInt64(&c.sendBytes, -int64(message.Size()))
3}

Byte budget 更接近記憶體風險，但也更複雜。只有在訊息大小差異大、或服務連線數高時才值得加入；小型服務先用固定 buffer 通常足夠。

【判讀】write pump 慢不一定是 client 的錯

慢寫入的核心原因可能在 client，也可能在 server。Client 網路慢、瀏覽器停住、行動裝置休眠會造成慢寫；server payload 太大、序列化太慢、單次寫入沒有 deadline 也會造成問題。

排查方向：

send buffer 長期接近滿載
write deadline 錯誤增加
單筆 message size 過大
broadcast 頻率超過 client 消費能力
某些 topic 推送量異常高

queue full 的歸因應同時檢查 client 與 server 端訊號。若所有 client 都慢，通常是 server 推送量、payload 大小或下游網路策略出問題。

【策略】滿載要有觀測欄位

慢 client 策略的核心要求是可觀測。若系統選擇 drop 或 disconnect，應記錄足夠欄位讓工程師知道原因。

 1func (h *Hub) handleFullClient(client *Client, topic string) {
 2    metrics.Inc("websocket_client_send_full")
 3    h.logger.Warn("websocket client send buffer full",
 4        "client_id", client.ID(),
 5        "topic", topic,
 6        "send_queue_len", len(client.send),
 7        "send_queue_cap", cap(client.send),
 8    )
 9    h.unregister <- client
10}

Log 用來追單次事件，metric 用來看趨勢。若滿載數量突然增加，可能是某個 topic 推送量上升，也可能是 client 版本或網路環境改變。

【測試】滿載測試要先填滿 buffer

慢 client 測試的核心是直接建立滿載條件。容量為 1 的 channel 加上預先填滿的資料，可以穩定製造 queue full；sleep 只是在等待排程運氣。

 1func TestTrySendReturnsFalseWhenBufferFull(t *testing.T) {
 2    client := &Client{
 3        id:   "client_1",
 4        send: make(chan ServerMessage, 1),
 5    }
 6    client.send <- ServerMessage{Type: "first"}
 7
 8    ok := client.TrySend(ServerMessage{Type: "second"})
 9    if ok {
10        t.Fatalf("TrySend should return false when buffer is full")
11    }
12}

Hub unregister 行為也可以測：

 1func TestBroadcastUnregistersFullClient(t *testing.T) {
 2    hub := NewHub()
 3    client := NewTestClient("client_1", 1)
 4    client.Subscribe("alerts")
 5    client.send <- ServerMessage{Type: "existing"}
 6    hub.clients[client] = struct{}{}
 7
 8    hub.Broadcast("alerts", ServerMessage{Type: "new"})
 9
10    select {
11    case got := <-hub.unregister:
12        if got != client {
13            t.Fatalf("unregister client mismatch")
14        }
15    default:
16        t.Fatalf("full client should be unregistered")
17    }
18}

這類測試直接驗證服務策略：client 滿載時，hub 不阻塞，而是走指定降級路徑。

本章不處理

本章先處理單一 server 內的慢 client 與 send buffer 邊界；跨節點 fan-out 與持久化同步，會在下列章節延伸：

Go 進階：跨節點 WebSocket、presence 與重連協定

和 Go 教材的關係

這一章承接的是 channel backpressure 、non-blocking send 與 rate limiting；如果你要先回看語言教材，可以讀：

小結

慢客戶端是 WebSocket 服務的容量控制問題。每個 client 的 send buffer 必須有上限，hub broadcast 不應被單一 client 阻塞，queue full 策略要符合訊息語意。必要時可加入 byte budget，但更重要的是明確決定 drop、disconnect、coalesce 或可靠儲存，並用 log、metric、測試讓降級行為可見。

3.4 資料結構與 allocation 壓力

Wed, 22 Apr 2026 00:00:00 +0000

Allocation 分析的核心目標是區分必要的安全複製與可優化的重複配置。Go 服務中很多配置來自 slice 成長、map/list 複製、JSON marshal、buffer 建立與 WebSocket payload；優化前要先確認配置是否位於熱路徑，且不能破壞狀態邊界。

本章目標

學完本章後，你將能夠：

理解 allocation 如何增加 GC 壓力
分辨必要 copy boundary 與不必要重複配置
用預配置降低 slice 成長成本
判斷 JSON marshal 與 WebSocket payload 的重用邊界
用 pprof 的 alloc_space 與 inuse_space 決定優化方向

【觀察】allocation 壓力會放大 GC 成本

Allocation 的核心影響是增加 heap 成長速度，進而增加 GC 工作量。即使物件很快被回收，大量短命配置仍可能造成 CPU 與 latency 壓力。

常見熱路徑：

每次 WebSocket broadcast 都對每個 client 重新 marshal。
每次 API list 都建立大型 slice。
每次 repository 查詢都 copy 大型 map。
每次 log 都組大量臨時欄位。
每次 encode 都建立新的 bytes.Buffer。

不是所有 allocation 都要消除。診斷重點是找出高頻、可避免、且不破壞邊界的配置。

【判讀】預配置解決的是成長成本

Slice 預配置的核心用途是讓底層 array 成長符合預期。若結果長度可預估，應用 make 設定容量。

未預配置：

1func BuildNames(users []User) []string {
2    var names []string
3    for _, user := range users {
4        names = append(names, user.Name)
5    }
6    return names
7}

預配置：

1func BuildNames(users []User) []string {
2    names := make([]string, 0, len(users))
3    for _, user := range users {
4        names = append(names, user.Name)
5    }
6    return names
7}

這不是微優化。若這段程式在高頻 list API、background projection 或 broadcast path 中執行，預配置可以減少反覆擴容與 copy。

【判讀】copy boundary 是必要成本

安全複製的核心目的是保護內部可變狀態。Repository 回傳資料時 copy slice 或 map，會增加 allocation，但能避免外部突變與 data race。

 1func (r *UserRepository) ListUsers(ctx context.Context) ([]User, error) {
 2    r.mu.RLock()
 3    defer r.mu.RUnlock()
 4
 5    users := make([]User, 0, len(r.users))
 6    for _, user := range r.users {
 7        users = append(users, user)
 8    }
 9    return users, nil
10}

這個 allocation 是狀態邊界的成本。優化前要先確認它是否真的是瓶頸，不能只因為 profile 看到配置就移除 copy。

若列表很大且讀取頻繁，應考慮分頁、projection、snapshot cache 或只回傳必要欄位。不要為了省配置而直接暴露內部 map。

【策略】大型 list 優先改資料形狀

大型 list allocation 的核心問題常常是 API 一次回太多資料。若每次請求都複製整個 repository，配置與延遲都會隨資料量線性成長。

可選策略：

策略	適用情境	代價
分頁	使用者只需要部分資料	API 需要 cursor 或 offset
projection	只需要摘要欄位	要維護讀取模型
snapshot cache	讀多寫少	要處理快取失效
incremental update	WebSocket 推送最新變化	client 要能合併狀態

優化資料形狀通常比取消 copy 更安全。Copy boundary 保護正確性，資料形狀決定每次 copy 的成本。

【執行】JSON marshal 是 WebSocket 常見配置來源

JSON 序列化的核心成本是把 Go 資料結構轉成 bytes。高頻 WebSocket 推送若對每個 client 反覆 marshal 同一份 message，會造成大量短命配置。

反模式：

1for _, client := range clients {
2    payload, err := json.Marshal(message)
3    if err != nil {
4        return err
5    }
6    client.SendBytes(payload)
7}

同一份 message 可以先 marshal 一次：

1payload, err := json.Marshal(message)
2if err != nil {
3    return err
4}
5
6for _, client := range clients {
7    client.SendBytes(payload)
8}

這個優化的前提是 payload 被視為只讀。Send path 不應修改傳入的 bytes；若某個 client 需要修改，就應在該 client 邊界 copy，而不是讓共享 payload 被改動。

【判讀】bytes 重用要先定義所有權

Bytes 重用的核心風險是共享 slice 被修改。[]byte 是可變資料，傳給多個 client 時要明確規定它只讀。

可以用型別或註解表達語意：

1type EncodedMessage []byte
2
3func (c *Client) SendEncoded(message EncodedMessage) bool {
4    return c.TrySend(ServerMessage{
5        Encoded: message,
6    })
7}

這不能從型別上完全禁止修改，但能讓 API 語意更清楚。真正保護仍靠 ownership 規則、測試與 code review。

若無法保證下游不修改，就必須 copy：

1func CloneBytes(input []byte) []byte {
2    output := make([]byte, len(input))
3    copy(output, input)
4    return output
5}

效能優化不能建立在模糊的可變資料共享上。

【策略】sync.Pool 只適合已證明的熱路徑

sync.Pool 的核心用途是複用高頻、短命、可重建的暫存物件。它可以降低配置，但會增加所有權複雜度。

 1var bufferPool = sync.Pool{
 2    New: func() any {
 3        return new(bytes.Buffer)
 4    },
 5}
 6
 7func Encode(value any) ([]byte, error) {
 8    buf := bufferPool.Get().(*bytes.Buffer)
 9    defer bufferPool.Put(buf)
10    buf.Reset()
11
12    if err := json.NewEncoder(buf).Encode(value); err != nil {
13        return nil, err
14    }
15
16    output := append([]byte(nil), buf.Bytes()...)
17    return output, nil
18}

這裡仍然 copy 出 output，因為 buf 會被放回 pool。若直接回傳 buf.Bytes()，呼叫端拿到的 slice 可能在 pool 重用後被覆寫。

不要一開始就使用 sync.Pool。先用 pprof 證明配置是瓶頸，再評估 pool 是否值得承擔額外複雜度。

【判讀】inuse 與 alloc 回答不同問題

Heap profile 的核心判讀是分清 inuse_space 與 alloc_space。

1go tool pprof http://localhost:8080/debug/pprof/heap
2go tool pprof -alloc_space http://localhost:8080/debug/pprof/heap

指標	問題	常見修正
`inuse_space` 高	現在誰保留記憶體	cache 淘汰、釋放引用、限制 buffer
`alloc_space` 高	誰累積配置最多	預配置、重用、減少 marshal、改資料形狀

若 alloc_space 高但 inuse_space 不高，代表配置很多但大多被回收，問題可能是 GC 壓力。若 inuse_space 持續上升，代表資料被長期保留，應檢查 cache、map、slice、goroutine reference 或 send buffer。

【策略】allocation 優化要保留正確性邊界

Allocation 優化的核心底線是不能破壞狀態安全。以下做法通常不可接受：

為了省 copy，直接回傳 repository 內部 map。
為了省 bytes，讓多個 client 共享可修改 payload。
為了省 allocation，把 buffer 放回 pool 後仍回傳其底層 slice。
為了少建立 struct，把 request DTO 和 domain state 混用。

較安全的優化順序：

用 pprof 確認熱點。
預配置已知大小的 slice/map。
減少重複 marshal。
改 API 資料形狀，例如分頁或 projection。
最後才考慮 sync.Pool。

這個順序先處理低風險、高可讀性的改動，再處理高複雜度工具。

【測試】優化後要補邊界測試

Allocation 優化的測試核心是確保共享資料沒有被外部修改。若你重用 bytes、snapshot 或 pooled buffer，要補測試保護 ownership。

例如 repository list 仍要回傳 copy：

 1func TestListUsersReturnsCopy(t *testing.T) {
 2    repo := NewUserRepository()
 3    ctx := context.Background()
 4    _ = repo.Save(ctx, User{ID: "user_1"})
 5
 6    users, err := repo.ListUsers(ctx)
 7    if err != nil {
 8        t.Fatalf("list users: %v", err)
 9    }
10    users[0].ID = "changed"
11
12    again, err := repo.ListUsers(ctx)
13    if err != nil {
14        t.Fatalf("list users again: %v", err)
15    }
16    if again[0].ID != "user_1" {
17        t.Fatalf("repository data was modified through returned slice")
18    }
19}

這種測試能防止未來為了省 allocation 而移除必要 copy。

本章不處理

本章先處理熱路徑上的配置與資料形狀；更大範圍的序列化與 payload 策略，會在下列章節再往外延伸：

和 Go 教材的關係

這一章承接的是 copy boundary、JSON 與 runtime profile；如果你要先回看語言教材，可以讀：

小結

Allocation 優化要先判斷配置是否必要。保護狀態的 copy 是合理成本，高頻熱路徑的重複配置才是優先目標。JSON marshal、slice 成長、map/list 複製與 buffer 建立都是常見來源；用 pprof 區分 inuse_space 與 alloc_space 後，再決定預配置、分頁、projection、payload 重用或 sync.Pool。

2.5 指標與資料複製邊界

Wed, 22 Apr 2026 00:00:00 +0000

Go 的指標讓函式可以操作原本的資料，而不是資料複本。這很有效率，也很危險：當多個地方共享同一份資料時，你需要明確決定誰可以修改，誰只能讀取。

本章目標

學完本章後，你將能夠：

理解值傳遞與指標傳遞的差異
判斷何時使用 pointer
理解 slice、map 本身已經帶有共享底層資料的特性
用 copy 保護資料邊界

【觀察】Go 預設是值傳遞

值傳遞的核心規則是：函式收到的是參數值的複本，修改複本不會改到呼叫端原值。以下範例中，Rename 修改的是複本：

 1type User struct {
 2 Name string
 3}
 4
 5func Rename(u User) {
 6 u.Name = "Bob"
 7}
 8
 9func main() {
10 user := User{Name: "Alice"}
11 Rename(user)
12 fmt.Println(user.Name) // Alice
13}

Rename 修改的是複本，不是 main 裡的 user。

指標傳遞的核心規則是：函式收到原值位址，因此可以修改呼叫端原值。如果想修改原本的值，就要傳指標：

1func Rename(u *User) {
2 u.Name = "Bob"
3}
4
5func main() {
6 user := User{Name: "Alice"}
7 Rename(&user)
8 fmt.Println(user.Name) // Bob
9}

&user 取得位址，*User 表示指向 User 的指標。

【判讀】pointer 表示共享修改權

pointer 的核心語意是共享修改權，不只是效能工具。它表示被呼叫者可能看到或修改原本那份資料。

適合使用 pointer 的情境：

情境	原因
方法需要修改 receiver	例如 `Counter.Inc()`
struct 很大，複製成本高	避免每次呼叫都複製大量資料
需要表示 optional object	`nil` 可表示不存在
多個方法共享同一份狀態	例如 repository、server、cache

不適合濫用 pointer 的情境：

小型不可變資料，例如 time.Time 常直接值傳遞
只是為了「看起來像物件導向」
不希望呼叫者能修改內部資料

【策略】slice 和 map 要特別小心

slice 和 map 的核心風險是：即使參數不是 pointer，也會共享底層資料。

slice 共享底層陣列

slice 參數會複製 slice header，但 header 指向同一個底層 array；因此函式內修改元素，外面會看見。

1func Modify(items []string) {
2 items[0] = "changed"
3}
4
5func main() {
6 names := []string{"Alice", "Bob"}
7 Modify(names)
8 fmt.Println(names[0]) // changed
9}

map 本身就是 reference-like

map 傳入函式後，函式可以修改同一份 map。這是很多共享狀態 bug 的來源。

1func Modify(m map[string]int) {
2 m["count"] = 10
3}
4
5func main() {
6 values := map[string]int{"count": 1}
7 Modify(values)
8 fmt.Println(values["count"]) // 10
9}

【執行】回傳資料時建立 copy 邊界

copy 邊界的核心規則是：不希望外部修改內部狀態時，不要直接回傳內部 map、slice 或 pointer。假設 UserRepository 內部保存一組使用者：

1type User struct {
2 ID string
3 Name string
4}
5
6type UserRepository struct {
7 users map[string]User
8}

直接回傳 map 會把內部狀態暴露給呼叫者：

1func (r *UserRepository) Users() map[string]User {
2 return r.users
3}

呼叫者就可以繞過 UserRepository 修改內部資料：

1users := repo.Users()
2users["1"] = User{ID: "1", Name: "Changed"}

安全做法是回傳複製：

1func (r *UserRepository) Users() map[string]User {
2 result := make(map[string]User, len(r.users))
3 for id, user := range r.users {
4 result[id] = user
5 }
6 return result
7}

回傳 slice 時也要複製 slice：

1func (r *UserRepository) ListUsers() []User {
2 result := make([]User, 0, len(r.users))
3 for _, user := range r.users {
4 result = append(result, user)
5 }
6 return result
7}

這樣呼叫者可以自由排序、append 或修改回傳資料，不會影響 repository 內部狀態。

深層複製與淺層複製

深層複製的核心規則是：struct 裡面若含 slice、map 或 pointer，只複製 struct 本身仍會共享內部資料。以下 Profile 包含 slice：

1type Profile struct {
2 Name string
3 Tags []string
4}

淺層複製：

1copyProfile := profile

copyProfile.Tags 和 profile.Tags 仍然指向同一個底層 array。若要保護邊界，需要複製 slice：

Memcached slab allocator 與記憶體經濟學：明明有記憶體卻在 evict

Tue, 16 Jun 2026 00:00:00 +0000

本文是 Memcached overview 的 implementation-layer deep article。選型層（純 KV vs Redis data types、何時選 Memcached）見 overview；本文只處理「決定用 Memcached 後，slab 記憶體怎麼配才不會莫名淘汰」。命令實機驗證於 memcached:1.6（VERSION 1.6.42）、最後檢查日 2026-06-16；機制以 Memcached 官方 wiki 為準。

明明有記憶體、卻在 evict

Memcached 最違反直覺的故障是這樣：監控顯示 evictions 持續上升、hit rate 在掉，但 stats 算下來實際用掉的記憶體遠低於 -m 設的上限——機器明明還有空間，Memcached 卻在淘汰資料。換成 Redis 思維的人會卡住，因為 Redis 是一個共用的記憶體池，不會出現「有空間卻淘汰」。

這個現象叫 slab calcification，根因在 Memcached 的記憶體模型：它把記憶體預先切成許多固定大小的格子（slab class），每個 class 各自管自己那塊，跟 Redis 共用一個記憶體池的模型相反。記憶體一旦分配給某個 class，預設不會還回去給別的 class 用。如果你的 value 大小分布隨時間改變（早期都是小 value、後來都是大 value），早期被小 value 佔走的記憶體還鎖在小 class 裡，大 value 的 class 沒有足夠空間、開始淘汰——即使整體還有大量「屬於別人」的空閒記憶體。

理解 Memcached 就是理解這套 slab 經濟學。它用「放棄記憶體的靈活性」換到了「永不碎片化、O(1) 分配、可預測的多執行緒擴展」。這個取捨在純 cache 場景非常划算，但它的失敗模式跟 Redis 完全不同，要用 slab 的語言來判讀。

核心概念：slab allocator 的會計模型

Memcached 啟動時不會把 -m 指定的記憶體一次配掉，而是按需求以 page（預設 1MB）為單位分配給 slab class，每個 class 存放某個大小區間的 item。

slab class 與 chunk size。每個 slab class 對應一個固定的 chunk size，item 被放進「裝得下它的最小 class」。class 的 chunk size 按 growth_factor 等比成長——實機看預設值：

1printf 'stats settings\r\nquit\r\n' | nc localhost 11211 | grep growth_factor
2# STAT growth_factor 1.25
3
4printf 'set k1 0 0 5\r\nhello\r\nstats slabs\r\nquit\r\n' | nc localhost 11211 | grep -E "chunk_size|active_slabs"
5# STAT 1:chunk_size 96      ← 最小的 slab class、chunk 96 bytes
6# STAT active_slabs 1

growth_factor 1.25 表示每個 class 的 chunk size 是前一個的 1.25 倍：class 1 是 96 bytes、class 2 約 120、class 3 約 152……一路到 item 大小上限。一個 100 bytes 的 value 放不進 96 bytes 的 class 1，被放進 120 bytes 的 class 2——浪費 20 bytes。這個「向上取整到 chunk size」的浪費是 slab 模型的固有成本。

page 分配是單向的。當某個 class 需要空間，Memcached 給它一個 1MB 的 page，切成該 class 的 chunk。這個 page 預設永久屬於這個 class——這就是 calcification 的來源。-o slab_automove 與手動 slabs reassign 可以把 page 在 class 間搬移，但預設行為偏保守。

LRU 是 per-slab-class 的。淘汰不是全域的，是每個 slab class 維護自己的 LRU。所以「class 2 滿了開始淘汰、但 class 5 有空閒 page」是正常現象——淘汰看的是該 class 自己的空間，不是全域記憶體。

這三點合起來解釋了開頭的悖論：evict 發生在某個 class 內，跟全域剩餘記憶體無關。

配置：slab 與多執行緒的設定路徑

1# 啟動參數（Memcached 的調校多在啟動參數、不像 Redis 有大量 runtime CONFIG SET）
2docker run -d --name memcached -p 11211:11211 memcached:1.6 \
3  memcached \
4    -m 1024 \          # 記憶體上限 1024 MB
5    -t 4 \             # worker thread 數（多執行緒、對齊 CPU 核數）
6    -f 1.25 \          # slab growth factor（預設 1.25、調小→class 更密集→浪費更少但 class 更多）
7    -I 2m \            # 單一 item 大小上限（預設 1MB、超過要調大或拆 value）
8    -o slab_automove=1 # 自動把空閒 page 從一個 class 搬到吃緊的 class（緩解 calcification）

調校判讀：

-m 是給 item 資料的上限，Memcached 自身的 hash table、連線 buffer 等 overhead 在 -m 之外，機器要留 headroom
-t 對齊 CPU 核數——Memcached 從早期就是 multi-threaded，這是它跟早期單執行緒 Redis 的核心差異
-f 調小（例如 1.08）讓 slab class 更密集、向上取整浪費更少，代價是 class 數變多、管理開銷略增
-I 是單 item 上限，超過會 store 失敗（見故障演練 Case 3）
slab_automove=1 是緩解 calcification 的關鍵，預設視版本而定，明確開啟較穩

Production 故障演練

Case 1：slab calcification——value 大小漂移造成假性記憶體不足

徵兆：evictions 上升、hit rate 下降，但 stats 顯示 bytes 遠低於 limit_maxbytes。stats slabs 看到某個 class 的 page 用滿在淘汰，另一個 class 有大量空閒 chunk。

根因：value 大小分布隨時間漂移。早期 value 小、記憶體被分配給小 slab class；後來 value 變大、需要大 class，但 page 已被小 class 鎖住不還，大 class 空間不足開始淘汰。整體記憶體沒滿，但「對的 class」沒空間。

修法：

開 -o slab_automove=1，讓 Memcached 自動把空閒 page 從冷 class 搬到吃緊的 class
手動觸發搬移：slabs reassign （緊急救火用）
監控 stats slabs 各 class 的 used_chunks vs total_chunks 與 stats items 的 per-class evicted，找出失衡的 class
從源頭穩定 value 大小分布——序列化格式統一、避免同類資料時大時小

Case 2：chunk 向上取整浪費大量記憶體

徵兆：存的 value 總大小算起來只有 600MB，但 Memcached 報用掉接近 1GB，記憶體效率異常低。

根因：value 大小剛好落在 slab class chunk size 的「上緣之外」，被向上取整到下一個更大的 class，每個 item 浪費接近一個 growth step 的空間。例如大量 130 bytes 的 value 被放進 152 bytes 的 class，每個浪費 22 bytes，量大就顯著。

修法：

-f 調小（1.25 → 1.08）讓 class 粒度更細，向上取整的浪費變小
stats slabs 看主要 class 的 chunk_size 跟你的 value 實際大小差多少，量化浪費
value 設計上靠近 chunk 邊界（例如壓縮或裁剪 metadata 讓 value 剛好塞進較小的 class）
浪費是 slab 模型的固有成本，純 KV 的 trade-off——換到的是永不碎片化與 O(1) 分配

Case 3：value 超過 item 大小上限、store 直接失敗

徵兆：某些大 value 的寫入回 SERVER_ERROR object too large for cache，application 端 cache 寫入靜默失敗、之後一直 miss。

根因：單一 item 超過 -I 設的上限（預設 1MB）。Memcached 設計上不適合存大 object，預設 1MB 是刻意的純 cache 邊界。

修法：

確認 value 大小分布，大 value 是否真該進 Memcached（純 KV cache 不適合大 blob）
必要時調大 -I（例如 -I 2m），但這會改變 slab class 結構、增加大 chunk 的記憶體佔用
大 object 考慮壓縮、或拆成多個小 key、或改放適合的儲存（物件儲存 / Redis 的 hash）
application 端要處理 store 失敗，不要假設 set 一定成功——失敗就走 origin

Case 4：thread 數設太高、lock contention 反而拖慢

徵兆：把 -t 從 4 調到 32 想榨多核效能，throughput 沒升反降，CPU 在 system time 飆高。

根因：Memcached 的多執行緒有 per-item lock（hash bucket lock），thread 數遠超核數時，執行緒互搶 lock 與 CPU、context switch 開銷超過平行收益。

修法：

-t 對齊實體核數，不要超配（多數場景 4-8 已足夠，極高核機器再往上調並壓測）
用實際 workload 壓測對比不同 -t 的 throughput，找拐點
hot key 集中時 lock contention 更明顯（同 bucket），這是資料分布問題不是 thread 數問題
跨機器水平擴展（client-side consistent hashing）比單機堆 thread 更能解規模，見本文整合段

Case 5：連線數打到上限、新連線被拒

徵兆：高並發下新連線報錯或 hang，stats 的 curr_connections 接近 max_connections，listen_disabled_num 在增加。

根因：每個 client 連線佔一個 connection slot，Memcached 預設 -c 1024。大量 client（尤其沒用連線池、每請求建連）會打滿 connection 上限。

修法：

client 端用連線池重用連線，不要每請求建連
調高 -c（例如 -c 4096），但連線本身有記憶體 overhead（在 -m 之外），要算進機器容量
監控 curr_connections 與 listen_disabled_num，後者非零代表曾達上限拒絕連線
連線數爆炸常是 client fan-out 問題，跨多 Memcached node 分散（consistent hashing）能攤平單 node 連線壓力

Capacity / cost 邊界

Memcached 的容量判讀，核心在 slab 效率與多執行緒擴展：

訊號	健康區間	警戒與動作
`evictions` 速率	接近 0（working set 放得下）	持續高但記憶體沒滿 → calcification、開 slab_automove
各 class `used / total chunks`	各 class 均衡	單 class 滿、其他空 → calcification
chunk 向上取整浪費	小（value 貼近 chunk size）	大 → 調小 `-f` 或調整 value 大小
`curr_connections / -c`	< 80%	接近上限 → 用連線池或調高 `-c`
多執行緒 CPU	核數內、system time 低	system time 高 → `-t` 超配、lock contention

撞牆後的路由判斷：

需要 data types / 持久化 / distributed lock：Memcached 是純 KV、刻意不做這些。需要這些走 Redis / Valkey，這是 capability 差異不是調校能補。
單機容量 / throughput 不夠：Memcached 沒有 server-side cluster，靠 client-side consistent hashing（ketama）水平擴展到多 node，見整合。
想要 Memcached 的多執行緒 + Redis 的 data types：DragonflyDB 兼具多核與 Redis 相容，是兩者的中間點。

整合 / 下一步

Memcached 的單機很簡單，它的工程深度在「如何把多個 Memcached node 組成一個 cache 層」——而這發生在 client 端與代理層，不在 server：

client-side consistent hashing（ketama）：Memcached server 之間互不知道彼此，sharding 由 client library 用 consistent hashing 決定 key 去哪個 node，加減 node 時最小化 key 重新分布。這是 Memcached 水平擴展的基礎。
跟 Meta mcrouter：Meta 的 mcrouter 是 Memcached 專屬的 protocol-aware routing proxy，把跨叢集 / 跨區的流量收斂、失效隔離、pool 管理從 client 端移到代理層——這是 Memcached 大規模治理的標準答案。
跟 Netflix EVCache：EVCache 基於 Memcached，Netflix 在上面加跨 AZ replication 與 client-side smart routing，補足 Memcached 沒有的跨區 HA。
跟 Meta TAO：TAO 底層用 Memcached 作為 social graph 的 cache 層，上層加一致性與關聯查詢——展示了純 KV 之上如何疊加語意。
跟 Meta CacheLib + Kangaroo：當 DRAM 的記憶體經濟撞到極限，Meta 用 CacheLib 把 cache 分層到 flash——這是 slab 記憶體經濟學的下一個邊界。

Redis 記憶體與淘汰調校：maxmemory-policy、LFU 與碎片化的實戰判讀

Tue, 16 Jun 2026 00:00:00 +0000

本文是 Redis overview 的 implementation-layer deep article。選型層（Redis vs Valkey vs Memcached）見 overview；本文只處理「已經選了 Redis、記憶體怎麼配才不會在尖峰爆掉」。配置以 Redis 官方 memory optimization 文件為準、最後檢查日 2026-06-16。

你的 Redis 會在凌晨三點 OOM

Redis 的記憶體問題很少在有人盯著儀表板時發生。它發生在流量爬升、某個 key 集合悄悄長大、AOF rewrite 剛好撞上 RDB save 的那個瞬間——通常是凌晨三點，沒人盯著。徵兆是 application 端突然一片 OOM command not allowed when used memory > 'maxmemory'，所有寫入失敗，但讀取還活著，於是監控的「Redis 還在回應」綠燈騙過了 on-call。

這類事故的根因幾乎都不是「Redis 不夠快」，而是三個記憶體旋鈕在設計時被當成預設值放著沒動：maxmemory 設多少、maxmemory-policy 選哪個、以及沒人注意到的記憶體碎片化。這三個旋鈕決定了 Redis 在記憶體壓力下是「優雅地淘汰冷資料繼續服務」還是「拒絕所有寫入直到有人重啟」。本文處理這三者的會計模型、選型判讀，以及它們怎麼被寫成事故。

對延遲就是業務 KPI 的服務，這個旋鈕的代價更直接。Tinder 的配對引擎每次滑動要查多個快取（profile、距離、偏好、推薦池），4700 萬月活下 cache 不是 DB 的補救、是主要服務面，cache miss 是邊緣案例。eviction policy 選錯，淘汰掉的若是熱資料，下一次滑動就打回 origin，sub-millisecond 的延遲預算瞬間破表。

核心概念：Redis 記憶體的會計模型

要調校記憶體，先要分清楚 used_memory 這個數字到底由什麼組成。INFO memory 回報的是幾層疊加的記憶體會計，每一層去處不同：

used_memory 是 Redis allocator（預設 jemalloc）配給資料、結構與 buffer 的總量。used_memory_rss 是作業系統視角看到的 Redis 進程實體記憶體（resident set size），它通常大於 used_memory——兩者的比值就是 mem_fragmentation_ratio。used_memory_dataset 才是純資料的部分，扣掉了 Redis 自身的 overhead。

理解三個跟 OOM 直接相關的記憶體去處：

資料本身的編碼會放大或縮小記憶體。一個小 hash（field 數少於 hash-max-listpack-entries、value 短於 hash-max-listpack-value）用 listpack 緊湊編碼，記憶體可能只有大 hash 用 hashtable 編碼的幾分之一。同樣的邏輯套用在 list、set、sorted set。一個欄位設計的小決定（把 user object 拆成 200 個獨立 key 還是壓成一個 hash）會讓記憶體差好幾倍。

client output buffer 不計入 dataset 但會吃光記憶體。慢速 consumer、MONITOR、大量 pub/sub 訂閱者都會讓 Redis 在 server 端堆積 reply buffer。client-output-buffer-limit 沒設好，一個讀很慢的 replica 或一個掛著的 MONITOR 連線就能把記憶體推到 maxmemory。

fork 期間記憶體會短暫翻倍。RDB save 與 AOF rewrite 都靠 fork() + copy-on-write，父進程在 fork 後若持續寫入，被改動的 page 會被複製，最壞情況記憶體接近翻倍。這是 maxmemory 必須留 headroom 的核心原因，細節見 persistence 與 fork latency deep article。

maxmemory 框住的是 used_memory，不是 used_memory_rss。所以 maxmemory 設成機器 RAM 的 100% 是錯的——碎片化、fork copy-on-write、client buffer 都在 maxmemory 之外，會把 RSS 推爆系統，觸發 Linux OOM killer 直接砍掉 Redis 進程（比 Redis 自己的 noeviction 更糟，因為是無預警 SIGKILL）。

配置：maxmemory 與 policy 的設定路徑

設定分兩步：先框住記憶體上限，再決定撞到上限時的行為。

 1# 1. 設定記憶體上限（留 headroom 給 fork / fragmentation / client buffer）
 2# 機器 RAM 8GB → maxmemory 設 ~5-6GB、留 25-35% headroom
 3redis-cli CONFIG SET maxmemory 6gb
 4
 5# 2. 設定撞到上限時的淘汰行為
 6redis-cli CONFIG SET maxmemory-policy allkeys-lfu
 7
 8# 3. 永久化到 redis.conf（CONFIG SET 重啟後失效）
 9# redis.conf:
10#   maxmemory 6gb
11#   maxmemory-policy allkeys-lfu

八個 maxmemory-policy 選項分三類，選型靠「資料是不是全部都能淘汰」與「淘汰要靠存取頻率還是 TTL」兩個問題：

policy	淘汰範圍	淘汰依據	適用場景
`noeviction`	不淘汰	寫入直接報錯	資料是 source-of-truth、不能丟（少見）
`allkeys-lru`	所有 key	最近最少使用	純 cache、無法預判哪些該留
`allkeys-lfu`	所有 key	最少使用頻率	純 cache、有明顯熱資料（多數 cache 場景）
`allkeys-random`	所有 key	隨機	key 存取均勻、省 LRU/LFU 計算
`volatile-lru`	有 TTL 的 key	最近最少使用	cache 與持久資料混存、只淘汰可過期的
`volatile-lfu`	有 TTL 的 key	最少使用頻率	同上、有熱資料
`volatile-random`	有 TTL 的 key	隨機	同上、省計算
`volatile-ttl`	有 TTL 的 key	最接近過期的先淘汰	想讓近期過期的提早讓位

LRU 跟 LFU 的真實差異

allkeys-lru 跟 allkeys-lfu 看起來像同一件事的兩種寫法，但選錯會在特定 workload 下讓 hit rate 掉一截。LRU 看「最後一次被存取是多久以前」，LFU 看「被存取的頻率」。差別在一次性掃描（scan pollution）：某個批次任務一次讀過大量冷 key，LRU 會把這些剛被碰過的冷 key 排到淘汰隊伍最後面，反而把真正的熱 key 擠出去。LFU 因為看頻率，一次性的存取不會讓冷 key 假裝成熱 key。

Redis 4.0 後的 LFU 用的是 probabilistic counter（Morris counter）加 decay，不是精確計數，靠兩個參數調：

1# lfu-log-factor：counter 增長的對數速度、越大越能區分高頻 key
2redis-cli CONFIG SET lfu-log-factor 10
3# lfu-decay-time：counter 衰減的分鐘數、越小越快遺忘舊熱度
4redis-cli CONFIG SET lfu-decay-time 1

對 Tinder 這類有明顯熱資料（熱門 profile、熱區域推薦池）的服務，allkeys-lfu 比 allkeys-lru 更能保護熱 key 不被批次掃描或冷流量擠出。

approximate eviction 的取樣

Redis 的 LRU/LFU 都是近似演算法，不掃全 keyspace，而是每次取樣 maxmemory-samples 個 key（預設 5）挑最該淘汰的。樣本數越大越接近精確 LRU/LFU，但越吃 CPU。記憶體壓力大、淘汰頻繁時，預設 5 已夠；要更精準可調到 10，代價是淘汰路徑的 CPU 上升。

Production 故障演練

Case 1：noeviction 讓寫入全滅、讀取假裝健康

徵兆：application 寫入路徑大量 OOM command not allowed when used memory > 'maxmemory'，但 GET 仍正常、health check（通常打 PING 或 GET）綠燈，on-call 收到的是 application 層的 500、不是 Redis 告警。

根因：maxmemory-policy 預設是 noeviction。當 Redis 把 cache 當 cache 用，但 policy 留在 noeviction，記憶體一滿，所有會增加記憶體的命令（SET、LPUSH、HSET）直接報錯，唯讀命令照常。health check 若只測讀取，完全偵測不到。

修法：

純 cache 場景把 policy 改成 allkeys-lru 或 allkeys-lfu，讓記憶體壓力自動透過淘汰釋放
health check 加一個寫入探針（SET healthcheck:probe EX 10），讓 OOM 寫入失敗能被偵測
告警掛在 used_memory / maxmemory > 0.85，不要等 OOM 才反應
若資料真的不能淘汰（誤把 Redis 當 source-of-truth），那不該用 cache 配置，見本文 Capacity / cost 邊界段的路由判斷

Case 2：碎片化吃掉 30% 記憶體

徵兆：used_memory 顯示 4GB、但 used_memory_rss 是 5.5GB，mem_fragmentation_ratio 是 1.37，機器 RAM 開始吃緊但資料量沒漲。重啟 Redis 後 RSS 掉回 4GB 出頭。

根因：大量寫入後刪除、或 value 大小頻繁變動（例如 list 一直 push/pop），jemalloc 的記憶體頁出現空洞——配出去的 page 還佔著 RSS，但裡面只有零星資料。mem_fragmentation_ratio 持續 > 1.5 是明確訊號。

修法：

開 active defrag 讓 Redis 在背景整理（4.0+）：

1redis-cli CONFIG SET activedefrag yes
2redis-cli CONFIG SET active-defrag-ignore-bytes 100mb
3redis-cli CONFIG SET active-defrag-threshold-lower 10

fragmentation_ratio < 1.0 是另一種警訊——代表 Redis 在用 swap，比碎片化更危險，要立刻降記憶體壓力
結構選擇上避免大幅波動的 collection；穩態大小的資料碎片化天然較低
計算 maxmemory headroom 時把 1.2-1.4 的 fragmentation 算進去

Case 3：一個 MONITOR 連線把記憶體推爆

徵兆：某次 debug 後記憶體莫名持續上升，used_memory_dataset 沒變但 used_memory 一直漲，CLIENT LIST 看到一個連線的 omem（output buffer memory）有幾百 MB。

根因：有人開了 MONITOR 去看即時命令流、然後忘了關（或 client crash 但連線沒斷）。MONITOR 把每一條命令都推給該連線，高 QPS 下 server 端 output buffer 爆量堆積，計入 used_memory 但不在 dataset。慢速 replica 或大量 pub/sub 訂閱者也會觸發同類問題。

修法：

設定 client output buffer 上限，超過就斷線：

1# normal client / replica / pubsub 分開設
2redis-cli CONFIG SET client-output-buffer-limit "normal 256mb 64mb 60"
3redis-cli CONFIG SET client-output-buffer-limit "pubsub 32mb 8mb 60"

MONITOR 在 production 嚴格禁用或限時，它本身也拖慢整個 server
監控加 CLIENT LIST 的 omem 巡檢，找出異常 buffer 的連線
replica lag 過大時 output buffer 會堆，對應 replication / failover deep article

Case 4：欄位設計讓記憶體多用三倍

徵兆：資料筆數跟預估一致，但 used_memory 是試算的 3 倍。MEMORY USAGE 抽樣發現單筆 object 的記憶體遠超 value 本身的 byte 數。

根因：把一個有 10 個欄位的 user object 拆成 10 個獨立 string key（user:123:name、user:123:age…），每個 key 都帶 Redis 的 key overhead（dict entry、expire dict entry、key 字串本身）。10 個 key 的 overhead 是一個 hash 的好幾倍。反過來，超過 hash-max-listpack-entries 的大 hash 從緊湊的 listpack 退化成 hashtable 編碼，也會放大記憶體。

修法：

同一 entity 的欄位用一個 hash 存，共享 key overhead

保持 hash 在 listpack 閾值內以用緊湊編碼：

1redis-cli CONFIG GET hash-max-listpack-entries  # 預設 128
2redis-cli CONFIG GET hash-max-listpack-value    # 預設 64

用 MEMORY USAGE 跟 redis-cli --bigkeys 抽樣驗證實際記憶體，不靠試算
Shopify 的 serialization 遷移（Marshal → MessagePack）正是用更省的編碼壓 payload，欄位編碼決策對記憶體與頻寬同時有效

Case 5：淘汰把熱 key 一起帶走、hit rate 崩

徵兆：記憶體壓力下開始 eviction（evicted_keys 持續上升），同時 keyspace_hits / (hits + misses) 從 95% 掉到 70%，origin QPS 跟著飆，下游 DB 開始吃緊。

根因：用了 allkeys-random，或 allkeys-lru 撞上批次掃描污染，淘汰演算法把熱 key 跟冷 key 一視同仁，熱 key 被淘汰後下一個請求 miss、回源、再寫回，形成淘汰與回填的拉鋸，hit rate 持續惡化。

修法：

有明顯熱資料就用 allkeys-lfu，讓頻率高的 key 留下
把 maxmemory-samples 調到 10 提高淘汰精準度
根因常是記憶體真的不夠——evicted_keys 持續高代表 working set 超過 maxmemory，該擴容或分片，不是純調 policy 能解
熱 key 本身過熱（單 key QPS 遠超其他）要走 local cache + Redis 兩層，對應 2.6 high concurrency

Capacity / cost 邊界

記憶體配置的容量判讀，核心是「working set 對 maxmemory 的比值」與「淘汰是否健康」：

訊號	健康區間	警戒與動作
`used_memory / maxmemory`	< 80%	> 85% 告警、> 95% 接近 OOM 或大量淘汰
`mem_fragmentation_ratio`	1.0 - 1.5	> 1.5 開 active defrag、< 1.0 在用 swap 要救火
`evicted_keys` 速率	接近 0（working set 放得下）	持續高 → working set 超量、該擴容 / 分片
hit rate	> 90%（多數 cache）	持續下滑 → 淘汰太兇或 TTL 太短
fork 期間 RSS 峰值	< 機器 RAM	接近 RAM → maxmemory headroom 不足、降 maxmemory

撞牆後的路由判斷：

單機記憶體不夠、working set 持續超量：垂直擴容（換更大記憶體機型）是第一步，但有單機上限。超過後走 Redis Cluster 分片，把 keyspace 切到多 node。
想用 Redis API 但要極致單機記憶體效率：DragonflyDB 的 dashtable 在同 dataset 下通常比 Redis 省 20-40% 記憶體（依資料形狀、以官方 benchmark 為準），且單機多核能撐到 Redis 要靠 cluster 才能達到的規模——若 cluster re-sharding 頻繁觸發，評估直接遷 DragonflyDB 是否更省維運。
資料其實不能淘汰（被當 source-of-truth）：那它不是 cache，該走 durable store。AWS 生態下用 MemoryDB（Redis-compatible durable），或把正式狀態放回 database 模組。

整合 / 下一步

記憶體與淘汰是 Redis 運維的第一層旋鈕，但它跟其他子系統耦合：

跟 persistence / fork latency：fork 期間的 copy-on-write 是 maxmemory headroom 的主要消耗者，記憶體調校跟持久化調校必須一起看。
跟 TTL 與 eviction 概念：TTL 設計決定哪些 key 帶過期時間，直接影響 volatile-* policy 的淘汰範圍。
跟 cache stampede：大量 key 同時被淘汰或同時過期會引發回源雪崩，eviction 調校要跟 TTL jitter / singleflight 一起設計。
跟 Tubi 的 cache vs durable 選型：Tubi 把 ML feature store 從 ScyllaDB 遷到 ElastiCache，前提是「feature 可重新計算」——這個判斷決定了 eviction 是可接受的，記憶體調校才有意義。資料若不可重建，問題不在淘汰 policy，在選錯了儲存層。

4.19 Agent memory 分層架構

Tue, 12 May 2026 00:00:00 +0000

LLM 本身無狀態 — 每次 forward pass 從零開始、唯一輸入是 context window。但「agent」概念上有跨 session 狀態：使用者偏好、過去任務、累積知識、操作流程。Agent memory 是 harness 層的設計、把這些狀態持久化、按需 inject 到 working context。本章把 memory 分成五個層次、各層的寫入時機、retrieval 設計、失敗模式拆成可操作的工程實務。

本章目標

讀完本章後、你應該能：

區分 agent memory 的五個層次（working / short-term / long-term episodic / semantic / procedural）。
對自己 agent 場景判斷要哪幾層 memory、不要哪幾層。
設計 long-term memory 的「何時寫」「何時讀」邏輯。
認識 memory 的常見失敗模式（drift / PII / 污染）跟對應緩解。

五個層次的責任劃分

 1[Working memory]：當前 forward pass 的 context window
 2   - 規模：模型 context（4K-1M token）
 3   - 範圍：當下這次推論的全部輸入
 4   - 例：當下 user query + recent tool result + reasoning trace
 5
 6       ↑ 從這層讀 / 寫到這層
 7
 8[Short-term / session memory]：單一 session 的 scratchpad
 9   - 規模：一輪對話到一天
10   - 範圍：跨多個 turn、但 session 結束就丟
11   - 例：本 session 算過的中間結果、tried strategies
12
13       ↑ session 結束時可選擇 persist 到 long-term
14
15[Long-term episodic memory]：跨 session 的「事件」
16   - 規模：永久（直到主動刪除）
17   - 範圍：跨所有 session、按時間順序
18   - 例：「上週解過這個 race condition」「alice 上個月問過 X」
19
20[Long-term semantic memory]：跨 session 的「事實 / 知識」
21   - 規模：永久
22   - 範圍：跨所有 session、按主題索引
23   - 例：「user 偏好 markdown 輸出」「專案用 React 18」「team 不用 Tailwind」
24
25[Long-term procedural memory]：跨 session 的「流程 / 技能」
26   - 規模：永久
27   - 範圍：可重複使用的 known-good 程序
28   - 例：「跑測試前先 npm install」「commit 前要 lint」「deploy 前要 dry-run」

跟人類認知科學的對應：working ≈ 短期工作記憶、episodic ≈ 「我昨天去哪裡了」、semantic ≈ 「巴黎是法國首都」、procedural ≈ 「騎腳踏車的肌肉記憶」。

不是每個 agent 都要五個層次都用

選擇看用例：

用例	Working	Session	Episodic	Semantic	Procedural
Autocomplete（單行補完）	需要	不需要	不需要	不需要	不需要
Single-turn Q&A	需要	不需要	不需要	不需要	不需要
Chat IDE assistant（短對話）	需要	需要	不需要	不需要	不需要
Chat IDE assistant（長期使用）	需要	需要	可選	需要	可選
長期 coding agent（持續同 codebase）	需要	需要	需要	需要	需要
Multi-session research agent	需要	需要	需要	需要	需要

實務啟示：從「最少 memory」開始、有具體 trigger 才加。memory 不是越多越好、每加一層都增加複雜度跟失敗面。

Long-term memory 的寫入時機

何時寫是設計核心、影響 memory 的品質跟成本。三種主流模式：

1. 每 turn 寫（Auto-write）

每個對話 turn 結束都寫一條 memory。實作簡單但 memory 變垃圾場 — 太多瑣碎內容、retrieval 時混淆 signal。

適合：實驗階段、想看 memory 怎麼累積 不適合：production、長期使用

2. 任務結束寫（Task-end write）

每個明確「任務」（如「修完 bug」「寫完 feature」）結束時、寫一條 episodic / semantic memory 摘要。

實作：

1任務開始 → working memory 進入「task mode」
2   ↓ 多 turn 累積 session scratchpad
3任務結束（user 說「好了」/ test 通過 / commit done）
4   ↓ trigger memory write
5LLM call：「請從本 session 提取值得記得的 episodic / semantic / procedural memory」
6   ↓ 結構化輸出
7寫進 long-term store

適合：production agent、明確任務邊界 不適合：開放式對話、無明確任務終點

3. 主動觸發寫（Reflection / consolidation）

定期（每 N turn / 每天）跑「memory consolidation」step、LLM 自己決定該寫什麼。借鑒人類睡眠時 memory consolidation 的研究。

適合：長 running agent、有明確 idle 時間 不適合：低 cost 場景（consolidation 額外 LLM call 是常駐成本）

混用：production 多用「task-end write」為主 + 偶爾 reflection 做 consolidation。

Long-term memory 的 retrieval

何時讀也是設計核心。三種主流模式：

1. Inject-on-startup

把 long-term memory 在 session / agent 啟動時一次塞進 system prompt。

1System prompt:
2  "你是 coding assistant、user alice。
3   semantic memory: {markdown 偏好、React 18、Python 3.11、...}
4   procedural memory: {npm install before test、lint before commit、...}"

適合：memory 量小（< 1K token）、相對穩定 不適合：memory 多、變動快、retrieval 不準

2. Retrieval-on-demand

每次 user query 來、用 embedding similarity 從 vector store retrieve 相關 memory、塞進 context。

1User query → embed → cosine similarity vs memory vectors → top-K → inject

適合：memory 量大、跨主題、需要動態 不適合：高頻 / 低 latency 要求（retrieval overhead）

3. Hybrid（混合）

Procedural / semantic（穩定）→ inject-on-startup；episodic（動態）→ retrieval-on-demand。

1Session 啟動：
2  inject procedural + semantic（小、穩定）
3
4每 user query：
5  retrieve top-K episodic（動態）+ inject

實務 production 多採 hybrid。

跟 RAG 的邊界

Agent memory 跟 RAG 容易混淆、實際上是不同概念：

維度	RAG	Long-term agent memory
主要內容	外部知識庫（docs、wiki、codebase）	Agent 跟特定 user 的互動歷史
Per-user？	通常通用	Per-user / per-session
寫入時機	Build time / ingestion pipeline	Runtime（agent 自己決定何時寫）
變動頻率	較慢（doc 更新）	快（每 session 都可能變）
是否含「事件」	否（純知識）	Episodic memory 是事件

但兩者實作層常共享：vector store / embedding model / retrieval logic 可重用。設計上：

如果讀者問「跟『過去聊過的事』有關」→ memory
如果讀者問「跟『某個固定知識』有關」→ RAG
同一個 query 兩者都要 → hybrid retrieval、結果合併

失敗模式

1. Memory drift（記憶過時）

舊 memory 寫的內容不再正確、但仍被 retrieve、agent 用過時資訊。

例：兩個月前寫 memory「user 偏好 React class component」、user 已換 hooks、agent 仍寫 class component。

緩解：

Memory 加 timestamp、retrieval 時加 time decay weighting
定期 consolidation：LLM 跑一遍判斷哪些 memory 過時
Procedural / semantic memory 跑「validation step」：當前對話是否仍 align、不 align 就 mark stale

2. PII 寫入

User 不知情下、agent 把 PII（email、phone、社群 ID）寫進 long-term memory、跨 session retrieve 出來、可能洩漏。

緩解：

Memory write 前過 PII detection（regex 或專門模型）
Memory store 加 encryption-at-rest
User 可看 / 編輯 / 刪除自己 memory（GDPR / 隱私法規要求）
跟 6.4 跨雲端資料邊界結合判讀

3. Context 污染

不相關 memory 被 retrieve 進 working memory、模型把 irrelevant 內容當 signal、輸出飄。

例：user 問 React 問題、retrieve 出兩個月前的 Vue 經驗、模型混淆。

緩解：

Retrieval 加 similarity threshold（< 0.7 不 inject）
Memory 加 metadata（topic / project / language）、retrieval 加 filter
Inject 後加 explicit framing：「以下是過去相關 memory、僅供參考、若跟當前問題不符請忽略」

4. Memory 跟 hallucination 互相 boost

Hallucination 寫進 memory、變成「事實」、後續 retrieve 強化 hallucination、agent 越來越相信錯誤內容。

緩解：

Memory write 前要求 LLM 標「不確定」flag、retrieval 時 deprioritize
定期 ground truth validation（如連結 memory 到實際檔案、檔案變了 memory 失效）
Critical memory 要 user 確認才寫入

5. 跨 user memory 污染

Production 多 user 場景、memory store 沒做 user isolation、A user 的 memory 流到 B user。

緩解：

Memory store schema 強制 user_id 索引
Retrieval query 必加 user_id filter
跟 6.5 routing-to-production 的多租戶 isolation 結合

主流實作

工具 / framework	特色
Mem0	開源、五層 memory framework、retrieval-on-demand
Letta（前 MemGPT）	LLM-managed memory hierarchy、自動 page in/out
LangGraph memory	LangChain 系、跟 graph workflow 整合
Zep	雲端 memory service、含 PII detection
Self-implemented（DIY）	多數 production 自寫、用 vector store + metadata

判讀：用既有 framework vs 自己寫、取決於 memory 邏輯複雜度。簡單 case（per-user semantic preferences）用 DIY 即可；多層 memory + consolidation + GDPR 合規要 framework / SaaS。

跟 Coding agent 的整合

Coding agent 場景的 memory 案例：

Memory 類型	內容例子
Semantic	「專案用 TypeScript strict mode」「team 不用 anonymous default export」
Procedural	「跑測試 = `npm test`」「commit 前 `npm run lint`」
Episodic	「上週解過 race condition 在 user_session.ts」「alice 的 retry 邏輯偏好」

跟 4.17 coding agent harness 的關係：

Procedural memory 編進 scaffold 的 system prompt 或 skill registry
Semantic memory 可 inject-on-startup 或 retrieval-on-demand
Episodic memory 用 retrieval-on-demand、跟 RAG 共享 infrastructure

何時過時 / 何時不過時

不會過時的部分：

五層 memory 分類（working / session / episodic / semantic / procedural）
「不是每個 agent 都要五層都用」的選擇框架
寫入時機的三種模式（auto / task-end / reflection）
Retrieval 的三種模式（inject / retrieval / hybrid）
五個失敗模式分類

會變的部分：

具體 framework（Mem0 / Letta / LangGraph）的 API
LLM-managed memory 的具體實作（如 MemGPT 風格的 paging）
Memory consolidation 的最佳實踐
整合 LLM 跟 vector store / DB 的最佳方式

下一章：4.20 LLM tracing 與 observability、看 production debug 跟 cost 監控的工具層。

MySQL Cross-buffer Memory Contention

Fri, 22 May 2026 00:00:00 +0000

MySQL cross-buffer memory contention 的核心責任是把 MySQL memory tuning 從單一 buffer pool 參數擴展到整體記憶體競爭。InnoDB buffer pool、redo log buffer、sort buffer、join buffer、tmp table、thread stack、connection memory、OS page cache 與 container limit 會共同決定 latency 與 OOM 風險。

本文的判讀錨點是：MySQL memory 問題常來自「每連線 / 每操作」記憶體乘上 concurrency，而非只來自全域 buffer pool。調大單一 buffer 前，要先看 workload 與同時執行的 query。

Memory Surfaces

Memory surfaces 的核心責任是列出會互相競爭的記憶體來源。

Surface	類型	風險
InnoDB buffer pool	global	太小造成 read I/O，太大壓縮 OS 空間
Redo log buffer	global	大交易 / burst write 需要審查
Sort buffer	per session / operation	concurrent sort 放大 memory
Join buffer	per session / join	missing index 時放大
Temp table	memory / disk	group / sort / derived table
Connection overhead	per connection	connection storm / thread memory
OS page cache	system	file、backup、binlog、tmp

Per-session buffer 是最容易誤調的項目。把 sort / join buffer 全域調大，會在高 concurrency 下造成 memory spike。

Contention Signals

Contention signals 的核心責任是把 memory pressure 從 symptom 轉成可排查訊號。

Signal	意義
OOM / container restart	total memory 超出限制
swap activity	memory pressure 已影響 latency
Created_tmp_disk_tables 增加	memory temp table 不足或 query 太大
Sort_merge_passes 增加	sort memory / query shape 問題
Buffer pool hit rate 下降	working set / query pattern 問題
Threads_connected 高	per-connection memory 放大

Signal 要和 query workload 對照。Temp table 與 sort 問題通常需要 query rewrite、index 或報表隔離，而非只調 memory。

Tuning Order

Tuning order 的核心責任是建立安全調整順序。

先確認 host / container memory limit。
設定 InnoDB buffer pool baseline。
控制 max connections 與 application pool。
用 top query 找 sort / join / temp table 來源。
對特定 session / workload 調 buffer，而非全域放大。
將 analytics / reporting 移到 replica 或 OLAP。

這個順序讓全域 memory 先穩定，再處理 query 層問題。若反過來先調大 per-session buffer，壓力會在尖峰流量時爆發。

Query Patterns

Query patterns 的核心責任是找出 memory heavy 查詢。

Pattern	Memory 風險	修正方向
Large sort	sort buffer / temp table	index order、limit、pagination
Missing join index	join buffer 放大	補 index、改 join order
Big GROUP BY	tmp table / disk spill	pre-aggregate、OLAP、covering index
Large transaction	undo / lock / memory	batch、縮短 transaction
Many idle sessions	connection memory	pooler、timeout、max connection

Memory tuning 要服務 query design。若 query 本身無界，memory 只會把問題延後到更大資料量。

Runbook

Runbook 的核心責任是把 memory incident 分流。

Step	操作
Confirm pressure	OS memory、swap、OOM、MySQL status
Identify workload	processlist、performance schema、top SQL
Reduce concurrency	限流、停報表、降 background job
Protect OLTP	kill heavy query、切 read replica
Tune safely	session-level buffer、index、query
Retrospective	pool size、query guard、dashboard

OOM 後要保存 evidence：memory limit、MySQL variables、Threads_connected、top queries、tmp table counters、container restart time。

下一步路由

Cross-buffer memory contention 完成後，InnoDB 基礎讀 InnoDB Tuning；query 層讀 Query Optimization；lock 與 transaction 壓力讀 Lock Contention。

Memory on Tarragon

Agent Memory

概念位置

設計責任

MoE CPU 卸載

概念位置

可觀察訊號與例子

設計責任

VRAM

概念位置

設計責任

3.1 GC 與 memory limit

本章目標

【觀察】長時間服務的記憶體問題通常是趨勢問題

【判讀】GC 控制的是 heap 成長

【判讀】memory limit 是 runtime 軟目標

【執行】設定值應來自部署環境

【策略】runtime metrics 用來看調整是否有效

【判讀】memory limit 不能修正仍被引用的資料

【策略】判斷是 GC 壓力還是長期保留

【測試】runtime 設定函式可以獨立測解析

本章不處理

和 Go 教材的關係

小結

3.1 PyObject 與物件模型

先備知識

本章目標

【原理層】一切皆物件

什麼是「一切皆物件」？

PyObject 結構

變長物件：PyVarObject

【設計層】參考計數

工作原理

參考計數的增減時機

參考計數的優缺點

【實作層】觀察物件

使用 id() 觀察記憶體位址

小整數快取

字串駐留（String Interning）

使用 ctypes 觀察記憶體

觀察物件大小

【深入】PyTypeObject

型別物件的結構

在 Python 中觀察型別資訊

為什麼 is 比 == 快？

【實戰】效能影響

避免不必要的物件建立

使用物件池

思考題

實作練習

延伸閱讀

案例：記憶體優化

先備知識

問題背景

現有設計

記憶體問題

進階解決方案

優化目標

實作步驟

步驟 1：使用 __slots__ 減少物件大小

記憶體結構比較

大量物件的記憶體節省

步驟 2：使用 weakref 避免強引用

使用 callback 追蹤物件回收

步驟 3：使用 WeakValueDictionary

步驟 4：測量記憶體使用

比較記憶體差異的完整腳本

完整程式碼

使用範例

設計權衡

__slots__ vs 標準類別

強引用 vs 弱引用快取

何時使用哪種技術？

什麼時候該用這個技術？

適合使用

不建議使用

優化決策流程

練習

基礎練習：比較有無 __slots__ 的記憶體差異

進階練習：實作 weakref 快取

步驟 1：使用 `slots` 減少物件大小

`slots` vs 標準類別

基礎練習：比較有無 `slots` 的記憶體差異

為什麼 `slots` 省記憶體？