Add API endpoints
Signed-off-by: Naarcha-AWS <naarcha@amazon.com>
This commit is contained in:
Naarcha-AWS
parent
f78b5f612d
commit
3b79db7383
|
|
@ -2,9 +2,11 @@
|
|||
layout: default
|
||||
title: API
|
||||
has_children: false
|
||||
nav_order: 90
|
||||
nav_order: 99
|
||||
---
|
||||
|
||||
# ML Commons API
|
||||
|
||||
The Machine Learning (ML) commons API lets you create, train, and store machine learning algorithms both synchronously and asynchronously.
|
||||
|
||||
In order to train tasks through the API, three inputs are required.
|
||||
|
|
@ -15,5 +17,464 @@ In order to train tasks through the API, three inputs are required.
|
|||
|
||||
## Train model
|
||||
|
||||
Training can occur both synchronously and asynchronously.
|
||||
|
||||
### Request
|
||||
|
||||
The following examples use the kmeans algorithm to train index data.
|
||||
|
||||
**Train with kmeans synchronously**
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/_train/kmeans
|
||||
{
|
||||
"parameters": {
|
||||
"centroids": 3,
|
||||
"iterations": 10,
|
||||
"distance_type": "COSINE"
|
||||
},
|
||||
"input_query": {
|
||||
"_source": ["petal_length_in_cm", "petal_width_in_cm"],
|
||||
"size": 10000
|
||||
},
|
||||
"input_index": [
|
||||
"iris_data"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
**Train with kmeans asynchronously**
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/_train/kmeans?async=true
|
||||
{
|
||||
"parameters": {
|
||||
"centroids": 3,
|
||||
"iterations": 10,
|
||||
"distance_type": "COSINE"
|
||||
},
|
||||
"input_query": {
|
||||
"_source": ["petal_length_in_cm", "petal_width_in_cm"],
|
||||
"size": 10000
|
||||
},
|
||||
"input_index": [
|
||||
"iris_data"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
**Synchronously**
|
||||
|
||||
For synchronous responses, the API returns the model_id, which can be used to get info or modify the model.
|
||||
|
||||
```json
|
||||
{
|
||||
"model_id" : "lblVmX8BO5w8y8RaYYvN",
|
||||
"status" : "COMPLETED"
|
||||
}
|
||||
```
|
||||
|
||||
**Asynchronously**
|
||||
|
||||
For asynchronous responses, the API returns the task_id, which can be used to get info or modify a task.
|
||||
|
||||
```json
|
||||
{
|
||||
"task_id" : "lrlamX8BO5w8y8Ra2otd",
|
||||
"status" : "CREATED"
|
||||
}
|
||||
```
|
||||
|
||||
## Get model information
|
||||
|
||||
You can retrieve information on your model using the model_id.
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/models/<model-id>
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
The API returns information on the model, the algorithm used, and the content found within the model.
|
||||
|
||||
```json
|
||||
{
|
||||
"name" : "KMEANS",
|
||||
"algorithm" : "KMEANS",
|
||||
"version" : 1,
|
||||
"content" : ""
|
||||
}
|
||||
```
|
||||
|
||||
## Get task information
|
||||
|
||||
You can retrieve information about a task using the task_id.
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/tasks/<task_id>
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
The response includes information about the task.
|
||||
|
||||
```json
|
||||
{
|
||||
"model_id" : "l7lamX8BO5w8y8Ra2oty",
|
||||
"task_type" : "TRAINING",
|
||||
"function_name" : "KMEANS",
|
||||
"state" : "COMPLETED",
|
||||
"input_type" : "SEARCH_QUERY",
|
||||
"worker_node" : "54xOe0w8Qjyze00UuLDfdA",
|
||||
"create_time" : 1647545342556,
|
||||
"last_update_time" : 1647545342587,
|
||||
"is_async" : true
|
||||
}
|
||||
```
|
||||
|
||||
## Predict
|
||||
|
||||
Should you trained a synchronous, ML commons can predict new data with your trained model either from indexed data or a data frame.
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/_predict/<algorithm_name>/<model_id>
|
||||
```
|
||||
|
||||
### Request
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/_predict/kmeans/eQlomX8Br-2Nu7fWjUu3
|
||||
{
|
||||
"input_query": {
|
||||
"_source": ["petal_length_in_cm", "petal_width_in_cm"],
|
||||
"size": 10000
|
||||
},
|
||||
"input_index": [
|
||||
"iris_data"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"status" : "COMPLETED",
|
||||
"prediction_result" : {
|
||||
"column_metas" : [
|
||||
{
|
||||
"name" : "ClusterID",
|
||||
"column_type" : "INTEGER"
|
||||
}
|
||||
],
|
||||
"rows" : [
|
||||
{
|
||||
"values" : [
|
||||
{
|
||||
"column_type" : "INTEGER",
|
||||
"value" : 1
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"values" : [
|
||||
{
|
||||
"column_type" : "INTEGER",
|
||||
"value" : 1
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"values" : [
|
||||
{
|
||||
"column_type" : "INTEGER",
|
||||
"value" : 0
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"values" : [
|
||||
{
|
||||
"column_type" : "INTEGER",
|
||||
"value" : 0
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"values" : [
|
||||
{
|
||||
"column_type" : "INTEGER",
|
||||
"value" : 0
|
||||
}
|
||||
]
|
||||
},
|
||||
{
|
||||
"values" : [
|
||||
{
|
||||
"column_type" : "INTEGER",
|
||||
"value" : 0
|
||||
}
|
||||
]
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
## Search model
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/_search
|
||||
{query}
|
||||
```
|
||||
|
||||
|
||||
### Example 1: Query all models
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/_search
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"size": 1000
|
||||
}
|
||||
```
|
||||
|
||||
### Example 2: query models with algorithm "BATCh_RCF"
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/_search
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"algorithm": {
|
||||
"value": "BATCH_RCF"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 8,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 2,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 2.4159138,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : ".plugins-ml-model",
|
||||
"_type" : "_doc",
|
||||
"_id" : "-QkKJX8BvytMh9aUeuLD",
|
||||
"_version" : 1,
|
||||
"_seq_no" : 12,
|
||||
"_primary_term" : 15,
|
||||
"_score" : 2.4159138,
|
||||
"_source" : {
|
||||
"name" : "FIT_RCF",
|
||||
"version" : 1,
|
||||
"content" : "xxx",
|
||||
"algorithm" : "FIT_RCF"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : ".plugins-ml-model",
|
||||
"_type" : "_doc",
|
||||
"_id" : "OxkvHn8BNJ65KnIpck8x",
|
||||
"_version" : 1,
|
||||
"_seq_no" : 2,
|
||||
"_primary_term" : 8,
|
||||
"_score" : 2.4159138,
|
||||
"_source" : {
|
||||
"name" : "FIT_RCF",
|
||||
"version" : 1,
|
||||
"content" : "xxx",
|
||||
"algorithm" : "FIT_RCF"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Delete task
|
||||
|
||||
```json
|
||||
DELETE /_plugins/_ml/tasks/{task_id}
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"_index" : ".plugins-ml-task",
|
||||
"_type" : "_doc",
|
||||
"_id" : "xQRYLX8BydmmU1x6nuD3",
|
||||
"_version" : 4,
|
||||
"result" : "deleted",
|
||||
"_shards" : {
|
||||
"total" : 2,
|
||||
"successful" : 2,
|
||||
"failed" : 0
|
||||
},
|
||||
"_seq_no" : 42,
|
||||
"_primary_term" : 7
|
||||
}
|
||||
```
|
||||
|
||||
## Search task
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/tasks/_search
|
||||
{query body}
|
||||
```
|
||||
|
||||
|
||||
### Example: search task which "function_name" is "KMEANS"
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/tasks/_search
|
||||
{
|
||||
"query": {
|
||||
"bool": {
|
||||
"filter": [
|
||||
{
|
||||
"term": {
|
||||
"function_name": "KMEANS"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
```json
|
||||
{
|
||||
"took" : 12,
|
||||
"timed_out" : false,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
},
|
||||
"hits" : {
|
||||
"total" : {
|
||||
"value" : 2,
|
||||
"relation" : "eq"
|
||||
},
|
||||
"max_score" : 0.0,
|
||||
"hits" : [
|
||||
{
|
||||
"_index" : ".plugins-ml-task",
|
||||
"_type" : "_doc",
|
||||
"_id" : "_wnLJ38BvytMh9aUi-Ia",
|
||||
"_version" : 4,
|
||||
"_seq_no" : 29,
|
||||
"_primary_term" : 4,
|
||||
"_score" : 0.0,
|
||||
"_source" : {
|
||||
"last_update_time" : 1645640125267,
|
||||
"create_time" : 1645640125209,
|
||||
"is_async" : true,
|
||||
"function_name" : "KMEANS",
|
||||
"input_type" : "SEARCH_QUERY",
|
||||
"worker_node" : "jjqFrlW7QWmni1tRnb_7Dg",
|
||||
"state" : "COMPLETED",
|
||||
"model_id" : "AAnLJ38BvytMh9aUi-M2",
|
||||
"task_type" : "TRAINING"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index" : ".plugins-ml-task",
|
||||
"_type" : "_doc",
|
||||
"_id" : "wwRRLX8BydmmU1x6I-AI",
|
||||
"_version" : 3,
|
||||
"_seq_no" : 38,
|
||||
"_primary_term" : 7,
|
||||
"_score" : 0.0,
|
||||
"_source" : {
|
||||
"last_update_time" : 1645732766656,
|
||||
"create_time" : 1645732766472,
|
||||
"is_async" : true,
|
||||
"function_name" : "KMEANS",
|
||||
"input_type" : "SEARCH_QUERY",
|
||||
"worker_node" : "A_IiqoloTDK01uZvCjREaA",
|
||||
"state" : "COMPLETED",
|
||||
"model_id" : "xARRLX8BydmmU1x6I-CG",
|
||||
"task_type" : "TRAINING"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Stats
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/stats
|
||||
GET /_plugins/_ml/<nodeId>/stats/
|
||||
GET /_plugins/_ml/<nodeId>/stats/<stat>
|
||||
GET /_plugins/_ml/stats/<stat>
|
||||
```
|
||||
|
||||
|
||||
### Example1: get all stats
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/stats
|
||||
```
|
||||
|
||||
### Response
|
||||
|
||||
```json
|
||||
{
|
||||
"zbduvgCCSOeu6cfbQhTpnQ" : {
|
||||
"ml_executing_task_count" : 0
|
||||
},
|
||||
"54xOe0w8Qjyze00UuLDfdA" : {
|
||||
"ml_executing_task_count" : 0
|
||||
},
|
||||
"UJiykI7bTKiCpR-rqLYHyw" : {
|
||||
"ml_executing_task_count" : 0
|
||||
},
|
||||
"zj2_NgIbTP-StNlGZJlxdg" : {
|
||||
"ml_executing_task_count" : 0
|
||||
},
|
||||
"jjqFrlW7QWmni1tRnb_7Dg" : {
|
||||
"ml_executing_task_count" : 0
|
||||
},
|
||||
"3pSSjl5PSVqzv5-hBdFqyA" : {
|
||||
"ml_executing_task_count" : 0
|
||||
},
|
||||
"A_IiqoloTDK01uZvCjREaA" : {
|
||||
"ml_executing_task_count" : 0
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
Loading…
Reference in New Issue