概念位置

Word2Vec 屬於 LLM 前一代的 static embedding 方法，常見訓練方式是 skip-gram 與 CBOW。它跟現代 embedding model 的差異是：Word2Vec 對同一個詞給固定向量，現代 Transformer 會依上下文產生 contextual representation。

可觀察訊號與例子

經典例子是 king - man + woman ≈ queen 這類向量類比。它展示 embedding space 可以承載語意方向，但也暴露靜態詞向量對多義詞與上下文的限制。

設計責任

讀 embedding 章節看到 Word2Vec 時，把它當成「embedding 概念的歷史基線」。實務 RAG 選型通常看現代 embedding model 與 MTEB，不是直接使用 Word2Vec。

概念位置

Contrastive learning 的核心訓練形態：

 1正向對（positive pair）：
 2  (query, relevant_doc) — 應該在 embedding 空間靠近
 3  例：("Python how to read file", "Python file reading tutorial...")
 4
 5負向對（negative pair）：
 6  (query, irrelevant_doc) — 應該在 embedding 空間遠離
 7  例：("Python how to read file", "CSS flexbox guide...")
 8
 9Loss（簡化的 InfoNCE loss）：
10  pull positive pair 靠近
11  push negative pair 遠離（多個 negative samples 對比）

主流形式：

關鍵特性：

1. 資料量需求大：contrastive learning 需要億級的正向對才能訓出好 embedding；資料來源是 query-doc click log、StackExchange QA pair、CC-paraphrase 等
2. Hard negative mining 是品質關鍵：隨機選 negative 容易（從 batch 取就行）、找「看似相關但實際無關」的 hard negative 更挑戰、是 embedding quality 提升的關鍵
3. 不能直接拿 pretrained LLM 用：LLM 的 hidden state 不是「為 retrieval 優化」的、要再 fine-tune 一輪 contrastive learning 才能當 embedding model

設計責任

讀 embedding model paper / 訓練 code 看到「InfoNCE」「triplet」「hard negatives」「mining strategy」就是這 paradigm。寫 code 場景的判讀：

1. 挑 embedding model 看訓練資料 domain：通用 retrieval（如 bge-large、nomic-embed）vs code-specific（如 jina-embeddings-v2-code、CodeT5+）、訓練資料分佈影響大
2. 不能拿任意 LLM 抽 hidden state 當 embedding：如「Llama 的 last hidden state 當 embedding」這類做法在 retrieval 上通常顯著輸給專門 contrastive-trained embedding model
3. Fine-tune embedding model 通常用 LoRA + contrastive loss：在自己 domain 資料上 fine-tune、提升 in-domain retrieval；標準 pipeline 是 sentence-transformers + LoRA

概念位置

MTEB 的 8 大任務類別：

對寫 code / RAG 場景最相關：Retrieval、Reranking 兩類（粗體）。其他類別反映通用能力、但不直接影響 RAG 應用品質。

主流 embedding model 在 MTEB Retrieval 的代表性能（2026/5 估計、會持續變動）：

事實查核註：MTEB 數字依模型版本、評估配置變動、上述為 2026/5 大致排名、引用前以 MTEB Leaderboard 當前狀態為準。

設計責任

讀 embedding model 比較看到「MTEB score」就是這 benchmark。寫 code / RAG 場景的判讀：

1. 看 Retrieval 子分數、不是 overall：MTEB overall 含 8 類、跟 RAG 場景關係最大的是 Retrieval 子分；通用 retrieval 分數高、reranking 分數高、就值得試
2. 跟自己 domain 對齊：MTEB 多為通用語料、自己 domain（如 code、medical、legal）可能跟 MTEB 落差大；in-domain benchmark 比 MTEB 更重要
3. 大小 / 速度 / 品質 trade-off：bge-large（335M）vs nomic-embed（137M）、後者跑得快、適合本地 RAG；前者品質略高、適合雲端或 latency 不敏感場景
4. MTEB 高分不代表「適合你」：高分模型可能是 instruction-tuned embedding（query 需要加特定前綴）、用法跟簡單模型不同、要看 model card

本章拆開 embedding 的三件事：怎麼從 token ID 變成向量、向量空間怎麼承載語意、embedding 是怎麼學出來的。

本章目標

讀完本章後、你應該能：

1. 解釋 embedding layer 在 LLM 中的位置。
2. 看到「embedding dimension = 4096」時、知道指什麼。
3. 解釋 RAG / semantic search 為什麼用 embedding similarity。
4. 區分 word2vec、句子 embedding、contextual embedding 的差別。

Embedding Layer：從 token ID 到向量

Embedding layer（嵌入層）的核心結構是「一個 lookup table、把 token ID（整數）map 到向量」。形式上是一個 (vocab_size, hidden_dim) 的矩陣 E：

1token_id = 12345
2embedding = E[12345]   ← 取出第 12345 row、得到 hidden_dim 維向量

Gemma 4 31B 的 embedding matrix：

• vocab_size = 256,000
• hidden_dim = 5120
• 總參數 = 256,000 × 5120 ≈ 1.3 billion

光是 embedding layer 就佔 31B 中的 1.3B（約 4%）。70B 模型的 embedding layer 更大、可達 2B 以上。

實作上 embedding lookup 比矩陣乘法便宜（只是查表）、但記憶體佔用顯著。

向量空間：用 hidden_dim 維空間編碼語意

Embedding 的設計目標是「讓相似 token 在向量空間中靠近、不相似的遠」。具體用內積 或 cosine similarity 衡量相似度：

1cosine_sim(a, b) = (a · b) / (||a|| × ||b||)

訓練後的 embedding 會展現語意結構：

• embedding(cat) 跟 embedding(kitten) 內積大。
• embedding(cat) 跟 embedding(algorithm) 內積小。
• 著名的「king - man + woman ≈ queen」現象（word2vec 時代發現、Transformer 上也成立）。

這個性質讓 embedding 能做：

• Semantic search：把 query 跟 documents 都轉成 embedding、用 cosine similarity 找相似的。
• RAG：把 codebase chunks embed、用 query embedding 找相關片段。
• Clustering：embedding 上跑 k-means、把語意相近的 document 分組。
• Anomaly detection：embedding 離 cluster 中心遠的就是異常。

Embedding 怎麼學出來

Embedding layer 跟其他 layer 一樣、是訓練過程中學出來的。具體機制：

1. 訓練初期 embedding 是隨機初始化。
2. Forward pass 用這些 embedding 跑模型、預測下一個 token。
3. 預測錯了、loss 大、backprop 算 gradient、更新 embedding。
4. 反覆 trillion token 訓練、embedding 收斂到能表達語意。

訓練機制讓「常在類似 context 出現的 token」拿到相似的 embedding。例如 cat 跟 kitten 在訓練資料中常出現在類似句子（「The ___ is sleeping」「I have a pet ___」等）、模型最佳化的方向會自然讓兩者的 embedding 接近。

這就是「distributional semantics」（分佈式語意）的核心假設：字詞的意義由它周圍的字詞決定（“You shall know a word by the company it keeps”, J. R. Firth, 1957）。

Word2Vec：embedding 的早期實作

Word2Vec（Mikolov et al., 2013）是 embedding 的經典實作、影響後續所有 NLP。它的核心是「用淺層網路專門學 embedding」、不做下游任務：

• Skip-gram：給一個中心字、預測周圍字。
• CBOW：給周圍字、預測中心字。

訓練後 embedding 展現語意結構（包括「king - man + woman ≈ queen」這個著名實驗、近年研究指出該類比有 cherry-picking 質疑、Linzen 2016 / Nissim et al. 2020、是入門啟發、非嚴格 evidence）。Word2Vec 在大型語意理解場景已被 contextual embedding 取代、但在「靜態查表、邊緣計算、輕量 baseline」等情境仍有用、不是完全淘汰。

Word-level vs Contextual Embedding

Word-level embedding（Word2Vec、GloVe 等）每個字一個固定向量、不考慮 context：

• bank 在「river bank」跟「bank account」中拿到同樣的 embedding。
• 簡單、可預先計算、查表快。
• 限制：無法區分多義詞。

Contextual embedding（BERT、GPT 等 Transformer-based）的向量隨 context 改變：

• bank 在「river bank」跟「bank account」中拿到不同的向量。
• 模型每層輸出都可視為一種 contextual embedding、越深越抽象。
• 缺點：需要跑完整模型、不能預先計算。

LLM 內部用的是 contextual embedding。輸入端的 embedding layer 是 word-level（每個 token ID 對應固定向量）、但經過 attention 後變成 context-dependent。

Sentence / Paragraph Embedding

句子或段落級別的 embedding 是把整段文字壓成一個向量、用於 retrieval 與分類任務。常見實作：

Embedding 模型 跟 chat model 是不同訓練流程：

