實測日期：2026-07-01 環境：macOS Apple Silicon、Ollama 0.7.x、nomic-embed-text（768 維） Corpus：content/ 全量 2,738 個 markdown 檔、24,216 chunks 前置 demo：rag-demo（pickle、463 chunks）

讀法建議

本案例用 Go 重寫了 RAG storage 層，Go 實作細節佔不少篇幅。依你的背景選讀法：

• Python 開發者、想選自己專案的 storage 方案：先跳到「通用可複製流程」（語言無關的五步驟）→「四方案 benchmark」→「二次選型評估」（結論/理由/前提三層框架），這三段跨語言可遷移。Go 實作段（架構、效能優化）可 skim。
• Go 開發者、想做類似工具：從頭讀，每段都跟你相關。
• 只想看選型框架、不管實作：直接跳「二次選型評估」。

從 demo 到 production 的重寫動機

rag-demo 用 Python pickle 跑通了 RAG 概念驗證：71 篇 → 463 chunks → pickle 儲存 → cosine retrieval → Ollama 生成。概念層完全正確（4.1 的 retrieval + augmentation 骨架），但作為這個 blog 的日常工具有三個專案特有的限制：

1. 工具鏈語言不同：blog 的核心工具是 Go（lint / fmt / cards），加 Python dependency 讓其他維護者 clone 後多一步環境設定。Python 專案不會有這個問題 — pickle 綁 Python 對 Python 專案是優點而非缺點。
2. 只索引部分 corpus：rag-demo 只跑 content/llm/（71 篇），blog 全量有 2,738 篇、24 個 section。
3. Demo 定位：ingest.py / query.py 是教學程式碼，不是維護工具（沒有 status、沒有 section filter）。

這是一次完整重寫、不是漸進升級 — rag-demo 的 Python 程式碼不會被修改或遷移，而是用 Go 重新實作相同的 RAG pipeline（chunk → embed → store → search）、保留相同的概念架構。rag-demo 作為教學 demo 繼續存在。

升級目標：一個跟 mdtools 同級的 Go CLI 工具，能對全量 content 做語意搜尋，其他維護者 clone 後 go build 即可用。完整原始碼在 scripts/blogsearch/。

選型過程（對應 4.22 演化階梯 + 工程約束）

第一軸：規模判讀

全量 content 產生 24,216 chunks（原本估計 ~1,500）。按 4.22 判讀樹，24K 落在「10K-100K → HNSW 或 brute-force」區間。預估 vs 實際的 16 倍落差揭露一個教訓：估計 chunk 數不能用篇數乘以常數，要看每篇的實際長度跟 chunking 策略。

第二軸：工程約束（本專案特有）

以下四個 constraint 反映這個 blog 專案的偏好、不是通用判準。換一組 constraint 會篩出完全不同的方案 — Python 專案不會有「Go 單 binary」constraint、已有 Docker 的團隊不會排斥外部 server。讀者套用時應先列出自己專案的 constraint、不是照搬這張表。

剩餘選項：Go + flat file + brute-force。

第三軸：延遲容忍

CLI 工具、每天用幾次、不是 API server。< 500ms 可接受。

結論：選階段二（flat file），brute-force cosine。

實作架構

 1scripts/blogsearch/
 2├── main.go                     # CLI: ingest / query / status
 3├── cmd/
 4│   ├── ingest.go               # walk content/ → chunk → embed → store
 5│   ├── query.go                # load → embed query → cosine top-K → lazy load text
 6│   └── status.go               # index stats
 7└── internal/
 8    ├── chunk/chunk.go           # paragraph-aware markdown chunking
 9    ├── embed/embed.go           # Ollama HTTP API wrapper
10    ├── search/search.go         # brute-force cosine similarity
11    └── store/store.go           # 三檔案 binary store

日常使用

1# 語意搜尋
2./bin/blogsearch query "retry 策略"
3
4# 只搜特定 section
5./bin/blogsearch query -section backend "connection pool 設定"
6
7# 查 index 狀態
8./bin/blogsearch status

Storage 格式（三檔案分離）

1.blogsearch/
2├── vectors.bin    # float32 binary（70.9 MB）— bulk read + unsafe.Slice 零拷貝
3├── meta.json      # compact metadata 不含 text（7.3 MB）
4└── texts.bin      # length-prefixed chunk text（19.2 MB）— top-K 才 lazy load

分離 text 的設計理由：query 時只需要 vectors + metadata 做 cosine search（78 MB），top-K 結果才從 texts.bin 按 offset 讀取 5 筆 text。省掉 19 MB 的 JSON 解析。

效能優化歷程

初版：9.5 秒

初版用逐 4-byte Read 載入 vectors.bin（17.5M 次 f.Read(buf)），加上 27MB 的 index.json（含所有 chunk text）一次 JSON 解析。

