Chat Embedding
語意向量方法論

1. 概述

Chat Embedding 是 Uedu 平台的對話語意向量化模組，屬於 Educational Omics 框架中 Cognomics（認知歷程）與 Linguomics（語言表達）維度的基礎設施。

系統會將學生發送給 AI 助教的每一則訊息（request）轉換為高維度語意向量，儲存於資料庫中。這些向量可用於：

• 語意搜尋：在對話歷史中以自然語言進行語意檢索，取代傳統關鍵字搜尋
• 相似問題偵測：找出不同學生提出的語意相近問題，協助教師掌握學習痛點
• 研究聚類分析：透過向量空間中的分布，分析學生的提問模式與認知軌跡

2. 向量化流程

2.1 嵌入對象

系統僅嵌入學生發送的訊息（request），不嵌入 AI 的回應（response）。這是因為研究關注的是學生的提問行為與認知表達，而非 AI 的輸出。

2.2 文本前處理

訊息在嵌入前需經過以下前處理步驟：

1. 清理：去除多餘空白與格式雜訊
2. 最短長度檢查：訊息至少需 2 個字元，過短的訊息（如單一標點符號）將被跳過
3. Token 截斷：使用 cl100k_base tokenizer 計算 token 數，超過 8,000 tokens 的訊息會被截斷（並標記 was_truncated = 1）
4. 內容雜湊：計算 MD5 content hash，用於去重（deduplication），避免相同內容重複嵌入

2.3 嵌入模型

參數	值	說明
模型	text-embedding-3-small	OpenAI embedding model
向量維度	1536	輸出浮點數向量長度
Tokenizer	cl100k_base	GPT-4 / embedding 共用
最大 Token	8,000	超過即截斷

2.4 雙路徑處理

系統採用即時 + 批次回填的雙路徑架構，確保新訊息即時向量化，同時補齊歷史數據：

2.5 跳過訊息處理

不符合嵌入條件的訊息（過短、無實質內容）會被寫入一筆 NULL embedding 記錄，以防止批次回填程序反覆嘗試處理。這確保每則訊息只被評估一次。

3. 語意搜尋機制

3.1 搜尋原理

語意搜尋使用餘弦相似度（cosine similarity）計算查詢向量與資料庫中所有嵌入向量的相似程度。系統使用 numpy 矩陣運算進行高效計算：

similarity = (A · B) / (||A|| × ||B||)

3.2 範圍篩選

搜尋支援三種範圍篩選，可依研究需求限縮搜尋範圍：

篩選範圍	說明	適用場景
Classroom	限定特定課程的所有對話	教師搜尋全班學生的提問
User	限定特定學生的對話	追蹤個別學生的認知軌跡
Chat	限定特定對話串	在單一對話中搜尋上下文

3.3 搜尋參數

參數	預設值	範圍	說明
top_k	10	1 ~ 50	回傳最相似的前 k 筆結果
threshold	0.3	0.0 ~ 1.0	最低相似度門檻，低於此值的結果會被過濾

3.4 記憶體快取

為提升搜尋效能，系統為每個範圍鍵（scope key）維護一組記憶體快取（in-memory cache），快取策略如下：

• TTL：5 分鐘自動過期
• 快取失效：當該範圍有新的嵌入寫入時，快取即刻失效並重新載入
• 快取內容：包含向量矩陣與對應的 metadata，避免重複資料庫查詢

4. 系統參數

參數	值	說明
Embedding Model	text-embedding-3-small	OpenAI embedding 模型
向量維度	1536	每則訊息產生的浮點數向量長度
最短訊息長度	2 字元	低於此長度的訊息不嵌入
最大 Token 數	8,000	超過即截斷（cl100k_base）
Content Hash	MD5	用於內容去重
即時嵌入	daemon thread	每則新訊息觸發一個背景執行緒
批次 Workers	3	以 log_id % 3 分區
批次輪詢間隔	15 秒	每個 worker 的輪詢週期
批次大小	50 筆	每次輪詢處理的最大訊息數
搜尋 top_k	10（最大 50）	預設回傳筆數
搜尋門檻	0.3	最低 cosine similarity
快取 TTL	5 分鐘	per scope key
寫入策略	INSERT IGNORE	冪等性保證

5. 批次處理

5.1 批次回填架構

批次回填程序負責處理即時嵌入遺漏的訊息（例如服務重啟期間產生的訊息），以及系統上線前的歷史訊息。

• Worker 數量：3 個並行 worker
• 分區策略：以 log_id % 3 分配訊息到不同 worker，避免重複處理
• 輪詢間隔：每 15 秒查詢一次資料庫，取得尚未嵌入的訊息
• 批次大小：每次最多處理 50 筆訊息

5.2 冪等性保證

資料庫以 log_id 作為 UNIQUE KEY，寫入時使用 INSERT IGNORE。即使即時路徑與批次路徑同時處理同一則訊息，也不會產生重複記錄。

6. 資料儲存

6.1 資料表結構

嵌入結果儲存於 chat_message_embeddings 資料表：

欄位	型態	說明
id	INT AUTO_INCREMENT PK	主鍵
log_id	INT, UNIQUE KEY	對應 chat_log 的訊息 ID
embedding	BLOB	1536 維浮點數向量（二進位格式）
content_hash	CHAR(32)	MD5 內容雜湊，用於去重
content_preview	VARCHAR(200)	訊息前 200 字元預覽
token_count	INT	訊息的 token 數量
was_truncated	TINYINT(1)	是否經過截斷（0/1）
created_at	DATETIME	嵌入時間

6.2 NULL Embedding 記錄

不符合嵌入條件的訊息（長度不足、無實質內容）會寫入一筆 embedding = NULL 的記錄。這使得批次回填程序可以透過 LEFT JOIN 快速識別尚未處理的訊息，避免反覆嘗試。

7. 研究引用建議

建議同時提供：

• 嵌入的訊息類型（僅學生 request 或含 AI response）
• 資料收集期間與有效訊息數量
• 搜尋參數設定（top_k、threshold）
• 知情同意書版本與 IRB 核准文號
• 若用於聚類分析，說明所用的降維與聚類演算法