ai-question-generate

约 1742 字大约 6 分钟

2025-10-09

概述

ai-question-generate 是一个基于 Deno、Supabase 和 OpenAI SDK 的 AI 题目生成 API。它通过调用阿里云 DashScope（通义千问）API 生成各种类型的题目，并将生成的题目存储到 Supabase 数据库中。

接口定义

QuestionGenerateRequest 接口

题目生成请求的主体结构。

interface QuestionGenerateRequest {
  knowledge_point_id: string;  // 知识点ID
  question_bank_id: string;   // 题库ID
  created_by: string;         // 创建者标识
  type: "single_choice" | "multiple_choice" | "true_false" | "subjective";
  difficulty: "easy" | "medium" | "hard";
}

AIQuestionResponse 接口

AI 返回的题目结构。

interface AIQuestionResponse {
  title: string;
  content: string;
  options?: Record<string, string>;  // 选择题选项
  correct_answers: string[] | boolean[] | string;
  explanation: string;
}

环境变量配置

使用此 API 前需要配置以下环境变量：

# 阿里云 DashScope 配置
DASHSCOPE_BASE_URL="https://dashscope.aliyuncs.com/compatible-mode/v1"
DASHSCOPE_API_KEY="your-dashscope-api-key"
DASHSCOPE_CHAT_MODEL="qwen-max"  # 或其他支持的模型

# Supabase 配置（通常在共享模块中配置）
SUPABASE_URL="your-supabase-url"
SUPABASE_ANON_KEY="your-supabase-anon-key"

核心函数详解

validateEnvVars

功能: 验证必要的环境变量是否已配置

参数: 无

返回值: void

验证的环境变量:

DASHSCOPE_BASE_URL: DashScope API 基础URL
DASHSCOPE_API_KEY: DashScope API 密钥
DASHSCOPE_CHAT_MODEL: 使用的聊天模型

抛出错误: 当缺少任何必需的环境变量时抛出详细错误信息

validateQuestionRequest

功能: 验证题目生成请求的合法性

参数:

body: unknown - 待验证的请求体

返回值: QuestionGenerateRequest - 验证通过的请求对象

验证规则:

必填字段检查: knowledge_point_id, question_bank_id, created_by, type, difficulty
题型有效性检查: single_choice, multiple_choice, true_false, subjective
难度有效性检查: easy, medium, hard

抛出错误:

缺少必填字段时抛出详细错误信息
题型或难度无效时提供有效值列表

generateAIPrompt

功能: 根据题型和难度生成AI提示词

参数:

type: string - 题目类型
difficulty: string - 题目难度
knowledge_point_id: string - 知识点ID

返回值: string - 格式化后的AI提示词

提示词特点:

针对不同题型生成特定的提示词模板
严格要求AI返回纯JSON格式
包含知识点ID上下文信息
根据不同题型提供不同的JSON结构模板

支持的题型:

single_choice: 单选题
multiple_choice: 多选题
true_false: 判断题
subjective: 简答题

callDashScopeAPI

功能: 使用 OpenAI SDK 调用 DashScope API

参数:

prompt: string - AI提示词

返回值: Promise<AIQuestionResponse> - AI生成的题目数据

实现细节:

从环境变量获取API配置
创建OpenAI客户端（指向DashScope）
发送聊天补全请求
提取和解析返回的JSON内容
处理可能的解析错误

配置参数:

temperature: 0.7 - 控制生成随机性
max_tokens: 2000 - 最大生成长度
stream: false - 关闭流式输出

错误处理:

API调用失败时抛出错误
JSON解析失败时提供详细错误信息

formatQuestionData

功能: 格式化AI返回的题目数据为数据库存储格式

参数:

aiQuestion: AIQuestionResponse - AI返回的原始题目数据
type: string - 题目类型
questionRequest: QuestionGenerateRequest - 原始请求数据

返回值: 格式化后的题目数据对象

处理逻辑:

单选题/多选题: 处理选项和正确答案数组
判断题: 将字符串答案转换为布尔值
简答题: 处理参考答案文本格式
默认值处理: 为缺失字段提供合理的默认值

返回的数据结构:

{
  question_bank_id: string;
  type: string;
  title: string;
  content: string;
  options: Record<string, string> | null;
  correct_answers: string[] | boolean[] | string;
  explanation: string;
  difficulty: string;
  points: number;  // 默认1分
  created_by: string;
}