優化版：0.34 秒（28x）

三項改動：

瓶頸分析：0.34 秒裡、embedding API call（Ollama）約 77ms、file I/O + JSON parse 約 200ms、cosine 計算約 50ms。cosine 計算只佔 15%。

通用可複製流程（抽掉 Go/blog）

本案例的 Go 實作細節（unsafe.Slice、os.ReadFile）是語言特定的、但背後的流程步驟跨語言通用：

1. Walk corpus：遞迴掃描目標目錄的所有文件（markdown / code / 任意文字）
2. Chunk：段落感知分割、soft token cap、保留語意邊界（原理見 4.1 Chunking）
3. Embed：對每個 chunk 呼叫 embedding API（本地 Ollama 或 cloud API），得到固定維度向量
4. Store：向量 + metadata + text 分離存檔（binary vectors / compact JSON / lazy-load text）
5. Search：embed query → brute-force cosine → top-K → lazy load text for display

Python 實作同流程只是把第 4 步的 binary 檔換成 pickle / FAISS index / SQLite DB、第 5 步的 cosine 換成 numpy / FAISS / sqlite-vec query。Node.js / Rust 同理。

關鍵優化原則也跨語言：「分離向量與文字、query 時只載入向量、top-K 才載入文字」讓 I/O 量從 ~98MB 降到 ~78MB、JSON parse 從 27MB 降到 7MB。這個原則用什麼語言實作都有效。

四方案同 corpus Benchmark

用同一個 corpus（24,216 chunks、768 維、nomic-embed-text）比較四種 storage 方案。Benchmark 腳本在 scripts/blogsearch-bench/bench.py。

前置依賴

Benchmark 腳本讀 Go 工具產生的 index（.blogsearch/ 下的 vectors.bin + meta.json）。完整指令鏈：

1cd scripts/blogsearch && go build -o ../../bin/blogsearch .   # build Go 工具
2ollama serve &                                                  # 啟動 Ollama
3ollama pull nomic-embed-text                                    # pull embedding model
4./bin/blogsearch ingest -content content -out .blogsearch       # 建 index（~4 分鐘）
5uv run --with sqlite-vec --with faiss-cpu --with numpy \
6  scripts/blogsearch-bench/bench.py --index .blogsearch         # 跑 benchmark

若無 Go 環境，可用自己的 Python embedding 腳本產生相同格式的 vectors.bin（little-endian float32、n × dim 連續排列）+ meta.json（{"dim": 768, "count": n, "metas": [...]}），benchmark 腳本只讀這兩個檔案、不依賴 Go binary 本身。Corpus 格式無硬性要求，任何目錄下的 .md 檔案都可索引。

方法論

• Embedding：四方案共用同一組 embedding（從 Go index 載入），排除 embedding model 差異
• Query：同一句 query（“RAG storage 選型”），跑 5 次取 median
• Ingest 時間：只計 storage 操作（不含 embedding），Go 方案含 embedding 不可分離故標 —
• 環境：macOS Apple Silicon、Python 3.12、Go 1.25

結果

三個關鍵發現

延遲瓶頸在 I/O 和實作、不在演算法。Go flat file 的 151ms 裡、cosine 計算約 50ms、file I/O 約 100ms。FAISS flat 用 numpy BLAS 做同樣的 brute-force cosine、純計算 1.8ms — 計算層差約 28 倍（Go pure loop vs BLAS 向量化指令），加上 I/O 後端到端差 84 倍。

HNSW 的 query 加速在此規模 ROI 低。FAISS HNSW query 0.5ms vs flat 1.8ms、每次省 1.3ms。但 HNSW build 要 23.3s。每天查 100 次、要 179 天才回本 build 成本（23.3s ÷ 0.13s/天）。4.22 的判讀結論（「此規模 brute-force 夠用」）被數據驗證。

sqlite-vec 的 19ms 是「DB overhead 換功能」。比 FAISS flat 慢 10 倍、但多了 SQL metadata filter、transaction 保護、disk persistence。對「需要 filter 但不想維運 server」的場景有意義。

讀數據的注意事項

• Go 151ms 含 file I/O（每次 query 重載 78MB）；如果做 daemon mode（常駐、載入一次），query 會降到 ~50ms（純 cosine + overhead）
• FAISS 數字是 in-memory baseline（index 已載入），不含 index 檔案的載入時間
• sqlite-vec 數字含 disk I/O（每次 query 從 SQLite 讀取），是 persistent storage 的真實代價
• 四方案都不含 Ollama embedding call 時間（~77ms），實際端到端延遲要加上

二次選型評估：同結論、理由鏈翻轉

