docs/AI_QUIZ_API.md

AI Quiz API 接口文档

用于与前端/其他网页进行 AI Quiz 互动的统一接口规范。所有响应均包含 meta 用于模型追踪与排查；题目使用 question_id 与 correct_answers 便于后端存档与追溯。

---

1. 通用：所有响应增加 meta

用于排查模型问题与结果追溯，所有成功响应均需包含：

"meta": {
  "model": "gpt-4.1-mini",
  "model_version": "2024-07",
  "prompt_version": "quiz_v2",
  "temperature": 0.4,
  "tokens_used": 842,
  "latency_ms": 1280
}

字段	类型	说明
model	string	模型标识
model_version	string	模型版本（可选）
prompt_version	string	当前 prompt 版本，便于回溯
temperature	number	采样温度
tokens_used	number	本次请求消耗 token 数
latency_ms	number	请求耗时（毫秒）

---

2. Generate Quiz：题目与答案结构

2.1 删除字段

• 禁止使用 options[].is_correct 表示正确答案。

2.2 新增 / 修改结构

每题必须包含唯一 question_id，答案通过 correct_answers 数组表示，便于后端校验与存档。

题目项示例：

{
  "question_id": "ai_q_001",
  "type": "SINGLE_CHOICE",
  "question_text": "What is responsible AI?",
  "options": [
    { "key": "A", "text": "AI that only runs on servers" },
    { "key": "B", "text": "AI designed to be accountable and fair" },
    { "key": "C", "text": "AI that uses no data" }
  ],
  "correct_answers": ["B"]
}

答案规则（后端需校验，不合法可重试）：

题型	correct_answers 规则	备注
SINGLE_CHOICE	必须 恰好 1 个 答案	如 ["B"]
MULTIPLE_CHOICE	≥ 1 个答案	如 ["A","C"]
TRUE_FALSE	必须 2 个选项（True/False）	答案为其中之一
SHORT_ANSWER	不适用选项；必须返回 explanation	用于评分与反馈

SHORT_ANSWER 示例：

{
  "question_id": "ai_q_002",
  "type": "SHORT_ANSWER",
  "question_text": "Explain one risk of generative AI in education.",
  "explanation": "Reference answer: e.g. over-reliance may reduce critical thinking."
}

---

3. 标准错误返回

当 AI 输出不合法、超时或服务失败时，统一使用以下结构（非 2xx）：

{
  "code": 422,
  "error": {
    "type": "INVALID_GENERATION",
    "reason": "multiple_correct_answers"
  }
}

3.1 错误码与 type

HTTP code	error.type	说明
422	INVALID_GENERATION	AI 输出不合法（如单选多答、缺少必填字段等），reason 可细化
429	RATE_LIMIT	请求频率超限
500	MODEL_ERROR	模型/上游服务错误
504	TIMEOUT	请求超时

3.2 reason 示例（422）

• multiple_correct_answers：单选题返回了多个正确答案
• missing_question_id：缺少 question_id
• missing_correct_answers：缺少 correct_answers 或不符合题型规则
• invalid_short_answer：SHORT_ANSWER 缺少 explanation

---

4. Grade Quiz：每题解释

批改接口响应中，新增 per_question_feedback，对每题给出分数与简要理由：

{
  "overall_score": 75,
  "per_question_feedback": [
    {
      "question_id": "ai_q_001",
      "score": 10,
      "reasoning": "Correct choice; full marks."
    },
    {
      "question_id": "ai_q_002",
      "score": 7,
      "reasoning": "Concept correct but example missing."
    }
  ],
  "meta": {
    "model": "gpt-4.1-mini",
    "model_version": "2024-07",
    "prompt_version": "grade_v1",
    "temperature": 0.2,
    "tokens_used": 520,
    "latency_ms": 890
  }
}

字段	类型	说明
question_id	string	对应题目 ID，与 Generate 阶段一致
score	number	该题得分
reasoning	string	简短批改理由

---

5. 课程信息（参考）

• Course: IST345（来自 syllabus）
• Instructor: Yan Li — Yan.Li@cgu.edu
• TA: Kaijie Yu — Kaijie.Yu@cgu.edu
• TA: Yongjia Sun — Yongjia.Sun@cgu.edu

前端展示 Instructor 与多位 TA 时，可依此配置。

---

6. 外部网站调用方式（Generate Quiz）

其他网站/前端可通过 HTTP 调用 Clare 后端的 生成 Quiz 接口，无需登录、无会话依赖。

6.1 接口地址

• 方法: POST
• URL: https://你的Clare后端域名/api/quiz/generate
  例如部署在 Hugging Face Space 则为：https://xxx.huggingface.co/api/quiz/generate

6.2 CORS

后端已配置 allow_origins=["*"]，任意域名的网页均可通过浏览器 fetch 直接请求该接口（跨域可行）。

6.3 请求体（JSON）

字段	类型	必填	说明
topic	string	是	测验主题，如 "Responsible AI"、"IST345 Module 10"
num_questions	int	否	题目数量，默认 3，范围 1–10
language	string	否	题目语言：en（英语）或 zh（中文），默认 en

6.4 请求头（可选）

若你在后端环境变量中设置了 **QUIZ_API_KEY**，则请求必须在 Header 中带上：

• Header 名: X-API-Key
• 值: 与 QUIZ_API_KEY 一致

未设置 QUIZ_API_KEY 时，无需该 Header。

6.5 成功响应（200）

{
  "questions": [
    {
      "question_id": "ai_q_001",
      "type": "SINGLE_CHOICE",
      "question_text": "What is responsible AI?",
      "options": [
        { "key": "A", "text": "..." },
        { "key": "B", "text": "AI designed to be accountable and fair" }
      ],
      "correct_answers": ["B"]
    }
  ],
  "meta": {
    "model": "gpt-4.1-mini",
    "prompt_version": "quiz_generate_v1",
    "temperature": 0.4,
    "tokens_used": 842,
    "latency_ms": 1280
  }
}

6.6 错误响应

• 422：主题为空或 AI 输出不合法，body 含 code、error.type、error.reason
• 429：未带或错误的 X-API-Key（当已设置 QUIZ_API_KEY 时）
• 500：模型/服务异常

6.7 前端调用示例（fetch）

// 将 BASE 换成你的 Clare 后端地址，例如 https://your-space.hf.space
const BASE = "https://your-clare-api.com";

async function generateQuiz(topic, numQuestions = 3, language = "en") {
  const res = await fetch(`${BASE}/api/quiz/generate`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    // 若设置了 QUIZ_API_KEY，加上: "X-API-Key": "你的密钥"
    body: JSON.stringify({ topic, num_questions: numQuestions, language }),
  });
  if (!res.ok) {
    const err = await res.json().catch(() => ({}));
    throw new Error(err?.error?.reason || res.statusText);
  }
  return res.json(); // { questions, meta }
}

// 使用
generateQuiz("Responsible AI", 3, "en").then((data) => {
  console.log(data.questions);
  console.log(data.meta.latency_ms);
});

6.8 部署时建议

• 若只允许自家站点调用，可在后端设置 **QUIZ_API_KEY**，并在调用方请求头中携带 X-API-Key。
• 若需限流，可在后端对 /api/quiz/generate 做频率限制（或依赖 HF/网关的限流）。