Skip to content

Agent 接口清单 ​

这一页是 ruoyi-exam-agent(Python,端口 9221)的接口清单。

这些接口不经过网关

Agent 监听 9221,不注册到 Spring Cloud Gateway,不直接对外暴露。 正常业务链路里它由 ruoyi-exam-ai(9220)调用。

这一页主要用于调试、排查与二次集成。 对外(前端)可用的 AI 接口见 AI 接口。

通用约定 ​

项值
Base URLhttp://<agent-host>:9221
接口前缀/api/ai
数据格式application/json
统一返回体{"code": 200, "msg": "success", "data": {...}}
HTTP 状态码恒为 200,业务错误体现在 code 里

业务码:200 成功、400 参数错、401 未授权、403 禁止、404 未找到、 500 内部错误、503 AI 不可用。

/health 不包 R<T>

/health 与 /ping 返回裸结构,因为 Nacos 与 Docker HEALTHCHECK 要直接读 status 字段。

健康检查 ​

方法路径说明
GET/health完整状态(也挂了 /api/ai/health)
GET/ping{"pong": true},不查任何依赖

/health 返回:

json
{
  "status": "UP",
  "service": "ruoyi-exam-agent",
  "version": "1.0.0",
  "nacos":  {"enabled": true, "server": "127.0.0.1:8848", "registered": true, ...},
  "skills": 17,
  "prompts": 22,
  "rag":    {"enabled": false, "doc_count": 0, "chunk_count": 0, "term_count": 0},
  "model":  {"failover_enabled": true, "config_source": "mysql,env", "circuit": {}, ...},
  "call":   {"total": 128, "failed": 3, "switched": 5, "success_rate": 0.977}
}

排查故障时先看这个。

出题 ​

前缀 /api/ai/question

方法路径说明
POST/api/ai/question/generate生成试题(with_audit=true 时带质检)
POST/api/ai/question/generate-audit生成 + 逐题质检,返回 accepted / rejected
POST/api/ai/question/rewrite试题改写扩量
POST/api/ai/question/distractor生成干扰项
POST/api/ai/question/tag知识点打标
POST/api/ai/question/analysis生成解析

generate ​

请求:

json
{
  "knowledge_points": ["TCP/IP", "三次握手"],
  "difficulty": "medium",
  "question_type": "SINGLE",
  "count": 5,
  "score": 5,
  "material_key": "",
  "tenant_id": "000000",
  "with_audit": false,
  "extra": { "language": "zh" }
}

响应 data:

json
{
  "questions": [
    {
      "question_type": "SINGLE",
      "stem": "TCP 三次握手的第二步是?",
      "options": [{"key": "A", "content": "..."}],
      "answer": "{\"rightKeys\":[\"B\"]}",
      "analysis": "...",
      "knowledge_points": ["TCP/IP"],
      "difficulty": "medium",
      "score": 5
    }
  ],
  "count": 5,
  "model": "deepseek-chat",
  "attempt_chain": "DeepSeek",
  "prompt_version": "v1",
  "latency_ms": 8420,
  "trace_id": "a1b2c3d4e5f6"
}

count 取值 1~30。

generate-audit ​

多了两个数组:audits(逐题质检结果)与 rejected(未通过质检的题,含 index 与 audit)。

判定:passed 且 quality_score >= 6(reflection_min_score 0.6 × 10)。

阅卷 ​

前缀 /api/ai/grade

方法路径说明
POST/api/ai/grade/auto批量评分
POST/api/ai/grade/single单题评分(?tenant_id=)

auto ​

请求:

json
{
  "paper_id": "", "answer_sheet_id": "", "record_id": "",
  "tenant_id": "000000",
  "reflection": false,
  "max_parallel": 4,
  "items": [
    {
      "question_id": "1900000000000000001",
      "item_id": "1900000000000000002",
      "question_type": "SHORT_ANSWER",
      "stem": "简述 TCP 三次握手",
      "reference_answer": "SYN -> SYN-ACK -> ACK",
      "rubric": ["提到 SYN", "提到 SYN-ACK", "提到 ACK"],
      "student_answer": "客户端发 SYN,服务端回 SYN-ACK,客户端再发 ACK",
      "full_score": 10,
      "analysis": "",
      "anchor_high": "", "anchor_low": ""
    }
  ]
}

响应 data:

json
{
  "total": 1, "failed": 0, "need_human_count": 0,
  "confidence_floor": 0.6,
  "reflection": false,
  "results": [
    {
      "question_id": "...", "item_id": "...", "ok": true,
      "score": 8.5, "full_score": 10, "confidence": 0.88,
      "matched_points": [{"point": "提到 SYN", "got": true, "score": 3}],
      "reason": "...", "comment": "...",
      "need_human": false,
      "model": "deepseek-chat", "prompt_version": "v1",
      "trace_id": "...", "latency_ms": 6200
    }
  ],
  "hint": "score 为 AI 建议分,最终分必须由教师确认"
}

hint 字段不是装饰

score 是建议分。need_human=true 的结果不能自动落分。 Java 侧 ruoyi-exam-mark 的判据是置信度 < 0.6。

reflection=true 时每条结果额外带 reflection:{accepted, adjusted_score, score_quality, issues, comment}; accepted=false → need_human=true 且 score 用 adjusted_score。