主处理函数

Deno.serve

功能: 处理HTTP请求的主入口点

支持的HTTP方法: POST

处理流程:

处理CORS预检请求
验证请求方法
验证环境变量
解析和验证请求体
生成AI提示词
调用DashScope API生成题目
格式化题目数据
存储到Supabase数据库
返回成功响应

使用示例

请求示例

curl -X POST https://your-domain.com/functions/v1/ai-question-generate \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_SUPABASE_TOKEN" \
  -d '{
    "knowledge_point_id": "math-algebra-001",
    "question_bank_id": "high-school-math",
    "created_by": "teacher-123",
    "type": "single_choice",
    "difficulty": "medium"
  }'

成功响应示例

{
  "success": true,
  "message": "题目生成成功",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "question_bank_id": "high-school-math",
    "type": "single_choice",
    "title": "二次函数求解",
    "content": "求函数 f(x) = x² - 4x + 3 的零点",
    "options": {
      "A": "x=1, x=3",
      "B": "x=2, x=3",
      "C": "x=1, x=4",
      "D": "x=2, x=4"
    },
    "correct_answers": ["A"],
    "explanation": "通过因式分解可得 f(x) = (x-1)(x-3)，所以零点为 x=1 和 x=3",
    "difficulty": "medium",
    "points": 1,
    "created_by": "teacher-123",
    "created_at": "2024-01-01T00:00:00.000Z"
  }
}

错误响应示例

{
  "success": false,
  "error": "缺少必要的环境变量: DASHSCOPE_API_KEY",
  "code": "ENV_VAR_MISSING"
}

错误处理

验证错误 (400)

缺少必填字段
无效的题型或难度
环境变量未配置

API 错误 (500)

DashScope API 调用失败
JSON 解析错误
数据库插入失败

错误代码

VALIDATION_ERROR: 请求验证失败
ENV_VAR_MISSING: 环境变量缺失
API_CALL_FAILED: AI API 调用失败
DB_ERROR: 数据库操作失败

题型详细说明

单选题 (single_choice)

选项格式: { "A": "选项A", "B": "选项B", ... }
正确答案: ["A"] (单个字母的数组)
适用场景: 只有一个正确答案的选择题

多选题 (multiple_choice)

选项格式: 同单选题
正确答案: ["A", "C"] (多个字母的数组)
适用场景: 有多个正确答案的选择题

判断题 (true_false)

选项格式: null (不显示选项)
正确答案: [true] 或 [false] (布尔值数组)
适用场景: 判断陈述句的真假

简答题 (subjective)

选项格式: null (不显示选项)
正确答案: "完整的参考答案文本" (字符串)
适用场景: 需要文字回答的开放性问题

性能考虑

API 调用: 单次请求调用一次 DashScope API
超时设置: 建议设置适当的超时时间（默认约30秒）
重试机制: 未内置重试，建议客户端实现
速率限制: 受 DashScope API 速率限制约束

最佳实践

前端集成

// 前端调用示例
async function generateQuestion(requestData) {
  try {
    const response = await fetch('/ai-question-generate', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'Authorization': `Bearer ${supabase.auth.getSession().access_token}`
      },
      body: JSON.stringify(requestData)
    });

    const result = await response.json();
    
    if (result.success) {
      console.log('题目生成成功:', result.data);
      return result.data;
    } else {
      console.error('题目生成失败:', result.error);
      throw new Error(result.error);
    }
  } catch (error) {
    console.error('请求失败:', error);
    throw error;
  }
}

错误处理建议

// 错误处理示例
try {
  const question = await generateQuestion(requestData);
} catch (error) {
  if (error.message.includes('环境变量')) {
    // 处理配置错误
    showAlert('系统配置错误，请联系管理员');
  } else if (error.message.includes('题型')) {
    // 处理参数错误
    showAlert('请选择有效的题型');
  } else {
    // 处理其他错误
    showAlert('题目生成失败，请重试');
  }
}

注意事项

成本控制: AI API 调用会产生费用，建议监控使用量
质量保证: AI 生成的内容需要人工审核确保准确性
版本兼容: 注意 OpenAI SDK 和 DashScope API 的版本兼容性
超时处理: 网络不稳定时可能需要调整超时设置
数据隐私: 确保传输和存储的数据符合隐私政策

版权所有

版权归属：Evoliant

许可证：MIT