Add model access control documentation for ML Commons (#4223)
* Add model access control documentation for ML Commons Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Remove permissions for delete API Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Add copy buttons Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Updated model-level APIs Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Add delete model Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Reworded role-related text Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Implemented tech review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Rewording Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Remove experimental warning Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Register a model group in note format Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Implement tech review comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Resolved Vale comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Remove space Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Apply suggestions from code review Co-authored-by: Chris Moore <107723039+cwillum@users.noreply.github.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Implemented doc review feedback Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Implemented editorial comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Apply suggestions from code review Co-authored-by: Melissa Vagi <vagimeli@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> * Add more editorial comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Add more editorial comments Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Fix links Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> * Fix more links Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> --------- Signed-off-by: Fanit Kolchina <kolchfa@amazon.com> Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Co-authored-by: Chris Moore <107723039+cwillum@users.noreply.github.com> Co-authored-by: Melissa Vagi <vagimeli@amazon.com>
This commit is contained in:
kolchfa-aws
GitHub
parent
074d09c327
commit
52b4a9ee9f
|
|
@ -27,7 +27,7 @@ distance_type | enum, such as `EUCLIDEAN`, `COSINE`, or `L1` | The type of measu
|
|||
|
||||
### APIs
|
||||
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-model)
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#training-the-model)
|
||||
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict)
|
||||
* [Train and predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-and-predict)
|
||||
|
||||
|
|
@ -77,7 +77,7 @@ optimizerType | OptimizerType | The optimizer used in the model. | SIMPLE_SGD
|
|||
|
||||
### APIs
|
||||
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-model)
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#training-the-model)
|
||||
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict)
|
||||
|
||||
### Example
|
||||
|
|
@ -189,7 +189,7 @@ time_zone | string | The time zone for the `time_field` field. | "UTC"
|
|||
|
||||
### APIs
|
||||
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-model)
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#training-the-model)
|
||||
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict)
|
||||
* [Train and predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-and-predict)
|
||||
|
||||
|
|
@ -211,7 +211,7 @@ RCF Summarize is a clustering algorithm based on the Clustering Using Representa
|
|||
|
||||
### APIs
|
||||
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-model)
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#training-the-model)
|
||||
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict)
|
||||
* [Train and predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-and-predict)
|
||||
|
||||
|
|
@ -429,7 +429,7 @@ A classification algorithm, logistic regression models the probability of a disc
|
|||
|
||||
### APIs
|
||||
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#train-model)
|
||||
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#training-the-model)
|
||||
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict)
|
||||
|
||||
### Example: Train/Predict with Iris data
|
||||
|
|
|
|||
|
|
@ -9,31 +9,49 @@ nav_order: 99
|
|||
|
||||
---
|
||||
|
||||
#### Table of contents
|
||||
<details closed markdown="block">
|
||||
<summary>
|
||||
Table of contents
|
||||
</summary>
|
||||
{: .text-delta }
|
||||
- TOC
|
||||
{:toc}
|
||||
|
||||
</details>
|
||||
|
||||
---
|
||||
|
||||
The Machine Learning (ML) commons API lets you train ML algorithms synchronously and asynchronously, make predictions with that trained model, and train and predict with the same data set.
|
||||
The ML Commons API lets you train machine learning (ML) algorithms synchronously and asynchronously, make predictions with that trained model, and train and predict with the same dataset.
|
||||
|
||||
In order to train tasks through the API, three inputs are required.
|
||||
To train tasks through the API, three inputs are required:
|
||||
|
||||
- Algorithm name: Must be one of a [FunctionName](https://github.com/opensearch-project/ml-commons/blob/1.3/common/src/main/java/org/opensearch/ml/common/parameter/FunctionName.java). This determines what algorithm the ML Engine runs. To add a new function, see [How To Add a New Function](https://github.com/opensearch-project/ml-commons/blob/main/docs/how-to-add-new-function.md).
|
||||
- Model hyper parameters: Adjust these parameters to make the model train better.
|
||||
- Input data: The data input that trains the ML model, or applies the ML models to predictions. You can input data in two ways, query against your index or use data frame.
|
||||
- Model hyperparameters: Adjust these parameters to improve model accuracy.
|
||||
- Input data: The data that trains the ML model, or applies the ML models to predictions. You can input data in two ways, query against your index or use a data frame.
|
||||
|
||||
## Model access control considerations
|
||||
|
||||
For clusters with model access control enabled, users can perform API operations on models in model groups with specified access levels as follows:
|
||||
|
||||
- `public` model group: Any user.
|
||||
- `restricted` model group: Only the model owner or users who share at least one backend role with the model group.
|
||||
- `private` model group: Only the model owner.
|
||||
|
||||
For clusters with model access control disabled, any user can perform API operations on models in any model group.
|
||||
|
||||
Admin users can perform API operations for models in any model group.
|
||||
|
||||
For more information, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).
|
||||
|
||||
|
||||
## Train model
|
||||
## Training the model
|
||||
|
||||
The train operation trains a model based on a selected algorithm. Training can occur both synchronously and asynchronously.
|
||||
The train API operation trains a model based on a selected algorithm. Training can occur both synchronously and asynchronously.
|
||||
|
||||
### Request
|
||||
|
||||
The following examples use the kmeans algorithm to train index data.
|
||||
The following examples use the k-means algorithm to train index data.
|
||||
|
||||
**Train with kmeans synchronously**
|
||||
**Train with k-means synchronously**
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/_train/kmeans
|
||||
|
|
@ -52,8 +70,9 @@ POST /_plugins/_ml/_train/kmeans
|
|||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
**Train with kmeans asynchronously**
|
||||
**Train with k-means asynchronously**
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/_train/kmeans?async=true
|
||||
|
|
@ -72,12 +91,13 @@ POST /_plugins/_ml/_train/kmeans?async=true
|
|||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response
|
||||
|
||||
**Synchronously**
|
||||
**Synchronous**
|
||||
|
||||
For synchronous responses, the API returns the model_id, which can be used to get or delete a model.
|
||||
For synchronous responses, the API returns the `model_id`, which can be used to get or delete a model.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -86,9 +106,9 @@ For synchronous responses, the API returns the model_id, which can be used to ge
|
|||
}
|
||||
```
|
||||
|
||||
**Asynchronously**
|
||||
**Asynchronous**
|
||||
|
||||
For asynchronous responses, the API returns the task_id, which can be used to get or delete a task.
|
||||
For asynchronous responses, the API returns the `task_id`, which can be used to get or delete a task.
|
||||
|
||||
```json
|
||||
{
|
||||
|
|
@ -99,30 +119,56 @@ For asynchronous responses, the API returns the task_id, which can be used to ge
|
|||
|
||||
## Getting model information
|
||||
|
||||
You can retrieve information on your model using the model_id.
|
||||
You can retrieve model information using the `model_id`.
|
||||
|
||||
For information about user access for this API, see [Model access control considerations](#model-access-control-considerations).
|
||||
|
||||
### Path and HTTP methods
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/models/<model-id>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The API returns information on the model, the algorithm used, and the content found within the model.
|
||||
The response contains the following model information:
|
||||
|
||||
```json
|
||||
{
|
||||
"name" : "KMEANS",
|
||||
"algorithm" : "KMEANS",
|
||||
"version" : 1,
|
||||
"content" : ""
|
||||
"name" : "all-MiniLM-L6-v2_onnx",
|
||||
"algorithm" : "TEXT_EMBEDDING",
|
||||
"version" : "1",
|
||||
"model_format" : "TORCH_SCRIPT",
|
||||
"model_state" : "LOADED",
|
||||
"model_content_size_in_bytes" : 83408741,
|
||||
"model_content_hash_value" : "9376c2ebd7c83f99ec2526323786c348d2382e6d86576f750c89ea544d6bbb14",
|
||||
"model_config" : {
|
||||
"model_type" : "bert",
|
||||
"embedding_dimension" : 384,
|
||||
"framework_type" : "SENTENCE_TRANSFORMERS",
|
||||
"all_config" : """{"_name_or_path":"nreimers/MiniLM-L6-H384-uncased","architectures":["BertModel"],"attention_probs_dropout_prob":0.1,"gradient_checkpointing":false,"hidden_act":"gelu","hidden_dropout_prob":0.1,"hidden_size":384,"initializer_range":0.02,"intermediate_size":1536,"layer_norm_eps":1e-12,"max_position_embeddings":512,"model_type":"bert","num_attention_heads":12,"num_hidden_layers":6,"pad_token_id":0,"position_embedding_type":"absolute","transformers_version":"4.8.2","type_vocab_size":2,"use_cache":true,"vocab_size":30522}"""
|
||||
},
|
||||
"created_time" : 1665961344044,
|
||||
"last_uploaded_time" : 1665961373000,
|
||||
"last_loaded_time" : 1665961815959,
|
||||
"total_chunks" : 9
|
||||
}
|
||||
```
|
||||
|
||||
## Registering a model
|
||||
|
||||
Use the register operation to register a custom model to a model index. ML Commons splits the model into smaller chunks and saves those chunks in the model's index.
|
||||
Before you register a model, you must [register a model group]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control#registering-a-model-group) for the model.
|
||||
{: .important}
|
||||
|
||||
All versions of a particular model are held in a model group. After you register a model group, you can register a model to the model group. ML Commons splits the model into smaller chunks and saves those chunks in the model's index.
|
||||
|
||||
For information about user access for this API, see [Model access control considerations](#model-access-control-considerations).
|
||||
|
||||
### Path and HTTP methods
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/_register
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Request fields
|
||||
|
||||
|
|
@ -130,11 +176,13 @@ All request fields are required.
|
|||
|
||||
Field | Data type | Description
|
||||
:--- | :--- | :---
|
||||
`name`| string | The name of the model. |
|
||||
`version` | integer | The version number of the model. |
|
||||
`model_format` | string | The portable format of the model file. Currently only supports `TORCH_SCRIPT`. |
|
||||
`model_config` | json object | The model's configuration, including the `model_type`, `embedding_dimension`, and `framework_type`. `all_config` is an optional JSON string which contains all model configurations. |
|
||||
`url` | string | The URL which contains the model. |
|
||||
`name`| String | The model's name. |
|
||||
`version` | Integer | The model's version number. |
|
||||
`model_format` | String | The portable format of the model file. Currently only supports `TORCH_SCRIPT`. |
|
||||
`model_group_id` | String | The model group ID for the model.
|
||||
`model_content_hash_value` | String | The model content hash generated using the SHA-256 hashing algorithm.
|
||||
`model_config` | JSON object | The model's configuration, including the `model_type`, `embedding_dimension`, and `framework_type`. `all_config` is an optional JSON string that contains all model configurations. |
|
||||
`url` | String | The URL that contains the model. |
|
||||
|
||||
### Example
|
||||
|
||||
|
|
@ -143,18 +191,22 @@ The following example request registers a version `1.0.0` of an NLP sentence tra
|
|||
```json
|
||||
POST /_plugins/_ml/models/_register
|
||||
{
|
||||
"name": "all-MiniLM-L6-v2",
|
||||
"version": "1.0.0",
|
||||
"description": "test model",
|
||||
"model_format": "TORCH_SCRIPT",
|
||||
"model_config": {
|
||||
"model_type": "bert",
|
||||
"embedding_dimension": 384,
|
||||
"framework_type": "sentence_transformers",
|
||||
},
|
||||
"url": "https://github.com/opensearch-project/ml-commons/raw/2.x/ml-algorithms/src/test/resources/org/opensearch/ml/engine/algorithms/text_embedding/all-MiniLM-L6-v2_torchscript_sentence-transformer.zip?raw=true"
|
||||
"name": "all-MiniLM-L6-v2",
|
||||
"version": "1.0.0",
|
||||
"description": "test model",
|
||||
"model_format": "TORCH_SCRIPT",
|
||||
"model_group_id": "FTNlQ4gBYW0Qyy5ZoxfR",
|
||||
"model_content_hash_value": "c15f0d2e62d872be5b5bc6c84d2e0f4921541e29fefbef51d59cc10a8ae30e0f",
|
||||
"model_config": {
|
||||
"model_type": "bert",
|
||||
"embedding_dimension": 384,
|
||||
"framework_type": "sentence_transformers",
|
||||
"all_config": "{\"_name_or_path\":\"nreimers/MiniLM-L6-H384-uncased\",\"architectures\":[\"BertModel\"],\"attention_probs_dropout_prob\":0.1,\"gradient_checkpointing\":false,\"hidden_act\":\"gelu\",\"hidden_dropout_prob\":0.1,\"hidden_size\":384,\"initializer_range\":0.02,\"intermediate_size\":1536,\"layer_norm_eps\":1e-12,\"max_position_embeddings\":512,\"model_type\":\"bert\",\"num_attention_heads\":12,\"num_hidden_layers\":6,\"pad_token_id\":0,\"position_embedding_type\":\"absolute\",\"transformers_version\":\"4.8.2\",\"type_vocab_size\":2,\"use_cache\":true,\"vocab_size\":30522}"
|
||||
},
|
||||
"url": "https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/all-MiniLM-L6-v2/1.0.1/torch_script/sentence-transformers_all-MiniLM-L6-v2-1.0.1-torch_script.zip"
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response
|
||||
|
||||
|
|
@ -167,18 +219,27 @@ OpenSearch responds with the `task_id` and task `status`.
|
|||
}
|
||||
```
|
||||
|
||||
To see the status of your model registration, enter the `task_id` in the [task API] ...
|
||||
To see the status of your model registration and retrieve the model ID created for the new model version, pass the `task_id` as a path parameter to the Tasks API:
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/tasks/<task_id>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The response contains the model ID of the model version:
|
||||
|
||||
```json
|
||||
{
|
||||
"model_id" : "WWQI44MBbzI2oUKAvNUt",
|
||||
"task_type" : "UPLOAD_MODEL",
|
||||
"function_name" : "TEXT_EMBEDDING",
|
||||
"state" : "REGISTERED",
|
||||
"worker_node" : "KzONM8c8T4Od-NoUANQNGg",
|
||||
"create_time" : 1665961344003,
|
||||
"last_update_time" : 1665961373047,
|
||||
"is_async" : true
|
||||
"model_id": "Qr1YbogBYOqeeqR7sI9L",
|
||||
"task_type": "DEPLOY_MODEL",
|
||||
"function_name": "TEXT_EMBEDDING",
|
||||
"state": "COMPLETED",
|
||||
"worker_node": [
|
||||
"N77RInqjTSq_UaLh1k0BUg"
|
||||
],
|
||||
"create_time": 1685478486057,
|
||||
"last_update_time": 1685478491090,
|
||||
"is_async": true
|
||||
}
|
||||
```
|
||||
|
||||
|
|
@ -186,6 +247,10 @@ To see the status of your model registration, enter the `task_id` in the [task A
|
|||
|
||||
The deploy model operation reads the model's chunks from the model index and then creates an instance of the model to cache into memory. This operation requires the `model_id`.
|
||||
|
||||
For information about user access for this API, see [Model access control considerations](#model-access-control-considerations).
|
||||
|
||||
### Path and HTTP methods
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/<model_id>/_deploy
|
||||
```
|
||||
|
|
@ -197,6 +262,7 @@ In this example request, OpenSearch deploys the model to any available OpenSearc
|
|||
```json
|
||||
POST /_plugins/_ml/models/WWQI44MBbzI2oUKAvNUt/_deploy
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Example: Deploying to a specific node
|
||||
|
||||
|
|
@ -208,6 +274,7 @@ POST /_plugins/_ml/models/WWQI44MBbzI2oUKAvNUt/_deploy
|
|||
"node_ids": ["4PLK7KJWReyX0oWKnBA8nA"]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response
|
||||
|
||||
|
|
@ -220,7 +287,11 @@ POST /_plugins/_ml/models/WWQI44MBbzI2oUKAvNUt/_deploy
|
|||
|
||||
## Undeploying a model
|
||||
|
||||
To undeploy a model from memory, use the undeploy operation:
|
||||
To undeploy a model from memory, use the undeploy operation.
|
||||
|
||||
For information about user access for this API, see [Model access control considerations](#model-access-control-considerations).
|
||||
|
||||
### Path and HTTP methods
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/<model_id>/_undeploy
|
||||
|
|
@ -231,6 +302,7 @@ POST /_plugins/_ml/models/<model_id>/_undeploy
|
|||
```json
|
||||
POST /_plugins/_ml/models/MGqJhYMBbbh0ushjm8p_/_undeploy
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response: Undeploying a model from all ML nodes
|
||||
|
||||
|
|
@ -253,7 +325,7 @@ POST /_plugins/_ml/models/_undeploy
|
|||
"model_ids": ["KDo2ZYQB-v9VEDwdjkZ4"]
|
||||
}
|
||||
```
|
||||
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response: Undeploying specific models from specific nodes
|
||||
|
||||
|
|
@ -287,6 +359,7 @@ POST /_plugins/_ml/models/_undeploy
|
|||
"model_ids": ["KDo2ZYQB-v9VEDwdjkZ4"]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response: Undeploying specific models from all nodes
|
||||
|
||||
|
|
@ -302,15 +375,24 @@ POST /_plugins/_ml/models/_undeploy
|
|||
|
||||
## Searching for a model
|
||||
|
||||
Use this command to search models you've already created.
|
||||
Use this command to search for models you've already created.
|
||||
|
||||
The response will contain only those model versions to which you have access. For example, if you send a match all query, model versions for the following model group types will be returned:
|
||||
|
||||
- All public model groups in the index.
|
||||
- Private model groups for which you are the model owner.
|
||||
- Model groups that share at least one backend role with your backend roles.
|
||||
|
||||
For more information, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).
|
||||
|
||||
### Path and HTTP methods
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/_search
|
||||
{query}
|
||||
```
|
||||
|
||||
### Example: Querying all models
|
||||
### Example: Searching for all models
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/_search
|
||||
|
|
@ -321,8 +403,9 @@ POST /_plugins/_ml/models/_search
|
|||
"size": 1000
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Example: Querying models with algorithm "FIT_RCF"
|
||||
### Example: Searching for models with algorithm "FIT_RCF"
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/models/_search
|
||||
|
|
@ -336,6 +419,7 @@ POST /_plugins/_ml/models/_search
|
|||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response
|
||||
|
||||
|
|
@ -393,9 +477,14 @@ POST /_plugins/_ml/models/_search
|
|||
|
||||
Deletes a model based on the `model_id`.
|
||||
|
||||
For information about user access for this API, see [Model access control considerations](#model-access-control-considerations).
|
||||
|
||||
### Path and HTTP methods
|
||||
|
||||
```json
|
||||
DELETE /_plugins/_ml/models/<model_id>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The API returns the following:
|
||||
|
||||
|
|
@ -430,8 +519,8 @@ GET /_plugins/_ml/profile/tasks
|
|||
|
||||
Parameter | Data type | Description
|
||||
:--- | :--- | :---
|
||||
model_id | string | Returns runtime data for a specific model. You can string together multiple `model_id`s to return multiple model profiles.
|
||||
tasks | string | Returns runtime data for a specific task. You can string together multiple `task_id`s to return multiple task profiles.
|
||||
`model_id` | String | Returns runtime data for a specific model. You can string together multiple `model_id`s to return multiple model profiles.
|
||||
`tasks`| String | Returns runtime data for a specific task. You can string together multiple `task_id`s to return multiple task profiles.
|
||||
|
||||
### Request fields
|
||||
|
||||
|
|
@ -439,11 +528,11 @@ All profile body request fields are optional.
|
|||
|
||||
Field | Data type | Description
|
||||
:--- | :--- | :---
|
||||
node_ids | string | Returns all tasks and profiles from a specific node.
|
||||
model_ids | string | Returns runtime data for a specific model. You can string together multiple `model_id`s to return multiple model profiles.
|
||||
task_ids | string | Returns runtime data for a specific task. You can string together multiple `task_id`s to return multiple task profiles.
|
||||
return_all_tasks | boolean | Determines whether or not a request returns all tasks. When set to `false` task profiles are left out of the response.
|
||||
return_all_models | boolean | Determines whether or not a profile request returns all models. When set to `false` model profiles are left out of the response.
|
||||
`node_ids` | String | Returns all tasks and profiles from a specific node.
|
||||
`model_ids` | String | Returns runtime data for a specific model. You can string together multiple model IDs to return multiple model profiles.
|
||||
`task_ids` | String | Returns runtime data for a specific task. You can string together multiple task IDs to return multiple task profiles.
|
||||
`return_all_tasks` | Boolean | Determines whether or not a request returns all tasks. When set to `false`, task profiles are left out of the response.
|
||||
`return_all_models` | Boolean | Determines whether or not a profile request returns all models. When set to `false`, model profiles are left out of the response.
|
||||
|
||||
### Example: Returning all tasks and models on a specific node
|
||||
|
||||
|
|
@ -455,6 +544,7 @@ GET /_plugins/_ml/profile
|
|||
"return_all_models": true
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response: Returning all tasks and models on a specific node
|
||||
|
||||
|
|
@ -500,6 +590,10 @@ GET /_plugins/_ml/profile
|
|||
|
||||
ML Commons can predict new data with your trained model either from indexed data or a data frame. To use the Predict API, the `model_id` is required.
|
||||
|
||||
For information about user access for this API, see [Model access control considerations](#model-access-control-considerations).
|
||||
|
||||
### Path and HTTP methods
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/_predict/<algorithm_name>/<model_id>
|
||||
```
|
||||
|
|
@ -518,6 +612,7 @@ POST /_plugins/_ml/_predict/kmeans/<model-id>
|
|||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response
|
||||
|
||||
|
|
@ -587,15 +682,14 @@ POST /_plugins/_ml/_predict/kmeans/<model-id>
|
|||
|
||||
## Train and predict
|
||||
|
||||
Use to train and then immediately predict against the same training data set. Can only be used with unsupervised learning models and the following algorithms:
|
||||
Use to train and then immediately predict against the same training dataset. Can only be used with unsupervised learning models and the following algorithms:
|
||||
|
||||
- BATCH_RCF
|
||||
- FIT_RCF
|
||||
- kmeans
|
||||
- k-means
|
||||
|
||||
### Example: Train and predict with indexed data
|
||||
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/_train_predict/kmeans
|
||||
{
|
||||
|
|
@ -625,6 +719,7 @@ POST /_plugins/_ml/_train_predict/kmeans
|
|||
]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Example: Train and predict with data directly
|
||||
|
||||
|
|
@ -724,6 +819,7 @@ POST /_plugins/_ml/_train_predict/kmeans
|
|||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response
|
||||
|
||||
|
|
@ -798,6 +894,7 @@ You can retrieve information about a task using the task_id.
|
|||
```json
|
||||
GET /_plugins/_ml/tasks/<task_id>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The response includes information about the task.
|
||||
|
||||
|
|
@ -825,7 +922,7 @@ GET /_plugins/_ml/tasks/_search
|
|||
```
|
||||
|
||||
|
||||
### Example: Search task which "function_name" is "KMEANS"
|
||||
### Example: Search task which `function_name` is `KMEANS`
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/tasks/_search
|
||||
|
|
@ -843,6 +940,7 @@ GET /_plugins/_ml/tasks/_search
|
|||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response
|
||||
|
||||
|
|
@ -916,6 +1014,7 @@ ML Commons does not check the task status when running the `Delete` request. The
|
|||
```json
|
||||
DELETE /_plugins/_ml/tasks/{task_id}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
The API returns the following:
|
||||
|
||||
|
|
@ -944,24 +1043,28 @@ To receive all stats, use:
|
|||
```json
|
||||
GET /_plugins/_ml/stats
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
To receive stats for a specific node, use:
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/<nodeId>/stats/
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
To receive stats for a specific node and return a specified stat, use:
|
||||
To receive stats for a specific node and return a specified stat, use:
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/<nodeId>/stats/<stat>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
To receive information on a specific stat from all nodes, use:
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/stats/<stat>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
|
||||
### Example: Get all stats
|
||||
|
|
@ -969,6 +1072,7 @@ GET /_plugins/_ml/stats/<stat>
|
|||
```json
|
||||
GET /_plugins/_ml/stats
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Response
|
||||
|
||||
|
|
@ -1033,6 +1137,7 @@ POST /_plugins/_ml/_execute/anomaly_localization
|
|||
"num_outputs": 10
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
Upon execution, the API returns the following:
|
||||
|
||||
|
|
|
|||
|
|
@ -13,17 +13,16 @@ ML Commons for OpenSearch eases the development of machine learning features by
|
|||
|
||||
Interaction with the ML Commons plugin occurs through either the [REST API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api) or [`ad`]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/functions#ad) and [`kmeans`]({{site.url}}{{site.baseurl}}/search-plugins/sql/ppl/functions#kmeans) Piped Processing Language (PPL) commands.
|
||||
|
||||
Models [trained]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#train-model) through the ML Commons plugin support model-based algorithms such as kmeans. After you've trained a model enough so that it meets your precision requirements, you can apply the model to [predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#predict) new data safely.
|
||||
Models [trained]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#training-the-model) through the ML Commons plugin support model-based algorithms such as k-means. After you've trained a model enough so that it meets your precision requirements, you can apply the model to [predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#predict) new data safely.
|
||||
|
||||
Should you not want to use a model, you can use the [Train and Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#train-and-predict) API to test your model without having to evaluate the model's performance.
|
||||
|
||||
# Permissions
|
||||
|
||||
## Permissions
|
||||
The ML Commons plugin has two reserved roles:
|
||||
|
||||
There are two reserved user roles that can use of the ML Commons plugin.
|
||||
|
||||
- `ml_full_access`: Full access to all ML features, including starting new ML tasks and reading or deleting models.
|
||||
- `ml_readonly_access`: Can only read ML tasks, trained models and statistics relevant to the model's cluster. Cannot start nor delete ML tasks or models.
|
||||
- `ml_full_access`: Grants full access to all ML features, including starting new ML tasks and reading or deleting models.
|
||||
- `ml_readonly_access`: Grants read-only access to ML tasks, trained models, and statistics relevant to the model's cluster. Does not grant permissions to start or delete ML tasks or models.
|
||||
|
||||
## ML node
|
||||
|
||||
|
|
|
|||
|
|
@ -0,0 +1,593 @@
|
|||
---
|
||||
layout: default
|
||||
title: Model access control
|
||||
has_children: false
|
||||
nav_order: 180
|
||||
---
|
||||
|
||||
# Model access control
|
||||
|
||||
You can use the Security plugin with ML Commons to manage access to specific models for non-admin users. For example, one department in an organization might want to restrict users in other departments from accessing their models.
|
||||
|
||||
To accomplish this, users are assigned one or more [_backend roles_]({{site.url}}{{site.baseurl}}/security/access-control/index/). Rather than assign individual roles to individual users during user configuration, backend roles provide a way to map a set of users to a role by assigning the backend role to users when they log in. For example, users may be assigned an `IT` backend role that includes the `ml_full_access` role and have full access to all ML Commons features. Alternatively, other users may be assigned an `HR` backend role that includes the `ml_readonly_access` role and be limited to read-only access to machine learning (ML) features. Given this flexibility, backend roles can provide finer-grained access to models and make it easier to assign multiple users to a role rather than mapping a user and role individually.
|
||||
|
||||
## Model groups
|
||||
|
||||
For access control, models are organized into _model groups_---collections of versions of a particular model. Like users, model groups can be assigned one or more backend roles. All versions of the same model share the same model name and have the same backend role or roles.
|
||||
|
||||
You are considered a model _owner_ when you create a new model group. You remain the owner of the model and all its versions even if another user registers a model to this model group. When a model owner creates a model group, the owner can specify one of the following _access modes_ for this model group:
|
||||
|
||||
- `public`: All users who have access to the cluster can access this model group.
|
||||
- `private`: Only the model owner or an admin user can access this model group.
|
||||
- `restricted`: The owner, an admin user, or any user who shares one of the model group's backend roles can access any model in this model group. When creating a `restricted` model group, the owner must attach one or more of the owner's backend roles to the model.
|
||||
|
||||
An admin can access all model groups in the cluster regardless of their access mode.
|
||||
{: .note}
|
||||
|
||||
## Model access control prerequisites
|
||||
|
||||
Before using model access control, you must satisfy the following prerequisites:
|
||||
|
||||
1. Enable the Security plugin on your cluster. For more information, see [Security in OpenSearch]({{site.url}}{{site.baseurl}}/security/).
|
||||
2. For `restricted` model groups, ensure that an admin has [assigned backend roles to users](#assigning-backend-roles-to-users).
|
||||
3. [Enable model access control](#enabling-model-access-control) on your cluster. You can enable model access control dynamically by setting `plugins.ml_commons.model_access_control_enabled` to `true`.
|
||||
|
||||
If any of the prerequisites are not met, all models in the cluster are `public` and can be accessed by any user who has access to the cluster.
|
||||
{: .note}
|
||||
|
||||
## Assigning backend roles to users
|
||||
|
||||
Create the appropriate backend roles and assign those roles to users. Backend roles usually come from an [LDAP server]({{site.url}}{{site.baseurl}}/security/configuration/ldap/) or [SAML provider]({{site.url}}{{site.baseurl}}/security/configuration/saml/), but if you use the internal user database, you can use the REST API to [add them manually]({{site.url}}{{site.baseurl}}/security/access-control/api#create-user).
|
||||
|
||||
Only admin users can assign backend roles to users.
|
||||
{: .note}
|
||||
|
||||
When assigning backend roles, consider the following example of two users: `alice` and `bob`.
|
||||
|
||||
The following request assigns the user `alice` the `analyst` backend role:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/internalusers/alice
|
||||
{
|
||||
"password": "alice",
|
||||
"backend_roles": [
|
||||
"analyst"
|
||||
],
|
||||
"attributes": {}
|
||||
}
|
||||
```
|
||||
|
||||
The next request assigns the user `bob` the `human-resources` backend role:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/internalusers/bob
|
||||
{
|
||||
"password": "bob",
|
||||
"backend_roles": [
|
||||
"human-resources"
|
||||
],
|
||||
"attributes": {}
|
||||
}
|
||||
```
|
||||
|
||||
Finally, the last request assigns both `alice` and `bob` the role that gives them full access to ML Commons:
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/rolesmapping/ml_full_access
|
||||
{
|
||||
"backend_roles": [],
|
||||
"hosts": [],
|
||||
"users": [
|
||||
"alice",
|
||||
"bob"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
If `alice` creates a model group and assigns it the `analyst` backend role, `bob` cannot access this model.
|
||||
|
||||
## Enabling model access control
|
||||
|
||||
You can enable model access control dynamically as follows:
|
||||
|
||||
```json
|
||||
PUT _cluster/settings
|
||||
{
|
||||
"transient": {
|
||||
"plugins.ml_commons.model_access_control_enabled": "true"
|
||||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
## Registering a model group
|
||||
|
||||
Use the `_register` endpoint to register a model group. You can register a model group with a `public`, `private`, or `restricted` access mode.
|
||||
|
||||
### Path and HTTP method
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/model_groups/_register
|
||||
```
|
||||
|
||||
### Request fields
|
||||
|
||||
The following table lists the available request fields.
|
||||
|
||||
Field |Data type | Description
|
||||
:--- | :--- | :---
|
||||
`name` | String | The model group name. Required.
|
||||
`description` | String | The model group description. Optional.
|
||||
`model_access_mode` | String | The access mode for this model. Valid values are `public`, `private`, and `restricted`. When this parameter is set to `restricted`, you must specify either `backend_roles` or `add_all_backend_roles`, but not both. Optional. Default is `restricted`.
|
||||
`backend_roles` | Array | A list of the model owner's backend roles to add to the model. Can be specified only if the `model_access_mode` is `restricted`. Cannot be specified at the same time as `add_all_backend_roles`. Optional.
|
||||
`add_all_backend_roles` | Boolean | If `true`, all backend roles of the model owner are added to the model group. Default is `false`. Cannot be specified at the same time as `backend_roles`. Admin users cannot set this parameter to `true`. Optional.
|
||||
|
||||
#### Example request
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/model_groups/_register
|
||||
{
|
||||
"name": "test_model_group_public",
|
||||
"description": "This is a public model group",
|
||||
"model_access_mode": "public"
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"model_group_id": "GDNmQ4gBYW0Qyy5ZcBcg",
|
||||
"status": "CREATED"
|
||||
}
|
||||
```
|
||||
|
||||
### Response fields
|
||||
|
||||
The following table lists the available response fields.
|
||||
|
||||
Field |Data type | Description
|
||||
:--- | :--- | :---
|
||||
`model_group_id` | String | The model group ID that you can use to access this model group.
|
||||
`status` | String | The operation status.
|
||||
|
||||
### Registering a public model group
|
||||
|
||||
If you register a model group with a `public` access mode, any model in this model group will be accessible to any user with access to the cluster. The following request registers a public model group:
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/model_groups/_register
|
||||
{
|
||||
"name": "test_model_group_public",
|
||||
"description": "This is a public model group",
|
||||
"model_access_mode": "public"
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Registering a restricted model group
|
||||
|
||||
To limit access by backend role, you must register a model group with the `restricted` access mode.
|
||||
|
||||
When registering a model group, you must attach one or more of your backend roles to the model using one but not both of the following methods:
|
||||
- Provide a list of backend roles in the `backend_roles` parameter.
|
||||
- Set the `add_all_backend_roles` parameter to `true` to add all your backend roles to the model group. This option is not available to admin users.
|
||||
|
||||
Any user who shares a backend role with the model group can access any model in this model group. This grants the user the permissions included with the user role that is mapped to the backend role.
|
||||
|
||||
An admin user can access all model groups regardless of their access mode.
|
||||
{: .note}
|
||||
|
||||
#### Example request: A list of backend roles
|
||||
|
||||
The following request registers a restricted model group, which can be accessed only by users with the `IT` backend role:
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/model_groups/_register
|
||||
{
|
||||
"name": "model_group_test",
|
||||
"description": "This is an example description",
|
||||
"model_access_mode": "restricted",
|
||||
"backend_roles" : ["IT"]
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example request: All backend roles
|
||||
|
||||
The following request registers a restricted model group, adding all backend roles of the user to the model group:
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/model_groups/_register
|
||||
{
|
||||
"name": "model_group_test",
|
||||
"description": "This is an example description",
|
||||
"model_access_mode": "restricted",
|
||||
"add_all_backend_roles": "true"
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Registering a private model group
|
||||
|
||||
If you register a model group with a `private` access mode, any model in this model group will be accessible only to you and the admin users. The following request registers a private model group:
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/model_groups/_register
|
||||
{
|
||||
"name": "model_group_test",
|
||||
"description": "This is an example description",
|
||||
"model_access_mode": "private"
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Registering a model group in a cluster where model access control is disabled
|
||||
|
||||
If model access control is disabled on your cluster (one of the [prerequisites](#model-access-control-prerequisites) is not met), you can register a model group with a `name` and `description` but cannot specify any of the access parameters (`model_access_name`, `backend_roles`, or `add_backend_roles`). By default, in such a cluster, all model groups are public.
|
||||
|
||||
## Updating a model group
|
||||
|
||||
To update a model group, send a request to the `<model_group_id>_update` endpoint.
|
||||
|
||||
When updating a model group, the following restrictions apply:
|
||||
|
||||
- The model owner or an admin user can update all fields. Any user who shares one or more backend roles with the model group can update the `name` and `description` fields only.
|
||||
- When updating the `model_access_mode` to `restricted`, you must specify one but not both `backend_roles` or `add_all_backend_roles`.
|
||||
|
||||
### Path and HTTP method
|
||||
|
||||
```json
|
||||
PUT /_plugins/_ml/model_groups/<model_group_id>_update
|
||||
```
|
||||
|
||||
### Request fields
|
||||
|
||||
Refer to [Request fields](#request-fields-1) for request field descriptions.
|
||||
|
||||
#### Example request
|
||||
|
||||
```json
|
||||
PUT /_plugins/_ml/model_groups/<model_group_id>_update
|
||||
{
|
||||
"name": "model_group_test",
|
||||
"description": "This is an example description",
|
||||
"add_all_backend_roles": true
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
### Updating a model group in a cluster where model access control is disabled
|
||||
|
||||
If model access control is disabled on your cluster (one of the [prerequisites](#model-access-control-prerequisites) is not met), you can update only the `name` and `description` of a model group but cannot update any of the access parameters (`model_access_name`, `backend_roles`, or `add_backend_roles`).
|
||||
|
||||
## Searching for a model group
|
||||
|
||||
When you search for a model group, only those model groups to which you have access will be returned. For example, for a match all query, model groups that will be returned are:
|
||||
|
||||
- All public model groups in the index
|
||||
- Private model groups for which you are the owner
|
||||
- Model groups that share at least one of the `backend_roles` with you
|
||||
|
||||
### Path and HTTP method
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/model_groups/_search
|
||||
GET /_plugins/_ml/model_groups/_search
|
||||
```
|
||||
|
||||
#### Example request: Match all
|
||||
|
||||
The following request is sent by `user1` who has the `IT` and `HR` roles:
|
||||
|
||||
```json
|
||||
POST /_plugins/_ml/model_groups/_search
|
||||
{
|
||||
"query": {
|
||||
"match_all": {}
|
||||
},
|
||||
"size": 1000
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"took": 31,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 1,
|
||||
"successful": 1,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 7,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 1,
|
||||
"hits": [
|
||||
{
|
||||
"_index": ".plugins-ml-model-group",
|
||||
"_id": "TRqZfYgBD7s2oEFdvrQj",
|
||||
"_version": 1,
|
||||
"_seq_no": 2,
|
||||
"_primary_term": 1,
|
||||
"_score": 1,
|
||||
"_source": {
|
||||
"backend_roles": [
|
||||
"HR",
|
||||
"IT"
|
||||
],
|
||||
"owner": {
|
||||
"backend_roles": [
|
||||
"HR",
|
||||
"IT"
|
||||
],
|
||||
"custom_attribute_names": [],
|
||||
"roles": [
|
||||
"ml_full_access",
|
||||
"own_index",
|
||||
"test_ml"
|
||||
],
|
||||
"name": "user1",
|
||||
"user_requested_tenant": "__user__"
|
||||
},
|
||||
"created_time": 1685734407714,
|
||||
"access": "restricted",
|
||||
"latest_version": 0,
|
||||
"last_updated_time": 1685734407714,
|
||||
"name": "model_group_test",
|
||||
"description": "This is an example description"
|
||||
}
|
||||
},
|
||||
{
|
||||
"_index": ".plugins-ml-model-group",
|
||||
"_id": "URqZfYgBD7s2oEFdyLTm",
|
||||
"_version": 1,
|
||||
"_seq_no": 3,
|
||||
"_primary_term": 1,
|
||||
"_score": 1,
|
||||
"_source": {
|
||||
"backend_roles": [
|
||||
"IT"
|
||||
],
|
||||
"owner": {
|
||||
"backend_roles": [
|
||||
"HR",
|
||||
"IT"
|
||||
],
|
||||
"custom_attribute_names": [],
|
||||
"roles": [
|
||||
"ml_full_access",
|
||||
"own_index",
|
||||
"test_ml"
|
||||
],
|
||||
"name": "user1",
|
||||
"user_requested_tenant": "__user__"
|
||||
},
|
||||
"created_time": 1685734410470,
|
||||
"access": "restricted",
|
||||
"latest_version": 0,
|
||||
"last_updated_time": 1685734410470,
|
||||
"name": "model_group_test",
|
||||
"description": "This is an example description"
|
||||
}
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Example request: Search for model groups with an owner name
|
||||
|
||||
The following request to search for model groups of `user` is sent by `user2` who has the `IT` backend role:
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/model_groups/_search
|
||||
{
|
||||
"query": {
|
||||
"bool": {
|
||||
"must": [
|
||||
{
|
||||
"nested": {
|
||||
"query": {
|
||||
"term": {
|
||||
"owner.name.keyword": {
|
||||
"value": "user1",
|
||||
"boost": 1
|
||||
}
|
||||
}
|
||||
},
|
||||
"path": "owner",
|
||||
"ignore_unmapped": false,
|
||||
"score_mode": "none",
|
||||
"boost": 1
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"took": 6,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 1,
|
||||
"successful": 1,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 4,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 0,
|
||||
"hits": [
|
||||
{
|
||||
"_index": ".plugins-ml-model-group",
|
||||
"_id": "TRqZfYgBD7s2oEFdvrQj",
|
||||
"_version": 1,
|
||||
"_seq_no": 2,
|
||||
"_primary_term": 1,
|
||||
"_score": 0,
|
||||
"_source": {
|
||||
"backend_roles": [
|
||||
"HR",
|
||||
"IT"
|
||||
],
|
||||
"owner": {
|
||||
"backend_roles": [
|
||||
"HR",
|
||||
"IT"
|
||||
],
|
||||
"custom_attribute_names": [],
|
||||
"roles": [
|
||||
"ml_full_access",
|
||||
"own_index",
|
||||
"test_ml"
|
||||
],
|
||||
"name": "user1",
|
||||
"user_requested_tenant": "__user__"
|
||||
},
|
||||
"created_time": 1685734407714,
|
||||
"access": "restricted",
|
||||
"latest_version": 0,
|
||||
"last_updated_time": 1685734407714,
|
||||
"name": "model_group_test",
|
||||
"description": "This is an example description"
|
||||
}
|
||||
},
|
||||
...
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Example request: Search for model groups with a model group ID
|
||||
|
||||
```json
|
||||
GET /_plugins/_ml/model_groups/_search
|
||||
{
|
||||
"query": {
|
||||
"bool": {
|
||||
"must": [
|
||||
{
|
||||
"terms": {
|
||||
"_id": [
|
||||
"HyPNK4gBwNxGowI0AtDk"
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"took": 2,
|
||||
"timed_out": false,
|
||||
"_shards": {
|
||||
"total": 1,
|
||||
"successful": 1,
|
||||
"skipped": 0,
|
||||
"failed": 0
|
||||
},
|
||||
"hits": {
|
||||
"total": {
|
||||
"value": 1,
|
||||
"relation": "eq"
|
||||
},
|
||||
"max_score": 1,
|
||||
"hits": [
|
||||
{
|
||||
"_index": ".plugins-ml-model-group",
|
||||
"_id": "HyPNK4gBwNxGowI0AtDk",
|
||||
"_version": 3,
|
||||
"_seq_no": 16,
|
||||
"_primary_term": 5,
|
||||
"_score": 1,
|
||||
"_source": {
|
||||
"backend_roles": [
|
||||
"IT"
|
||||
],
|
||||
"owner": {
|
||||
"backend_roles": [
|
||||
"",
|
||||
"HR",
|
||||
"IT"
|
||||
],
|
||||
"custom_attribute_names": [],
|
||||
"roles": [
|
||||
"ml_full_access",
|
||||
"own_index",
|
||||
"test-ml"
|
||||
],
|
||||
"name": "user1",
|
||||
"user_requested_tenant": null
|
||||
},
|
||||
"created_time": 1684362035938,
|
||||
"latest_version": 2,
|
||||
"last_updated_time": 1684362571300,
|
||||
"name": "model_group_test",
|
||||
"description": "This is an example description"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Deleting a model group
|
||||
|
||||
You can only delete a model group if it does not contain any model versions.
|
||||
{: .important}
|
||||
|
||||
If model access control is enabled on your cluster, only the owner or users with matching backend roles can delete the model group. Any users can delete any public model group.
|
||||
|
||||
If model access control is disabled on your cluster, users with the `delete model group API` permission can delete any model group.
|
||||
|
||||
Admin users can delete any model group.
|
||||
{: .note}
|
||||
|
||||
#### Example request
|
||||
|
||||
```json
|
||||
DELETE _plugins/_ml/model_groups/<model_group_id>
|
||||
```
|
||||
{% include copy-curl.html %}
|
||||
|
||||
#### Example response
|
||||
|
||||
```json
|
||||
{
|
||||
"_index": ".plugins-ml-model-group",
|
||||
"_id": "l8nnQogByXnLJ-QNpEk2",
|
||||
"_version": 5,
|
||||
"result": "deleted",
|
||||
"_shards": {
|
||||
"total": 2,
|
||||
"successful": 1,
|
||||
"failed": 0
|
||||
},
|
||||
"_seq_no": 70,
|
||||
"_primary_term": 23
|
||||
}
|
||||
```
|
||||
Loading…
Reference in New Issue