max_parallel 取值 1~16。

学情 ​

前缀 /api/ai/recommend

方法路径说明
POST/api/ai/recommend/wrong按错题推题
POST/api/ai/recommend/diagnose错题归因(可带推题)
GET/api/ai/recommend/profile/{user_id}长期学情画像(?tenant_id=)

/diagnose 会把 weak_points 与 priority 写入长期记忆,供后续推题使用。 target_count 取值 1~10。

试卷 ​

前缀 /api/ai/paper

方法路径说明
POST/api/ai/paper/analyze试卷审查(知识点覆盖/难度分布/重复度/用时)
POST/api/ai/paper/review同上(别名)
POST/api/ai/paper/difficulty难度预估(平均分、通过率、分布)

请求体 PaperAnalyzeRequest:paper_id、title、duration(60)、pass_score(60)、 total_score(100)、questions[]、tenant_id、focus(全面审查)、extra。

监考 ​

前缀 /api/ai/proctor

方法路径说明
POST/api/ai/proctor/analyze监考行为分析

with_report=true 时额外走 report_write 生成自然语言报告(audience="监考员")。

返回值里 need_human 恒为 true

代码强制置位,不允许模型自己说「不需要人工」。 作弊认定必须由人来做。

Skill 通用入口 ​

前缀 /api/ai/skill

方法路径说明
GET/api/ai/skill/list17 个技能清单(含入参 JSON Schema)
GET/api/ai/skill/{code}单个技能详情
POST/api/ai/skill/{code}/run执行单个技能
POST/api/ai/skill/{code}/batch批量执行

run ​

bash
curl -X POST http://127.0.0.1:9221/api/ai/skill/mark_score/run \
  -H "Content-Type: application/json" \
  -d '{"tenant_id":"000000","input":{"stem":"...","full_score":10,
       "standard_answer":"...","answer_text":"..."}}'

响应:{skill, version, data, need_human, model, attempt_chain, latency_ms, prompt_version, trace_id}

batch ​

json
{
  "tenant_id": "000000",
  "items": [{"input": {...}}, {"input": {...}}],
  "max_parallel": 4,
  "skip_error": true
}

结果按 index 排序

并发执行不保证顺序,每条结果带 index。 Java 侧 judgeMarkBatch 会按 index 还原成入参顺序。

Tool 工具 ​

前缀 /api/ai/tool

方法路径说明
GET/api/ai/tool/list工具清单 + 护栏策略
GET/api/ai/tool/guardrail护栏策略
POST/api/ai/tool/{code}/invoke调用工具(approved 开关)
json
{"tenant_id":"000000","payload":{...},"approved":false}

护栏拦截时返回 {ok:false, blocked:true, error:"..."} 而不是抛异常。

Agent 编排 ​

前缀 /api/ai/agent

方法路径说明
GET/api/ai/agent/plan/list5 套预置计划
POST/api/ai/agent/plan/{task_type}/run执行计划
POST/api/ai/agent/orchestrate/pipeline串行流水线
POST/api/ai/agent/orchestrate/vote并行投票(阅卷双评)
POST/api/ai/agent/orchestrate/panel并行专家组
POST/api/ai/agent/reflectCritic 自检(kind=question|score)
POST/api/ai/agent/generate-and-audit生成 + 质检组合拳

vote 需要至少 2 个 skill,返回 agreed_score、max_gap、need_arbitration。

对话 ​

前缀 /api/ai/chat

方法路径说明
POST/api/ai/chat对话主入口
POST/api/ai/chat/reset清除会话
GET/api/ai/chat/sessions会话列表(?tenant_id=&user_id=&limit=30)
GET/api/ai/chat/session/{session_id}会话详情

请求 ChatIn:session_id、message、answers、tenant_id、user_id、 model_code、token、client_id、identity、options。

响应 ChatResult:session_id、reply(Markdown)、trace[]、ask(追问卡)、intent、data。

会话列表只带摘要,详情才带全量消息——避免一次拉回几十个会话的完整聊天记录。

模型网关 ​

前缀 /api/ai/model

方法路径说明
GET/api/ai/model/list模型清单(密钥脱敏)
GET/api/ai/model/health熔断状态与配置源
POST/api/ai/model/reload重新加载配置(热更新)
POST/api/ai/model/circuit/reset复位熔断(model_code 为空则全部)
GET/api/ai/model/call-log调用流水(?limit=50,1~500)

RAG ​

前缀 /api/ai/rag

方法路径说明
POST/api/ai/rag/ingest灌入文档(切片 + 建索引)
POST/api/ai/rag/retrieve检索(top_k 1~20)
GET/api/ai/rag/stats索引统计
POST/api/ai/rag/enable运行时开关(?flag=true)

一期用 BM25 关键词检索(内存倒排),不需要向量库, 所以 requirements-rag.txt(chromadb + sentence-transformers)不用装。

AGENT_RAG_ENABLED 默认 False。

端点总数 ​

health 2(各双路径)+ question 6 + grade 2 + recommend 3 + paper 3 + proctor 1 + skill 4 + tool 3 + agent 7 + chat 4 + model 5 + rag 4 = 44 个逻辑端点。

相关文档 ​

砚考 · 让每一次考试都经得起检验