Quiz Generator
AI 出題方法論

1. 概述

Uedu 的 Quiz Generator（AI 出題系統）讓教師只需提供教學內容，即可由 LLM 自動生成多種題型與難度的測驗題目。系統核心為 QuizAIGenerator 類別，使用 gpt-5-mini 模型，支援中英雙語生成。

生成過程採用題型 × 難度分批策略，每個批次獨立呼叫 LLM，並透過 progress callback 即時回報進度，讓教師在前端看到即時的生成狀態。

2. 輸入參數

教師在建立 AI 出題任務時，需提供以下參數：

參數	型別	說明
source_content	String	教學內容文本，作為出題的知識來源
question_types	Dict	欲生成的題型與各題型的題數，例如 {"multiple_choice": 10, "true_false": 5}
difficulty_dist	Dict	難度分布比例，例如 {"easy": 0.3, "medium": 0.5, "hard": 0.2}
course_context	String	課程背景資訊（選填），幫助 LLM 理解出題情境
language	String	生成語言：zh（繁體中文）或 en（英文）

2.1 支援的題型

題型代碼	說明
multiple_choice	單選題（四選一）
true_false	是非題
fill_in_blank	填充題
short_answer	簡答題
essay	申論題

2.2 難度等級

等級	英文	說明
簡單	easy	記憶性、直接回想型題目
中等	medium	理解與應用型題目
困難	hard	分析、評鑑與創造型題目

3. 難度分布計算

系統透過 _calculate_difficulty_counts() 方法，將每種題型的總題數按難度比例拆分為各難度的實際題數：

3.1 計算邏輯

1. 對每種題型，將總題數乘以各難度的比例，取 floor（向下取整）
2. 因捨入誤差，各難度題數的總和可能小於原始總題數
3. 將差額依比例最大者優先的方式逐一補回，確保題數總和正確

3.2 計算範例

假設 multiple_choice: 10 題，difficulty_dist: {"easy": 0.3, "medium": 0.5, "hard": 0.2}：

難度	比例	計算	floor	最終
easy	0.3	10 × 0.3 = 3.0	3	3
medium	0.5	10 × 0.5 = 5.0	5	5
hard	0.2	10 × 0.2 = 2.0	2	2

4. 分批生成策略

4.1 批次拆分

系統將出題任務拆分為題型 × 難度的批次矩陣。例如，若教師要求 multiple_choice（10 題）和 true_false（5 題），難度分布為 easy/medium/hard，則拆分為：

• multiple_choice × easy（3 題）
• multiple_choice × medium（5 題）
• multiple_choice × hard（2 題）
• true_false × easy（2 題）
• true_false × medium（2 題）
• true_false × hard（1 題）

每個批次獨立呼叫一次 LLM API。

4.2 即時進度回報

系統支援 progress callback 機制。每個批次完成後，callback 函數會被呼叫，回報：

• 目前已生成的題目數（current）
• 總預計題目數（total）
• 進度百分比（progress，0.0 ~ 1.0）
• 目前狀態（processing、completed、failed）

前端透過輪詢進度 API 即時顯示生成狀態。

4.3 題目排序

所有批次的題目生成完成後，系統會將全部題目隨機打亂順序（shuffle），並重新編排 question_order，確保不同難度與題型的題目均勻穿插。

5. 輸出格式

LLM 生成的每道題目包含以下欄位：

欄位	型別	說明
question_text	String	題目文本
question_type	String	題型代碼（multiple_choice、true_false 等）
difficulty	String	難度等級（easy、medium、hard）
options	Array	選項列表（選擇題、是非題適用）
correct_answer	String	正確答案
explanation	String	答案解析
question_order	Number	題目順序（全部生成後隨機重排）

6. 研究引用建議

建議同時提供：

• 生成時使用的教學內容來源與長度
• 題型分布與難度比例設定
• 生成語言（zh / en）
• 教師事後編輯的比例（修改 / 刪除 / 保留原樣）