A retrieval-augmented knowledge base over semiconductor / AI-infrastructure research notes, with a hermetic retrieval eval harness gated in CI (no API key, no vector-DB service). See Retrieval evaluation.
本專案的主題是「半導體 / AI 基礎設施產業分析」。我把平常閱讀的產業筆記、法說整理、供應鏈框架與風險觀察整理成一個可重建的個人知識 RAG 系統，目標不只是單次問答，而是進一步自動生成可供 Agent 使用的 skill.md。
知識邊界刻意收斂在幾個互相關聯的子題：先進製程、CoWoS 與先進封裝、HBM 記憶體供應鏈、foundry vs IDM 決策框架、AI server BOM 壓力，以及地緣政治與出口管制對產業分析的影響。這樣的收斂可以讓 retrieval 更精準，也讓最終 skill.md 更像領域入門指南，而不是泛化的半導體百科。
目前語料庫共有 35 份原始文件，全部存放在 data/raw/：
27份 Markdown 文件（其中22份為研究筆記 / synthesis notes，5份為官方來源優先摘要）8份 TXT 法說 / Q&A 摘要- 目前沒有 PDF 語料，但
data_update.py已支援.md、.txt、.pdf三種格式
資料時間範圍以 2025 年半導體與 AI 基礎設施脈絡為主。data_update.py 會將原始資料清理後輸出到 data/processed/，再做 chunking、embedding、向量寫入與 manifest 同步。rag_query.py 提供 CLI 問答介面，skill_builder.py 則會對整個知識庫提出一組全域問題，最後輸出 skill.md。
本專案的技術選型如下：
- Vector DB:
ChromaDB - Embedding:
sentence-transformers/paraphrase-multilingual-MiniLM-L12-v2 - LLM gateway:
LiteLLM - PDF extractor:
PyMuPDF
graph LR
A["data/raw/"] --> B["data_update.py"]
B --> C["data/processed/*.txt"]
B --> D["manifest.json"]
C --> E["Chunking 1100 chars + 180 overlap"]
E --> F["SentenceTransformer embeddings"]
F --> G[("ChromaDB")]
G --> H["rag_query.py"]
H --> I["Retrieve top 8 -> rerank -> keep top 5"]
I --> J["LiteLLM completion()"]
J --> K["Grounded answer"]
K --> L["Deterministic Python citations"]
G --> M["skill_builder.py"]
M --> N["14 global synthesis questions"]
N --> O["JSON synthesis + schema validation"]
O --> P["skill.md"]
- 採用「段落優先 + 固定長度補切」策略。
- 預設參數為
target_chars = 1100、overlap_chars = 180。 - 先依文件結構拆 section，再依段落與句界切 chunk；真的沒有句界時才退化成固定字數切割。
- Markdown 文件優先保留
# heading與類似Prepared Remarks:這種結構。 - Q&A 文件優先保留完整問答對，避免問題與答案被拆散到不同 chunk。
這個策略適合目前的語料型態，因為本 corpus 不是長篇論文，而是研究筆記、框架整理與法說摘要。若直接用固定字數切，CoWoS / HBM / foundry vs IDM 這種框架型內容很容易失去語意邊界。
- Provider:
sentence-transformers - Model:
paraphrase-multilingual-MiniLM-L12-v2
選擇理由：
- 完全本地，可免費使用，不依賴額外 embedding API 成本。
- 支援中英混合，適合「英文原始資料 + 中文提問 / 中文 skill 輸出」的情境。
- 對目前
35份文件規模足夠，品質與推論成本平衡良好。
本專案使用 ChromaDB，而不是 pgvector。
主要理由是這次作業我把「可重現性」與「零額外服務依賴」放在第一優先。ChromaDB 直接以本地資料夾持久化，clone repo 後不需要先啟動 Docker 或額外資料庫服務，因此助教可以更快照著 README 重現整個流程。若未來要擴充成多人共用或加入更重的 metadata filter，再升級到 pgvector 會更合理。
- Query 先做 embedding
- 從 ChromaDB 先抓
top 8候選 - 以
semantic distance + lexical overlap做輕量 rerank - 最終保留
top 5chunks - 每份文件最多保留
2個 chunks，避免單一文件壟斷 context
這樣設計的原因是：單純 semantic top-k 很容易命中概念接近但過度泛化的內容。加入 lexical overlap 後，對 HBM、CoWoS、foundry vs IDM、export controls 這類帶明確術語的問題會更穩。每份文件設上限則能提高 context 的多樣性。
rag_query.py 的回答 prompt 原則如下：
- 嚴格限制只能使用 retrieved context
- 證據不足時必須明講
- 回答正文不讓模型自行輸出 citation block
- 來源列表由 Python 端固定輸出
source file + section title + chunk index
這樣做的好處是可以降低模型自行發明 citation format 的風險，同時保留 rubric 需要的來源可追溯性。
skill_builder.py 的 synthesis prompt 則是另一條路徑：它仍然建立在同一個 RAG 系統上，但要求輸出乾淨的分析型摘要，不混入 CLI 專用的 Sources: boilerplate，最後再由 Python 驗證 JSON schema，render 成穩定的 skill.md。
data_update.py 的增量更新不只看原始檔案 raw_hash，還會比對 pipeline_fingerprint。目前 fingerprint 包含：
cleaning_versionembedding_providerembedding_modelchunk_target_charschunk_overlap_chars
因此只要我改了清理邏輯、chunk 參數、或 embedding 設定，即使原始文件沒變，也會觸發重新處理與重新索引。這比單純看修改時間更可靠。
skill_builder.py 固定提出 14 個全域問題，涵蓋：
- 主題邊界與不在範圍內的議題
- 核心概念
- 2025 年重要趨勢
- 公司、機構與供應鏈角色
- CoWoS / HBM / chiplet / 先進製程關係
- AI server 出貨瓶頸
- foundry vs IDM 決策框架
- 地緣政治與出口管制
- 代表性 Q&A
- 知識缺口與限制
- 常見分析誤判
- 表面需求與可部署供給之間的落差
- 容易混淆的概念
- 證據最強的結論與僅具方向性的跡象
這樣做可以讓 skill.md 不只是模型 freestyle 寫作，而是基於多輪 RAG 查詢後的整合結果，格式與內容都更穩定。
- 開發版本：
Python 3.11.3 - 作業最低要求：
Python >= 3.10
# ① 確認 Python 版本
python3 --version
# ② 建立虛擬環境
python3 -m venv .venv
# ③ 啟動虛擬環境
source .venv/bin/activate
# Windows:
# .venv\Scripts\activate
# ④ 安裝依賴
pip install -r requirements.txt本專案使用 ChromaDB，不需要額外啟動 Docker service，因此 不需要 docker-compose.yml。
cp .env.example .env接著將 .env 中的 LITELLM_API_KEY 與 LITELLM_BASE_URL 填入助教提供的值。Embedding 預設使用本地 sentence-transformers，不需要另外設定 API key。
以下流程可在乾淨環境中直接逐行執行：
# ① 確認 Python 版本
python3 --version
# ② 建立並啟動虛擬環境
python3 -m venv .venv
source .venv/bin/activate
# ③ 安裝套件
pip install -r requirements.txt
# ④ 設定環境變數
cp .env.example .env
# 將 .env 中的 LITELLM_API_KEY / LITELLM_BASE_URL 填入助教提供的值
# ⑤ 啟動 Vector DB
# 本專案使用 ChromaDB，本步驟跳過，不需要 docker compose up
# ⑥ 全量重建索引
python data_update.py --rebuild
# ⑦ 測試 RAG 問答
python rag_query.py --query "請問這個知識庫的核心主題是什麼？"
# ⑧ 生成 Skill 文件
python skill_builder.py --output skill.md本專案在提交前已於全新的 Python 3.11.3 虛擬環境中重新驗證上述流程，確認 pip install -r requirements.txt、python data_update.py --rebuild、python data_update.py、python rag_query.py --query "請問這個知識庫的核心主題是什麼？" 與 python skill_builder.py --output skill.md 皆可成功執行。
以下三題是我用來驗證此 RAG 是否真的具備分析價值的代表性查詢：
為什麼 AI 需求強不等於立即出貨？這題驗證系統是否能把 GPU、HBM、封裝、網路、散熱與系統整合視為同一個部署瓶頸鏈，而不是只回答單一元件需求。分析 foundry vs IDM 時，哪些判準最重要？這題驗證系統是否能提供框架型回答，區分資本密集度、控制力、速度、生態系統存取與策略韌性等分析維度。HBM、CoWoS 與先進製程之間的瓶頸如何轉移？這題驗證系統是否能把記憶體、封裝與前段製程連成一個系統級敘事，而不是把它們視為彼此獨立的供應鏈事件。
python rag_query.py互動模式支援以下指令：
clear: 清除最近三輪對話歷史exitquit
data/processed/*.txt: 清理後、可直接 chunk 的標準化文字，已提交到 repodata/processed/manifest.json: 記錄 raw hash、processed hash、chunk ids、source metadata、pipeline fingerprintchroma_db/: ChromaDB 持久化目錄，已在.gitignore中忽略，不應提交
本 repo 僅使用合法公開資料與個人整理筆記，不包含付費牆、需登入下載或受帳號限制的內容。
| 來源名稱 | 類型 | 授權 / 合規依據 | 數量 |
|---|---|---|---|
| 個人研究筆記與 synthesis notes | Markdown | 由公開產業材料、公司 IR、技術觀察與個人整理組成；僅作課程作業與研究用途 | 22 |
| 公司 IR / earnings-derived digests | TXT | 依據公司 investor relations 與公開說明材料整理，不含付費內容逐字轉載 | 8 |
| 官方政策 / regulatory source summaries | Markdown | 根據美國 BIS 等官方政策文件整理，保留政策脈絡與合規限制 | 1 |
| 官方 infrastructure / supplier source summaries | Markdown | 根據 SK hynix、ASML、Broadcom、Dell 等官方材料整理，聚焦 HBM、設備、網路與 rack-scale 部署 | 4 |
| PDF 文件 | 目前語料庫未納入 PDF，但系統已支援 PDF ingestion | 0 |
代表性來源脈絡包括：
- TSMC quarterly results / investor relations materials
- AMD, Intel, Micron, NVIDIA, Samsung investor relations materials
- SK hynix, ASML, Broadcom, Dell official materials
- U.S. BIS official policy materials
- 公開供應鏈與產業觀察材料
- 個人對公開技術與市場資訊的結構化整理
目前系統仍有以下限制：
- 語料雖然已超過作業最低門檻，但仍以筆記型與摘要型文件為主，官方白皮書、完整 PDF 與更長篇逐字稿比例仍可增加。
- Retrieval 是輕量 rerank，不是 cross-encoder 等級 reranker，因此在非常細緻的問題上仍可能錯過最佳 chunk。
skill_builder.py已加入 JSON schema 驗證與一次重試，但仍仰賴 LLM 的整合能力，若要再提高穩定性，可加入更細的 section-level validation。- 目前主題邊界聚焦在 2025 年半導體 / AI 基礎設施分析。如果改問更廣泛的半導體子領域，coverage 會下降。
若有更多時間，我會優先做：
- 擴充更多一手資料，例如官方 PDF、設備商資料與政策文件。
- 加入 metadata filter，支援只查
HBM、只查Q&A digest、只查risk notes。 - 加入更強的 reranker 與 retrieval evaluation。
- 為每份文件補更完整的 provenance map，將原始來源連結、日期與 primary references 全面結構化。
The claim that this knowledge base retrieves the right sources is measured, not
asserted. evals/eval_set.json is a labeled set of
questions, each tagged with the source document(s) a correct retriever should
surface. evals/retrieval_eval.py embeds the corpus
and the questions with the same model the pipeline uses, ranks documents by cosine
similarity, and reports Recall@1, Recall@3 and MRR.
It is deliberately hermetic — no API key, no ChromaDB service, only the embedding
model — so it runs the same on a laptop and on a clean CI runner. The GitHub
Actions eval workflow fails the build if retrieval
quality drops below the gate (Recall@3 >= 0.80, MRR >= 0.70).
pip install -r evals/requirements.txt
python evals/retrieval_eval.py # prints a per-question rank table
pytest -q tests/test_retrieval_eval.py