Benchmark 數據出來後，80 倍效能差距讓原始選型（Go + flat file）受到質疑：「是否該換 Python + FAISS 或 sqlite-vec？」重新用 WRAP 框架評估，結論相同（維持 Go），但理由鏈完全不同。

第一次選型的理由（事前）

「Go 工具鏈統一（mdtools 是 Go）+ 單 binary 分發（clone 後 go build 即可）。」

實測推翻的前提

第一次的理由鏈幾乎全數被推翻。如果只看理由，應該換方案。

第二次選型的理由（事後）

重新評估時加入三個第一次沒有的變數：

端到端延遲 vs in-memory benchmark。84 倍是端到端的數字（Go 151ms 含 I/O vs FAISS 1.8ms in-memory）。但 FAISS 從 disk 載入 index 也要 ~100-200ms，端到端差距縮小到 2 倍。sqlite-vec 是唯一不需要全量載入的方案（disk-based HNSW、端到端 19ms），差距從「84 倍」變成「8 倍」。

使用頻率決定 ROI。CLI 工具、每天 ~10 次手動 query。每次省 130ms（151 vs 19），一天省 1.3 秒。重寫投入 2-3 小時，回本時間 ≈ 19 年。注意這個計算對頻率極敏感：每天 100 次（如被整合進 MCP server 當 agent 工具）回本縮短到 1.9 年、每天 1000 次則 69 天。上方 HNSW ROI 也用每天 100 次計算 — 兩處頻率假設不同是因為比較對象不同（HNSW build 成本 vs 語言重寫成本），但讀者套到自己場景時應先確定自己的查詢頻率。

Ingest 瓶頸在 Ollama API、跟語言無關。~4 分鐘的 ingest 裡、embedding API call 佔 95% 以上。換 Python 不會改善 ingest 速度。

維持的理由是「痛點不存在」

維持 Go 的理由是改善的絕對收益太小、投入回不了本 — 151ms 對 CLI 使用模式不構成痛點，與「Go 好」或「工具鏈統一」無關。

這個翻轉的教學意義

正確的結論配錯誤的理由是脆弱的。第一次 WRAP 的結論（選 Go）在當時是對的，但理由鏈（工具鏈統一、< 10ms）被實測推翻後，如果不重新建立正確的理由鏈，下次環境變動（比如 blogsearch 從 CLI 變成 API server）就會用已失效的理由做出錯誤判斷。

判讀工具選型時，要區分三層：

1. 結論：選什麼方案
2. 理由：為什麼選（可能被推翻）
3. 前提：理由依賴的假設（規模、使用模式、效能數字）

前提變了、理由就要重建，即使結論沒變。寫進決策紀錄時，三層都要記 — 只記結論的話，下次重新評估時沒有判讀基礎。

區分「正當理由重建」跟「動機性推理」（先有結論再找理由）的判準：新理由是否在看到數據之前也能成立？本例的「130ms 對 CLI 不痛」在實測前也成立（CLI 使用模式本來就低頻），所以是正當重建。如果新理由只能在看到特定數字之後才講得通（如「151ms 剛好在 200ms 閾值內」——但閾值是事後設的），就是 post-hoc rationalization。

觸發換方案的訊號

Embedding model 選型（對應 4.12 constraint 優先序）

選 nomic-embed-text 的理由鏈：

1. Ollama 原生支援：ollama pull 一行、不需要額外 Python library 或 API key
2. 體積小：274 MB、跟 chat model 共用記憶體不打架
3. 已有驗證基線：rag-demo 用同一個模型跑過 463 chunks、retrieval 命中率確認可用
4. 768 維 sweet spot：24K chunks × 768 dim × 4 bytes = 70.9 MB，brute-force 可行

未來如果 CJK retrieval 品質不夠（目前可用但未做系統性評估），multilingual-e5-large 或 bge-m3 是備選。換模型只需改 embed.go 的 Model 變數 + 重新 blogsearch ingest（4.22 的「四層可替換」設計）。

CJK 混合 Chunking 觀察

Blog 內容是繁體中文 + 英文術語混合。Chunking 策略沿用 rag-demo 的 paragraph-aware split（空白行切段、soft token cap 400）。

Token 估算用 len(s) / 2 的 heuristic（CJK 字元多算一次）。不精確但 chunking 只需要粗略估算。跟 tokenizer 精確計算的差異在 ±20%、對 chunking 品質影響小於 chunk 邊界選擇的影響。

實際觀察：24,216 chunks 的 retrieval 品質在語意搜尋場景（「哪些文章跟 retry 有關」「RAG storage 選型」）表現良好。keyword 精確搜尋場景（「找 RFC 7807」）表現較弱 — 這是 embedding-only retrieval 的已知限制（見 4.1 的語意 vs 字面相似度對比），未來可加 BM25 做 hybrid search。

