diff --git a/_ml-commons-plugin/api.md b/_ml-commons-plugin/api.md index 65a74a03..a472fdaa 100644 --- a/_ml-commons-plugin/api.md +++ b/_ml-commons-plugin/api.md @@ -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/ +``` + +### 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/ +``` + +### 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// +``` + +### 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//stats/ +GET /_plugins/_ml//stats/ +GET /_plugins/_ml/stats/ +``` + + +### 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 + } +} +``` + +