• Chat model 學「下個 token 機率分佈」。
• Embedding model 學「整段文字壓成一個向量、用 cosine similarity 衡量語意相似度」。

兩者底層架構都是 Transformer、但訓練 objective 不同、得到的向量空間不通用。

向量空間互不相容

不同 embedding 模型的向量空間互不相容：

• nomic-embed-text 輸出 768 維向量。
• OpenAI text-embedding-3-small 輸出 1536 維向量。
• 兩者各自的座標軸有獨立意義、不能拿 nomic 的向量跟 OpenAI 的向量算 cosine。

實務啟示：

1. 換 embedding 模型要重建 vector database。
2. 一個 retrieval 系統用同一個 embedding 模型 throughout、混用會壞。
3. 模型升級時要 backfill 舊資料。

Embedding similarity 的失效情境

Embedding similarity 在多數 retrieval / semantic search 場景能用、但有幾類已知失效模式、影響 RAG / @codebase 的回答品質：

實作層級的修法多半是 hybrid retrieval（embedding + BM25 / TF-IDF 各跑一次、合併分數）或加 reranker 做最終排序、純依賴 cosine similarity 風險高的場景值得納入這層。

位置編碼：把順序資訊加進 embedding

純 embedding layer 沒有「順序資訊」、[cat, dog] 跟 [dog, cat] 的 embedding 序列只是 order 不同的 set。Transformer 用 positional encoding 把位置資訊加進去。

主流位置編碼方法：

RoPE 是 2026 年的主流選擇。詳細展開見 3.3 Transformer 架構。

Tied vs Untied Embedding

「Tied embedding」指「input embedding（token → vector）跟 output projection（hidden → logits）共用同一個矩陣」。實作上 input embedding 矩陣 E 的 shape 是 (vocab_size, hidden_dim)、output projection 矩陣的 shape 是 (hidden_dim, vocab_size)；tied 模式直接用 E^T（轉置）當 output projection、省下一份 (vocab_size, hidden_dim) 大小的權重。GPT-2 系列預設 tied、節省參數。

「Untied embedding」是兩者各自獨立、各自訓練。Llama 系列預設 untied、品質略好（兩個矩陣可以各自最佳化）、但 embedding layer 跟 output layer 都要存。

實務上、大模型（30B+）幾乎都採 untied、用較多參數換較高品質；小模型（1B 以下）為了壓縮參數量仍會 tied。

Embedding 在 LLM forward pass 中的位置

LLM 的 forward pass 概略：

 1tokens (整數序列)
 2  ↓ embedding lookup
 3embeddings (向量序列、shape: [seq_len, hidden_dim])
 4  ↓ + positional encoding
 5positioned embeddings
 6  ↓ Transformer block × N
 7final hidden states
 8  ↓ output projection
 9logits (shape: [seq_len, vocab_size])
10  ↓ softmax
11機率分佈

每個 Transformer block 內部都對向量做變換、向量維度保持 hidden_dim 不變、只有 input embedding 跟 output projection 在 vocab_size 跟 hidden_dim 之間轉換。

下一章

下一章：3.2 attention 機制、Transformer 的招牌技術。

本章把 RAG 拆成不會隨工具世代消失的部分：retrieval 的本質、chunking 的取捨、失敗模式的分類、跟 fine-tuning / long context 三種路線的比較。LangChain、LlamaIndex、Vector database 選型等具體實作不在本章範圍——這些半年一個版本、教程價值低於壽命。本章寫的是「為什麼 retrieval 會這樣設計、什麼時候會失敗、什麼時候改用其他方案」。

本章目標

讀完本章後你能：

1. 解釋為什麼 LLM 需要外掛知識、純靠模型參數記憶解不了什麼問題。
2. 區分「語意相似」與「字面相似」對 retrieval 的影響、看到 retrieval 結果不理想時、判斷是哪一類失配。
3. 看到 chunking 參數時、知道背後的 resolution vs context 取捨。
4. 在「RAG / fine-tuning / long context」三者之間、依任務做合理選擇。

為什麼模型需要外掛知識

LLM 的參數記憶是「壓縮過的訓練資料」：權重把預訓練看過的所有文字壓進一個固定大小的數值結構、推論時用這份壓縮表示生成下一個 token。這個結構有三個天然限制：

1. 訓練 cutoff：模型只認識訓練資料截止前的世界、cutoff 之後發生的事完全看不見。Claude 4 cutoff 是 2026/1、2026/5 的新聞模型不知道。
2. 私有資料缺席：訓練資料是公開來源、私有 codebase、內部文件、個人筆記都不在裡面。再強的模型也不會「知道你 repo 的內部慣例」。
3. 長尾事實壓縮損失：訓練資料中出現很多次的常識（如 Python 語法）模型記得清楚、出現一兩次的長尾事實（如某個 obscure library 的某個 function）會被壓縮損失。

RAG 把這三個限制都繞開：retrieval 階段從動態外部 retrieval source（可即時更新、可放私有資料、可保留長尾完整內容）拉出相關片段、augmentation 階段把這些片段塞進 prompt 當 context。模型不需要「知道」這份知識、只需要「讀懂」當下 prompt 裡的這份知識。

這個結構的根本價值是「把知識從模型權重解耦」。模型負責「語言理解 + 推理」、知識負責「事實儲存 + 動態更新」、兩者各自演化：模型升級不需重建知識庫、知識更新不需重訓模型。具體 retrieval 機制依賴 embedding model 把文字轉成向量、用相似度衡量「相關性」。

Retrieval 的核心問題：語意相似 vs 字面相似

Retrieval 解的是「給一個 query、找出相關的 document」這個問題、但「相關」有兩種定義：

• 字面相似（lexical similarity）：query 跟 document 共用多少 keyword。傳統 search engine 用這套（如 Elasticsearch / OpenSearch 的 BM25 算法、以 keyword 出現頻率加權的傳統檢索演算法、不考慮語意）。
• 語意相似（semantic similarity）：query 跟 document 表達的意思接近、即使共用 keyword 少。Embedding-based retrieval 用這套。

兩種模式的失敗模式恰好互補：

實務上現代 RAG 多半用「hybrid retrieval」：BM25 + embedding 分數加權合併、補單一模式的失敗模式。但理解兩者本質的差異、能解釋為什麼 retrieval 結果有時很準、有時莫名其妙。

語意 retrieval 還帶來一個容易忽略的限制：embedding 模型本身有訓練分佈。它在 Wikipedia / Common Crawl 風格的文字上表現好、在你的內部 codebase 風格上表現未必好。Domain shift 是 retrieval 失敗的常見根本原因、不是「embedding 不夠強」、是「embedding 沒見過這類資料」。

Chunking 的本質取捨

RAG 若把整份文件當 retrieval 單位、document 太長、retrieval 拿到的太粗、實務上要先切成 chunk。Chunk 大小的選擇是 retrieval 設計最關鍵也最容易誤判的決定。

Chunk 太小（如每段 100 token）的失敗模式：

• 每塊資訊不完整、retrieval 拿到的 fragment 無法獨立理解（如「他在第三章提到這個概念」、但「他」「這個概念」需要前文才解得開）。
• 跨 chunk 的語意關聯被切斷、retrieval 拿到一個 chunk 但相關的補充資訊在下個 chunk。
• 同一個概念可能切到多個 chunk、retrieval 拿其中一個是不完整論述。

Chunk 太大（如每段 2000 token）的失敗模式：

• Retrieval 精確度低、一個 chunk 包含多個主題、相似度計算被無關內容稀釋。
• 塞進 prompt 浪費 token、context 利用率差。
• 重要訊號可能埋在 chunk 中間、被前後 noise 蓋過。

「resolution vs context loss」是無法兩全的設計問題：細粒度精確但缺脈絡、粗粒度有脈絡但精度差。不同任務有不同最適點：

• 問答任務（答案是短句）：偏細粒度、500 token 左右常見。
• 摘要任務（答案需要長段脈絡）：偏粗粒度、1500-2000 token 常見。
• Code retrieval：以邏輯單位切（function、class）、不是按 token 數切。
• 規格 / 法律文件：按章節結構切、保留 hierarchy。

Chunking 還有兩個常被忽略的設計維度：

• Overlap：相鄰 chunk 之間留 10-20% overlap、避免「重要訊號剛好被切斷」。
• 語意邊界 vs 字數邊界：純按字數切會穿過句子或段落中間；按段落 / heading / 邏輯單位切保留語意完整、但實作複雜。

寫 code 場景的 retrieval（如 Continue.dev 的 @codebase、即 IDE 內把整個 codebase 當 retrieval 來源的指令）多半按邏輯單位切 code（function、class、import block）、配合 AST 解析、比純文字 chunking 收益高很多。

Retrieval 失敗的根本原因

Retrieval 結果不理想時、根本原因通常落在這幾類：