跟其他章節的對應

本章整理 storage layer 的工程設計空間：什麼規模用什麼儲存、什麼訊號觸發升級、index 怎麼建怎麼更新、schema 怎麼設計、dependency chain 怎麼影響選型。全篇以一個約 2,700 篇 markdown（24K chunks）、Go 工具鏈的個人技術 blog 作為 running example（從 pickle demo 升級到 production 工具的過程）；Go-specific 的約束見「工程約束」段，Python 專案的路徑在各階段標示。

本章目標

本章涵蓋：

1. RAG pipeline 的四個可替換層、判斷當前瓶頸落在哪一層。
2. Corpus 規模跟使用模式對應的 storage backend 選擇。
3. Index 的 build / update / rebuild 生命週期設計。
4. ANN index 策略（HNSW / IVF / brute-force）的適用邊界。
5. Storage 選型的 dependency 約束（語言生態、build chain、環境管理）。

RAG pipeline 的四個可替換層

RAG 不是一個 monolithic 系統。從 query 進來到 augmented prompt 送進 LLM，經過四個獨立可替換的層：

四層各自演化、各自有不同的升級時機。Chunking 跟 embedding model 影響 retrieval 品質（找到的東西對不對）；storage backend 跟 retrieval algorithm 影響 retrieval 效能（找的速度跟規模上限）。

常見的認知混淆是把「RAG」跟「vector database」綁在一起。這個綁定在 production 規模可能合理（10M chunks 不用 vector DB 很難做），但在小規模場景會導致過度工程 — 1500 個 chunks 用 Pinecone 就像用 PostgreSQL 存 10 筆 config。

Storage backend 的演化階梯

Storage backend 的選擇是規模驅動的工程決策。每個階段都能做 RAG，差別在效能、持久性、query 能力。以下規模閾值基於 768 維 embedding、單機常見配置的經驗判斷，切點依向量維度與硬體規格移動；實測數字（如 20 chunks/sec）另行標示：

階段一：In-memory（pickle / Python list）

把所有 chunk embeddings 載入記憶體，brute-force 算 cosine similarity。

1適用規模：< 10K chunks
2延遲：cosine 計算 < 2ms（numpy BLAS、in-memory）；file-based 實作加 I/O 載入時間
3持久性：pickle 檔、每次啟動重載
4優點：零 dependency、程式碼 < 50 行、debug 容易
5限制：記憶體受限、無 metadata filter、無 incremental update

本 blog 的 rag-demo 就在這個階段：71 篇 markdown、463 chunks、pickle 儲存、22 秒索引、query < 10ms。概念驗證完全夠用。

階段二：Flat file（binary embedding store）

把 embeddings 存成 binary 格式（而非 Python pickle），配 JSON metadata index。跟階段一的差異是 language-agnostic persistence — 不綁定 Python 的 pickle 格式、Go / Rust / Node 都能讀。

1適用規模：< 10K chunks
2延遲：cosine 計算 < 2ms；加 file I/O 載入（70MB vectors ≈ 150ms Go / < 50ms mmap）
3持久性：binary file + metadata JSON、可 rebuild
4優點：跨語言、單檔案部署、不需要 DB server
5限制：brute-force O(n)、metadata filter 靠程式碼、schema 演化需 rebuild（換 embedding 模型要重建整個 index）、無 transaction 保護（binary 損毀靠 rebuild 復原）、每次 query 重載 file 是效能瓶頸

Running example 的 blog 選了這個方案。驅動選擇的是工具鏈約束：該 blog 的核心工具是 Go（單 binary 分發的 lint / fmt 工具），用 pickle 就綁定 Python runtime、其他維護者 clone 後多一步環境設定（同規模下效能無差異）。Binary flat file 讓 Go 工具直接讀寫、維持單 binary 分發。Python 專案留在 pickle 完全合理，規模到 10K 再跳階段三 FAISS 更自然。

階段三：Embedded library（FAISS / HNSWLib / Annoy）

引入 ANN（Approximate Nearest Neighbor）index，查詢從 O(n) 變成 O(log n)。

1適用規模：10K - 100K chunks
2延遲：< 5ms（HNSW sublinear）
3持久性：index 檔案、可 rebuild
4優點：不需要 server、嵌入應用 process
5限制：需要安裝 library（FAISS 有平台相依的 wheel）、index build 較慢

升級訊號：brute-force latency 開始感覺到（> 50ms）、或 corpus 大到記憶體載入太慢。1M chunks × 768 dim × 4 bytes = 3GB，載入開始有感。

階段三½：Piggyback 既有 DB（pgvector / Redis vector）

已有 PostgreSQL 或 Redis 的專案有一條跳板路徑：直接在既有 DB 加向量能力、不引入新 server。

