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 基础URLDASHSCOPE_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