語意 gap

Query 跟 document 描述的是同一個東西、但用詞、立場、抽象層級都差很多，這是 query-document gap。例：query 是「怎麼讓 API 跑快」、document 是「latency optimization techniques」。Embedding 模型訓練得好的話可以對齊、訓練不好或 domain 不熟就 miss。緩解：query rewriting（讓 LLM 把 query 改成更接近 document 的 phrasing）、HyDE（hypothetical document embeddings、用 LLM 生成「假設的答案」、用這個假答案的 embedding 去 retrieval）。

超出訓練分佈

Embedding 模型對某個 domain 表現崩（如金融術語、醫療 jargon、特殊 codebase 慣例）。判讀訊號：retrieval 結果看起來「隨機」、語意相關性低。緩解：換 domain-specific embedding 模型、或退回 BM25。

Chunk 邊界穿過語意單位

正確答案被切到兩個 chunk、retrieval 拿到的只是其中半邊。判讀訊號：模型回答不完整或「我看到 X 但不知道 Y」、檢查發現 Y 在相鄰 chunk。緩解：加 overlap、改用語意邊界 chunking。

Query 過短缺乏 disambiguation context

Query 太短、模型不知道使用者真正想要什麼（如 query 「python」可以指語言、shell binary、套件、文件章節）。Retrieval 拿到的可能語意完全錯。緩解：在 retrieval 前讓 LLM expand query、加上對話歷史當 context。

Embedding 跟下游 LLM 訓練分佈不一致

Embedding 模型擅長把「相關」拉近、但「相關」的定義可能跟下游 LLM 「能用」的定義不同。例：embedding 把同義詞拉近、但下游 LLM 需要的是「能完整回答 query 的 document」、不是「跟 query 同義」。判讀訊號：retrieval 看起來合理但回答品質差。緩解：retrieval + re-ranker（用較強模型對 retrieval candidates 再排序）。

這五類失敗各有自己的訊號、根本原因不同、緩解策略也不同。Retrieval 出問題時、先用症狀分類、再對應到根因、比「換更大 embedding 模型」這種反射式修法有效得多。

Production retrieval pipeline：hybrid + reranker

實務 production RAG 多不只用單一 embedding-based retrieval、而是「hybrid search + reranker」兩段式：

 1User query
 2   ↓
 3[Stage 1: Hybrid retrieve top-50]
 4   ├── BM25（字面）retrieve top-25      ← 抓精確 keyword、識別碼、罕見 entity
 5   └── Embedding（語意）retrieve top-25  ← 抓同義詞、jargon、語意相似
 6   ↓ Reciprocal Rank Fusion 合併
 7   top-50 candidates
 8   ↓
 9[Stage 2: Reranker rerank to top-5]
10   Cross-encoder 對每對 (query, doc) 算 fine-grained relevance
11   ↓
12   top-5 給 LLM

為什麼兩段式：

何時不需要 reranker：

• 小語料（< 1000 docs）、embedding 已準
• 純 keyword 任務、BM25 已準
• 極低 latency 要求（reranker 加幾百 ms）

主流 reranker：Cohere Rerank 3（SaaS）、Jina Reranker v2（OSS）、BGE Reranker（OSS、中文友善）、Voyage rerank-2。詳細選型見 reranker 卡。

Chunking 策略對比

chunking 卡 講概念、實務有五種主流策略：

判讀流程：

 1內容類型？
 2├── 純文字 / 文章       → Recursive 或 Semantic
 3├── Markdown 文檔       → Markdown header（fallback recursive）
 4├── 程式碼              → Code-aware（tree-sitter）
 5├── 混合（文章 + code） → Markdown header 主、code block 用 tree-sitter
 6└── PDF                 → 先轉 Markdown 再用 Markdown header
 7
 8Chunk 大小？
 9├── 一般 RAG            → 512-1024 token、overlap 50-100 token
10├── 短回答 / 精確匹配  → 256-512 token、更精確
11└── 整段理解 / 長 narrative → 1024-2048 token、配合 long context model

實務常見錯誤：

1. 拿 raw PDF 直接 chunking：PDF 結構亂、應該先轉 markdown
2. 過大 chunk 套小 context embedding：bge-large context limit 512、塞 2048 chunk 直接截斷
3. 不加 overlap：句子被切斷、retrieval 漏前後文
4. 混合語料用同樣 chunking：technical doc + casual blog + code 一視同仁、品質都差

RAG vs Fine-tuning vs Long Context

「讓模型知道新東西」有三條路、解的問題層級不同：

三者不互斥、實際應用常組合使用：fine-tune 模型懂 domain jargon、RAG 拉動態知識、long context 在單一任務塞完整脈絡。

判讀「該用哪一條」的核心問題：

• 知識會不會變？常變 → RAG。穩定 → fine-tune 或 long context。
• 知識量多大？小（< 100K tokens、塞得進 context window）→ long context。大 → RAG。
• 需要 traceable（知道答案來源）？是 → RAG（每個 chunk 有 source）。否 → fine-tune 也可。
• 是行為 / 風格還是事實？行為 → fine-tune（教模型「該怎麼回應」）。事實 → RAG（教模型「該知道什麼」）。

寫 code 場景：codebase 變得快、量大、需要 traceable（要知道參考的是哪個 file）——RAG 是預設選擇。Fine-tune 在「想讓模型懂特定 codebase 風格 / 慣例」時補上、但在 codebase 變動頻繁的多數場景成本壓過收益；少數穩定大型 codebase 且風格規範強的情境（如金融 / 醫療 SDK）才值得評估 fine-tune。

何時不適合 RAG

RAG 適用面有邊界、下列情境改用其他方案更划算：

• 需要 holistic 理解整份文件：如改寫整篇文章的風格、跨段邏輯重組。Retrieval 拿到的是片段、看不到整體。改用 long context 把整份塞進 prompt、或先讓 LLM summarize 再對 summary 操作。
• 知識是高度結構化資料：如使用者資料庫、產品目錄。直接用 SQL query 比 embedding retrieval 精確得多。RAG 變成繞遠路。
• 知識量小、每次都會用到：如系統 prompt 的角色設定、不變的規則。直接寫進 system prompt 比每次 retrieval 簡單。
• Retrieval cost 高於 long context：知識量壓過 context 但壓力不大（如 50K tokens）、retrieval pipeline 維護成本可能高於直接塞長 context。值不值得做 RAG 看 query 頻率：偶爾用就 long context、高頻用才值得建 retrieval。
• Latency 敏感場景：RAG 加一輪 retrieval、TTFT 變長。即時補完場景可能受不了。

判讀「該不該做 RAG」的反射：先問「不做 RAG 會怎樣」、再評估 RAG 的維護成本。RAG 不是免費的——需要 ingestion pipeline、embedding 服務、vector database、retrieval logic、re-ranker、評估系統。判讀 overengineering 的訊號：查詢量 < 100/day、文件 < 1000 份、變動頻率 < 月一次、這類規模通常 long context + 簡單檔案讀取已足夠；超過這個量級才值得建完整 RAG stack。

何時過時 / 何時不過時

不會過時的部分：

• Retrieval + augmentation 的二段式結構：retrieve 找相關內容、augment 塞進 prompt。這個 framing 跟具體實作無關。
• 語意 vs 字面相似的差異跟互補性。
• Chunking 的 resolution vs context loss 取捨。
• 五類 retrieval 失敗模式的分類。
• RAG / fine-tuning / long context 三條路線的判讀框架。

會變的部分：

• 具體 embedding 模型（nomic-embed、bge、mxbai 等會持續更新）。
• Vector database 選型（Pinecone / Weaviate / Chroma / pgvector 等市場格局會變）。Storage layer 的工程判讀（規模驅動升級、dependency 約束、index 生命週期）見 4.22 RAG storage 工程。
• Framework API（LangChain / LlamaIndex 的具體呼叫方式半年一變）。
• 最佳 chunk size 數字（隨 embedding 模型跟 LLM context 能力演化）。
• Hybrid retrieval / re-ranker 的具體實作（會持續優化）。

當這篇文章「過時」的時候、過時的是參考數字跟工具選型；retrieval 本質、失敗模式、跟其他路線的取捨判讀仍會成立。看到新 RAG 工具時、回到本章的 framing：它解的是哪類問題、它的 chunking 策略是什麼、它如何處理五類失敗模式——能很快判斷它解的問題跟你的場景是否對齊。

下一章

本章預設「有 backend」、沒 backend 的場景（個人 blog、docs site 加 RAG）的 deployment 取捨見 4.16 靜態 / serverless RAG deployment。