1適用規模：10K - 1M chunks（pgvector）、10K - 500K（Redis vector）
2延遲：< 10ms（HNSW、同 DB process）
3持久性：DB 管理、有 transaction / WAL / backup
4優點：不增 server、SQL metadata filter 原生支援、既有維運流程直接沿用
5限制：DB 本身要夠大（向量索引佔額外記憶體）、效能跟 DB 負載共享

升級訊號：已有 Postgres / Redis、需要 metadata filtering、但不想維運獨立 vector DB server。pgvector 讓「有 SQL 能力 + 有向量搜尋」在同一個 DB 完成；Redis vector（RediSearch）適合已有 Redis 且延遲敏感的場景。

這條路徑跟階段四的差異：階段四（Qdrant / Weaviate）是專用 vector DB、向量搜尋效能更高、但多一個 server 維運。Piggyback 路徑犧牲一些向量搜尋效能、換來零新增 server 的維運簡化。選擇取決於「向量搜尋是核心能力（階段四）、還是輔助功能（piggyback）」。

階段四：Self-hosted vector database（Qdrant / Weaviate / Milvus）

獨立 server process，專精向量搜尋，支援 metadata filtering、incremental update、backup、replication。

1適用規模：100K - 10M chunks
2延遲：< 10ms（HNSW + 網路 overhead）
3持久性：server 管理、disk-based
4優點：metadata filter（SQL-like）、REST/gRPC API、可水平擴展
5限制：需要維運 server、佔用資源、增加系統複雜度

升級訊號：需要 metadata filtering（「只搜 report/ 下的卡片」且頻率高）、需要多 process 並發 query、需要 incremental update 而非全量 rebuild。

典型場景是十人以上的團隊共用 RAG 知識庫：多人同時 query、文件隨 sprint 密集更新、需要按 project / team / access level 做 metadata filter。單人或小團隊的 side project 通常停在階段二或三就夠。回退路徑是「關掉 server、退回 embedded library」— 向量跟 metadata 仍在、只是失去 incremental update 跟 REST API。

階段五：Hosted SaaS（Pinecone / Weaviate Cloud / Qdrant Cloud）

由 vendor 管理的 vector database，免維運。

1適用規模：> 10M chunks、或不想維運
2延遲：10-50ms（加上網路 round trip）
3持久性：vendor 管理
4優點：免維運、自動擴展、SLA
5限制：cost、vendor lock-in、資料離開本地

升級訊號：corpus 超過單機記憶體（10M+ chunks 的 HNSW index 含 graph overhead 可達數十 GB）、或團隊沒有 infra 維運能力。

典型場景是跨國 SaaS 產品的 knowledge base：文件數百萬、多語言、需要 geo-distributed 部署。此規模下 self-hosted 的維運成本（on-call、capacity planning、backup）可能高於 SaaS 訂閱。風險是 vendor lock-in — 切換 vendor 要 re-index 全量資料、migration 成本跟 corpus 大小成正比。回退計畫是保留 ingest pipeline 的 vendor-agnostic 部分（chunking + embedding），只替換 storage layer。

階梯的核心判讀

每階段的升級都帶來新的 dependency 跟維護成本。判讀「該不該升級」看三個訊號：

1. 目前這個階段有具體痛點嗎？ 沒有就不升級。
2. 升級解的是效能瓶頸還是功能缺口？ 效能瓶頸先量測再決定；功能缺口（如 metadata filter）看使用頻率。
3. 升級引入的 dependency 成本能接受嗎？ 單人 blog 加一個 server process 的維護成本跟十人團隊不同。

常見路徑速查：Python 小型 side project 留在 pickle（階段一），規模到 10K 再上 FAISS（階段三）；Go 專案跳階段二（flat file）避免 Python dependency；已有 Postgres 的專案直接評估 pgvector（階段三½）；已有 Docker 的團隊直接評估階段四（vector DB container）。

常見誤解：「FAISS 跟 Pinecone 選哪個」— 兩者差在規模量級（FAISS 是嵌入式 library、適合 < 100K；Pinecone 是 hosted SaaS、適合 > 10M 或免維運），不是同層級的互斥選項。

同 corpus 實測比較

以下是同一個 corpus（24,216 chunks、768 維、nomic-embed-text）在四種 storage 方案的實測結果（2026-07 macOS Apple Silicon）：

這張表揭露三個容易被理論估計遮蓋的事實：

延遲的瓶頸在 I/O 和實作、不在演算法。Go flat file 的 151ms 裡，cosine 計算約 50ms、其餘約 100ms 是檔案載入（70MB vectors + 7MB metadata）。FAISS flat 用 numpy BLAS 做同樣的 brute-force cosine，純計算只要 1.8ms — 計算層差約 28 倍（Go pure loop vs BLAS 向量化指令），加上 I/O 差異後端到端差 84 倍。

