Skip to content

API.md

Latest commit

 

History

History
356 lines (291 loc) · 6.67 KB

API.md

File metadata and controls

356 lines (291 loc) · 6.67 KB

EduAdmin 主观题自动化评估系统 API 文档

概述

本文档描述了EduAdmin主观题自动化评估系统的API接口。系统采用微服务架构，包含以下服务：

  • eval-service: Python + FastAPI 微服务（NLP 计算）
  • go-backend: Go 后端服务（业务逻辑）
  • frontend: Vue.js 前端（管理端和学员端）

服务地址

eval-service API

1. 健康检查

GET /health

响应:

{
  "status": "healthy",
  "service": "eval-service",
  "version": "1.0.0"
}

2. 主观题评估

POST /api/v1/evaluate

请求体:

{
  "question_id": "string",
  "reference_answer": "string",
  "student_answer": "string",
  "language": "zh|en|uk|...|auto",
  "human_score": null
}

响应:

{
  "final_score": 85.5,
  "semantic_score": 0.8234,
  "keyterm_score": 78.0,
  "coherence_score": 0.7567,
  "hit_keywords": {
    "core": ["人工智能", "机器学习"],
    "related": ["算法", "数据"],
    "aux": ["技术", "应用"]
  },
  "explanations": {
    "summary": "总分85.5分（良好）：答案质量较好，基本符合要求",
    "notes": [
      "语义理解基本正确，与参考答案较为一致",
      "关键词覆盖较好，主要要点已包含",
      "表达基本连贯，逻辑较为清晰"
    ]
  },
  "artifacts": {
    "heatmap_url": null,
    "word_cloud_url": null,
    "keyword_analysis": {
      "total_keywords": 5,
      "core_count": 2,
      "related_count": 2,
      "aux_count": 1
    }
  }
}

3. 提交反馈

POST /api/v1/feedback

请求体:

{
  "question_id": "string",
  "user_id": "string",
  "human_score": 88.0,
  "system_score": 85.0
}

响应:

{
  "success": true,
  "message": "反馈已成功提交，权重已更新",
  "updated_weights": {
    "semantic": 0.6,
    "keyterm": 0.3,
    "coherence": 0.1
  }
}

go-backend API

1. 健康检查

GET /health

2. 考试相关

提交考试

POST /api/v1/exam/submit

请求体:

{
  "paper_id": "string",
  "user_id": "string",
  "answers": {
    "question_1": "answer_1",
    "question_2": "answer_2"
  },
  "subjective_questions": {
    "subjective_1": "学生的主观题答案",
    "subjective_2": "另一道主观题答案"
  }
}

获取考试结果

GET /api/v1/exam/result/{paperId}/{userId}

3. 主观题相关

评估主观题

POST /api/v1/subjective/evaluate

获取评估结果

GET /api/v1/subjective/result/{questionId}/{userId}

提交反馈

POST /api/v1/subjective/feedback

4. 教师端API

获取教师评分

GET /api/v1/teacher/scores/{paperId}

响应:

{
  "paper_id": "paper_001",
  "scores": [
    {
      "paper_id": "paper_001",
      "question_id": "question_001",
      "user_id": "user_001",
      "student_name": "张三",
      "final_score": 85.5,
      "semantic_score": 0.8234,
      "keyterm_score": 78.0,
      "coherence_score": 0.7567,
      "hit_keywords": {
        "core": ["人工智能", "机器学习"],
        "related": ["算法", "数据"],
        "aux": ["技术", "应用"]
      },
      "explanations": {
        "summary": "总分85.5分（良好）：答案质量较好，基本符合要求",
        "notes": ["语义理解基本正确", "关键词覆盖较好"]
      },
      "can_override": true,
      "created_at": "2024-01-15T14:30:25Z"
    }
  ],
  "total": 1
}

覆盖系统评分

POST /api/v1/teacher/override-score

请求体:

{
  "paper_id": "string",
  "question_id": "string",
  "user_id": "string",
  "new_score": 88.0
}

5. 学生端API

获取学生评分

GET /api/v1/student/scores/{paperId}/{userId}

响应:

{
  "paper_id": "paper_001",
  "user_id": "user_001",
  "scores": [
    {
      "paper_id": "paper_001",
      "question_id": "question_001",
      "final_score": 85.5,
      "hit_keywords": {
        "core": ["人工智能", "机器学习"],
        "related": ["算法", "数据"],
        "aux": ["技术", "应用"]
      },
      "explanations": {
        "summary": "总分85.5分（良好）：答案质量较好，基本符合要求",
        "notes": ["语义理解基本正确", "关键词覆盖较好"]
      },
      "created_at": "2024-01-15T14:30:25Z"
    }
  ],
  "total": 1
}

错误处理

所有API都遵循统一的错误响应格式：

{
  "error": "错误描述",
  "details": "详细错误信息"
}

常见HTTP状态码：

  • 200: 成功
  • 400: 请求参数错误
  • 404: 资源不存在
  • 422: 数据验证错误
  • 500: 服务器内部错误

认证

目前系统未实现认证机制，在生产环境中应该添加适当的认证和授权。

限流

建议在生产环境中添加API限流机制，防止滥用。

监控

系统提供健康检查接口，可用于监控服务状态。

示例代码

Python 客户端示例

import requests

# 评估主观题
def evaluate_subjective(question_id, reference_answer, student_answer, language="zh"):
    url = "http://localhost:8000/api/v1/evaluate"
    data = {
        "question_id": question_id,
        "reference_answer": reference_answer,
        "student_answer": student_answer,
        "language": language
    }
    response = requests.post(url, json=data)
    return response.json()

# 使用示例
result = evaluate_subjective(
    question_id="q001",
    reference_answer="人工智能是计算机科学的一个分支。",
    student_answer="AI是让机器智能的技术。"
)
print(f"最终得分: {result['final_score']}")

JavaScript 客户端示例

// 评估主观题
async function evaluateSubjective(questionId, referenceAnswer, studentAnswer, language = 'zh') {
  const response = await fetch('http://localhost:8000/api/v1/evaluate', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      question_id: questionId,
      reference_answer: referenceAnswer,
      student_answer: studentAnswer,
      language: language
    })
  });
  
  return await response.json();
}

// 使用示例
const result = await evaluateSubjective(
  'q001',
  '人工智能是计算机科学的一个分支。',
  'AI是让机器智能的技术。'
);
console.log(`最终得分: ${result.final_score}`);

更新日志

v1.0.0 (2024-01-15)

  • 初始版本发布
  • 实现BCHS + REWT + CAMF算法
  • 支持中英文评估
  • 提供完整的REST API
  • 集成前后端界面