# CLAUDE.md

這個檔案為 Claude Code (claude.ai/code) 在此程式庫中工作時提供指引。

> **重要提示**：這是一份學習導向的實作指引。請在關鍵步驟詢問使用者的理解，而非直接給答案。

## 專案概述

這是一個為期 3 天的密集 RAG（檢索增強生成）學習衝刺專案，專為面試準備而設計。此專案採用「實驗→觀察→結論」的工程思維，幫助學習者從零開始理解和建構 RAG 系統。

## 程式庫結構

- `LLM-Introduct.md` - 完整的 3 天 RAG 學習計畫，包含理論與實作指引
- `day1.md` - 詳細的第一天實作指引（RAG 系統從零到一），涵蓋：
  - **上午任務**（3-4小時）：環境建置、核心概念、第一個 RAG 程式
  - **下午任務**（3-4小時）：深入理解 Embedding、參數調整實驗
  - 包含 5 個概念檢查點和實作驗證
- `rag-interview-prep/` - 工作目錄，包含 Python 虛擬環境
  - `venv/` - 已安裝相依套件的 Python 虛擬環境

## 核心技術與相依套件

此專案使用的關鍵技術：
- **Python 3.11+** - 核心程式語言
- **LangChain** - RAG 框架與流程編排
- **ChromaDB** - 向量資料庫，用於 embeddings 儲存
- **Google Gemini API** - 生成用的大語言模型（需要 API 金鑰）
- **HuggingFace Transformers** - 多語言 embeddings（`paraphrase-multilingual-MiniLM-L12-v2`）
- **sentence-transformers** - Embedding 模型函式庫

## 開發指令

### 環境設定
```bash
# 導航至工作目錄
cd rag-interview-prep

# 啟動虛擬環境
source venv/bin/activate  # Linux/Mac
# 或 venv\Scripts\activate  # Windows

# 安裝相依套件（如需要）
pip install langchain-google-genai sentence-transformers chromadb python-dotenv langchain
```

### 設定
- API 金鑰設定：建立 `.env` 檔案，內容為 `GOOGLE_API_KEY=你的金鑰`
- 取得 Gemini API 金鑰：https://makersuite.google.com/app/apikey

### 預期的 Python 腳本（依據 day1.md 指引）
- `simple_rag.py` - 核心 RAG 系統實作，包含：
  - 文件讀取與切分
  - Embedding 模型載入
  - 向量資料庫建立
  - LLM 設定與 QA Chain
  - 互動式測試介面
- `embedding_experiment.py` - Embedding 相似性實驗，包含：
  - 向量維度觀察
  - 語意相似度測試
  - 餘弦相似度計算
- `parameter_experiments.py` - RAG 參數調校實驗，測試：
  - chunk_size 影響（200, 500, 1000）
  - top_k 影響（1, 3, 5）
  - 自動比較與結果輸出

### 資料結構
- `data/knowledge.txt` - RAG 實驗用的知識庫檔案（建議內容：個人履歷、技術專長等）
- `db/` - ChromaDB 向量資料庫持久化目錄（自動建立）
- `db_temp/` - 參數實驗用的臨時資料庫目錄
- `experiments.md` - 實驗結果文件（包含觀察紀錄表格）

## 架構概念

### RAG 管線組件
1. **文件處理**：使用 RecursiveCharacterTextSplitter 進行文字切分
2. **Embedding**：使用 HuggingFace 模型將文字塊轉換為向量
3. **向量儲存**：ChromaDB 進行高效相似性搜尋
4. **檢索**：在向量空間中進行 k-最近鄰搜尋
5. **生成**：使用增強上下文的 Gemini LLM

### 調校關鍵參數
- `chunk_size`：200-1000 字元（通常 500 為最佳）
- `chunk_overlap`：50-100 字元，用於保持上下文連貫性
- `top_k`：3-5 個文件，達到檢索平衡
- `temperature`：0 用於確定性回應

## 教育重點領域

此專案特別針對以下理解：
- 向量 embeddings 與語意相似性
- 文字切塊策略及其對檢索的影響
- RAG 與傳統搜尋方法的比較
- 透過實驗進行參數最佳化
- 實作挑戰與解決方案

## 學習流程（Day 1）

### 上午任務（3-4小時）
1. **Hour 1-2：環境建置與核心概念**
   - 套件安裝與 API 金鑰設定
   - 理解 Embedding 與 LLM 的分工
   - 手繪 RAG 資料流程圖
2. **Hour 3-4：寫第一個 RAG 程式**
   - 準備知識庫 `data/knowledge.txt`
   - 實作 `simple_rag.py` 完整流程
   - 測試與觀察檢索結果

### 下午任務（3-4小時）
3. **Hour 5-6：深入理解 Embedding**
   - 執行 `embedding_experiment.py`
   - 觀察向量維度與相似度計算
   - 自主實驗延伸測試
4. **Hour 7-8：參數調整實驗**
   - 執行 `parameter_experiments.py`
   - 記錄 chunk_size 和 top_k 影響
   - 完成 `experiments.md` 觀察紀錄

## 概念檢查點

Day 1 包含 5 個重要的概念驗證點：
1. **Embedding 與 LLM 分工理解**
2. **RAG vs 直接詢問 LLM 的差異**
3. **檢索結果觀察與幻覺問題**
4. **語意相似度實驗結果分析**
5. **參數調整的取捨思考**

## Claude Code 使用指引

### 引導原則
- **概念優先**：在每個關鍵步驟詢問使用者的理解，而非直接給答案
- **實驗導向**：鼓勵觀察與記錄，而非只是執行程式
- **漸進式學習**：確保前一個概念理解後再進行下一步

### 常見問題處理
1. **環境建置**：確認 sentence-transformers 安裝（會下載模型）
2. **CPU 優化**：VM 環境下需在 HuggingFaceEmbeddings 加入 `model_kwargs={'device': 'cpu'}`
3. **API 限制**：如遇 Gemini API 超限，建議加入 `time.sleep(2)`
4. **第一次執行**：建議使用簡單的 knowledge.txt（3-5 句話）測試
5. **實驗記錄**：提醒「記錄觀察」比「跑完實驗」更重要

### 學習成果驗證
完成 Day 1 後，學習者應能：
- 畫出完整的 RAG 流程圖並解釋每個步驟
- 說明為什麼 RAG 優於直接詢問 LLM
- 理解 chunk_size、top_k、overlap 的取捨
- 獨立調整參數並觀察結果差異

## 未來開發注意事項

- 重點在概念理解而非程式碼最佳化
- 所有實驗都設計為觀察參數影響
- 採用模組化設計，可獨立替換 Embedding 和 LLM
- 成本考量：使用免費的 HuggingFace Embedding 模型