模多多教育版

Appearance

作业批改 AI 建议（文本/代码/图片/混合） ​

本功能在不改变对外接口的前提下，复用 ai_intent 的模型通道，为作业提交生成结构化的“批改建议”。支持文本类（代码、人文、常识、解题回答）与图片类内容，并严格参考 assignment 的名称与描述进行判断与输出。

能力概览 ​

  • 多模态支持: 自动检测提交内容是否包含文本/代码/图片或混合，图片以 URL 形式传入多模态模型。
  • 对齐要求: 先从 assignment 名称和描述中抽取关键要求，再据此评分与建议。
  • 统一结构化输出: 返回统一 JSON，包括总分、各维度得分、与作业要求的匹配度、缺失点、可执行改进建议等。
  • 稳健性: 强制 JSON 输出，提供 JSON 解析兜底，失败时返回可空字段的统一结构。

关键代码位置 ​

  • 服务编排: app/services/assignment_service.py 中 AssignmentService.generate_ai_suggestions
  • Pydantic 模型: app/schemas/assignment.py 中 AIAssignmentGradingSuggestion 及相关子模型
  • 配置项: app/core/config.py 中 AI_INTENT_BASE_URL、AI_INTENT_KEY、AI_INTENT_MODEL、AI_REQUEST_TIMEOUT

环境配置 ​

确保以下变量配置正确（可通过 .env 或环境变量）：

  • AI_INTENT_BASE_URL（默认 https://www.moduoduo.pro）
  • AI_INTENT_KEY
  • AI_INTENT_MODEL（默认 claude-sonnet-4-20250514）
  • AI_REQUEST_TIMEOUT（默认 600 秒）

调用方式（内部） ​

服务层调用示例（伪代码）：

python
svc = AssignmentService(db)
suggestions = await svc.generate_ai_suggestions(assignment_id=1, user_id=10001)

行为说明：

  • 从数据库获取 assignment 与该用户的 submission。
  • 自动识别 content_type：text | code | image | mixed。
  • 组装多模态消息（文本/图片 URL），调用 ai_intent 的 /v1/chat/completions。
  • 解析返回内容为严格 JSON；失败时进行轻量兜底（正则提取首个 JSON）。
  • 将解析结果写回 assignment_submissions.ai_suggestions 并返回。

输出结构（Schema） ​

位置：app/schemas/assignment.py

python
class RubricItem(BaseModel):
    score: float | None = None
    max: float | None = None
    reason: str | None = None

class AssignmentAlignment(BaseModel):
    title_match: float | None = None
    description_coverage: float | None = None
    missing_requirements: list[str] = []

class AIAssignmentGradingSuggestion(BaseModel):
    score: float | None = None
    rubric_scores: dict[str, RubricItem] | None = None
    assignment_alignment: AssignmentAlignment | None = None
    key_findings: list[str] = []
    actionable_suggestions: list[str] = []
    confidence: float | None = None
    extracted_summary_from_images: str | None = None

注意：服务层对返回 JSON 进行弱约束解析。若模型输出字段缺失，服务层会回退到包含空字段的统一结构，以保证接口稳定性。

提示词要点（内置） ​

  • 角色要求：严格依据 assignment 名称与描述进行评判。
  • 先抽取“关键要求清单”，再进行评分与建议。
  • 类型分支：code 关注正确性/边界/复杂度；text 关注论证/结构；image 先识别文字或关键信息再评分；mixed 同时处理。
  • 强制 JSON 输出：服务端设置 response_format={"type": "json_object"} 并在 developer 提示中附带 Schema。

失败与兜底策略 ​

  • 网络/鉴权失败：返回空结构（各字段 None 或空数组），并不中断调用链。
  • 模型返回非 JSON：做一次正则提取 { ... } 的尝试，仍失败则返回空结构。
  • 图片过多或过大：建议在调用前对图片数量与分辨率做限制（上线可按业务需求补充）。

前端集成建议 ​

  • 展示 rubric 各维度得分与理由；
  • 将 assignment_alignment.missing_requirements 和 actionable_suggestions 以高亮/列表展示；
  • 若为图片类作业，展示 extracted_summary_from_images；
  • 允许教师一键“采纳建议”（更新 ai_adopted）或手动编辑后保存。

常见问题 ​

  1. 无 AI 建议返回？

    • 检查 AI_INTENT_KEY 是否配置；
    • 查看网络出站与目标域名连通；
    • 检查 assignment 与 submission 是否存在且内容非空。

  2. 字段缺失或类型不匹配？

    • 属模型输出差异，服务层已有兜底，建议在 UI 层做空值兼容渲染。