下一章：4.2 RAG 檢索增強、看 vanilla RAG 不夠用時的下一層工具箱（query rewriting / HyDE / multi-step / context packing）。把 LLM 從讀資料延伸到對外部世界做事見 4.3 Tool use 原理。Retrieval 把外部內容引入 prompt 本身就是攻擊面（同個機制讓 codebase 內容、外部文件、剪貼簿都能間接影響模型輸出）、IDE 場景的 prompt injection 判讀見 6.3 IDE 場景的 prompt injection。

驗證日期：2026-05-12 環境：macOS、Ollama 0.23.2、nomic-embed-text、gemma3:1b Corpus：本 blog 的 content/llm/、71 個 markdown 檔 結果：22 秒索引 463 個 chunk、retrieval 命中率好、generation 受 1B 模型能力限制——剛好示範「retrieval 跟 generation 各自會失敗」的兩段式失敗模式

前置設定

驗證 embedding API 可用

1curl -s http://localhost:11434/api/embeddings \
2  -d '{"model":"nomic-embed-text","prompt":"hello world"}' \
3  | python3 -c "import json,sys; r=json.load(sys.stdin); print('dim:', len(r['embedding']))"

逐項說明：

• curl -s：-s 是 silent 模式、不顯示下載進度條（不然會混進 stdout、後面 python parse 會炸）。
• http://localhost:11434/api/embeddings：用 Ollama 原生 embedding endpoint。也有 /v1/embeddings（OpenAI 相容）、但原生回應結構較簡（直接 {"embedding": [...]}、不是 OpenAI 那種 {"data": [{"embedding": [...]}]} 巢狀）。本 demo 用原生、parse 更直接。
• -d '{"model":"...","prompt":"..."}'：JSON payload。model 是 Ollama tag、prompt 是要 embed 的文字。
• python3 -c "..."：stdin 接 curl 輸出、parse JSON、印 embedding 長度。
• 為什麼測 dim: 768：nomic-embed-text 模型架構決定 embedding 維度是 768。每次 embed 任何文字都會回固定 768 維向量、是 retrieval 的基本資料形狀。看到 dim: 768 表示：API 通了、模型載入了、輸出形狀對。

設計取捨

實作前先對齊 4.1 RAG 原理 提的設計取捨、決定每段怎麼做：

這些選擇都對應到 4.0 章節的「會變的部分」清單——可預期半年後 embedding 模型有新選擇、chunking 有更好策略、re-ranker 變主流。但骨架（retrieval + augmentation 兩段式）不變。

Ingest：把 corpus 變索引

完整檔案：scripts/rag-demo/ingest.py（本 repo 下）。三段 function：切 chunk、embed、走訪 + 持久化。

1. slice_markdown：段落感知的 chunk 切割

 1def slice_markdown(text: str, soft_token_cap: int = 400) -> list[str]:
 2    paragraphs = [p.strip() for p in re.split(r"\n\s*\n", text) if p.strip()]
 3    chunks = []
 4    buf, buf_len = [], 0
 5    for p in paragraphs:
 6        plen = len(p) / 2  # char-count / 2 ≈ token (CJK + English heuristic)
 7        if buf and buf_len + plen > soft_token_cap:
 8            chunks.append("\n\n".join(buf))
 9            buf, buf_len = [], 0
10        buf.append(p)
11        buf_len += plen
12    if buf:
13        chunks.append("\n\n".join(buf))
14    return chunks

每段做什麼：

1. re.split(r"\n\s*\n", text)：用「空白行」當分隔符切段落。\n\s*\n 比 \n\n 寬一點、允許中間有 whitespace（空白、tab）。Markdown 段落的標準分隔是空白行、這個 regex 捕捉所有段落邊界。
2. [p.strip() for ... if p.strip()]：每段去除前後空白、過濾掉純空段落。
3. buf, buf_len = [], 0：累積一個正在構建的 chunk。buf 是段落 list、buf_len 是該 chunk 的 token 累計估算。
4. plen = len(p) / 2：估算這段的 token 數。
5. if buf and buf_len + plen > soft_token_cap：「greedy pack」邏輯——如果加上這段就會超過 cap、把目前 buffer flush 成一個 chunk、再開新 buffer 裝這段。
6. if buf: chunks.append(...)：迴圈結束後、最後一個 buffer 還沒 flush、補上。

為什麼這樣設計：

