UeduGPTs
Jupyters
說明 Uedu 平台如何透過大型語言模型（LLM）自動分類學生與 AI 助教對話中的認知層次，供教學研究者撰寫論文時參考。
Uedu 平台在學生與 AI 助教（UeduGPTs）的每一次對話中，自動對學生發送的訊息進行 Bloom's Revised Taxonomy 認知層次分類。此分析完全在後端執行，不影響學生的使用體驗，分析結果供教師在儀表板中檢視，亦可匯出供研究使用。
本文件說明此自動分類系統的完整方法論，包含理論依據、技術實作、Prompt 設計、資料品質控管等面向，協助研究者理解數據的產生過程。
本文件描述的分類邏輯基於 v1.4，使用模型為 gpt-5-mini。歷次版本變更請見第 10 節。
本系統採用 Bloom's Revised Taxonomy（Anderson & Krathwohl, 2001）作為認知層次分類框架，將學生的認知操作分為由低到高的六個層次：
| 層次 | 英文 | 定義 | 學生訊息範例 |
|---|---|---|---|
| 1. 記憶 | Remember | 回憶、辨識事實性知識 | 「什麼是光合作用？」 |
| 2. 理解 | Understand | 解釋、歸納、推論意義 | 「為什麼要用遞迴？」 |
| 3. 應用 | Apply | 在新情境中執行或使用知識 | 「如何用 for 迴圈印九九乘法表？」 |
| 4. 分析 | Analyze | 分解要素、找出關係與結構 | 「這兩種方法差在哪？」 |
| 5. 評鑑 | Evaluate | 根據準則做出判斷 | 「A 和 B 方案哪個更適合？」 |
| 6. 創造 | Create | 整合元素產生新的東西 | 「幫我設計一個實驗方案」 |
bloom_level以下流程圖說明一則學生訊息從送出到完成 Bloom 分類的完整資料流：
app.py 將原始訊息寫入 classroomgpt_my_log 資料表analyze_bloom_async() 啟動背景 threadclassroomgpt_bloom_analysisPrompt 採用 System / User 拆分模式（v1.2 起）：
分類前，LLM 會先判斷該訊息是否為有意義的學習訊息（is_meaningful）。以下類型被視為無意義：
短但有明確學習意圖的訊息仍判定為有意義，例如「為什麼？」「什麼是 DNA？」。
系統會查詢學生當前訊息之前最近 2-3 輪的對話紀錄（學生提問 + AI 回覆）作為前文脈絡，但 LLM 只分類最後一則學生訊息，前文僅用於理解語境。
例如，當學生回覆「為什麼？」時，前文可以幫助判斷這是在追問概念解釋（Understand）還是在探究因果關係（Analyze）。
學生訊息可能附帶圖片（截圖、照片、手寫筆記等）。系統會將圖片編碼為 base64，以 OpenAI 的 multimodal content 格式送入 LLM，讓分類器能綜合文字與圖片內容進行判斷。
LLM 回傳嚴格 JSON 格式，經系統驗證後存入資料庫。每一筆分析結果包含以下欄位：
| 欄位 | 型別 | 說明 |
|---|---|---|
is_meaningful |
Boolean | 是否為有意義的學習訊息 |
bloom_level |
Enum | 主要認知層次：remember / understand / apply / analyze / evaluate / create（無意義訊息為 NULL） |
scores |
6 個 Float | 六個層次各自的佔比分數，總和 = 1.0 |
evidence |
Text | LLM 提供的判斷依據（30 字以內） |
skip_reason |
String | 若 is_meaningful = false，記錄原因 |
method |
String | 使用的模型名稱（如 gpt-5-mini） |
prompt_version |
String | Prompt 版本號（如 v1.4） |
bloom_level 代表 LLM 判定的主要認知層次（單一標籤），而 scores 六維分數則反映該訊息在各層次間的分布。研究者可依需求選用單一標籤（分布統計）或連續分數（雷達圖、軌跡分析）。
系統採用即時路徑 + 批次路徑雙軌並行，確保每一則學生訊息都能被分析：
| 即時路徑（Real-time） | 批次路徑（Batch） | |
|---|---|---|
| 觸發時機 | 學生送出訊息後立即觸發 | 背景 daemon 每 10 秒輪詢 |
| 實作方式 | 單一 daemon thread | 10 個並行 daemon thread （依 log_id % 10 分區） |
| 用途 | 即時分析新訊息 | 回補歷史資料、處理即時路徑遺漏 |
| 防重複機制 | 資料庫 UNIQUE KEY on log_id，INSERT IGNORE 確保冪等 |
|
系統對 LLM 回傳的每一筆結果進行多層驗證：
response_format=json_object 強制 LLM 輸出 JSON，並在客戶端再次 parse 驗證任何驗證失敗會觸發重試，最多重試 3 次，每次間隔 1 秒。若 3 次均失敗，系統會寫入一筆 failure record（method='error'），防止批次 worker 無限重試同一筆資料。
每筆分析結果都記錄使用的 prompt_version 與 method（模型名稱）。當 Prompt 或模型更新時，研究者可依版本號篩選資料，確保分析的一致性。
教師（需具備該課程的教師 / 助教權限）可透過以下 API 取得分析資料：
| API 端點 | 說明 |
|---|---|
GET /api/bloom/classroom/{id}/overview |
全班認知層次分布概覽（各層次筆數、平均分數） |
GET /api/bloom/classroom/{id}/students |
每位學生的分析摘要（主要認知層次、平均分數） |
GET /api/bloom/classroom/{id}/trajectory |
認知層次時間軌跡（按週彙整，可篩選特定學生） |
GET /api/bloom/classroom/{id}/export |
匯出全班完整數據（JSON，按學生 × 週次彙整） |
若您在學術論文中使用 Uedu 平台產生的 Bloom's Taxonomy 認知層次資料，建議在方法論章節中說明以下資訊：
學生與 AI 助教對話中的每則訊息，由 Uedu 平台自動進行 Bloom's Revised Taxonomy（Anderson & Krathwohl, 2001）認知層次分類。分類系統使用大型語言模型（LLM; OpenAI gpt-5-mini）作為分類器，透過結構化 Prompt（版本 v1.4）指示模型依據學生展現的認知操作（而非話題難度）判定主要認知層次，並輸出六維度分數分布。分類時納入前 2-3 輪對話脈絡以理解語境，並支援文字與圖片的多模態輸入。系統對每筆 LLM 回應進行格式與合法性驗證，失敗時最多重試三次。詳細方法論說明見 https://uedu.tw/doc/bloom。
建議同時提供以下資訊：
prompt_version 欄位確認）method 欄位確認）| 版本 | Prompt 模式 | 主要變更 |
|---|---|---|
| v1.4 | System / User 拆分 | 精簡版，針對 gpt-5-mini 優化，減少空回應。新增無意義類型（情緒反應、閒聊、確認附和、催促、純貼上）。新增多模態（圖片）支援說明。 |
| v1.3 | System / User 拆分 | 新增對話脈絡處理規則（只分類最後一則、前文僅供語境理解） |
| v1.2 | System / User 拆分 | 首次拆分為 system prompt + user prompt，啟用 prompt caching |
| v1.1 | 合併式 | 新增 is_meaningful 有意義性判斷、skip_reason 欄位 |
| v1.0 | 合併式 | 初始版本，基本六層次分類 |