HNSW 的 query 加速在此規模 ROI 低，但原因要看對。FAISS HNSW query 0.5ms vs flat 1.8ms，每次查詢省 1.3ms；但 HNSW build 要 23.3s。如果每天查 100 次，要 179 天才回本 build 成本。在 10 萬+ chunks 規模這個比例會翻轉。

sqlite-vec 的 19ms 是「DB overhead 換功能」的真實代價。比 FAISS flat 慢 10 倍，但多了 SQL metadata filter、transaction 保護、disk persistence — 不需要另起 server。這個 trade-off 在「需要 filter 但不想維運 server」的場景有意義。

ANN index 策略

Storage backend 到了階段三以上，需要選 ANN（Approximate Nearest Neighbor）index 策略。Vector database 卡列了三種主流演算法，本段補充工程判讀。

Brute-force（exhaustive search）

對 query vector 跟所有 stored vectors 算 cosine similarity，取 top-K。

1時間複雜度：O(n × d)（n = chunk 數、d = 向量維度）
2精確度：100%（exact nearest neighbor）
3記憶體：n × d × 4 bytes（float32）
4適用：< 10K chunks

1500 chunks × 768 dim 的 brute-force，現代 CPU 做一次 cosine similarity sweep 大約 1-5ms。在這個規模，HNSW 的建 index 時間（秒級）反而比它省下的查詢時間（毫秒級）長。

HNSW（Hierarchical Navigable Small World）

建多層隨機圖，查詢時從稀疏高層往密集低層跳，sublinear 找到近似最近鄰。

1時間複雜度：O(log n × d)
2精確度：95-99%（approximate、可調 ef_search 參數換精度）
3記憶體：n × d × 4 bytes + graph overhead（通常 1.2-1.5x）
4Build 時間：O(n × log n)、比 brute-force 慢
5適用：10K - 10M chunks、記憶體充足

HNSW 是目前 vector DB 的主流 index。工程取捨在兩個參數：ef_construction（build 精度、越高越慢但 graph 品質越好）跟 ef_search（query 精度、越高越慢但 recall 越高）。多數 vector DB 的預設值已經針對「recall > 95%」調過。

IVF（Inverted File Index）

先把向量 K-means 分群，query 時只搜最近的幾個群。

1時間複雜度：O(n/k × d)（k = 群數、nprobe = 搜幾個群）
2精確度：依 nprobe、通常 90-98%
3記憶體：可以 disk-based（比 HNSW 省）
4Build 時間：K-means 收斂需要時間
5適用：> 1M chunks、記憶體受限、可接受較低 recall

IVF 在超大規模（10M+）的 disk-based 場景有優勢，實務常配 product quantization（PQ）壓縮向量換記憶體。PQ / scalar quantization 跟 index 演算法（HNSW / IVF）正交 — 是記憶體受限時的壓縮手段，可疊加在任一 index 上。消費級場景通常不需要 quantization。

判讀流程

1Corpus 規模？
2├── < 10K chunks   → Brute-force（此規模無需再評估）
3├── 10K - 100K     → HNSW（如果記憶體夠）或 brute-force（如果 latency 可接受）
4├── 100K - 10M     → HNSW（主流）
5└── > 10M          → IVF 或 HNSW + sharding

規模是第一軸。兩個修正軸在同規模下改變選擇：

• Dependency constraint（見「工程約束」段）：規模小但工具鏈排除某些 storage（如 Go 專案排除 CGo dependency）→ 從可行選項中選。
• Metadata filter 需求：規模小但高頻需要按 section / tag 過濾 → 跳過 embedded library、直接評估 vector DB 或 code filter。

一個常見的過度工程信號：corpus 只有幾千筆但花時間調 HNSW 的 ef_construction。實測數據（24K chunks）：FAISS HNSW query 0.5ms vs flat 1.8ms、每次省 1.3ms，但 HNSW build 要 23.3s。每天查 100 次要 179 天回本 build 成本（23.3s ÷ 0.13s/天）。此規模的 brute-force 絕對延遲已在感知閾值下，HNSW 的優化收益趨近零。

判讀流程之外還有一個容易忽略的變數：實作語言的計算效能差異。同一個 brute-force cosine，numpy BLAS 做 24K × 768 只要 1.8ms，Go pure cosine 做同樣運算約需 50-80ms（不含 I/O）。選 storage 方案時如果估「brute-force < 10ms」、前提是用了向量化計算的 library；pure Go / pure Python loop 會慢一到兩個數量級。

Index 生命週期

Index 的 build / update / rebuild 流程影響日常維護成本。

Full rebuild

每次從 corpus 全量重建 index：walk 所有檔案 → chunk → embed → store。

