my_ml_service 机器学习 REST API 完整参考清单：7 个接口、参数与响应字段一次讲透

my_ml_service 机器学习 REST API 完整参考清单：7 个接口、参数与响应字段一次讲透

【免费下载链接】my_ml_serviceMy Machine Learning Web Service项目地址: https://gitcode.com/gh_mirrors/my/my_ml_service

my_ml_service 是一个基于 Django + Django REST Framework 的机器学习模型 Web 服务，通过 REST API 对外提供模型预测、版本管理、请求审计和 A/B 测试能力。本文是它的完整接口参考清单：所有 URL、查询参数、请求体字段和响应字段一网打尽，帮你快速集成自己的 ML 服务。

一、接口总览：一张表看懂全部 API

所有接口统一挂载在/api/v1/前缀下，路由定义见 urls.py。注意该服务使用了trailing_slash=False，接口路径不带末尾斜杠。

方法	路径	功能
GET	/api/v1/endpoints	列出所有 ML 端点
GET	/api/v1/endpoints/{id}	获取端点详情
GET	/api/v1/mlalgorithms	列出所有 ML 算法
GET	/api/v1/mlalgorithms/{id}	获取算法详情
GET / POST	/api/v1/mlalgorithmstatuses	查询/创建算法状态
GET / PUT / PATCH	/api/v1/mlrequests	查询请求记录 / 提交反馈
GET / POST / PUT / PATCH	/api/v1/abtests	A/B 测试的查询与创建
POST	/api/v1/{endpoint_name}/predict	⭐ 模型预测（核心接口）
POST	/api/v1/stop_ab_test/{ab_test_id}	结束 A/B 测试并结算胜者

二、模型预测接口：如何调用 ML 预测 REST API

请求：POST /api/v1/income_classifier/predict，请求体为 JSON（实现见 views.py 中的PredictView，约 L74-L115）。

2.1 查询参数一览

参数	必填	默认值	说明
status	否	production	算法状态，可选production/testing/staging/ab_testing
version	否	—	指定算法版本号；当同状态存在多个版本时必须指定

2.2 请求体字段（Adult-Income 数据集，14 个特征）

字段	类型	示例
age	数字	37
workclass	字符串	"Private"
fnlwgt	数字	34146
education	字符串	"HS-grad"
education-num	数字	9
marital-status	字符串	"Married-civ-spouse"
occupation	字符串	"Craft-repair"
relationship	字符串	"Husband"
race	字符串	"White"
sex	字符串	"Male"
capital-gain	数字	0
capital-loss	数字	0
hours-per-week	数字	68
native-country	字符串	"United-States"

2.3 响应字段

成功时（HTTP 200）：

字段	说明
status	固定为"OK"
label	预测标签：">50K"或"<="50K"
probability	预测为正类的概率值
request_id	本次请求的审计记录 ID（用于后续反馈）

失败时（HTTP 400）返回{"status": "Error", "message": "..."}，常见原因有两条：

• ML algorithm is not available：该端点下没有匹配status且处于激活状态的算法；
• ML algorithm selection is ambiguous：同状态存在多个版本算法，请在查询参数中指定version。

💡 每次预测都会被自动落库为一条MLRequest记录，这是后续审计与 A/B 测试结算的数据基础。

三、端点与算法管理接口：查询参数与响应字段

3.1 列出端点 / 算法（只读）

GET /api/v1/endpoints与GET /api/v1/mlalgorithms均为只读列表 + 按 ID 查询接口，无额外查询参数。响应字段（见 serializers.py）：

• Endpoint：id、name（预测 URL 中的端点名）、owner、created_at
• MLAlgorithm：id、name、description、code（算法源码）、version、owner、created_at、parent_endpoint、current_status（自动计算的当前最新状态）

3.2 创建算法状态：POST /api/v1/mlalgorithmstatuses

请求体字段：status（testing/staging/production/ab_testing）、created_by、parent_mlalgorithm（算法 ID）。id与active为只读字段。

🔑 关键行为：创建后新状态自动置为active=True，同算法的旧状态会被批量置为失效（原子事务完成），保证每个算法任一时刻只有一个生效状态。

四、请求审计接口：如何查看与反馈预测记录

GET /api/v1/mlrequests返回所有历史预测记录，字段包括：id、input_data（入参 JSON 字符串）、full_response（完整响应）、response（标签）、feedback（反馈，初始为空）、created_at、parent_mlalgorithm。

对单条记录执行PUT/PATCH /api/v1/mlrequests/{id}时，唯一可写字段是feedback——把实际结果写回后，A/B 测试即可用它结算准确率。

五、A/B 测试接口：创建实验与自动结算胜者

5.1 创建 A/B 测试：POST /api/v1/abtests

请求体字段：title、created_by、parent_mlalgorithm_1、parent_mlalgorithm_2（两个待对比算法的 ID）。只读字段：id、created_at、ended_at、summary。

创建时服务会自动把这两个算法的状态切换为ab_testing并激活（事务保证）。

5.2 结束测试并选出胜者：POST /api/v1/stop_ab_test/{ab_test_id}

• 成功响应：{"message": "AB Test finished.", "summary": "Algorithm #1 accuracy: x, Algorithm #2 accuracy: y"}，胜者（准确率高者）自动切回production，败者转为testing；
• 重复调用：返回"AB Test already finished."；
• 异常时返回 HTTP 400 与错误信息。

准确率计算逻辑见 views.py 中StopABTestView（约 L152-L204）。

六、快速上手：3 步完成首次预测调用

1. 获取端点名：GET /api/v1/endpoints，示例项目内置端点为income_classifier；
2. 发起预测：向/api/v1/income_classifier/predict发送上文 14 个字段的 JSON；
3. 查看记录：拿响应中的request_id到/api/v1/mlrequests/{id}核对入参、响应并补交feedback。

七、关键源码位置速查 📁

内容	文件
路由注册	backend/server/apps/endpoints/urls.py
各接口的视图实现	backend/server/apps/endpoints/views.py
响应字段（序列化器）	backend/server/apps/endpoints/serializers.py
数据模型定义	backend/server/apps/endpoints/models.py
算法注册表	backend/server/apps/ml/registry.py
内置算法启动加载	backend/server/server/wsgi.py
随机森林分类器示例	backend/server/apps/ml/income_classifier/random_forest.py

掌握这份清单后，你就能用 my_ml_service 的 REST API 完成从预测调用、版本管理到 A/B 实验结算的完整闭环。

【免费下载链接】my_ml_serviceMy Machine Learning Web Service项目地址: https://gitcode.com/gh_mirrors/my/my_ml_service