简介以Java为主、Python为辅开发的AI模型评估平台后端设计源码面向需要构建模型测试、评估与比较服务的后端开发者和算法研究人员。项目利用Java构建稳定可靠的核心后端架构Python脚本则承担数据预处理与模型评估相关算法逻辑既兼顾性能又保持灵活性。压缩包共76个文件其中Java源文件66个Python脚本2个另有Dockerfile、pom.xml、YAML、Git忽略规则等辅助文件用于容器化部署、Maven依赖管理与版本控制整体仅143KB轻量易入手。已有496人学习下载。源码完整呈现了多语言混合开发的工程组织方式从项目配置到部署说明一应俱全既可直接作为AI评估平台的后端脚手架也可作为学习Java与Python协作开发、Maven与Docker联动实践的参考范例适合中高级开发者深入研读。1. AI模型评估平台的后端到底在评估什么先说清楚一个容易混淆的点这里说的“后端设计”是服务端后端不是芯片行业里的数字后端、物理后端。常见的场景是——算法团队训了三五个检测模型准备上线需要统一跑一遍 mAP、F1、推理延迟但每个人都拿自己写的脚本评测有人用全量测试集有人只跑了 200 张图指标口径对不上开会互相甩锅。这套基于 Java 和 Python 开发的 AI 模型评估平台就是把“评估”这个动作沉淀成一个后端系统Java 负责任务调度、权限、模型资产和状态流转Python 负责加载模型、跑推理、算指标。它不是做训练而是解决“评估任务怎么提交、怎么排队、怎么复现、结果怎么让人信服”的问题。适合后端开发、算法工程师和做测试开发的人尤其是想搭一套可追溯的评测流水线、又不想从零踩坑的人。2. Java 与 Python 混合后端职责怎么切源码怎么组织2.1 Java 管状态Python 管计算这个分工边界在哪混合后端最容易翻车的不是代码写不出来而是两个语言各自该管什么没有划清楚。我见过把评测任务编排用 Python 写、把指标计算塞进 Java 的项目最后两边都在等对方的数据链路一长就没人敢动。常见的做法是Java 管“有状态的东西”——用户、角色、模型注册、数据集版本、任务状态、权限审核Python 管“吃算力的东西”——模型加载、推理、指标计算、预测结果落盘。为什么不用 Java 全栈因为 AI 生态的模型权重、推理框架、指标库基本都在 Python 一侧用 Java 重新实现一套代价极高。为什么不用 Python 全栈因为评测平台要对接企业内部的权限体系、要做任务编排和消息可靠投递这些工程化能力 Java 侧更成熟。所以技术选型不是谁好用选谁而是谁在哪个环节更省事就选谁。2.2 一张表说清模块边界谁负责提交谁负责跑分我一般把整个后端拆成六个模块边界用接口说清楚。模块语言职责关键接口或产物业务 API 层Java接收创建、查询、取消评测请求/api/v1/tasks调度层Java状态机流转、幂等控制、发送队列消息体EvalTaskMessage评测执行层Python拉取任务、加载模型、跑测试集消费队列、回调状态指标计算层Python计算准确率、mAP、推理延迟等metrics.json存储两边共用MySQL 存任务和元数据Redis 存缓存任务表、配置快照表消息队列中间件Java 和 Python 解耦RabbitMQ 或 Kafka这个切法有一个核心思想Java 侧完全不碰模型文件Python 侧完全不碰用户和权限。两边通过队列和数据库交接谁掉了都能单独重启恢复。评测任务从 API 进来后Java 只负责把“任务状态”推到 RUNNING随后把任务 ID 和路径参数发给 Python剩下的业务逻辑不再回头查库等结果——这种异步模型对长耗时任务尤其重要因为一个评测任务可能跑几十分钟HTTP 同步调用根本扛不住。2.3 源码目录怎么组织一个仓库还是两个仓库这套源码的工程组织我建议放在同一个 Git 仓库里分成两个子目录。原因很简单评测平台的前后端联调和用例回归经常要同时改 Java 和 Python分开仓库会带来版本不同步问题。一个仓库、一条 CI改完 Java 改 Python打包在一起发布版本天然对齐。eval-platform/ ├── backend-java/ │ ├── system/ # 用户、权限、审计日志 │ ├── task/ # 任务创建、状态机、调度 │ ├── model/ # 模型注册与版本管理 │ ├── dataset/ # 数据集版本管理 │ └── api/ # REST API 层对接前端 ├── backend-python/ │ ├── worker/ # 队列消费、任务执行 │ ├── evaluator/ # 各类型模型评测实现 │ ├── metrics/ # 指标计算 │ └── app/ # FastAPI 入口健康检查/回写接口 ├── deploy/ └── sql/ └── 001_schema.sqlJava 侧用 Maven 多模块Python 侧用 src 布局。这里有一个细节Java 和 Python 之间的数据结构不要靠“大家都在看同一份文档”来对齐建议把消息体定义生成到两边都能依赖的格式比如用 JSON Schema 或者 proto 文件做约束。实际项目里我吃过亏Java 发的字段叫modelIdPython 这边成了model_id对不上任务全部失败在解析字段上。后来强制统一用 snake_case在 Java 侧用JsonProperty(model_id)做映射这类问题才消停。2.4 任务状态机评测任务的四个状态和迁移规则评测任务必须有一个明确的状态机不能靠日志猜。常见的设计是四态PENDING、RUNNING、SUCCESS、FAILED再加一个 TIMEOUT 用于兜底。动作前置状态后置状态谁触发创建任务无PENDINGJava 提交接口开始执行PENDINGRUNNINGPython worker 置 RUNNING成功回传RUNNINGSUCCESSPython 写指标后回传失败回传RUNNINGFAILEDPython 捕获异常超时取消PENDING / RUNNINGTIMEOUTJava 定时任务状态迁移为什么强调“前置状态”因为评测任务可能会被重复消费如果没有前置状态校验同一个任务在故障恢复后会被两个 worker 同时跑结果写两次。我见过最典型的问题Java 端超时重试Python 端也超时重发最后数据库里同一任务出现两套 metrics。解决办法是把状态机约束落到数据库层面执行状态变更时带上前置状态条件UPDATE ... WHERE status PENDING更新行数为 0 就直接 ACK 丢弃不重复跑。3. 从任务提交到指标回传核心链路怎么做到最小可复现3.1 任务表和接口字段上线前先定协议写代码之前先把任务表字段定下来。这套后端里最关键的表叫eval_task字段不多但每个都有讲究task_id是全局唯一任务号idempotent_key是幂等键model_id、dataset_id是关联资产config_json存评测参数快照error_message存 Python 侧回传的错误堆栈。其中config_json是最容易被忽视的它必须把评测时的所有参数原样固定住——阈值、批大小、随机种子甚至显卡型号否则结果不可复现。CREATE TABLE eval_task ( task_id VARCHAR(64) PRIMARY KEY, idempotent_key VARCHAR(128) NOT NULL UNIQUE, model_id BIGINT NOT NULL, dataset_id BIGINT NOT NULL, dataset_version_hash VARCHAR(64), config_json TEXT NOT NULL, status VARCHAR(16) NOT NULL DEFAULT PENDING, error_message TEXT, create_time DATETIME NOT NULL, update_time DATETIME NOT NULL );这里UNIQUE约束是幂等处理的第一道防线。说明一下评测任务不像普通接口调用失败重发是常态没有唯一键重复提交就会产生两条任务记录。dataset_version_hash是数据集内容的 SHA-256 摘要有了它哪怕测试集文件被替换也能立刻发现。3.2 Java 端提交接口创建任务要同步返回还是异步返回评测任务跑起来要几分钟甚至几十分钟所以接口设计必须是“提交即返回”不能等推理结束。后端创建任务后立即返回task_id PENDING 状态前端拿到任务号后轮询状态或等 WebSocket 推送。RestController RequestMapping(/api/v1/tasks) public class TaskController { private final TaskService taskService; public TaskController(TaskService taskService) { this.taskService taskService; } PostMapping public ResponseEntityTaskVO createTask(RequestBody CreateTaskRequest req) { // 幂等键由调用方生成前端按钮点击时生成一次并复用 String taskId taskService.submit( req.getIdempotentKey(), req.getModelId(), req.getDatasetId(), req.getEvalConfig() ); return ResponseEntity.accepted().body(new TaskVO(taskId, PENDING)); } }调用方必须传idempotent_key否则按钮重复点击、前端超时重试时后端无法判断是不是同一操作。202 Accepted比200 OK更贴合这种异步语义。Transactional public String submit(String idempotentKey, Long modelId, Long datasetId, EvalConfig config) { // 同一幂等键重复提交直接返回已创建的任务不新建 EvalTask old taskMapper.selectByIdempotentKey(idempotentKey); if (old ! null) { return old.getTaskId(); } // 校验模型已发布、数据集已就绪避免评测跑到一半发现文件缺失 ModelInfo model modelMapper.selectByIdForUpdate(modelId); DatasetInfo dataset datasetMapper.selectByIdForUpdate(datasetId); if (model null || !PUBLISHED.equals(model.getStatus())) { throw new BizException(model not published); } if (dataset null || !READY.equals(dataset.getVersionStatus())) { throw new BizException(dataset not ready); } EvalTask task new EvalTask(); task.setTaskId(UUID.randomUUID().toString().replace(-, )); task.setIdempotentKey(idempotentKey); task.setModelId(modelId); task.setDatasetId(datasetId); task.setConfigJson(JSON.toJSONString(config)); task.setStatus(PENDING); taskMapper.insert(task); // 事务提交后再发消息避免消息发出但数据库回滚 TransactionSynchronizationManager.registerSynchronization( new TransactionSynchronization() { Override public void afterCommit() { rabbitTemplate.convertAndSend( eval.task.exchange, eval.task.routing, new EvalTaskMessage(task.getTaskId())); } }); return task.getTaskId(); }这里有两个参数值得说明。第一个是selectByIdForUpdate它是行级锁防止两个请求同时对同一个模型做更新。第二个是“事务提交后再发消息”这是分布式事务里的常见坑消息先发出去了数据库事务回滚Python worker 拿着一个不存在的任务 ID 去跑报错又查不到任务。用afterCommit把发送动作挂到事务成功之后能避免这个时序问题。3.3 Python 端评测 Worker手动 ACK 还是自动 ACKPython 侧我用 FastAPI 搭一个独立的 worker 进程启动时连接 RabbitMQ 消费任务。注意worker 不一定需要暴露 HTTP 接口真正的入口是队列消费函数FastAPI 只承担健康检查和指标查询这些辅助功能。评测主循环要手动 ACK原因在后面展开。import json import logging import traceback import pika logger logging.getLogger(eval_worker) def callback(ch, method, properties, body): msg json.loads(body) task_id msg[task_id] logger.info(receive eval task: %s, task_id) # 将任务从 PENDING 置为 RUNNING若更新失败说明任务已被消费直接丢弃 if not mark_running(task_id): logger.warning(task is not PENDING, skip: %s, task_id) ch.basic_ack(delivery_tagmethod.delivery_tag) return try: model_path get_model_path(task_id) dataset_path get_dataset_path(task_id) # 模型在进程内只加载一次后续评测任务复用避免反复加载权重 model ModelHolder.get(model_path) metrics run_eval(model, dataset_path, task_id) save_metrics(task_id, metrics) finish_task(task_id, SUCCESS, metrics) except Exception: # noqa: BLE001 logger.exception(eval failed for task %s, task_id) fail_task(task_id, traceback.format_exc()) finally: # 无论成功失败都 ACK失败信息已写库不触发无限重试 ch.basic_ack(delivery_tagmethod.delivery_tag) def main(): connection pika.BlockingConnection( pika.ConnectionParameters(host127.0.0.1)) channel connection.channel() channel.queue_declare(eval.task.queue, durableTrue) # 一个 worker 同时只处理一个任务防止多任务并发导致显存溢出 channel.basic_qos(prefetch_count1) channel.basic_consume(eval.task.queue, callback, auto_ackFalse) channel.start_consuming()这段代码里有三个点必须说透。第一mark_running内部执行的是UPDATE eval_task SET statusRUNNING WHERE task_id%s AND statusPENDING这就是状态机在 Python 侧的落点防止重复消费。第二auto_ackFalse配合basic_ack确保 worker 在处理中途崩溃时消息不会丢失RabbitMQ 会把它重新投递。第三prefetch_count1很关键评测任务吃的不是普通 IO 而是显存和内存如果 prefetch 设成 10一个 worker 同时加载 10 个模型机器直接 OOM。3.4 指标回传与前端对接跨域和重复提交怎么兜底Python 算完指标后写入 MySQLJava 端提供一个查询接口供前端轮询。这里要处理前后端分离环境下两个高频问题跨域和按钮重复提交。Vue3 前端和后端不在同一个端口的场景很常见Java 侧可以用全局 CORS 配置放开本地调试。Configuration public class CorsConfig implements WebMvcConfigurer { Override public void addCorsMappings(CorsRegistry registry) { registry.addMapping(/api/**) .allowedOriginPatterns(http://localhost:*) .allowedMethods(GET, POST, PUT, DELETE) .allowedHeaders(*) .maxAge(3600); } }allowedOriginPatterns比allowedOrigins(*)安全它允许携带 Cookie 的同时不会把接口开放给所有站点。生产环境记得把它收敛成具体域名。按钮重复提交校验要前后端一起做。前端在提交按钮点击后立即置灰这是体验层兜底真正的防线在后端idempotent_key唯一索引。只要前端生成一次幂等键后面不管因为网络超时重发了三次后端都返回同一个task_id。这个方案比单纯的“短时间内禁止重复请求”可靠因为幂等键语义是“这是同一操作”而时间窗口可能出现误杀用户隔了两秒正常提交第二次也被拦掉。4. Java 和 Python 之间的通信层队列参数、ACK 与版本锁定4.1 同步 HTTP 还是异步消息队列评测任务能不能用 Java 直接 HTTP 调用 Python能但只适合内部快速 demo。评估一个模型动辄几分钟HTTP 同步调用需要客户端一直保持连接网关超时、连接中断都会让任务状态不可知。更关键的是并发控制如果五个评测任务同时发到 PythonPython 进程的显存和内存瞬间爆炸。用消息队列之后队列本身就充当了缓冲池worker 的消费速度就是任务的执行速度天然限流。对比项HTTP 同步调用消息队列超时控制难网关层容易断消息持久化worker 恢复后继续并发限制需额外做信号量prefetch_count直接控制故障恢复调用方重试逻辑复杂未 ACK 消息自动重投任务追踪连接即生命周期任务 ID 贯穿队列和状态表4.2 RabbitMQ 关键参数手动 ACK、prefetch、死信队列队列参数是这套后端最容易“跑起来能用、一压测就挂”的地方。我一般按下表设初值。参数推荐值说明auto_ackFalse处理完成后手动 ACK崩溃可重投prefetch_count1单 worker 同时只处理一个任务队列durabletrueRabbitMQ 重启后队列不丢消息delivery_mode2消息持久化到磁盘死信队列eval.task.dlq重试超限或异常任务进死信Java 发送超时3000ms发送失败快速失败并告警手动 ACK 的“手动”是双向的成功要 ACK失败也要 ACK。这一点很多人想不通——失败为什么不把消息放回去重试因为评测失败的原因大概率是代码逻辑或数据问题立刻重试十次也是同样的失败还会把错误日志刷屏。正确做法是失败时把 traceback 写进error_message然后 ACK 掉这条消息让任务进入 FAILED 状态由人工或者定时任务决定要不要重跑。如果消息本身是环境抖动造成的比如数据库连接断了几秒那应该由 Java 端定时扫描把 FAILED 任务重新置回 PENDING 重投而不是让 MQ 不停重试。4.3 模型和数据集怎么传路径传递与版本锁定评测任务的消息体里不能塞文件内容只能传“资产 ID 路径”。模型权重和测试集通常存在 NFS 或对象存储上Java 创建任务时把model_path和dataset_path解析好写进配置Python worker 按照路径去本地挂载点读取。def get_dataset_path(task_id: str) - str: cfg load_task_config(task_id) return cfg[dataset_path]路径传递有一个隐藏很深的坑Windows 和 Linux 路径分隔符不一致。如果有人在 Windows 上手工插入了一条评测任务路径写成E:\data\eval_set\Python 挂在 Linux 上读会直接 FileNotFoundError。我一般在 Java 侧统一把路径标准化为/分隔并在写入数据库前做一次合法性检查。另一个坑是路径中带空格尤其数据集目录名是中文或带日期的文件夹比如数据集 v2-0715消息体如果按空格拆分就会取错路径。所以消息协议用 JSON不要自己拼接字符串拼接出来的协议迟早被特殊字符干趴。数据集版本锁定用哈希最稳妥。每次注册数据集时计算目录内所有文件的 SHA-256任务提交时把这个哈希写进eval_task表。评测结束后核对当前目录哈希和任务记录是否一致不一致就标记结果不可信。import hashlib def compute_dir_hash(data_dir: str) - str: sha hashlib.sha256() for f in sorted(Path(data_dir).rglob(*)): if f.is_file(): sha.update(f.name.encode(utf-8)) with f.open(rb) as fh: for chunk in iter(lambda: fh.read(65536), b): sha.update(chunk) return sha.hexdigest()4.4 失败补偿机制谁负责把队列消息重新投喂评测任务的全链路故障点很多Java 发送后进程崩溃、RabbitMQ 节点重启、Python worker 被 OOM Killer 杀掉。我的做法是Java 端起一个TaskRecoverScheduler每 30 秒扫描一次任务表把“长时间停在 RUNNING 但心跳已过期”的任务重置为 PENDING 并重新投递到队列。Component public class TaskRecoverScheduler { Scheduled(fixedDelay 30000) public void recoverTimeoutTasks() { // 只处理 RUNNING 且心跳时间距今超过 10 分钟的任务 ListEvalTask stuckTasks taskMapper.selectRunningTimeout(10); for (EvalTask task : stuckTasks) { taskMapper.resetToPending(task.getTaskId()); rabbitTemplate.convertAndSend( eval.task.exchange, eval.task.routing, new EvalTaskMessage(task.getTaskId())); } } }这里要配套一个心跳机制Python worker 每 15 秒把当前任务的心跳时间写一次 Redis 或数据库。如果 worker 直接被系统杀掉心跳就停掉调度器才能识别出“这个任务卡死了”。注意重置之前要确认评测进程真的死了否则会出现两个 worker 跑同一个任务的并发问题。常见做法是worker 启动时把自己的 PID 写进任务表调度器重置前先检查 PID 是否还存活活着的就等下一轮确认死了才重置。5. 避坑混合评测后端最常见的 5 个翻车点5.1 Java 看到的 Python 异常是黑匣子现象任务状态直接 FAILEDJava 日志里只有一句“Python process exited with code 1”具体哪行代码报错完全看不到。原因Java 只捕获了子进程的退出码Python 的 traceback 打到了自己的 stdoutJava 没有读取。解决Python 端在except里把traceback.format_exc()写入数据库error_message同时按 task_id 打日志到统一采集系统。排查时打开任务详情页直接看原始异常不用再登录 worker 机器翻日志。5.2 连续提评测任务导致 Python 进程被 OOM现象队列同时来了四五个任务每从 PENDING 切到 RUNNING跑了不到一半Worker 机器负载飙升部分任务失败日志出现“Killed”。原因prefetch_count没设或设太大一个 Python 进程同时加载了多个模型权重显存或内存被打满。解决把prefetch_count调成 1并在 worker 启动时检查 GPU 显存余量不足 20% 直接拒绝拉取新任务。这不是玄学评测任务不是短接口每个都占独立推理资源必须一个一个来。5.3 同一个模型两次评测指标对不上现象昨天跑 mAP 是 0.82今天跑变成 0.78代码没改数据没动。原因评测配置里的置信度阈值、NMS 阈值或随机种子不一致或者测集文件在某次同步时被覆盖了。解决所有评测配置在任务创建时做 JSON 快照不再从当前模型配置读取数据侧重算目录哈希存进任务表跑完核对哈希。我后来还在报告里加了 Git commit id 和 Python 依赖包版本号结果变得随时可复核。5.4 Java 重试和 Python 回传叠加任务跑了两遍现象网络抖动导致 Python 指标回传超时Java 端判定失败并重新投递但原任务其实已经跑完最终同一任务 ID 出现两份指标记录。原因状态机前置条件没有起作用重投前没有检查任务是否已经结束。解决任何重投动作都要执行UPDATE eval_task SET statusPENDING WHERE task_id? AND status ! SUCCESS如果更新行数为 0说明任务已成功直接丢弃重投消息。这个兜底就是状态机的价值。5.5 任务超时时间设置不科学现象大模型评测偶尔要跑 40 分钟超时时间定了 30 分钟任务还没跑完就被强制置为 TIMEOUT。原因超时参数是拍脑袋定的没有按模型规模和测试集大小做预估值。解决把超时时间拆成“提交配置里显式指定”的字段Java 创建任务时根据评测类型给默认值比如图像分类默认 20 分钟、大语言模型默认 4 小时。超时阈值要写入配置快照不能用全局默认值不同任务差异太大。6. 验证与进阶一台机器跑通闭环再谈结果可复现6.1 单机启动的最小流程本地验证尽量用 Docker Compose 把 MySQL 和 RabbitMQ 拉起来然后前后台分别启动 Java 和 Python 服务。我不想在部署步骤上浪费时间一个跑通判断标准是提交一个评测任务状态能从 PENDING 走到 SUCCESS并且指标表里有数据。# 组件容器编排由 deploy/docker-compose.yml 完成 docker compose up -d mysql rabbitmq cd backend-java mvn spring-boot:run cd ../backend-python uvicorn app.main:app --port 80016.2 用一个结果可预测的假模型验证链路刚搭好的平台不要直接拿真实模型跑先用假模型。比如写一个“输入长度偶数返回 0奇数返回 1”的固定规则构造 10 条样本手算出期望准确率提交任务后对比报告。这个验证的意义是链路通不通和模型强不强是两回事假模型能把平台逻辑的误差排除掉。class FakeModel: 固定输出模型用于评测链路自测。 def predict(self, x): return 0 if len(x) % 4 0 else 16.3 按任务 ID 贯穿日志排查不靠猜评测任务排错时最怕“Java 说发出去Python 说没收到”。我的习惯是Java 和 Python 的日志都把task_id放进结构化字段日志采集系统里直接按task_id搜索一条链路从提交、入队、消费到出报告时间线完整拉出来。Python 日志格式显式加上task_id是这套后端维护成本最低的配置。我自己第一次搭评测平台时只把“模型路径 测试集坐标 跑出的数字”存下来一个月后同事拿着截图来问为什么复现不了我只能认栽。后来把配置快照、数据集哈希、代码版本号一起写进报告才让评测结果不再是黑匣子。这个习惯现在成了我的默认要求——跑分不可复现等于没跑。希望帮到你。本文还有配套的精品资源点击获取