1適用：corpus 小（< 10K chunks）、更新頻率低（每週幾次）
2優點：邏輯最簡單、index 跟 corpus 保證一致
3成本：依 corpus 規模線性成長（本地 Ollama sequential embedding 約 100 chunks/sec、24K chunks ≈ 4 分鐘）

Running example 的 blog 選 full rebuild：2,738 篇 markdown 產生 24K chunks，全量 ingest 在本地 Ollama 約 4 分鐘。每天變動 0-3 篇，rebuild 頻率跟 git push 對齊就夠。

Incremental update

只處理有變動的檔案：偵測 diff → 刪除舊 chunks → 重新 chunk + embed 變動檔 → 插入新 chunks。

1適用：corpus 大（> 10K chunks）、更新頻繁
2優點：只處理 delta、省 embedding API cost
3複雜度：需要 chunk ID 穩定（file path + chunk offset）、刪除 orphan

Incremental update 的工程難點是 chunk ID 穩定性。如果 chunking 策略對同一個檔案的切法會因為上游內容變動而改變（例如段落感知 chunking，加一段就改變後續所有 chunk 邊界），「只更新變動的 chunk」就需要 diff 整個 chunk 序列，邏輯接近全量重建。

判讀「該不該做 incremental」：

• Embedding 是 cost 瓶頸嗎？本地 Ollama 的 embedding 幾乎免費（約 50ms/chunk、sequential）；cloud API（OpenAI text-embedding-3-small 約 $0.02/1M tokens、Cohere 類似）按 token 計費、corpus 大時差異顯著。
• 全量 rebuild 的時間能接受嗎？1500 chunks 在本地約 60-90 秒可以接受；15 萬 chunks 約 2 小時可能不行。
• 能容忍短暫不一致嗎？Full rebuild 期間 index 可能是舊版；incremental update 隨改隨更新。

Rebuild trigger

不管 full 或 incremental，都要決定「什麼觸發 rebuild」：

Trigger 跟團隊協作模式對齊：單人用手動；多人但 review cycle 長（每天幾次 push）用 Git hook 或 CI/CD；開發中密集寫作想即時看 retrieval 結果用 file watcher。Git hook 跟 CI/CD 的差異在 rebuild 跑在本地（hook）還是 server（CI）— 本地 rebuild 快（< 2 分鐘）就用 hook、慢就推到 CI 避免 push 卡住。

本 blog 目前用手動 trigger — 維護者在寫新文章、需要查相關內容時跑 blogsearch ingest，日常使用頻率不高、不需要即時同步。

Schema 設計

每個 chunk 存的不只向量。至少有三類資料需要管理：

 1chunk = {
 2    vector:   float32[768],       // embedding
 3    text:     string,             // 原始文字（generation 用）
 4    metadata: {                   // filtering + 溯源
 5        source:    string,        // 來源檔案路徑
 6        section:   string,        // 所屬 section（llm/ / backend/ / report/）
 7        title:     string,        // 文章標題
 8        date:      string,        // 文章日期
 9        tags:      []string,      // 文章 tags
10        chunk_idx: int,           // 該檔案內的第幾個 chunk
11    }
12}

Metadata filter 的設計取捨

Metadata filter 是「在向量相似度之外加條件」：例如「只搜 report/ 下的卡片」「只搜 2026 年之後的文章」。

兩種實作路線：

Code filter：先做 brute-force / ANN 取 top-N（N 大於最終需要的 K），再用程式碼 filter metadata，取 top-K。

1優點：不需要 DB、flat file 就能做
2限制：filter 比例高時（如 90% 被 filter 掉）需要取很大的 N
3適用：filter 條件少、filter 比例低（< 50%）

DB filter：在 vector DB 的 query 語法中直接加 metadata condition（如 Qdrant 的 must filter）。

1優點：filter 在 index 層執行、效率高
2限制：需要 vector DB、schema 要先定好
3適用：filter 條件多、filter 比例高、query 頻繁

本 blog 選 code filter：section 只有幾個值（llm / backend / report / work-log），filter 比例低，brute-force top-20 再 filter 到 top-5 就夠。

Hybrid search 的 schema 考量

4.1 RAG 原理介紹了 hybrid search（BM25 關鍵字精確匹配 + embedding 語意相似度的加權合併），在 storage 層的 schema 影響是：需要同時存原始文字（給 BM25）跟向量（給 embedding search）。

• In-memory / flat file：BM25 自己實作（或用 library），原始文字本來就存了。
• Vector DB：多數支援 hybrid search（Qdrant 有 full-text index、Weaviate 有 BM25 + vector 合併查詢）。
• SQLite-vec + FTS5：SQLite 原生支援 full-text search（FTS5），配 sqlite-vec 可以在同一個 DB 做 hybrid search。

