「在 AI Agent 的知識庫架構中，RAG 是消除大模型幻覺的定海神針。透過在地化的 Embedding 模型、asyncio.to_thread 非阻斷線程池委派，以及餘弦相似度門檻，我們能確保 Agent 在毫秒級時間內取得最精準的金融知識 context。」

先前，我們陸續解析了 FastAPI Web 服務入口與 ConversationMemory 對話記憶服務。今天我們將深入 Angelina AI Agent 的知識庫心臟。
為了讓系統在處理複雜向量運算時不卡死 FastAPI 的 asyncio Event Loop，RAGEngine 採取了 Thread-pool Offloading 設計，並整合 ChromaDB 本地持久化資料庫與 HuggingFace 在地 Embedding 模型。
今天我們將解剖 rag_engine.py 的核心架構、分詞策略與 Self-healing 重構機制！

本篇重點摘要

1. 剖析 asyncio.to_thread 異步委派架構與 sentence-transformers/all-MiniLM-L6-v2 在地模型。
2. 拆解 ChromaDB 餘弦相似度（hnsw:space: cosine）計算與 SIMILARITY_THRESHOLD = 0.5 硬性門檻過濾。
3. 解析 tiktoken (cl100k_base) 500-token 切分演算法與資料庫毀損時的 _auto_rebuild 自動復原機制。

一、非阻斷異步委派與在地化 Embedding 架構

Embedding 與向量資料庫 I/O 屬於典型的 CPU/Disk-Bound 阻塞型任務。在 RAGEngine 中，所有對外公開方法均為 async，並在內部透過 asyncio.to_thread 轉交線程池執行：

  1. 在地化向量模型 (sentence-transformers/all-MiniLM-L6-v2)
     (1) 零 API 延遲與費用：採用在地化 HuggingFace 模型 sentence-transformers/all-MiniLM-L6-v2，完全不需要外呼第三方 API，實現極速、零成本且高度隱私的 Vector Generation。
     (2) 單例延遲載入 (_load_embedding_model)：採用 Lazy Initialization 策略，僅在服務初始化時載入一次模型，避免重複占用記憶體。

  2. ChromaDB 持久化客戶端 (_get_or_create_collection)
     (1) 資料庫預設存放在 data/vector_store 目錄下，使用 angelina_knowledge Collection。
     (2) 顯式指定 HNSW 索引演算法為餘弦距離：metadata={"hnsw:space": "cosine"}。

二、語意搜尋與餘弦相似度過濾

當 /chat 或 daily_analysis.py 呼叫 rag_engine.search(query, top_k=5) 時，系統執行以下精準檢索流程：

  1. 餘弦相似度轉換演算法
     ChromaDB 在 cosine 空間中回傳的是「距離（Distance）」，模組將其精準轉換為人類可讀的「相似度」：

# rag_engine.py 關鍵相似度轉換邏輯
similarity = 1.0 - float(distance)

2. 0.5 硬性門檻過濾 (SIMILARITY_THRESHOLD = 0.5)
   (1) 品質護欄：僅有 similarity >= 0.5 的知識 Chunk 才允許被回傳給 LLM 作為參考 Context。
   (2) 降級標記：若搜尋結果全數低於 0.5，search() 會回傳空陣列 []。在 app/main.py 中收到空陣列時，系統會自動將 used_general_knowledge 標示為 True，告知前端本次回答完全使用 Gemini 通用知識庫。

三、tiktoken 文本切分與全量重構機制

當管理員透過 POST /knowledge/update 端點更新知識庫，或系統觸發自動學習重構時，會執行 rebuild_index(export_path)：

  1. 精準 Token 級分詞策略
     (1) cl100k_base 編碼：整合 tiktoken 計算真實 Token 長度。
     (2) 分詞參數：CHUNK_SIZE_TOKENS = 500（區段大小）、CHUNK_OVERLAP_TOKENS = 50（重疊長度）。
     (3) 分隔符優先順序：依序採用 ["\n\n", "\n", "。", ".", " ", ""]，優先維護段落與中文句號的語意完整度。

  2. 向量庫自癒機制
     在 initialise() 啟動階段，若檢測到本地 ChromaDB 檔案損壞或遺失，系統不會掛掉，而是自動觸發 _auto_rebuild()：
     (1) 自動掃描 data/notebooklm 目錄下最新修改的 .txt 或 .md 匯出檔。
     (2) 重新建構 Collection、重新分詞與 Embedding，在數秒內讓 Agent 的知識庫「起死回生」！

四、今日總結

透過 app/services/rag_engine.py 的解剖，我們確認了：

1. 高併發非阻斷：asyncio.to_thread 與在地化 MiniLM 模型，確保了核心 Event Loop 毫秒級流暢度。
2. 高品質 Context 護欄：0.5 相似度門檻與 used_general_knowledge 降級機制，杜絕無關文本干擾 LLM 生成。
3. 高韌性架構：tiktoken 500-token 精準切分與 _auto_rebuild 自癒機制，確保系統長久穩定運行。

明日預告：敬請期待~!