• 為什麼 paragraph-aware、不是固定 token cap：4.1 RAG 原理 提的 chunking 設計取捨——固定 token cap 容易切過句子或段落中間、語意被截斷。Paragraph-aware 切在自然邊界、保留段落內語意完整。
• 為什麼 soft token cap（軟限制）而不是硬切：硬切會把一個 800-token 段落切成兩半；軟切讓「目前 chunk + 下一段超過 cap」時 flush 目前 chunk、下一段獨立成新 chunk（即使超過 cap 也保留段落完整）。代價：個別 chunk 可能超過 cap、retrieval 拿到的塊較大、但內容完整。
• 為什麼 len(p) / 2 估 token：英文約 4 字元 / token、中文約 1.5 字元 / token、混合平均 / 2 在兩種場景都合理。要精確用 tokenizer（如 tiktoken）、但 demo 不需要——這個 heuristic 在 ±20% 內、夠用來做 chunking 決策。
• 為什麼 \n\n.join(buf)`：flush 成 chunk 時、段落間保留空白行分隔、讀者看到 chunk 仍是合法 markdown 結構、不是平鋪文字。

2. embed：呼叫 Ollama embedding API

1def embed(text: str) -> list[float]:
2    payload = json.dumps({"model": "nomic-embed-text", "prompt": text}).encode()
3    req = urllib.request.Request(
4        "http://localhost:11434/api/embeddings",
5        data=payload,
6        headers={"Content-Type": "application/json"},
7    )
8    with urllib.request.urlopen(req, timeout=60) as resp:
9        return json.loads(resp.read())["embedding"]

每行做什麼：

1. payload = json.dumps(...).encode()：把 dict 轉成 JSON 字串、再 encode 成 bytes。HTTP body 必須是 bytes、不能直接傳 str。
2. urllib.request.Request(...)：建立 HTTP request 物件。沒寫 method 預設是 GET、但有 data 參數會自動變 POST。
3. headers={"Content-Type": "application/json"}：告訴 server payload 是 JSON。少了這個、Ollama 可能 parse 不出 body。
4. urlopen(req, timeout=60)：發送 request、timeout=60 是 socket-level timeout（連線 + 讀取總共最多 60 秒）。
5. json.loads(resp.read())["embedding"]：讀回應 body、parse JSON、取 embedding 欄位（768 維 list of float）。

為什麼這樣設計：

• 為什麼用 stdlib urllib 而不是 requests：完全沒有外部 dependency、urllib 是 Python stdlib 內建。requests 較友善但要 pip install、本 demo 想 minimal。
• 為什麼 timeout=60：embed 一段文字通常 < 200ms、60 秒夠 buffer 意外（首次 model 載入記憶體可能 5-10 秒）。設無限會在 Ollama 掛掉時整個 script hang。
• 為什麼 /api/embeddings、不是 /v1/embeddings：兩者都可。原生 endpoint 回應結構平、parse 直接（r["embedding"]）；OpenAI 相容回應較巢狀（r["data"][0]["embedding"]）。對 demo、寫法簡單較重要。

3. 走訪 + 持久化

 1md_files = sorted(args.content_root.rglob("*.md"))
 2records = []
 3for md in md_files:
 4    text = md.read_text(encoding="utf-8")
 5    text = re.sub(r"^---\n.*?\n---\n", "", text, count=1, flags=re.DOTALL)  # 去掉 frontmatter
 6    chunks = slice_markdown(text)
 7    for j, chunk in enumerate(chunks):
 8        vec = embed(chunk)
 9        records.append({
10            "source": str(md.relative_to(args.content_root.parent)),
11            "chunk_index": j,
12            "text": chunk,
13            "embedding": vec,
14        })
15with open("scripts/rag-demo/index.pkl", "wb") as f:
16    pickle.dump(records, f)

每段做什麼：

1. args.content_root.rglob("*.md")：recursive glob、回 Path iterator、找出 content_root 下所有 .md 檔（含子目錄）。
2. sorted(...)：排序、讓每次 ingest 順序穩定（git diff 比較友善、retrieval 結果可重現）。
3. text.read_text(encoding="utf-8")：讀檔、明確指定 UTF-8（中文 markdown 必要、否則 macOS / Linux 預設可能不一致）。
4. re.sub(r"^---\n.*?\n---\n", "", text, count=1, flags=re.DOTALL)：去掉 Hugo frontmatter。
   • ^---\n：開頭 ---\n。
   • .*?：non-greedy match、配到下一個 --- 就停。
   • \n---\n：closing fence。
   • count=1：只 strip 第一個（檔案中可能有其他 --- 是水平分隔線、不要誤殺）。
   • flags=re.DOTALL：讓 . 也匹配換行符（預設 . 不匹配 \n、規 frontmatter 跨行就吃不到）。
5. records.append({...})：每個 chunk 一個 record、含 source path、chunk index、原文、embedding。
6. md.relative_to(args.content_root.parent)：把絕對 path 變成 llm/00-foundations/xxx.md 形式、retrieval 顯示時短、跨機器可移植。
7. pickle.dump(records, f)：把整個 records list 序列化到 binary 檔。

為什麼這樣設計：

• 為什麼要 strip frontmatter：Frontmatter 是 title、date、tags 等 metadata、不是文章正文。embed 進去會稀釋向量語意（讓「date」「2026-05-11」等 keyword 影響相似度計算）。Strip 後 embedding 只 capture 內容語意。
• 為什麼 records 是 list of dict 而不是 numpy array：兩個原因。(1) 每個 record 含 source / chunk_index / text / embedding 四種異質欄位、numpy 處理不直接。(2) 463 chunks 規模、純 Python list 跑 cosine 也只是毫秒級、不需要 vectorize。十萬 chunk 以上才考慮 numpy array + batched dot product。
• 為什麼 pickle 而不是 JSON：embedding 是 768-float list、JSON 序列化會把每個 float 變成 ASCII 字串（每個 ~20 bytes）、檔案大很多、parse 也慢。Pickle 是 binary format、保留原本資料結構、檔案小、loader 快。代價：pickle 有 Python 版本相依、跨語言不能讀——但本 demo 索引只給自家 query.py / mcp_server.py 用、可接受。
• 為什麼存 text 跟 embedding、不只 embedding：retrieval 要回 chunk 原文給 LLM 看、不能只有 source path（不然每次 query 還要再讀檔）。這裡的 corpus 檔案就是 retrieval source；Pickle 多存原文成本低（~100 byte / chunk）、查詢時方便很多。

跑 ingest

1cd ~/Projects/blog
2python3 scripts/rag-demo/ingest.py

• cd ~/Projects/blog：切到 repo 根、讓相對路徑 content/llm 對得到 corpus、scripts/rag-demo/index.pkl 對得到 output 位置。
• python3 scripts/rag-demo/ingest.py：跑 ingest script、預設讀 content/llm/、寫 scripts/rag-demo/index.pkl。

實測輸出：

1Found 71 markdown files under content/llm
2  [10/71] 86 chunks in 4.5s
3  [20/71] 181 chunks in 8.6s
4  ...
5  [70/71] 461 chunks in 22.2s
6Wrote 463 records to scripts/rag-demo/index.pkl (22.3s)

463 chunks、22 秒、平均 ~21 chunks/sec。瓶頸是 sequential API call、用 async / batch 能快 5-10 倍、但這個量級不值得。

Query：retrieval + augmentation + generation

完整檔案：scripts/rag-demo/query.py。三段。

1. Cosine similarity + top-K retrieval

 1def cosine(a, b):
 2    dot = sum(x * y for x, y in zip(a, b))
 3    na = math.sqrt(sum(x * x for x in a))
 4    nb = math.sqrt(sum(y * y for y in b))
 5    return dot / (na * nb) if na and nb else 0.0
 6
 7def retrieve(records, query_vec, top_k):
 8    scored = [(cosine(query_vec, r["embedding"]), r) for r in records]
 9    scored.sort(key=lambda x: x[0], reverse=True)
10    return scored[:top_k]

每行做什麼：

1. dot = sum(x * y for x, y in zip(a, b))：兩個向量的內積（dot product）。zip(a, b) 把兩個 list 對位配對、generator expression 算每對相乘、sum 加起來。
2. na = math.sqrt(sum(x * x for x in a))：a 的 L2 norm（歐氏範數）—— sqrt(x1² + x2² + ... + xn²)。
3. nb = math.sqrt(sum(y * y for y in b))：b 的 L2 norm。
4. return dot / (na * nb) if na and nb else 0.0：cosine = dot / (||a|| × ||b||)。三元運算子防 zero division——若任一向量是零向量、na 或 nb 為 0、回 0.0 而不是 crash。
5. scored = [(cosine(query_vec, r["embedding"]), r) for r in records]：對每個 record 算相似度、組成 (score, record) tuple 的 list。
6. scored.sort(key=lambda x: x[0], reverse=True)：按 score 從大到小排序。key=lambda x: x[0] 取 tuple 第一個元素（score）當排序 key。
7. return scored[:top_k]：取前 K 個。

為什麼這樣設計：

• 為什麼 cosine 而不是純 dot product：純 dot product 受向量長度影響——長向量自動拿高分、跟「相似度」無關。Cosine 把向量正規化到單位長度、純看方向、是「語意相似」的標準衡量。語意相似 embedding 應該方向相近、長度差異不重要。
• 為什麼用 math.sqrt 而不是 **0.5：兩者數學等價、但 math.sqrt 用 C-level 實作、CPython 中比 Python 級 **0.5 快幾倍。對 463 chunks 影響不大、但 production scale 會放大差異——習慣寫 math.sqrt 的好。
• 為什麼 if na and nb else 0.0：防禦性程式設計。理論上 embedding 不會是零向量（模型架構保證有非零權重）、但邊界情況（空輸入、API 出錯回 placeholder）可能出現、避免 ZeroDivisionError 整個 query 失敗。回 0.0 表示「無法判斷相似度」、retrieval 排序時自然排到最後。
• 為什麼 sort 全部、不用 heap：463 records、Python sort 是 O(n log n)、毫秒級。heapq.nlargest(top_k, ...) 是 O(n log k)、在 k=4、n=463 上實測幾乎沒差。十萬 record 以上才看到顯著差別。
• 為什麼用 list of tuple、不用 numpy：跟 ingest 同樣的理由——小規模不需要 vectorize、純 Python 清楚。

2. 建 augmented prompt

 1context_blocks = []
 2for score, r in retrieved:
 3    context_blocks.append(
 4        f"[來源：{r['source']}#chunk{r['chunk_index']} 相似度：{score:.3f}]\n{r['text']}"
 5    )
 6
 7system = (
 8    "你是一個技術文件問答助手。"
 9    "依下方 context 內容回答問題、不要編造 context 外的事實。"
10    "若 context 不足以回答、明確說『資料不足』。"
11    "回答末尾列出引用的來源 path。"
12)
13user = "## Context\n\n" + "\n\n---\n\n".join(context_blocks) + f"\n\n## Question\n\n{question}"
14
15messages = [
16    {"role": "system", "content": system},
17    {"role": "user", "content": user},
18]

每行做什麼：

1. f"[來源：{...} 相似度：{score:.3f}]\n{r['text']}"：每個 retrieved chunk 加 header 標明出處跟相似度、再接原文。:.3f 是 score 格式化到三位小數。
2. "\n\n---\n\n".join(context_blocks)：用 --- 水平分隔線分隔各 chunk、視覺上清楚。
3. {"role": "system", "content": system}：system message 給 LLM 設定角色 + 約束。
4. {"role": "user", "content": user}：user message 含 context 跟 question、是 LLM 實際讀的內容。

為什麼這樣設計：

• 為什麼 system prompt 約束四件事（角色、忠於 context、資料不足時明說、引用來源）：
  • 角色：「技術文件問答助手」框定模型行為、減少 off-topic 回應。
  • 忠於 context：對抗 RAG 最常見的失敗模式——LLM 看到 context 但用自己訓練的 knowledge 補完、結果跟 corpus 不一致。明確要求 follow context 能降低（雖然不能完全消除、見實測 1）。
  • 資料不足時明說：避免 LLM「硬要回答」造成 hallucination。對 weak model 這條 follow 度差、但對 large model 有效。
  • 引用來源：traceability。讀者能回查 corpus、驗證模型答案。
• 為什麼 ## Context / ## Question 結構：用 markdown heading 結構幫助 LLM 區分「我要讀什麼」「我要回答什麼」。比平鋪文字穩定（即使對小模型）。
• 為什麼把 retrieved chunks 全塞 user message、不分開：MCP / function calling 的更現代做法是把 retrieved 結果做成 tool response、模型主動 call retrieval tool。本 demo 不引入 tool use、直接塞 prompt 較單純——能說明 RAG 核心（augmentation）不必牽扯 tool use。

3. 呼叫 chat completions

1def chat(messages, model):
2    payload = json.dumps({"model": model, "messages": messages, "stream": False}).encode()
3    req = urllib.request.Request(
4        "http://localhost:11434/v1/chat/completions",
5        data=payload,
6        headers={"Content-Type": "application/json"},
7    )
8    with urllib.request.urlopen(req, timeout=180) as resp:
9        return json.loads(resp.read())["choices"][0]["message"]["content"]

每行做什麼：

1. json.dumps({"model": ..., "messages": ..., "stream": False}).encode()：構造 OpenAI 相容 chat completions request body。stream: False 讓 server 等生成完再一次回、不要 SSE 串流。
2. /v1/chat/completions：OpenAI 相容 endpoint、跟雲端 OpenAI 完全同樣 schema。
3. timeout=180：3 分鐘、給長 context + 慢模型空間。
4. ["choices"][0]["message"]["content"]：parse OpenAI 標準 response 結構、取第一個 choice 的 content。

為什麼這樣設計：

• 為什麼 stream: False：demo 要把完整 answer 印出、不需要 incremental display。stream: True 要寫 SSE parser、複雜。Production 互動式 UI 才需要 streaming。
• 為什麼 timeout=180、不是 60：1B 模型 + 4 個 retrieved chunks 的 context、prefill 可能要 5-30 秒、生成 100-500 token 又要 5-20 秒、保守設 3 分鐘。embed function 用 60 是因為 embedding 是純 forward pass、單一 token 量級操作、不需要這麼長。
• 為什麼 /v1/... 而不是 /api/...：chat completions 走 OpenAI 相容 endpoint、生態都用這個格式（Continue.dev、Cursor、各家 SDK）。embedding 用 /api/... 是因為原生 schema 簡單；chat 用 /v1/... 是因為 message-based 結構是 OpenAI 標準、跨工具互通。

實測結果：retrieval 對、generation 弱

測試 1：「什麼是 MTP？為什麼對寫 code 場景特別有效？」

1python3 scripts/rag-demo/query.py --show-retrieved "什麼是 MTP？為什麼對寫 code 場景特別有效？"

--show-retrieved 是個 flag、開啟後在 stderr 印 retrieved chunks 跟 score、答案還是進 stdout。是 debug 跟教學用、不會影響 LLM 看到的 prompt。

Retrieval：

10.870  llm/knowledge-cards/transformer.md#chunk2
20.825  llm/03-theoretical-foundations/sampling-and-decoding.md#chunk8
30.782  llm/knowledge-cards/ttft.md#chunk1
40.771  llm/knowledge-cards/mtp.md#chunk2

四個 chunk 都跟問題相關、相似度合理。MTP 卡確實被命中（雖然不是 top-1、是因為 transformer.md 該段提到 MTP）。

Generation（1B 模型）：

MTP 僅指使用 Ollama 進行 Coding 模型訓練與部署、它是一種系統性的方式… 來源：llm.dev

錯：1B 模型編造了「MTP 僅指使用 Ollama」這個事實（不對、MTP 是 Google 為 Gemma 釋出的、跟 Ollama 沒直接關係）、來源 URL 也是 hallucination。

測試 2：「MCP 跟 function calling 有什麼差別？」

Retrieval：

10.721  llm/04-applications/application-protocols.md#chunk2
20.704  llm/04-applications/application-protocols.md#chunk1
30.702  llm/04-applications/application-protocols.md#chunk0
40.693  llm/knowledge-cards/function-calling.md#chunk1

完美命中——4.3 應用層協議章節三個 chunk + function-calling 卡。

Generation：模型把幾段重複拼接、framing 跟原文有出入、但比測試 1 好（因為 context 涵蓋直接答案）。

觀察跟原理對應

這個 demo 剛好示範 4.1 RAG 原理 提的兩段式失敗模式：

換 31B+ 模型 generation 會改善很多——這也是 4.0 章節提到「retrieval 跟下游 LLM 訓練分佈不一致」會放大失敗的具體例子。寫 RAG 系統時、generation 失敗不一定是「retrieval 沒給對 context」、可能是「模型不夠強」。

何時這份 demo 會過時

• Ollama API 形狀：短期內不會變（生態都依賴）。
• nomic-embed-text / gemma3:1b 具體 tag：預期會被新模型取代、但 retrieval + augmentation 結構不變。
• Chunking heuristic：簡單 char-count / 2 很粗、半年後若有便宜的 token counter 直接接會更準。
• Pickle 儲存：production 場景建議換 vector DB、本 demo 是教學用。

實作換代時、保留 ingest / retrieve / augment / generate 四段、各段內部換工具即可——這四段是 RAG 的骨架、跨工具世代不變。

跑這個 demo 的指令總結

1# 一次性建索引（每次 corpus 變動才需要重建）
2cd ~/Projects/blog
3python3 scripts/rag-demo/ingest.py

• cd：切到 repo 根、relative path 對得到。
• python3 ingest.py：跑索引、預設讀 content/llm/、寫 scripts/rag-demo/index.pkl。每次 corpus 變動才需要重跑、不變的話 index 就一直用。

1# 查詢（任意次）
2python3 scripts/rag-demo/query.py --show-retrieved "你的問題"
3python3 scripts/rag-demo/query.py --top-k 5 --model gemma3:1b "問題"

• --show-retrieved：教學 / debug 用、列 retrieved chunks 跟 score 到 stderr。
• --top-k 5：取 top 5 instead of 預設 4。chunks 越多 context 越長、TTFT 越久、但訊息越完整。
• --model gemma3:1b：指定 chat model。換 gemma3:4b、gemma4:31b-coding-mtp-bf16 等 generation 品質會大幅改善。

完整 source 在 scripts/rag-demo/ 下、200 行 Python、無外部 dependency。

跟其他 hands-on 章節的關係：完整 hands-on 系列見 Hands-on 章節索引、把 retrieval 包成 MCP server 暴露給 LLM application 見 MCP demo、RAG + MCP 同跑的記憶體 / 程序預算見 RAG + MCP resource footprint、術語見 RAG 跟 embedding model。

本章目標

讀完本章後、你應該能：

1. 解釋 embedding model 跟 base LLM 的訓練差異。
2. 看到 MTEB / BEIR 分數時、知道對自己場景的意義。
3. 對自己 domain 選對 embedding model（通用 vs code vs multilingual）。
4. 判斷「需要 fine-tune 自己的 embedding model」的時機跟方法。

Embedding model vs LLM 的訓練差異

兩者底層架構可能類似（都用 Transformer）、但訓練 objective 完全不同：

關鍵理解：不能拿任意 LLM 的最後 hidden state 當 embedding — LLM hidden state 是為「預測下一個 token」優化、不為「相似度比較」優化。要再經過 contrastive learning fine-tune 才能當 embedding model 用。

Embedding model 的典型訓練 pipeline：

 1Stage 1: 從 base model 開始（如 BERT、RoBERTa、Mistral、Llama）
 2   ↓
 3Stage 2: Contrastive pre-training
 4   用大量 weak supervised pair（如 Reddit title-body、StackExchange QA）
 5   InfoNCE loss、batch size 大、hard negative mining
 6   ↓
 7Stage 3: Supervised fine-tune
 8   用標註好的 (query, relevant_doc) pair
 9   來源如 MSMARCO、Natural Questions
10   ↓
11Stage 4（可選）: Task-specific instruction tuning
12   讓模型懂「task description」、可針對不同 retrieval 任務切換
13   代表：bge-large、e5-mistral-7b-instruct

Stage 4 的「instruction-tuned embedding」是 2024 後流行的設計：query 前加「Represent this sentence for retrieving relevant passages:」這類前綴、embedding model 學會依任務調整向量。

選型維度

主流 embedding model 的選型維度：

1. Domain 相符

2. 大小（模型大小 / 向量維度）

3. Context window 上限

不同 embedding model 對單次 embed 的 token 上限不同：

事實查核註：本節所列具體型號（bge-large-en-v1.5、jina-embeddings-v3、nomic-embed-text-v1.5、voyage-3 等）、向量維度、context limit、訓練資料 domain、MTEB / BEIR 排名 — 都是 2026/5 主流版本的估計、各模型升級節奏快、引用前以 MTEB Leaderboard 跟對應 model card 當前狀態為準。

選擇影響 chunking 策略（見 4.1 RAG 的 chunking 段）：短 context embedding 要切細、長 context embedding 可保留更完整段落、但內部 attention 對長段中段仍可能 lost-in-the-middle。

4. Cosine similarity 設計

部分 embedding model 訓練時就 L2-normalized、用 cosine = dot product；部分沒 normalize、要自己處理：

詳細見 vector-norm 跟 dot-product 卡片。

評估：MTEB 跟自己 domain 的對齊

MTEB 是現在挑選 embedding model 最常用的 leaderboard、但要正確讀：

1. 看 Retrieval 子分數、不是 Overall：MTEB 含 8 大類、跟 RAG 最直接相關的是 Retrieval 跟 Reranking
2. 跟自己 domain 對齊：MTEB 通用 corpus、自己 domain 可能跟 MTEB 落差大
3. In-domain benchmark 才是 final test：用自己工作流的真實 query 跟 expected doc、自建小型評估集（如 100-200 對）、看候選 embedding model 的 hit rate / nDCG

In-domain 評估的最小可行流程：

1# 偽代碼
21. 蒐集 50-100 個 query + expected_doc（已知答案的對）
32. 對 candidate embedding models 各跑：
4   - embed 所有 doc（含 expected 跟 distractor、~1000 個 distractor）
5   - embed 每個 query
6   - 算 query-doc similarity、看 expected 是否在 top-5 / top-10
73. 比較 candidate 的 hit_rate@5 / hit_rate@10

跑完這個再決定用哪個 embedding model、比看 MTEB leaderboard 可靠很多。

實務選型的 constraint 優先序

上面四個維度（domain / 大小 / context / cosine 設計）跟 MTEB 評估是「品質軸」— 哪個 embedding model 最能解你的 retrieval 問題。但實際選型時，品質軸之前通常有一組工程 constraint 先砍掉大量選項，剩下的候選才進品質比較。

常見的工程 constraint 依砍選項力度排序：

1. Runtime 可用性：推論伺服器支援哪些模型？Ollama 目前原生支援 nomic-embed-text、mxbai-embed-large、snowflake-arctic-embed 等，但不支援所有 Hugging Face 模型。用 cloud API（OpenAI / Cohere / Voyage）則受 vendor 綁定跟成本約束。這一條通常砍掉最多選項。
2. 體積 / 記憶體預算：個人機器常駐 embedding model 跟 chat model 共用記憶體。137M 的 nomic-embed-text 跟 7B 的 e5-mistral 在記憶體佔用上差一個數量級。
3. 已有驗證基線：團隊或前期 demo 已用某個模型跑過、retrieval 品質已確認可用。換模型要重建 index + 重新驗證，成本不只是 MTEB 分數比較。
4. 向量維度的 storage 成本：維度影響 index 大小（n × d × 4 bytes）跟 brute-force search 延遲。768 維 vs 1024 維在小規模無感，但 100K+ chunks 時差異開始有意義。詳見 4.22 RAG storage 工程。

實務流程是：先用 constraint 1-3 收窄到 2-3 個候選，再跑 in-domain benchmark（上段的 hit rate 流程）做最終決定。直接從 MTEB leaderboard 挑最高分的模型、到實際場景才發現 runtime 不支援或體積太大，是常見的繞路。

何時該 fine-tune 自己的 embedding model

通常不該 fine-tune embedding model — 用現成的 bge-large、jina-v3 已經很好。但下列情境值得評估：

1. Domain 跟通用 corpus 差距大：

   • 醫療 / 法律 / 金融的專業術語、通用 embedding model 對「同義詞」「同概念不同表述」recall 差
   • In-domain term frequency 跟通用 corpus 差距大（如「IRA」在金融 vs 政治語境）

2. In-domain benchmark hit rate 顯著低於通用 benchmark：

   • 用 MTEB 高分模型、in-domain hit rate@5 仍 < 60%
   • 換多個候選 embedding model、所有都類似低分

3. 有足夠 in-domain (query, doc) 對：

   • Fine-tune 需要至少數千對、最好 1-10 萬對
   • 對少於 1000 對的場景、fine-tune 收益通常低於數據增強 / 提升 retrieval pipeline

Fine-tune 流程（詳細）：

Step 1：蒐集 in-domain training data

三種主流形態：

實務多從 positive pair 開始（InfoNCE loss 在 batch 內自動取其他樣本當 negative）、品質提升再進 triplet（hard negative mining）。

Step 2：選 base model

選擇看資料量跟硬體：

選擇原則：base model 在 generic benchmark 越強、fine-tune 後上限越高、但訓練成本越高。

Step 3：Loss 選擇

實務 default：MultipleNegativesRankingLoss + batch size 64-128（越大 negatives 越多、品質越高）。

Step 4：Hard negative mining

純隨機 negative（batch 內其他樣本）容易、但 hard negative（看似相關但實際無關）才能 push 模型品質：

11. 用初版 fine-tuned model 對每個 query 跑 retrieve top-50
22. 對每個 query 的 top-50：
3   - 真正 relevant doc（known positive）→ skip
4   - 其他 → 候選 hard negative
53. 篩 hard negatives（LLM-as-judge 或人工確認真的「看似相關但不對」）
64. 用 (query, positive, hard_negative) 重訓
75. Iterate 2-3 輪

Hard negative 是 embedding fine-tune 品質的關鍵差距 — 沒做的 fine-tune 通常 plateau 早、做了的可超越通用 model。

Step 5：LoRA fine-tune 而非 full fine-tune

跟 LLM fine-tune 一樣、embedding model fine-tune 也用 LoRA：

主流 framework：sentence-transformers + PEFT、Hugging Face Transformers + LoRA library。

Step 6：Evaluate

不只看 training loss、要實測：

11. Build in-domain test set（held-out、跟 training 完全分開）
22. 算 [hit_rate@K](/llm/knowledge-cards/retrieval-recall/)（query 的 expected doc 是否在 top-K retrieval result）
33. 跟「base model 未 fine-tune」對比：
4   - Fine-tune 後 hit_rate@5 提升 ≥ 10 percentage point → 成功
5   - 提升 < 5pp → fine-tune 沒效益、不如優化 retrieval pipeline
64. 確認沒崩通用能力：在 MTEB 跑、看主流 retrieval 任務沒大降

失敗模式

跟 LLM 的整合：retrieval pipeline

完整 RAG pipeline 裡 embedding model 的位置：

 1[Ingestion 階段（離線）]
 2  Documents
 3    ↓ chunking
 4  Chunks
 5    ↓ embedding model
 6  Chunk vectors → 存進 vector DB
 7
 8[Query 階段（線上）]
 9  User query
10    ↓ embedding model
11  Query vector
12    ↓ vector DB ANN search
13  Top-K chunks
14    ↓ (optional) reranking
15  Top-N chunks
16    ↓ augment LLM prompt
17  LLM response

關鍵設計決策：

1. Embedding model 一致性：ingestion 跟 query 必須用同個 model（換 model = 整批 re-embed）；chunk vectors 存進 vector DB 之後的 index 結構、維度成本與生命週期見 4.22 RAG storage 工程
2. Chunking 策略對齊 embedding context：見 4.1 RAG chunking
3. Reranking model 通常用 cross-encoder：embedding model 是 bi-encoder（query 跟 doc 分開 embed）、reranker 是 cross-encoder（query + doc 一起算）、品質更高但慢、適合在 top-50 → top-5 之間做 reranking
4. Hybrid retrieval：BM25（字面）+ embedding（語意）混用、用 RRF（Reciprocal Rank Fusion）合併、是 production 常見配置

本地 vs 雲端 embedding

寫 code 場景的判讀：

• codebase 內部 RAG（NDA / 機密 code）：本地 embedding 必選
• 個人開源專案 RAG：本地 embedding 是合理 default、簡單、free
• 公司內部 RAG（需高品質、量大）：評估 voyage-3 / OpenAI v3 vs 本地 bge-large
• 產品級 production RAG：通常雲端 API + 自己 fine-tune 的 embedding（最佳品質）

何時過時 / 何時不過時

不會過時的部分：

• Contrastive learning 是 embedding model 的核心訓練 paradigm
• MTEB 作為通用 embedding 評估的角色
• 「跟自己 domain 對齊」的 in-domain benchmark 必要性
• Bi-encoder vs cross-encoder 的分工（retrieval vs reranking）
• Hybrid retrieval（BM25 + embedding）的設計

會變的部分：

• 具體 embedding model（bge → bge-v2 → …、jina-v3 → v4 → …）
• MTEB leaderboard 排名（每月變）
• Instruction-tuned embedding 的 prompt format（標準化中）
• Embedding model 的 context window 上限（推升中）
• Long-context embedding 的研究（如 ColBERT-style late interaction）

下一章

沒 backend 的靜態場景（個人 blog / docs site）做 embedding 搜尋的 deployment 選擇見 4.16 靜態 / serverless RAG deployment。

下一章：4.13 Eval 設計座標系、看 eval 三軸八象限 meta 框架（先選軸再選工具）、再進 4.14 Benchmarking 與評估方法論 看具體 benchmark 設計。

本章整理 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 內部。

本文是 PostgreSQL overview 的 implementation-layer deep article。Overview 已說明 PG 在 OLTP 譜系的定位、本文聚焦 pgvector extension — 用 PG 解 vector search workload 的路徑、是 extension-ecosystem 內最受關注的 extension。

pgvector 是 PG 變 Vector DB 的最短路徑

pgvector 加兩件事：

 1CREATE EXTENSION vector;
 2
 3-- 加 vector column（dimension 必須事先決定）
 4CREATE TABLE documents (
 5    id SERIAL PRIMARY KEY,
 6    content TEXT,
 7    embedding vector(1536)  -- OpenAI ada-002 維度
 8);
 9
10-- 三種 distance operator
11SELECT * FROM documents ORDER BY embedding <-> '[0.1, 0.2, ...]' LIMIT 10;  -- L2
12SELECT * FROM documents ORDER BY embedding <#> '[0.1, 0.2, ...]' LIMIT 10;  -- inner product
13SELECT * FROM documents ORDER BY embedding <=> '[0.1, 0.2, ...]' LIMIT 10;  -- cosine

Operator 對應：

對 OpenAI / Cohere / sentence-transformers embedding、通常用 <=>（cosine）— embedding model 訓練時是 cosine objective。

ANN Index 是 Vector Search 的核心

不加 index 的 ORDER BY embedding <=> ? 是 full scan：

• 100K row、1536 dim、每 query ~2-5s（不可用）
• 1M row 直接超時

pgvector 提供兩種 Approximate Nearest Neighbor（ANN）index：

選 IVFFlat 的場景：

• Embedding 量 < 1M
• Build 時間敏感（CI / batch 環境）
• Memory 緊
• 接受重建 cost（每月 / 每季）

選 HNSW 的場景：

• Embedding 量 1M-100M
• Query latency < 50ms 要求
• Memory 充足
• Insert 量穩定（不會爆炸性增長）

IVFFlat：分 Cluster 找鄰居

IVFFlat 機制：

1. Build：跑 k-means 把所有 vector 分 lists 個 cluster
2. Query：先找最近的 probes 個 cluster、再在這些 cluster 內找 nearest neighbor

1-- Build（lists 數量重要）
2CREATE INDEX ON documents USING ivfflat (embedding vector_cosine_ops) WITH (lists = 100);
3
4-- Query 時調 probes 換 recall vs latency
5SET ivfflat.probes = 10;
6SELECT * FROM documents ORDER BY embedding <=> ? LIMIT 10;

Lists 跟 probes sizing 規則（pgvector 官方建議）：

實務：100K row → lists=100 / probes=10、1M row → lists=1000 / probes=32。

IVFFlat 的 recall drift：cluster 是 build 時固定的、新 insert 的 vector 進入「最近 cluster」、但隨資料分布改變、cluster center 可能不再代表性、recall 隨時間下降。

修法：定期 REINDEX INDEX CONCURRENTLY ...（每月 / 每 100K 新 row）。

HNSW：Multi-level Graph 找鄰居

HNSW（Hierarchical Navigable Small World）機制：

1. 多層 graph、上層稀疏、下層密集
2. Query 從上層 entry point 開始、逐層找近鄰、最後在底層精細搜尋
3. Insert 漸進維護 graph、不必重建

1-- Build（兩個關鍵參數）
2CREATE INDEX ON documents USING hnsw (embedding vector_cosine_ops)
3WITH (m = 16, ef_construction = 64);
4
5-- Query 時調 ef_search
6SET hnsw.ef_search = 100;
7SELECT * FROM documents ORDER BY embedding <=> ? LIMIT 10;

參數含義：

Build cost 真實量級（1M vector × 1536 dim）：

Production 多數選中間 m=16, ef_construction=64、recall / cost 平衡。

Hybrid Search：Vector + Filter 一起

Vector search 加 SQL filter 是 pgvector 比專業 vector DB 強的場景：

1-- Vector + metadata filter
2SELECT * FROM documents
3WHERE category = 'tech' AND created_at > '2025-01-01'
4ORDER BY embedding <=> '[0.1, 0.2, ...]'
5LIMIT 10;

但這裡有個 pgvector 的踩雷：filter 跟 ANN index 互動有兩種模式：

1. Pre-filter（planner 選）：先 filter 出符合條件的 row、再對 subset 跑 vector ordering → 不用 ANN index、可能慢
2. Post-filter：用 ANN index 找 top-N、再 filter、可能 N 不夠補

pgvector 0.8+（2024-10 release）加入 iterative index scan：HNSW / IVFFlat 一邊掃 graph 一邊 filter、效能比 pre-filter 好 5-10x。0.7+（2024-07）加 halfvec / binary quantization / parallel HNSW build。

實務：filter selectivity 高（< 10%）時、考慮對 filter column 加 index 走 pre-filter；selectivity 低（> 50%）走 iterative scan。

Quantization 跟 Dimension Reduction

1536 dim float32 vector 一筆 6KB、1M row 6GB、加 HNSW index 後 ~20GB。Memory 緊時的省法：

Half-precision（pgvector 0.7+）

1CREATE TABLE documents (
2    embedding halfvec(1536)
3);

halfvec 是 float16、storage 減半、recall 損失通常 < 1%。

Binary quantization

1-- 把每維壓成 1 bit
2CREATE INDEX ON documents USING hnsw (embedding bit_hamming_ops);

Recall 下降明顯（85-90%）、但 storage 1/32、適合「先粗篩再 rerank」hybrid pipeline。

Dimension reduction

訓練 PCA / Matryoshka model 把 1536 dim 降到 256-512 dim、recall 通常損失 < 3%、storage 1/3-1/6。

5 個 Production 踩雷

Case 1：Dimension 超 2000 限制

情境：要用 OpenAI text-embedding-3-large（3072 dim）、CREATE TABLE ... embedding vector(3072) 報錯。

pgvector vector type 上限 2000 dim（IVFFlat / HNSW index 限制）。

修法：

• 改用 halfvec（pgvector 0.7+ 支援 4000 dim）
• 用 Matryoshka 截斷到 2000 dim 以下
• 換 embedding model（OpenAI text-embedding-3-small 1536 dim / 可截斷到 256-1024）

Case 2：HNSW build 太慢

情境：1M row build HNSW、跑 8 小時、blocking production。

修法：

1-- 用 CONCURRENTLY 不 block
2CREATE INDEX CONCURRENTLY ON documents USING hnsw (...);
3
4-- 開 maintenance_work_mem
5SET maintenance_work_mem = '8GB';
6
7-- 開 parallel
8SET max_parallel_maintenance_workers = 7;

仍慢的話、考慮：

• 切分 batch insert + index（適合 read-heavy）
• 用 IVFFlat 短期上線、之後再切 HNSW
• 改用 cloud managed pgvector（提供更大 instance）

Case 3：IVFFlat 不重建 recall 漂移

情境：IVFFlat build 時資料 100K、現在 500K、新資料 recall 從 92% 降到 75%、user 抱怨「找不到相關文件」。

修法：

• Monitor recall：定期跑 ground-truth eval（brute-force 對比）
• 設定 reindex policy：每 100K 新 row 或每月 reindex
• 換 HNSW：insert 漸進維護、不需 reindex（trade-off：build 更慢）

Case 4：Hybrid search filter selectivity 沒設計

情境：query WHERE user_id = ? ORDER BY embedding <=> ?、user_id 高選擇性（1/1M）、planner 選 vector index scan、掃到 top-K 全不符 user_id、補抓無止盡。

修法：

• EXPLAIN 看 planner 選 pre-filter 還是 vector-first
• 對 user_id 加 B-tree index、強 planner pre-filter（hint 不容易、用 statistics）
• pgvector 0.8+ 用 iterative scan、自動處理
• 設計 schema：高選擇性 filter（user_id）建議走 pre-filter；低選擇性（category）走 iterative

Case 5：Memory budget 沒抓

情境：1M vector × 1536 dim × HNSW（m=16）= ~12GB index、shared_buffers 8GB、index 不在 cache、每 query disk IO、latency 100ms+。

修法：

• 算 vector + index memory：row × dim × 4 bytes × (1 + index_overhead)
• shared_buffers 至少能放 hot index portion
• 不行就降 dim（halfvec）/ 升 instance / 拆 sharded

跟專業 Vector DB 對比

選 pgvector 的場景：

• Application 已用 PG、不想多管系統
• Vector 量 < 100M
• 需要 join vector + relational
• Team SQL 熟、不想學 API SDK
• Cost 敏感（managed Pinecone 1M vector 月 ~$70+）

選專業 vector DB 的場景：

• Vector 量 > 5-20M（依 dim / QPS / recall 要求、pgvector 在這個級別 + 高 QPS 已開始痛、不必撐到 100M 才換）
• 純 vector workload（沒 relational integration）
• 需要 multi-tenant SaaS
• Throughput 要求極高（> 10K QPS）
• 不想自管 HNSW build / memory budget / recall drift（managed Pinecone 把這層 ops 轉嫁、cost 換 ops 時間）
• 需要 dim > 2000（pgvector vector type 限制、halfvec 可到 4000、再大需 dimension reduction）

相關連結

• extension-ecosystem：其他 PG extension
• jsonb-deep-dive：embedding 通常配 metadata JSONB
• index-selection：B-tree / GIN / HNSW 整體比較
• query-optimization：vector query 的 EXPLAIN

下一步

• 看 extension-ecosystem 探索其他 PG 擴展可能
• 回 PostgreSQL overview 看全圖