判讀「要不要 hybrid」：先只用 embedding search，retrieval 品質不夠再加 BM25。多數場景 embedding-only 已經夠用；keyword 精確匹配需求高的場景（如搜特定 error message、RFC 編號）才需要 BM25 補。

工程約束：dependency chain 與 build system

Storage 選型不只看功能跟效能，還受工程約束影響 — 包括 dependency chain 跟實作語言的計算效能。以下用 Go 專案示範這兩類 constraint 的思考方式；Python / Docker / 前端專案的 constraint 不同、結論見「不同專案的 constraint 不同」段。

Case study：Go 專案為什麼不選 SQLite-vec

SQLite-vec 是 SQLite 的 C extension，提供向量搜尋能力。功能上完全符合需求。但在 Go 生態裡，CGo（Go 呼叫 C 程式碼的橋接機制）引入額外代價：

選 mattn/go-sqlite3 意味著：

• 其他維護者 clone 後需要裝 C compiler（macOS 要 Xcode CLI tools、Linux 要 gcc）
• CI/CD 需要配 CGo 環境
• 單 binary 分發的優勢消失（動態連結 libc）

這些代價在大團隊可能值得，但對一個個人 blog 的工具來說，dependency chain 的複雜度超過功能收益。

判讀 dependency 約束的反射

每個 storage 選項都帶一條 dependency chain。評估時要問：

1. 新維護者 clone 後要裝什麼？ pip install / go build / docker pull / apt install？
2. CI 要加什麼？ C compiler / Python runtime / Docker image？
3. 哪些平台要支援？ macOS / Linux / Windows？交叉編譯需求？
4. runtime dependency 還是 build-time dependency？ Runtime（要 server 跑著）的維護成本遠高於 build-time（build 完就不需要了）。

本 blog 的 constraint 是：Go 單 binary、clone 後 go build 即可、不需要外部 server。這個 constraint 排除了 CGo dependency 跟任何 server-based 方案，把選項收窄到 flat file。代價是 Go pure cosine + file I/O 讓 query 延遲（151ms）比 Python FAISS（1.8ms）慢 80 倍 — 對 CLI 工具可接受，對高頻 API server 則是致命瓶頸。選型時把 dependency chain 跟計算效能一起評估，避免「dependency 輕但效能差」或「效能好但 dependency 重」的單軸判斷。

不同專案的 constraint 不同

這個 constraint 是本 blog 的特定情境。其他專案的 constraint 可能完全不同：

• Python 生態的專案：pip install 是標準流程，但 FAISS 的 CPU/GPU wheel 有平台相依（M1 Mac 需要 faiss-cpu 特定版本、glibc 版本影響 Linux wheel），不是完全零 constraint。
• 已有 Docker 的專案：加一個 Qdrant container 看似 docker-compose.yml 多三行，但要考慮 image 體積（數百 MB）、記憶體分配、冷啟動時間、以及 CI 環境是否支援 Docker-in-Docker。
• 前端專案：WebAssembly 版 HNSW 可行但受 bundle size 跟瀏覽器記憶體上限約束，跟 backend storage 的 constraint 型態完全不同。

Storage 選型沒有「最佳方案」— 只有在特定 constraint 下的最適方案。

何時過時 / 何時不過時

不會過時的部分：

• RAG pipeline 的四層可替換結構。
• Storage 升級的判讀訊號（規模驅動、痛點驅動、不是技術驅動）。
• Index 生命週期的 full rebuild vs incremental update 取捨。
• Dependency chain 作為選型約束的思考框架。
• ANN 策略的複雜度分析（brute-force O(n) vs HNSW O(log n) vs IVF O(n/k)）。

會變的部分：

• 具體 vector DB 的市場格局（Pinecone / Qdrant / Weaviate 的功能差異會持續變動）。
• ANN library 的實作效能（新演算法可能比 HNSW 更好）。
• 語言生態的 binding 成熟度（Go 的 SQLite-vec 純 Go binding 可能出現）。
• 具體規模閾值（隨硬體進步、「brute-force 可行」的上限會提高）。

跟其他章節的關係

下一步

本章整理的是跨場景的 storage 工程原則。Running example 的 blog 基於這些原則選了「Go + flat file + brute-force」方案，完整實作過程（選型→重寫→效能優化→四方案 benchmark→二次選型評估）見 Case Study：Blog 語意搜尋從 pickle 到 production。

想看 retrieval 品質不夠時的增強手段（query rewriting / HyDE / multi-step），回到 4.2 RAG 檢索增強。想看 embedding 模型怎麼選（含工程 constraint 如何先砍選項再比品質）、怎麼判讀 MTEB 分數，回到 4.12 Embedding model 內部。