iSharkFly-Docs
/
opensearch-docs-cn
mirror of https://github.com/iSharkFly-Docs/opensearch-docs-cn
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Refactor ML section - local and remote models (#5609) 

* Refactor ML section - local and remote models

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Added command to calculate checksum

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Add ONNX format to register API

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Add sparse encoding predict example

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Add API section

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Refactor the API section

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Typo

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Implemented Vale comments

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Add get connector API

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Reword heading

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>

* Addressed tech review 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>

---------

Signed-off-by: Fanit Kolchina <kolchfa@amazon.com>
Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com>
Co-authored-by: Melissa Vagi <vagimeli@amazon.com>
This commit is contained in:
kolchfa-aws 2023-11-17 15:59:27 -05:00 committed by GitHub
parent ddbb16599b
commit 826e6771ed
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
46 changed files with 3040 additions and 2234 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

193
_ml-commons-plugin/algorithms.md
View File

@ -9,7 +9,7 @@ nav_order: 30
ML Commons supports various algorithms to help train and predict machine learning (ML) models or test data-driven predictions without a model. This page outlines the algorithms supported by the ML Commons plugin and the API operations they support.
## Common limitation
## Common limitations
Except for the Localization algorithm, all of the following algorithms can only support retrieving 10,000 documents from an index as an input.
@ -19,17 +19,17 @@ K-means is a simple and popular unsupervised clustering ML algorithm built on to
### Parameters
Parameter | Type | Description | Default Value
Parameter | Type | Description | Default value
:--- |:--- | :--- | :---
centroids | integer | The number of clusters in which to group the generated data | `2`
iterations | integer | The number of iterations to perform against the data until a mean generates | `10`
distance_type | enum, such as `EUCLIDEAN`, `COSINE`, or `L1` | The type of measurement from which to measure the distance between centroids | `EUCLIDEAN`
`centroids` | integer | The number of clusters in which to group the generated data | `2`
`iterations` | integer | The number of iterations to perform against the data until a mean generates | `10`
`distance_type` | enum, such as `EUCLIDEAN`, `COSINE`, or `L1` | The type of measurement from which to measure the distance between centroids | `EUCLIDEAN`
### APIs
### Supported APIs
* [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)
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train/)
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/)
* [Train and predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train-and-predict/)
### Example
@ -55,7 +55,7 @@ POST /_plugins/_ml/_train/kmeans
### Limitations
The training process supports multi-threads, but the number of threads should be less than half of the number of CPUs.
The training process supports multithreading, but the number of threads must be less than half of the number of CPUs.
## Linear regression
@ -63,28 +63,28 @@ Linear regression maps the linear relationship between inputs and outputs. In ML
### Parameters
Parameter | Type | Description | Default Value
Parameter | Type | Description | Default value
:--- |:--- | :--- | :---
learningRate | Double | The initial step size used in an iterative optimization algorithm. | 0.01
momentumFactor | Double | The extra weight factors that accelerate the rate at which the weight is adjusted. This helps move the minimization routine out of local minima. | 0
epsilon | Double | The value for stabilizing gradient inversion. | 1.00E-06
beta1 | Double | The exponential decay rates for the moment estimates. | 0.9
beta2 | Double | The exponential decay rates for the moment estimates. | 0.99
decayRate | Double | The Root Mean Squared Propagation (RMSProp). | 0.9
momentumType | MomentumType | The defined Stochastic Gradient Descent (SGD) momentum type that helps accelerate gradient vectors in the right directions, leading to a fast convergence.| STANDARD
optimizerType | OptimizerType | The optimizer used in the model. | SIMPLE_SGD
`learningRate` | Double | The initial step size used in an iterative optimization algorithm. | `0.01`
`momentumFactor` | Double | The extra weight factors that accelerate the rate at which the weight is adjusted. This helps move the minimization routine out of local minima. | `0`
`epsilon` | Double | The value for stabilizing gradient inversion. | `1.00E-06`
`beta1` | Double | The exponential decay rates for the moment estimates. | `0.9`
`beta2` | Double | The exponential decay rates for the moment estimates. | `0.99`
`decayRate` | Double | The Root Mean Squared Propagation (RMSProp). | `0.9`
`momentumType` | String | The defined Stochastic Gradient Descent (SGD) momentum type that helps accelerate gradient vectors in the right directions, leading to a fast convergence.| `STANDARD`
`optimizerType` | String | The optimizer used in the model. | `SIMPLE_SGD`
### APIs
### Supported APIs
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#training-the-model)
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict)
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train/)
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/)
### Example
The following example creates a new prediction based on the previously trained linear regression model.
**Request**
#### Example request
```json
POST _plugins/_ml/_predict/LINEAR_REGRESSION/ROZs-38Br5eVE0lTsoD9
@ -121,7 +121,7 @@ POST _plugins/_ml/_predict/LINEAR_REGRESSION/ROZs-38Br5eVE0lTsoD9
}
```
**Response**
#### Example response
```json
{
@ -155,44 +155,45 @@ ML Commons only supports the linear Stochastic gradient trainer or optimizer, wh
[Random Cut Forest](https://github.com/aws/random-cut-forest-by-aws) (RCF) is a probabilistic data structure used primarily for unsupervised anomaly detection. Its use also extends to density estimation and forecasting. OpenSearch leverages RCF for anomaly detection. ML Commons supports two new variants of RCF for different use cases:
* Batch RCF: Detects anomalies in non-time series data.
* Fixed in time (FIT) RCF: Detects anomalies in time series data.
* Batch RCF: Detects anomalies in non-time-series data.
* Fixed in time (FIT) RCF: Detects anomalies in time-series data.
### Parameters
RCF supports the following parameters.
#### Batch RCF
Parameter | Type | Description | Default Value
Parameter | Type | Description | Default value
:--- |:--- | :--- | :---
number_of_trees | integer | The number of trees in the forest. | 30
sample_size | integer | The same size used by the stream samplers in the forest. | 256
output_after | integer | The number of points required by stream samplers before results return. | 32
training_data_size | integer | The size of your training data. | Dataset size
anomaly_score_threshold | double | The threshold of the anomaly score. | 1.0
`number_of_trees` | integer | The number of trees in the forest. | `30`
`sample_size` | integer | The same size used by the stream samplers in the forest. | `256`
`output_after` | integer | The number of points required by stream samplers before results return. | `32`
`training_data_size` | integer | The size of your training data. | Dataset size
`anomaly_score_threshold` | double | The threshold of the anomaly score. | `1.0`
#### Fit RCF
All parameters are optional except `time_field`.
Parameter | Type | Description | Default Value
Parameter | Type | Description | Default value
:--- |:--- | :--- | :---
number_of_trees | integer | The number of trees in the forest. | 30
shingle_size | integer | A shingle, or a consecutive sequence of the most recent records. | 8
sample_size | integer | The sample size used by stream samplers in the forest. | 256
output_after | integer | The number of points required by stream samplers before results return. | 32
time_decay | double | The decay factor used by stream samplers in the forest. | 0.0001
anomaly_rate | double | The anomaly rate. | 0.005
time_field | string | (**Required**) The time field for RCF to use as time series data. | N/A
date_format | string | The date and time format for the `time_field` field. | "yyyy-MM-ddHH:mm:ss"
time_zone | string | The time zone for the `time_field` field. | "UTC"
`number_of_trees` | integer | The number of trees in the forest. | `30`
`shingle_size` | integer | A shingle, or a consecutive sequence of the most recent records. | `8`
`sample_size` | integer | The sample size used by stream samplers in the forest. | `256`
`output_after` | integer | The number of points required by stream samplers before results return. | `32`
`time_decay` | double | The decay factor used by stream samplers in the forest. | `0.0001`
`anomaly_rate` | double | The anomaly rate. | `0.005`
`time_field` | string | (**Required**) The time field for RCF to use as time-series data. | N/A
`date_format` | string | The date and time format for the `time_field` field. | `yyyy-MM-ddHH:mm:ss`
`time_zone` | string | The time zone for the `time_field` field. | `UTC`
### APIs
* [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)
### Supported APIs
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train/)
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/)
* [Train and predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train-and-predict/)
### Limitations
@ -204,22 +205,24 @@ RCF Summarize is a clustering algorithm based on the Clustering Using Representa
### Parameters
| Parameter | Type | Description | Default Value |
| Parameter | Type | Description | Default value |
|---|---|---|---|
| max_k | integer | The max allowed number of centroids. | 2 |
| distance_type | enum, such as `EUCLIDEAN`, `L1`, `L2`, or `LInfinity` | The type of measurement used to measure the distance between centroids. | EUCLIDEAN |
| `max_k` | Integer | The max allowed number of centroids. | 2 |
| `distance_type` | String. Valid values are `EUCLIDEAN`, `L1`, `L2`, and `LInfinity` | The type of measurement used to measure the distance between centroids. | `EUCLIDEAN` |
### APIs
### Supported APIs
* [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)
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train/)
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/)
* [Train and predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train-and-predict/)
### Example: Train and predict
The following example estimates cluster centers and provides cluster labels for each sample in a given data frame.
```bash
#### Example request
```json
POST _plugins/_ml/_train_predict/RCF_SUMMARIZE
{
"parameters": {
@ -256,7 +259,7 @@ POST _plugins/_ml/_train_predict/RCF_SUMMARIZE
}
```
**Response**
#### Example response
The `rows` parameter within the prediction result has been modified for length. In your response, expect more rows and columns to be contained within the response body.
@ -293,24 +296,24 @@ The Localization algorithm finds subset-level information for aggregate data (fo
All parameters are required except `filter_query` and `anomaly_start`.
Parameter | Type | Description | Default Value
Parameter | Type | Description | Default value
:--- | :--- | :--- | :---
index_name | String | The data collection to analyze. | N/A
attribute_field_names | List<String> | The fields for entity keys. | N/A
aggregations | List<AggregationBuilder> | The fields and aggregation for values. | N/A
time_field_name | String | The timestamp field. | null
start_time | Long | The beginning of the time range. | 0
end_time | Long | The end of the time range. | 0
min_time_interval | Long | The minimum time interval/scale for analysis. | 0
num_outputs | integer | The maximum number of values from localization/slicing. | 0
filter_query | Long | (Optional) Reduces the collection of data for analysis. | Optional.empty()
anomaly_star | QueryBuilder | (Optional) The time after which the data will be analyzed. | Optional.empty()
`index_name` | String | The data collection to analyze. | N/A
`attribute_field_names` | List | The fields for entity keys. | N/A
`aggregations` | List | The fields and aggregation for values. | N/A
`time_field_name` | String | The timestamp field. | `null`
`start_time` | Long | The beginning of the time range. | `0`
`end_time` | Long | The end of the time range. | 0``
`min_time_interval` | Long | The minimum time interval/scale for analysis. | `0`
`num_outputs` | Integer | The maximum number of values from localization/slicing. | `0`
`filter_query` | Long | (Optional) Reduces the collection of data for analysis. | N/A
anomal`y_star | Time units | (Optional) The time after which the data will be analyzed. | N/A
### Example: Execute localization
The following example executes Localization against an RCA index.
**Request**
#### Example request
```bash
POST /_plugins/_ml/_execute/anomaly_localization
@ -336,7 +339,7 @@ POST /_plugins/_ml/_execute/anomaly_localization
}
```
**Response**
#### Example response
The API responds with the sum of the contribution and base values per aggregation, every time the algorithm executes in the specified time interval.
@ -411,26 +414,26 @@ A classification algorithm, logistic regression models the probability of a disc
### Parameters
| Parameter | Type | Description | Default Value |
| Parameter | Type | Description | Default value |
|---|---|---|---|
| learningRate | Double | The initial step size used in an iterative optimization algorithm. | 1 |
| momentumFactor | Double | The extra weight factors that accelerate the rate at which the weight is adjusted. This helps move the minimization routine out of local minima. | 0 |
| epsilon | Double | The value for stabilizing gradient inversion. | 0.1 |
| beta1 | Double | The exponential decay rates for the moment estimates. | 0.9 |
| beta2 | Double | The exponential decay rates for the moment estimates. | 0.99 |
| decayRate | Double | The Root Mean Squared Propagation (RMSProp). | 0.9 |
| momentumType | MomentumType | The Stochastic Gradient Descent (SGD) momentum that helps accelerate gradient vectors in the right direction, leading to faster convergence between vectors. | STANDARD |
| optimizerType | OptimizerType | The optimizer used in the model. | AdaGrad |
| target | String | The target field. | null |
| objectiveType | ObjectiveType | The objective function type. | LogMulticlass |
| epochs | Integer | The number of iterations. | 5 |
| batchSize | Integer | The size of minbatches. | 1 |
| loggingInterval | Integer | The interval of logs lost after many iterations. The interval is `1` if the algorithm contains no logs. | 1000 |
| `learningRate` | Double | The initial step size used in an iterative optimization algorithm. | `1` |
| `momentumFactor` | Double | The extra weight factors that accelerate the rate at which the weight is adjusted. This helps move the minimization routine out of local minima. | `0` |
| `epsilon` | Double | The value for stabilizing gradient inversion. | `0.1` |
| `beta1` | Double | The exponential decay rates for the moment estimates. | `0.9` |
| `beta2` | Double | The exponential decay rates for the moment estimates. | `0.99` |
| `decayRate` | Double | The Root Mean Squared Propagation (RMSProp). | `0.9` |
| `momentumType` | String | The Stochastic Gradient Descent (SGD) momentum that helps accelerate gradient vectors in the right direction, leading to faster convergence between vectors. | `STANDARD` |
| `optimizerType` | String | The optimizer used in the model. | `AdaGrad` |
| `target` | String | The target field. | null |
| `objectiveType` | String | The objective function type. | `LogMulticlass` |
| `epochs` | Integer | The number of iterations. | `5` |
| `batchSize` | Integer | The size of min batches. | `1` |
| `loggingInterval` | Integer | The interval of logs lost after many iterations. The interval is `1` if the algorithm contains no logs. | `1000` |
### APIs
### Supported APIs
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#training-the-model)
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict)
* [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train/)
* [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/)
### Example: Train/Predict with Iris data
@ -507,7 +510,7 @@ This example uses a multi-class logistic regression categorization methodology.
}
```
**Response**
#### Example response
The `model_id` will be used to predict the class of the Iris.
@ -593,7 +596,7 @@ POST _plugins/_ml/_predict/logistic_regression/SsfQaoIBEoC4g4joZiyD
}
```
**Response**
#### Example response
```json
{
@ -640,7 +643,7 @@ The metrics correlation algorithm finds events in a set of metrics data. The alg
To enable the metrics correlation algorithm, update the following cluster setting:
```
```json
PUT /_cluster/settings
{
"persistent" : {
@ -659,24 +662,24 @@ metrics | Array | A list of metrics within the time series that can be correlate
### Input
The metrics correlation input is an $M$ x $T$ array of metrics data, where M is the number of metrics and T is the length of each individual sequence of metric values.
The metrics correlation input is an M x T array of metrics data, where M is the number of metrics and T is the length of each individual sequence of metric values.
When inputting metrics into the algorithm, assume the following:
1. For each metric, the input sequence has the same length, $T$.
1. For each metric, the input sequence has the same length, T.
2. All input metrics should have the same corresponding set of timestamps.
3. The total number of data points are $M$ * $T$ <= 10000.
3. The total number of data points are M * T <= 10000.
### Example: Simple metrics correlation
The following example inputs the number of metrics ($M$) as 3 and the number of timesteps ($T$) as 128:
The following example inputs the number of metrics (M) as 3 and the number of time steps (T) as 128:
```
```json
POST /_plugins/_ml/_execute/METRICS_CORRELATION
{"metrics": [[-1.1635416, -1.5003631, 0.46138194, 0.5308311, -0.83149344, -3.7009873, -3.5463789, 0.22571462, -5.0380244, 0.76588845, 1.236113, 1.8460795, 1.7576948, 0.44893077, 0.7363948, 0.70440894, 0.89451003, 4.2006273, 0.3697659, 2.2458954, -2.302939, -1.7706926, 1.7445002, -1.5246059, 0.07985192, -2.7756078, 1.0002468, 1.5977372, 2.9152713, 1.4172368, -0.26551363, -2.2883027, 1.5882446, 2.0145164, 3.4862874, -1.2486862, -2.4811826, -0.17609037, -2.1095612, -1.2184235, 0.63118523, -1.8909532, 2.039797, -0.5317177, -2.2922578, -2.0179775, -0.07992507, -0.12554549, -0.2553092, 1.1450123, -0.4640453, -2.190223, -4.671612, -1.5076426, 1.635445, -1.1394824, -0.7503817, 0.98424894, -0.38896716, 1.0328646, 1.9543738, -0.5236269, 0.14298044, 3.2963762, 8.1641035, 5.717064, 7.4869685, 2.5987444, 11.018798, 9.151356, 5.7354255, 6.862203, 3.0524514, 4.431755, 5.1481285, 7.9548607, 7.4519925, 6.09533, 7.634116, 8.898271, 3.898491, 9.447067, 8.197385, 5.8284273, 5.804283, 7.7688456, 10.574343, 7.5679493, 7.1888094, 7.1107903, 8.454468, 8.066334, 8.83665, 7.11204, 4.4898267, 8.614764, 6.336754, 11.577503, 3.3998494, 9.501525, 13.17289, 6.1116023, 5.143777, 2.7813284, 3.7917604, 7.1683135, 7.627272, 7.290255, 3.1299121, 7.089733, 9.140584, 8.844729, 9.403275, 10.220029, 8.039719, 8.85549, 4.034555, 4.412663, 7.54451, 7.2116737, 4.6346946, 7.0044127, 9.7557, 10.982841, 5.897937, 6.870126, 3.5638695, 5.7872133], [1.3037996, 2.7976995, -0.12042701, 1.3688855, 1.6955005, -2.2575269, 0.080582514, 3.011721, -0.4320283, 3.2440786, -1.0321085, 1.2346085, -2.3152106, -0.9783513, 0.6837618, 1.5320586, -1.6148578, -0.94538075, 0.55978125, -4.7430468, 3.466028, 2.3792691, 1.3269067, -0.35359794, -1.5547276, 0.5202475, 1.0269136, -1.7531714, 0.43987304, -0.18845831, 2.3086758, 2.519588, 2.0116413, 0.019745048, -0.010070452, 2.496933, 1.1557871, 0.08433053, 1.375894, -1.2135965, -1.2588277, -0.31454003, 0.045949124, -1.7518936, -2.3533764, -2.0125146, 0.10255043, 1.1782314, 2.4579153, -0.8780899, -4.1442213, 3.8300152, 2.772975, 2.6803262, 0.9867382, 0.77618766, 0.46541777, 3.8959959, -2.1713195, 0.10609512, -0.26438138, -2.145317, 3.6734529, 1.4830295, -5.3445525, -10.6427765, -8.300354, -1.9608921, -6.6779685, -10.019544, -8.341513, -9.607174, -7.2441607, -3.411102, -6.180552, -8.318714, -6.060591, -7.790343, -5.9695, -7.9429936, -3.775652, -5.2827606, -3.7168224, -6.729588, -9.761094, -7.4683576, -7.2595067, -6.6790915, -9.832726, -8.352172, -6.936336, -8.252518, -6.787475, -9.091013, -11.465944, -6.712504, -8.987438, -6.946672, -8.877166, -6.7854185, -3.6417139, -6.1036086, -5.360772, -4.0435786, -4.5864973, -6.971063, -10.522461, -6.3692527, -4.387658, -9.723745, -4.7020173, -5.097396, -9.903703, -4.882414, -4.1999683, -6.7829437, -6.2555966, -8.121125, -5.334131, -9.174302, -3.9752126, -4.179469, -8.335524, -9.359406, -6.4938803, -6.794677, -8.382997, -9.879416], [1.8792984, -3.1561708, -0.8443318, -1.998743, -0.6319316, 2.4614046, -0.44511616, 0.82785237, 1.7911717, -1.8172283, 0.46574894, -1.8691323, 3.9586513, 0.8078605, 0.9049874, 5.4086914, -0.7425967, -0.20115769, -1.197923, 2.741789, 0.85432875, -1.1688408, -1.7771784, 1.615249, -4.1103697, 0.4721327, -2.75669, -0.38393462, -3.1137516, -2.2572582, 0.9580673, -3.7139492, -0.68303126, 1.6007807, 0.6313973, -2.5115106, 0.703251, 2.4844077, -1.7405633, -3.007687, 2.372802, 2.4684637, 0.6443977, -3.1433117, 0.05976736, -1.9809214, 3.514713, 2.1880944, 1.242541, 1.8236228, 0.8642841, -0.17313614, 1.7042321, 0.8298376, 4.2443194, 0.13983983, 1.1940852, 2.5076652, 39.285202, 82.73858, 44.707516, -4.267148, 0.25930226, 0.20799652, -3.7213502, 1.475217, -1.2394199, -0.0034497892, 1.1413965, 55.18923, -2.2969518, -4.1400924, -2.4707043, 43.193188, -0.19258368, 3.471275, 1.1374166, 1.2147579, 4.13017, -2.0576499, 2.1529694, -0.28360432, 0.8477302, -0.63012695, 1.2569811, 1.943168, 0.17070436, 3.2358394, -2.3737662, 0.77060974, 4.99065, 3.1079204, 3.6347675, 0.6801177, -2.2205186, 1.0961101, -2.4445753, -2.0919478, -2.895031, 2.5458927, 0.38599384, 1.0492333, -0.081834644, -7.4079595, -2.1785216, -0.7277175, -2.7413428, -3.2083786, 3.2958643, -1.1839997, 5.4849496, 2.0259023, 5.607272, -1.0125756, 3.721461, 2.5715313, 0.7741753, -0.55034757, 0.7526307, -2.6758716, -2.964664, -0.57379586, -0.28817406, -3.2334063, -0.22387607, -2.0793931, -6.4562697, 0.80134094]]}
```
**Response**
#### Example response
The API returns the following information:

1277
_ml-commons-plugin/api.md
View File

File diff suppressed because it is too large Load Diff

58
_ml-commons-plugin/api/connector-apis/create-connector.md Normal file
View File

@ -0,0 +1,58 @@
---
layout: default
title: Create connector
parent: Connector APIs
grand_parent: ML Commons API
nav_order: 10
---
# Create a connector
Creates a standalone connector. For more information, see [Connectors]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/connectors/).
## Path and HTTP methods
```json
POST /_plugins/_ml/connectors/_create
```
#### Example request
To create a standalone connector, send a request to the `connectors/_create` endpoint and provide all of the parameters described in [Connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/blueprints/):
```json
POST /_plugins/_ml/connectors/_create
{
"name": "OpenAI Chat Connector",
"description": "The connector to public OpenAI model service for GPT 3.5",
"version": 1,
"protocol": "http",
"parameters": {
"endpoint": "api.openai.com",
"model": "gpt-3.5-turbo"
},
"credential": {
"openAI_key": "..."
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://${parameters.endpoint}/v1/chat/completions",
"headers": {
"Authorization": "Bearer ${credential.openAI_key}"
},
"request_body": "{ \"model\": \"${parameters.model}\", \"messages\": ${parameters.messages} }"
}
]
}
```
{% include copy-curl.html %}
#### Example response
```json
{
"connector_id": "a1eMb4kBJ1eYAeTMAljY"
}
```

24
_ml-commons-plugin/api/connector-apis/delete-connector.md Normal file
View File

@ -0,0 +1,24 @@
---
layout: default
title: Delete connector
parent: Connector APIs
grand_parent: ML Commons API
nav_order: 30
---
# Delete a connector
Deletes a standalone connector. For more information, see [Connectors]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/connectors/).
## Path and HTTP methods
```json
DELETE /_plugins/_ml/connectors/<connector_id>
```
#### Example request
```json
DELETE /_plugins/_ml/connectors/KsAo1YsB0jLkkocY6j4U
```
{% include copy-curl.html %}

58
_ml-commons-plugin/api/connector-apis/get-connector.md Normal file
View File

@ -0,0 +1,58 @@
---
layout: default
title: Get connector
parent: Connector APIs
grand_parent: ML Commons API
nav_order: 20
---
# Get a connector
Use the `_search` endpoint to search for a connector.
To retrieve information about a connector, you can:
- [Get a connector by ID](#get-a-connector-by-id)
- [Search for a connector](#search-for-a-connector)
# Get a connector by ID
This API retrieves a connector by its ID.
## Path and HTTP methods
```json
GET /_plugins/_ml/connectors/<connector_id>
```
#### Example request
```json
GET /_plugins/_ml/connectors/N8AE1osB0jLkkocYjz7D
```
{% include copy-curl.html %}
## Search for a connector
This API searches for matching connectors using a query.
## Path and HTTP methods
```json
POST /_plugins/_ml/connectors/_search
GET /_plugins/_ml/connectors/_search
```
#### Example request
```json
POST /_plugins/_ml/connectors/_search
{
"query": {
"match_all": {}
},
"size": 1000
}
```
{% include copy-curl.html %}

17
_ml-commons-plugin/api/connector-apis/index.md Normal file
View File

@ -0,0 +1,17 @@
---
layout: default
title: Connector APIs
parent: ML Commons API
has_children: true
nav_order: 25
---
# Connector APIs
ML Commons supports the following connector APIs:
- [Create connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/connector-apis/create-connector/)
- [Search for a connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/connector-apis/get-connector/)
- [Delete connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/connector-apis/delete-connector/)
For more information, see [Connectors]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/connectors/).

155
_ml-commons-plugin/api/execute-algorithm.md Normal file
View File

@ -0,0 +1,155 @@
---
layout: default
title: Execute algorithm
parent: ML Commons API
nav_order: 30
---
# Execute algorithm
Some algorithms, such as [Localization]({{site.url}}{{site.baseurl}}/ml-commons-plugin/algorithms#localization), don't require trained models. You can run no-model-based algorithms using the `execute` API.
## Path and HTTP methods
```json
POST _plugins/_ml/_execute/<algorithm_name>
```
#### Example request: Execute localization
The following example uses the Localization algorithm to find subset-level information for aggregate data (for example, aggregated over time) that demonstrates the activity of interest, such as spikes, drops, changes, or anomalies.
```json
POST /_plugins/_ml/_execute/anomaly_localization
{
"index_name": "rca-index",
"attribute_field_names": [
"attribute"
],
"aggregations": [
{
"sum": {
"sum": {
"field": "value"
}
}
}
],
"time_field_name": "timestamp",
"start_time": 1620630000000,
"end_time": 1621234800000,
"min_time_interval": 86400000,
"num_outputs": 10
}
```
{% include copy-curl.html %}
#### Example response
```json
{
"results" : [
{
"name" : "sum",
"result" : {
"buckets" : [
{
"start_time" : 1620630000000,
"end_time" : 1620716400000,
"overall_aggregate_value" : 65.0
},
{
"start_time" : 1620716400000,
"end_time" : 1620802800000,
"overall_aggregate_value" : 75.0,
"entities" : [
{
"key" : [
"attr0"
],
"contribution_value" : 1.0,
"base_value" : 2.0,
"new_value" : 3.0
},
{
"key" : [
"attr1"
],
"contribution_value" : 1.0,
"base_value" : 3.0,
"new_value" : 4.0
},
{
"key" : [
"attr2"
],
"contribution_value" : 1.0,
"base_value" : 4.0,
"new_value" : 5.0
},
{
"key" : [
"attr3"
],
"contribution_value" : 1.0,
"base_value" : 5.0,
"new_value" : 6.0
},
{
"key" : [
"attr4"
],
"contribution_value" : 1.0,
"base_value" : 6.0,
"new_value" : 7.0
},
{
"key" : [
"attr5"
],
"contribution_value" : 1.0,
"base_value" : 7.0,
"new_value" : 8.0
},
{
"key" : [
"attr6"
],
"contribution_value" : 1.0,
"base_value" : 8.0,
"new_value" : 9.0
},
{
"key" : [
"attr7"
],
"contribution_value" : 1.0,
"base_value" : 9.0,
"new_value" : 10.0
},
{
"key" : [
"attr8"
],
"contribution_value" : 1.0,
"base_value" : 10.0,
"new_value" : 11.0
},
{
"key" : [
"attr9"
],
"contribution_value" : 1.0,
"base_value" : 11.0,
"new_value" : 12.0
}
]
},
...
]
}
}
]
}
```

23
_ml-commons-plugin/api/index.md Normal file
View File

@ -0,0 +1,23 @@
---
layout: default
title: ML Commons API
has_children: false
nav_order: 130
has_children: true
has_toc: false
redirect_from:
- /ml-commons-plugin/api/
---
# ML Commons API
ML Commons supports the following API types:
- [Model APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/index/)
- [Model group APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api//model-group-apis/index/)
- [Connector APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/connector-apis/index/)
- [Tasks APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/index/)
- [Train and Predict APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/index/)
- [Execute Algorithm API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/execute-algorithm/)
- [Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/profile/)
- [Stats API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/stats/)

47
_ml-commons-plugin/api/model-apis/delete-model.md Normal file
View File

@ -0,0 +1,47 @@
---
layout: default
title: Delete model
parent: Model APIs
grand_parent: ML Commons API
nav_order: 50
---
# Delete a model
Deletes a model based on the `model_id`.
When you delete the last model version in a model group, that model group is automatically deleted from the index.
{: .important}
For information about user access for this API, see [Model access control considerations]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/index/#model-access-control-considerations).
## Path and HTTP methods
```json
DELETE /_plugins/_ml/models/<model_id>
```
#### Example request
```json
DELETE /_plugins/_ml/models/MzcIJX8BA7mbufL6DOwl
```
{% include copy-curl.html %}
#### Example response
```json
{
"_index" : ".plugins-ml-model",
"_id" : "MzcIJX8BA7mbufL6DOwl",
"_version" : 2,
"result" : "deleted",
"_shards" : {
"total" : 2,
"successful" : 2,
"failed" : 0
},
"_seq_no" : 27,
"_primary_term" : 18
}
```

75
_ml-commons-plugin/api/model-apis/deploy-model.md Normal file
View File

@ -0,0 +1,75 @@
---
layout: default
title: Deploy model
parent: Model APIs
grand_parent: ML Commons API
nav_order: 30
---
# Deploy a model
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]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/index/#model-access-control-considerations).
## Path and HTTP methods
```json
POST /_plugins/_ml/models/<model_id>/_deploy
```
#### Example request: Deploying to all available ML nodes
In this example request, OpenSearch deploys the model to any available OpenSearch ML node:
```json
POST /_plugins/_ml/models/WWQI44MBbzI2oUKAvNUt/_deploy
```
{% include copy-curl.html %}
#### Example request: Deploying to a specific node
If you want to reserve the memory of other ML nodes within your cluster, you can deploy your model to a specific node(s) by specifying the `node_ids` in the request body:
```json
POST /_plugins/_ml/models/WWQI44MBbzI2oUKAvNUt/_deploy
{
"node_ids": ["4PLK7KJWReyX0oWKnBA8nA"]
}
```
{% include copy-curl.html %}
#### Example response
```json
{
"task_id" : "hA8P44MBhyWuIwnfvTKP",
"status" : "DEPLOYING"
}
```
## Check the status of model deployment
To see the status of your model deployment 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/hA8P44MBhyWuIwnfvTKP
```
{% include copy-curl.html %}
The response contains the model ID of the model version:
```json
{
"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
}
```

157
_ml-commons-plugin/api/model-apis/get-model.md Normal file
View File

@ -0,0 +1,157 @@
---
layout: default
title: Get model
parent: Model APIs
grand_parent: ML Commons API
nav_order: 20
---
# Get a model
To retrieve information about a model, you can:
- [Get a model by ID](#get-a-model-by-id)
- [Search for a model](#search-for-a-model)
## Get a model by ID
You can retrieve model information using the `model_id`.
For information about user access for this API, see [Model access control considerations]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/index/#model-access-control-considerations).
## Path and HTTP methods
```json
GET /_plugins/_ml/models/<model-id>
```
#### Example request
```json
GET /_plugins/_ml/models/N8AE1osB0jLkkocYjz7D
```
{% include copy-curl.html %}
#### Example response
```json
{
"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
}
```
## Search for a model
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
GET /_plugins/_ml/models/_search
POST /_plugins/_ml/models/_search
```
#### Example request: Searching for all models
```json
POST /_plugins/_ml/models/_search
{
"query": {
"match_all": {}
},
"size": 1000
}
```
{% include copy-curl.html %}
#### Example request: Searching for models with algorithm "FIT_RCF"
```json
POST /_plugins/_ml/models/_search
{
"query": {
"term": {
"algorithm": {
"value": "FIT_RCF"
}
}
}
}
```
{% include copy-curl.html %}
#### Example 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",
"_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",
"_id" : "OxkvHn8BNJ65KnIpck8x",
"_version" : 1,
"_seq_no" : 2,
"_primary_term" : 8,
"_score" : 2.4159138,
"_source" : {
"name" : "FIT_RCF",
"version" : 1,
"content" : "xxx",
"algorithm" : "FIT_RCF"
}
}
]
}
}
```

31
_ml-commons-plugin/api/model-apis/index.md Normal file
View File

@ -0,0 +1,31 @@
---
layout: default
title: Model APIs
parent: ML Commons API
has_children: true
nav_order: 10
---
# Model APIs
ML Commons supports the following model-level APIs:
- [Register model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/register-model/)
- [Get model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/get-model/)
- [Deploy model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/deploy-model/)
- [Undeploy model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/undeploy-model/)
- [Delete model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/delete-model/)
## 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/).

268
_ml-commons-plugin/api/model-apis/register-model.md Normal file
View File

@ -0,0 +1,268 @@
---
layout: default
title: Register model
parent: Model APIs
grand_parent: ML Commons API
nav_order: 10
---
# Register a model
All versions of a particular model are held in a model group. You can either [register a model group]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-group-apis/register-model-group/) before registering a model to the group or register a first version of a model, thereby creating the group. Each model group name in the cluster must be globally unique.
If you are registering the first version of a model without first registering the model group, a new model group is created automatically with the following name and access level:
- Name: The new model group will have the same name as the model. Because the model group name must be unique, ensure that your model name does not have the same name as any model groups in the cluster.
- Access level: The access level for the new model group is determined using the `access_mode`, `backend_roles`, and `add_all_backend_roles` parameters that you pass in the request. If you provide none of the three parameters, the new model group will be `private` if model access control is enabled on your cluster and `public` if model access control is disabled. The newly registered model is the first model version assigned to that model group.
Once a model group is created, provide its `model_group_id` to register a new model version to the model group. In this case, the model name does not need to be unique.
If you're using [pretrained models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models#supported-pretrained-models) provided by OpenSearch, we recommend that you first register a model group with a unique name for these models. Then register the pretrained models as versions to that model group. This ensures that every model group has a globally unique model group name.
{: .tip}
For information about user access for this API, see [Model access control considerations]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/index/#model-access-control-considerations).
If the model is more than 10 MB in size, ML Commons splits it into smaller chunks and saves those chunks in the model's index.
## Path and HTTP methods
```json
POST /_plugins/_ml/models/_register
```
{% include copy-curl.html %}
## Register an OpenSearch-provided pretrained model
OpenSearch provides several pretrained models. For more information, see [OpenSearch-provided pretrained models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/).
### Register a pretrained text embedding model
To register a pretrained text embedding model, the only required parameters are `name`, `version`, and `model_format`.
#### Request fields
The following table lists the available request fields.
Field | Data type | Required/Optional | Description
:--- | :--- | :---
`name`| String | Required | The model name. |
`version` | Integer | Required | The model version number. |
`model_format` | String | Required | The portable format of the model file. Valid values are `TORCH_SCRIPT` and `ONNX`. |
`description` | String | Optional| The model description. |
`model_group_id` | String | Optional | The model group ID of the model group to register this model to.
#### Example request: OpenSearch-provided text embedding model
```json
POST /_plugins/_ml/models/_register
{
"name": "huggingface/sentence-transformers/msmarco-distilbert-base-tas-b",
"version": "1.0.1",
"model_group_id": "Z1eQf4oB5Vm0Tdw8EIP2",
"model_format": "TORCH_SCRIPT"
}
```
{% include copy-curl.html %}
### Register a pretrained sparse encoding model
To register a pretrained sparse encoding model, you must set the function name to `SPARSE_ENCODING` or `SPARSE_TOKENIZE`.
#### Request fields
The following table lists the available request fields.
Field | Data type | Required/Optional | Description
:--- | :--- | :---
`name`| String | Required | The model name. |
`version` | Integer | Required | The model version number. |
`model_format` | String | Required | The portable format of the model file. Valid values are `TORCH_SCRIPT` and `ONNX`. |
`function_name` | String | Required | Set this parameter to `SPARSE_ENCODING` or `SPARSE_TOKENIZE`.
`model_content_hash_value` | String | Required | The model content hash generated using the SHA-256 hashing algorithm.
`url` | String | Required | The URL that contains the model. |
`description` | String | Optional| The model description. |
`model_group_id` | String | Optional | The model group ID of the model group to register this model to.
#### Example request: OpenSearch-provided sparse encoding model
```json
POST /_plugins/_ml/models/_register
{
"name": "amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v1",
"version": "1.0.0",
"model_group_id": "Z1eQf4oB5Vm0Tdw8EIP2",
"description": "This is a neural sparse encoding model: It transfers text into sparse vector, and then extract nonzero index and value to entry and weights. It serves only in ingestion and customer should use tokenizer model in query.",
"model_format": "TORCH_SCRIPT",
"function_name": "SPARSE_ENCODING",
"model_content_hash_value": "9a41adb6c13cf49a7e3eff91aef62ed5035487a6eca99c996156d25be2800a9a",
"url": "https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v1/1.0.0/torch_script/opensearch-neural-sparse-encoding-doc-v1-1.0.0-torch_script.zip"
}
```
{% include copy-curl.html %}
## Register a custom model
To use a custom model locally within the OpenSearch cluster, you need to provide a URL and a config object for that model. For more information, see [Custom local models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/custom-local-models/).
### Request fields
The following table lists the available request fields.
Field | Data type | Required/Optional | Description
:--- | :--- | :---
`name`| String | Required | The model name. |
`version` | Integer | Required | The model version number. |
`model_format` | String | Required | The portable format of the model file. Valid values are `TORCH_SCRIPT` and `ONNX`. |
`function_name` | String | Required | Set this parameter to `SPARSE_ENCODING` or `SPARSE_TOKENIZE`.
`model_content_hash_value` | String | Required | The model content hash generated using the SHA-256 hashing algorithm.
[`model_config`](#the-model_config-object) | Object | Required | 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 | Required | The URL that contains the model. |
`description` | String | Optional| The model description. |
`model_group_id` | String | Optional | The model group ID of the model group to register this model to.
#### The `model_config` object
| Field | Data type | Description |
| :--- | :--- | :---
| `model_type` | String | The model type, such as `bert`. For a Hugging Face model, the model type is specified in `config.json`. For an example, see the [`all-MiniLM-L6-v2` Hugging Face model `config.json`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/blob/main/config.json#L15). Required. |
| `embedding_dimension` | Integer | The dimension of the model-generated dense vector. For a Hugging Face model, the dimension is specified in the model card. For example, in the [`all-MiniLM-L6-v2` Hugging Face model card](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2), the statement `384 dimensional dense vector space` specifies 384 as the embedding dimension. Required. |
| `framework_type` | String | The framework the model is using. Currently, OpenSearch supports `sentence_transformers` and `huggingface_transformers` frameworks. The `sentence_transformers` model outputs text embeddings directly, so ML Commons does not perform any post processing. For `huggingface_transformers`, ML Commons performs post processing by applying mean pooling to get text embeddings. See the example [`all-MiniLM-L6-v2` Hugging Face model](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) for more details. Required. |
| `all_config` | String | This field is used for reference purposes. You can specify all model configurations in this field. For example, if you are using a Hugging Face model, you can minify the `config.json` file to one line and save its contents in the `all_config` field. Once the model is uploaded, you can use the get model API operation to get all model configurations stored in this field. Optional. |
You can further customize a pretrained sentence transformer model's post-processing logic with the following optional fields in the `model_config` object.
| Field | Data type | Description |
| :--- | :--- | :--- |
| `pooling_mode` | String | The post-process model output, either `mean`, `mean_sqrt_len`, `max`, `weightedmean`, or `cls`.|
| `normalize_result` | Boolean | When set to `true`, normalizes the model output in order to scale to a standard range for the model. |
#### Example request: Custom model
The following example request registers a version `1.0.0` of an NLP sentence transformation model named `all-MiniLM-L6-v2`.
```json
POST /_plugins/_ml/models/_register
{
"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 %}
## Register a model hosted on a third-party platform
To register a model hosted on a third-party platform, you can either first create a standalone connector and provide the ID of that connector or specify an internal connector for the model. For more information, see [Creating connectors for third-party ML platforms]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/connectors/).
### Request fields
The following table lists the available request fields.
Field | Data type | Required/Optional | Description
:--- | :--- | :---
`name`| String | Required | The model name. |
`function_name` | String | Required | Set this parameter to `SPARSE_ENCODING` or `SPARSE_TOKENIZE`.
`connector_id` | Optional | Required | The connector ID of a standalone connector to a model hosted on a third-party platform. For more information, see [Standalone connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/connectors/#standalone-connector). You must provide either `connector_id` or `connector`.
`connector` | Object | Required | Contains specifications for an internal connector to a model that is hosted on a third-party platform. For more information, see [Internal connector]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/connectors/#internal-connector). You must provide either `connector_id` or `connector`.
`description` | String | Optional| The model description. |
`model_group_id` | String | Optional | The model group ID of the model group to register this model to.
#### Example request: Remote model with a standalone connector
```json
POST /_plugins/_ml/models/_register
{
"name": "openAI-gpt-3.5-turbo",
"function_name": "remote",
"model_group_id": "1jriBYsBq7EKuKzZX131",
"description": "test model",
"connector_id": "a1eMb4kBJ1eYAeTMAljY"
}
```
{% include copy-curl.html %}
#### Example request: Remote model with an internal connector
```json
POST /_plugins/_ml/models/_register
{
"name": "openAI-GPT-3.5: internal connector",
"function_name": "remote",
"model_group_id": "lEFGL4kB4ubqQRzegPo2",
"description": "test model",
"connector": {
"name": "OpenAI Connector",
"description": "The connector to public OpenAI model service for GPT 3.5",
"version": 1,
"protocol": "http",
"parameters": {
"endpoint": "api.openai.com",
"max_tokens": 7,
"temperature": 0,
"model": "text-davinci-003"
},
"credential": {
"openAI_key": "..."
},
"actions": [
{
"action_type": "predict",
"method": "POST",
"url": "https://${parameters.endpoint}/v1/completions",
"headers": {
"Authorization": "Bearer ${credential.openAI_key}"
},
"request_body": "{ \"model\": \"${parameters.model}\", \"prompt\": \"${parameters.prompt}\", \"max_tokens\": ${parameters.max_tokens}, \"temperature\": ${parameters.temperature} }"
}
]
}
}
```
{% include copy-curl.html %}
#### Example response
OpenSearch responds with the `task_id` and task `status`.
```json
{
"task_id" : "ew8I44MBhyWuIwnfvDIH",
"status" : "CREATED"
}
```
## Check the status of model registration
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": "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
}
```

58
_ml-commons-plugin/api/model-apis/undeploy-model.md Normal file
View File

@ -0,0 +1,58 @@
---
layout: default
title: Undeploy model
parent: Model APIs
grand_parent: ML Commons API
nav_order: 40
---
# Undeploy a model
To undeploy a model from memory, use the undeploy operation.
For information about user access for this API, see [Model access control considerations]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/index/#model-access-control-considerations).
### Path and HTTP methods
```json
POST /_plugins/_ml/models/<model_id>/_undeploy
```
#### Example request: Undeploying a model from all ML nodes
```json
POST /_plugins/_ml/models/MGqJhYMBbbh0ushjm8p_/_undeploy
```
{% include copy-curl.html %}
#### Example request: Undeploying specific models from specific nodes
```json
POST /_plugins/_ml/models/_undeploy
{
"node_ids": ["sv7-3CbwQW-4PiIsDOfLxQ"],
"model_ids": ["KDo2ZYQB-v9VEDwdjkZ4"]
}
```
{% include copy-curl.html %}
#### Example request: Undeploying specific models from all nodes
```json
{
"model_ids": ["KDo2ZYQB-v9VEDwdjkZ4"]
}
```
{% include copy-curl.html %}
#### Example response
```json
{
"sv7-3CbwQW-4PiIsDOfLxQ" : {
"stats" : {
"KDo2ZYQB-v9VEDwdjkZ4" : "UNDEPLOYED"
}
}
}
```

49
_ml-commons-plugin/api/model-group-apis/delete-model-group.md Normal file
View File

@ -0,0 +1,49 @@
---
layout: default
title: Delete model group
parent: Model group APIs
grand_parent: ML Commons API
nav_order: 40
---
# Delete 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}
When you delete the last model version in a model group, that model group is automatically deleted from the index.
{: .important}
For more information, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).
#### 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
}
```

16
_ml-commons-plugin/api/model-group-apis/index.md Normal file
View File

@ -0,0 +1,16 @@
---
layout: default
title: Model group APIs
parent: ML Commons API
has_children: true
nav_order: 20
---
# Model group APIs
ML Commons supports the following model-group-level APIs:
- [Register model group]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-group-apis/register-model-group/)
- [Update model group]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-group-apis/update-model-group/)
- [Search for a model group]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-group-apis/search-model-group/)
- [Delete model group]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-group-apis/delete-model-group/)

150
_ml-commons-plugin/api/model-group-apis/register-model-group.md Normal file
View File

@ -0,0 +1,150 @@
---
layout: default
title: Register model group
parent: Model group APIs
grand_parent: ML Commons API
nav_order: 10
---
# Register a model group
To register a model group, send a `POST` request to the `_register` endpoint. You can register a model group in `public`, `private`, or `restricted` access mode.
Each model group name in the cluster must be globally unique.
{: .important}
For more information, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).
## 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.
`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. If you specify none of the security parameters (`access_mode`, `backend_roles`, and `add_all_backend_roles`), the default `access_mode` is `private`.
`backend_roles` | Array | A list of the model owner's backend roles to add to the model. Can be specified only if `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",
"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",
"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",
"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",
"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",
"access_mode": "private"
}
```
{% include copy-curl.html %}
If you don't specify any of the `access_mode`, `backend_roles`, or `add_all_backend_roles`, the model will have a `private` access mode:
```json
POST /_plugins/_ml/model_groups/_register
{
"name": "model_group_test",
"description": "This is an example description"
}
```
{% 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](ml-commons-plugin/model-access-control/#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.

302
_ml-commons-plugin/api/model-group-apis/search-model-group.md Normal file
View File

@ -0,0 +1,302 @@
---
layout: default
title: Search for a model group
parent: Model group APIs
grand_parent: ML Commons API
nav_order: 30
---
# Search 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
For more information, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).
## 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"
}
}
]
}
}
```

45
_ml-commons-plugin/api/model-group-apis/update-model-group.md Normal file
View File

@ -0,0 +1,45 @@
---
layout: default
title: Update model group
parent: Model group APIs
grand_parent: ML Commons API
nav_order: 20
---
# Update a model group
To update a model group, send a `PUT` request to the `model_groups` endpoint and provide the ID of the model group you want to update.
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 `access_mode` to `restricted`, you must specify either `backend_roles` or `add_all_backend_roles` but not both.
- When updating the `name`, ensure the name is globally unique in the cluster.
For more information, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).
## Path and HTTP method
```json
PUT /_plugins/_ml/model_groups/<model_group_id>
```
## Request fields
Refer to [Request fields](#request-fields) for request field descriptions.
#### Example request
```json
PUT /_plugins/_ml/model_groups/<model_group_id>
{
"name": "model_group_test",
"description": "This is the updated 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](ml-commons-plugin/model-access-control/#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`).

104
_ml-commons-plugin/api/profile.md Normal file
View File

@ -0,0 +1,104 @@
---
layout: default
title: Profile
parent: ML Commons API
nav_order: 40
---
# Profile
The profile API operation returns runtime information about ML tasks and models. The profile operation can help debug model issues at runtime.
## The number of requests returned
By default, the Profile API monitors the last 100 requests. To change the number of monitoring requests, update the following cluster setting:
```json
PUT _cluster/settings
{
"persistent" : {
"plugins.ml_commons.monitoring_request_count" : 1000000
}
}
```
To clear all monitoring requests, set `plugins.ml_commons.monitoring_request_count` to `0`.
## Path and HTTP methods
```json
GET /_plugins/_ml/profile
GET /_plugins/_ml/profile/models
GET /_plugins/_ml/profile/tasks
```
## Path parameters
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.
### Request fields
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 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 request: Returning all tasks and models on a specific node
```json
GET /_plugins/_ml/profile
{
"node_ids": ["KzONM8c8T4Od-NoUANQNGg"],
"return_all_tasks": true,
"return_all_models": true
}
```
{% include copy-curl.html %}
#### Example response
```json
{
"nodes" : {
"qTduw0FJTrmGrqMrxH0dcA" : { # node id
"models" : {
"WWQI44MBbzI2oUKAvNUt" : { # model id
"worker_nodes" : [ # routing table
"KzONM8c8T4Od-NoUANQNGg"
]
}
}
},
...
"KzONM8c8T4Od-NoUANQNGg" : { # node id
"models" : {
"WWQI44MBbzI2oUKAvNUt" : { # model id
"model_state" : "DEPLOYED", # model status
"predictor" : "org.opensearch.ml.engine.algorithms.text_embedding.TextEmbeddingModel@592814c9",
"worker_nodes" : [ # routing table
"KzONM8c8T4Od-NoUANQNGg"
],
"predict_request_stats" : { # predict request stats on this node
"count" : 2, # total predict requests on this node
"max" : 89.978681, # max latency in milliseconds
"min" : 5.402,
"average" : 47.6903405,
"p50" : 47.6903405,
"p90" : 81.5210129,
"p99" : 89.13291418999998
}
}
}
},
...
}
}
```

79
_ml-commons-plugin/api/stats.md Normal file
View File

@ -0,0 +1,79 @@
---
layout: default
title: Stats
parent: ML Commons API
nav_order: 50
---
# Stats
Gets statistics related to the number of tasks.
## Path and HTTP methods
```json
GET /_plugins/_ml/stats
GET /_plugins/_ml/stats/<stat>
GET /_plugins/_ml/<nodeId>/stats/
GET /_plugins/_ml/<nodeId>/stats/<stat>
```
#### Example request: Get all stats for all nodes
```json
GET /_plugins/_ml/stats
```
{% include copy-curl.html %}
#### Example 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
}
}
```
#### Example request: Get all stats for a specific node
```json
GET /_plugins/_ml/<nodeId>/stats/
```
{% include copy-curl.html %}
#### Example request: Get a specified stat for a specific node
```json
GET /_plugins/_ml/<nodeId>/stats/<stat>
```
{% include copy-curl.html %}
#### Example request: Get a specified stat for all nodes
```json
GET /_plugins/_ml/stats/<stat>
```
{% include copy-curl.html %}

45
_ml-commons-plugin/api/tasks-apis/delete-task.md Normal file
View File

@ -0,0 +1,45 @@
---
layout: default
title: Delete task
parent: Tasks APIs
grand_parent: ML Commons API
nav_order: 20
---
# Delete a task
Deletes a task based on the `task_id`.
ML Commons does not check the task status when running the delete request. There is a risk that a currently running task could be deleted before the task completes. To check the status of a task, run `GET /_plugins/_ml/tasks/<task_id>` before task deletion.
{: .note}
### Path and HTTP methods
```json
DELETE /_plugins/_ml/tasks/<task_id>
```
#### Example request
```json
DELETE /_plugins/_ml/tasks/xQRYLX8BydmmU1x6nuD3
```
{% include copy-curl.html %}
#### Example response
```json
{
"_index" : ".plugins-ml-task",
"_id" : "xQRYLX8BydmmU1x6nuD3",
"_version" : 4,
"result" : "deleted",
"_shards" : {
"total" : 2,
"successful" : 2,
"failed" : 0
},
"_seq_no" : 42,
"_primary_term" : 7
}
```

139
_ml-commons-plugin/api/tasks-apis/get-task.md Normal file
View File

@ -0,0 +1,139 @@
---
layout: default
title: Get task
parent: Tasks APIs
grand_parent: ML Commons API
nav_order: 10
---
# Get task
To retrieve information about a model, you can:
- [Get a task by ID](#get-a-task-by-id)
- [Search for a task](#search-for-a-task)
## Get a task by ID
You can retrieve information about a task using the `task_id`.
### Path and HTTP methods
```json
GET /_plugins/_ml/tasks/<task_id>
```
#### Example request
```json
GET /_plugins/_ml/tasks/MsBi1YsB0jLkkocYjD5f
```
{% include copy-curl.html %}
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
}
```
## Search for a task
Searches tasks based on parameters indicated in the request body.
### Path and HTTP methods
```json
GET /_plugins/_ml/tasks/_search
```
#### Example request: Search for a task in which `function_name` is `KMEANS`
```json
GET /_plugins/_ml/tasks/_search
{
"query": {
"bool": {
"filter": [
{
"term": {
"function_name": "KMEANS"
}
}
]
}
}
}
```
{% include copy-curl.html %}
#### Example response
```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",
"_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",
"_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"
}
}
]
}
}
```

14
_ml-commons-plugin/api/tasks-apis/index.md Normal file
View File

@ -0,0 +1,14 @@
---
layout: default
title: Tasks APIs
parent: ML Commons API
has_children: true
nav_order: 30
---
# Tasks APIs
ML Commons supports the following Tasks APIs:
- [Get task]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/get-task/)
- [Delete task]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/delete-task/)

23
_ml-commons-plugin/api/train-predict/index.md Normal file
View File

@ -0,0 +1,23 @@
---
layout: default
title: Train and Predict APIs
parent: ML Commons API
has_children: true
nav_order: 30
---
# Train and Predict APIs
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.
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 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.
ML Commons supports the following Train and Predict APIs:
- [Train]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train/)
- [Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/)
- [Train and Predict]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train-and-predict/)

102
_ml-commons-plugin/api/train-predict/predict.md Normal file
View File

@ -0,0 +1,102 @@
---
layout: default
title: Predict
parent: Train and Predict APIs
grand_parent: ML Commons API
has_children: true
nav_order: 20
---
# Predict
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]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/index/#model-access-control-considerations).
## Path and HTTP methods
```json
POST /_plugins/_ml/_predict/<algorithm_name>/<model_id>
```
#### Example request
```json
POST /_plugins/_ml/_predict/kmeans/<model-id>
{
"input_query": {
"_source": ["petal_length_in_cm", "petal_width_in_cm"],
"size": 10000
},
"input_index": [
"iris_data"
]
}
```
{% include copy-curl.html %}
#### Example 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
}
]
}
]
}
}
```

215
_ml-commons-plugin/api/train-predict/train-and-predict.md Normal file
View File

@ -0,0 +1,215 @@
---
layout: default
title: Train and predict
parent: Train and Predict APIs
grand_parent: ML Commons API
has_children: true
nav_order: 10
---
## Train and predict
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`
- `k-means`
#### Example request: Train and predict with indexed data
```json
POST /_plugins/_ml/_train_predict/kmeans
{
"parameters": {
"centroids": 2,
"iterations": 10,
"distance_type": "COSINE"
},
"input_query": {
"query": {
"bool": {
"filter": [
{
"range": {
"k1": {
"gte": 0
}
}
}
]
}
},
"size": 10
},
"input_index": [
"test_data"
]
}
```
{% include copy-curl.html %}
#### Example request: Train and predict with data directly
```json
POST /_plugins/_ml/_train_predict/kmeans
{
"parameters": {
"centroids": 2,
"iterations": 1,
"distance_type": "EUCLIDEAN"
},
"input_data": {
"column_metas": [
{
"name": "k1",
"column_type": "DOUBLE"
},
{
"name": "k2",
"column_type": "DOUBLE"
}
],
"rows": [
{
"values": [
{
"column_type": "DOUBLE",
"value": 1.00
},
{
"column_type": "DOUBLE",
"value": 2.00
}
]
},
{
"values": [
{
"column_type": "DOUBLE",
"value": 1.00
},
{
"column_type": "DOUBLE",
"value": 4.00
}
]
},
{
"values": [
{
"column_type": "DOUBLE",
"value": 1.00
},
{
"column_type": "DOUBLE",
"value": 0.00
}
]
},
{
"values": [
{
"column_type": "DOUBLE",
"value": 10.00
},
{
"column_type": "DOUBLE",
"value": 2.00
}
]
},
{
"values": [
{
"column_type": "DOUBLE",
"value": 10.00
},
{
"column_type": "DOUBLE",
"value": 4.00
}
]
},
{
"values": [
{
"column_type": "DOUBLE",
"value": 10.00
},
{
"column_type": "DOUBLE",
"value": 0.00
}
]
}
]
}
}
```
{% include copy-curl.html %}
#### Example 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" : 1
}
]
},
{
"values" : [
{
"column_type" : "INTEGER",
"value" : 0
}
]
},
{
"values" : [
{
"column_type" : "INTEGER",
"value" : 0
}
]
},
{
"values" : [
{
"column_type" : "INTEGER",
"value" : 0
}
]
}
]
}
}
```

82
_ml-commons-plugin/api/train-predict/train.md Normal file
View File

@ -0,0 +1,82 @@
---
layout: default
title: Train
parent: Train and Predict APIs
grand_parent: ML Commons API
has_children: true
nav_order: 10
---
# Train
The train API operation trains a model based on a selected algorithm. Training can occur both synchronously and asynchronously.
#### Example request
The following examples use the k-means algorithm to train index data.
**Train with k-means 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"
]
}
```
{% include copy-curl.html %}
**Train with k-means 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"
]
}
```
{% include copy-curl.html %}
#### Example response
**Synchronous**
For synchronous responses, the API returns the `model_id`, which can be used to get or delete a model.
```json
{
"model_id" : "lblVmX8BO5w8y8RaYYvN",
"status" : "COMPLETED"
}
```
**Asynchronous**
For asynchronous responses, the API returns the `task_id`, which can be used to get or delete a task.
```json
{
"task_id" : "lrlamX8BO5w8y8Ra2otd",
"status" : "CREATED"
}
```

11
_ml-commons-plugin/cluster-settings.md
View File

@ -7,6 +7,7 @@ nav_order: 10
# ML Commons cluster settings
To enhance and customize your OpenSearch cluster for machine learning (ML), you can add and modify several configuration settings for the ML Commons plugin in your 'opensearch.yml' file.
To learn more about static and dynamic settings, see [Configuring OpenSearch]({{site.url}}{{site.baseurl}}/install-and-configure/configuring-opensearch/index/).
@ -21,7 +22,11 @@ node.roles: [ ml ]
## Run tasks and models on ML nodes only
If `true`, ML Commons tasks and models run machine learning (ML) tasks on ML nodes only. If `false`, tasks and models run on ML nodes first. If no ML nodes exist, tasks and models run on data nodes. We recommend that you do not set this value to "false" on production clusters.
If `true`, ML Commons tasks and models run ML tasks on ML nodes only. If `false`, tasks and models run on ML nodes first. If no ML nodes exist, tasks and models run on data nodes.
We recommend setting `plugins.ml_commons.only_run_on_ml_node` to `true` on production clusters.
{: .tip}
### Setting
@ -83,7 +88,7 @@ plugins.ml_commons.max_model_on_node: 10
## Set sync job intervals
When returning runtime information with the [Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#profile), ML Commons will run a regular job to sync newly deployed or undeployed models on each node. When set to `0`, ML Commons immediately stops sync-up jobs.
When returning runtime information with the [Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/profile/), ML Commons will run a regular job to sync newly deployed or undeployed models on each node. When set to `0`, ML Commons immediately stops sync-up jobs.
### Setting
@ -181,7 +186,7 @@ The default value allows you to register a model file from any http/https/ftp/lo
### Setting
The default URL value for this trusted URL setting is not secure. To ensure the security, please use you own regex string to the trusted repository that contains your models, for example `https://github.com/opensearch-project/ml-commons/blob/2.x/ml-algorithms/src/test/resources/org/opensearch/ml/engine/algorithms/text_embedding/*`.
The default URL value for this trusted URL setting is not secure. For security, use you own regex string to the trusted repository that contains your models, for example `https://github.com/opensearch-project/ml-commons/blob/2.x/ml-algorithms/src/test/resources/org/opensearch/ml/engine/algorithms/text_embedding/*`.
{: .warning }

2
_ml-commons-plugin/conversational-search.md
View File

@ -407,5 +407,5 @@ If your LLM includes a set token limit, set the `size` field in your OpenSearch
## Next steps
- To learn more about connecting to models on external platforms, see [Connectors]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/connectors/).
- To learn more about using custom models within your OpenSearch cluster, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
- To learn more about using custom models within your OpenSearch cluster, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).

293
_ml-commons-plugin/custom-local-models.md Normal file
View File

@ -0,0 +1,293 @@
---
layout: default
title: Custom models
parent: Using ML models within OpenSearch
nav_order: 120
---
# Custom local models
**Generally available 2.9**
{: .label .label-purple }
To use a custom model locally, you can upload it to the OpenSearch cluster.
## Model support
As of OpenSearch 2.6, OpenSearch supports local text embedding models.
As of OpenSearch 2.11, OpenSearch supports local sparse encoding models.
## Preparing a model
For both text embedding and sparse encoding models, you must provide a tokenizer JSON file within the model zip file.
For sparse encoding models, make sure your output format is `{"output":<sparse_vector>}` so that ML Commons can post-process the sparse vector.
If you fine-tune a sparse model on your own dataset, you may also want to use your own sparse tokenizer model. It is preferable to provide your own [IDF](https://en.wikipedia.org/wiki/Tf%E2%80%93idf) JSON file in the tokenizer model zip file because this increases query performance when you use the tokenizer model in the query. Alternatively, you can use an OpenSearch-provided generic [IDF from MSMARCO](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1/1.0.0/torch_script/opensearch-neural-sparse-tokenizer-v1-1.0.0.zip). If the IDF file is not provided, the default weight of each token is set to 1, which may influence sparse neural search performance.
### Model format
To use a model in OpenSearch, you'll need to export the model into a portable format. As of Version 2.5, OpenSearch only supports the [TorchScript](https://pytorch.org/docs/stable/jit.html) and [ONNX](https://onnx.ai/) formats.
You must save the model file as zip before uploading it to OpenSearch. To ensure that ML Commons can upload your model, compress your TorchScript file before uploading. For an example, download a TorchScript [model file](https://github.com/opensearch-project/ml-commons/blob/2.x/ml-algorithms/src/test/resources/org/opensearch/ml/engine/algorithms/text_embedding/all-MiniLM-L6-v2_torchscript_sentence-transformer.zip).
Additionally, you must calculate a SHA256 checksum for the model zip file that you'll need to provide when registering the model. For example, on UNIX, use the following command to obtain the checksum:
```bash
shasum -a 256 sentence-transformers_paraphrase-mpnet-base-v2-1.0.0-onnx.zip
```
### Model size
Most deep learning models are more than 100 MB, making it difficult to fit them into a single document. OpenSearch splits the model file into smaller chunks to be stored in a model index. When allocating ML or data nodes for your OpenSearch cluster, make sure you correctly size your ML nodes so that you have enough memory when making ML inferences.
## Prerequisites
To upload a custom model to OpenSearch, you need to prepare it outside of your OpenSearch cluster. You can use a pretrained model, like one from [Hugging Face](https://huggingface.co/), or train a new model in accordance with your needs.
### Cluster settings
This example uses a simple setup with no dedicated ML nodes and allows running a model on a non-ML node.
On clusters with dedicated ML nodes, specify `"only_run_on_ml_node": "true"` for improved performance. For more information, see [ML Commons cluster settings]({{site.url}}{{site.baseurl}}/ml-commons-plugin/cluster-settings/).
To ensure that this basic local setup works, specify the following cluster settings:
```json
PUT _cluster/settings
{
"persistent": {
"plugins": {
"ml_commons": {
"allow_registering_model_via_url": "true",
"only_run_on_ml_node": "false",
"model_access_control_enabled": "true",
"native_memory_threshold": "99"
}
}
}
}
```
{% include copy-curl.html %}
## Step 1: Register a model group
To register a model, you have the following options:
- You can use `model_group_id` to register a model version to an existing model group.
- If you do not use `model_group_id`, ML Commons creates a model with a new model group.
To register a model group, send the following request:
```json
POST /_plugins/_ml/model_groups/_register
{
"name": "local_model_group",
"description": "A model group for local models"
}
```
{% include copy-curl.html %}
The response contains the model group ID that you'll use to register a model to this model group:
```json
{
"model_group_id": "wlcnb4kBJ1eYAeTMHlV6",
"status": "CREATED"
}
```
To learn more about model groups, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).
## Step 2: Register a local model
To register a remote model to the model group created in step 1, provide the model group ID from step 1 in the following request:
```json
POST /_plugins/_ml/models/_register
{
"name": "huggingface/sentence-transformers/msmarco-distilbert-base-tas-b",
"version": "1.0.1",
"model_group_id": "wlcnb4kBJ1eYAeTMHlV6",
"description": "This is a port of the DistilBert TAS-B Model to sentence-transformers model: It maps sentences & paragraphs to a 768 dimensional dense vector space and is optimized for the task of semantic search.",
"model_task_type": "TEXT_EMBEDDING",
"model_format": "TORCH_SCRIPT",
"model_content_size_in_bytes": 266352827,
"model_content_hash_value": "acdc81b652b83121f914c5912ae27c0fca8fabf270e6f191ace6979a19830413",
"model_config": {
"model_type": "distilbert",
"embedding_dimension": 768,
"framework_type": "sentence_transformers",
"all_config": """{"_name_or_path":"old_models/msmarco-distilbert-base-tas-b/0_Transformer","activation":"gelu","architectures":["DistilBertModel"],"attention_dropout":0.1,"dim":768,"dropout":0.1,"hidden_dim":3072,"initializer_range":0.02,"max_position_embeddings":512,"model_type":"distilbert","n_heads":12,"n_layers":6,"pad_token_id":0,"qa_dropout":0.1,"seq_classif_dropout":0.2,"sinusoidal_pos_embds":false,"tie_weights_":true,"transformers_version":"4.7.0","vocab_size":30522}"""
},
"created_time": 1676073973126,
"url": "https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/msmarco-distilbert-base-tas-b/1.0.1/torch_script/sentence-transformers_msmarco-distilbert-base-tas-b-1.0.1-torch_script.zip"
}
```
{% include copy-curl.html %}
For a description of Register API parameters, see [Register a model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-apis/register-model/).
OpenSearch returns the task ID of the register operation:
```json
{
"task_id": "cVeMb4kBJ1eYAeTMFFgj",
"status": "CREATED"
}
```
To check the status of the operation, provide the task ID to the [Get task]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/get-task/):
```bash
GET /_plugins/_ml/tasks/cVeMb4kBJ1eYAeTMFFgj
```
{% include copy-curl.html %}
When the operation is complete, the state changes to `COMPLETED`:
```json
{
"model_id": "cleMb4kBJ1eYAeTMFFg4",
"task_type": "REGISTER_MODEL",
"function_name": "REMOTE",
"state": "COMPLETED",
"worker_node": [
"XPcXLV7RQoi5m8NI_jEOVQ"
],
"create_time": 1689793598499,
"last_update_time": 1689793598530,
"is_async": false
}
```
Take note of the returned `model_id` because you’ll need it to deploy the model.
## Step 3: Deploy the model
The deploy operation reads the model's chunks from the model index and then creates an instance of the model to load into memory. The bigger the model, the more chunks the model is split into and longer it takes for the model to load into memory.
To deploy the registered model, provide its model ID from step 3 in the following request:
```bash
POST /_plugins/_ml/models/cleMb4kBJ1eYAeTMFFg4/_deploy
```
{% include copy-curl.html %}
The response contains the task ID that you can use to check the status of the deploy operation:
```json
{
"task_id": "vVePb4kBJ1eYAeTM7ljG",
"status": "CREATED"
}
```
As in the previous step, check the status of the operation by calling the Tasks API:
```bash
GET /_plugins/_ml/tasks/vVePb4kBJ1eYAeTM7ljG
```
{% include copy-curl.html %}
When the operation is complete, the state changes to `COMPLETED`:
```json
{
"model_id": "cleMb4kBJ1eYAeTMFFg4",
"task_type": "DEPLOY_MODEL",
"function_name": "REMOTE",
"state": "COMPLETED",
"worker_node": [
"n-72khvBTBi3bnIIR8FTTw"
],
"create_time": 1689793851077,
"last_update_time": 1689793851101,
"is_async": true
}
```
## Step 4 (Optional): Test the model
Use the [Predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/) to test the model.
For a text embedding model, send the following request:
```json
POST /_plugins/_ml/_predict/text_embedding/cleMb4kBJ1eYAeTMFFg4
{
"text_docs":[ "today is sunny"],
"return_number": true,
"target_response": ["sentence_embedding"]
}
```
{% include copy-curl.html %}
The response contains text embeddings for the provided sentence:
```json
{
"inference_results" : [
{
"output" : [
{
"name" : "sentence_embedding",
"data_type" : "FLOAT32",
"shape" : [
768
],
"data" : [
0.25517133,
-0.28009856,
0.48519906,
...
]
}
]
}
]
}
```
For a sparse encoding model, send the following request:
```json
POST /_plugins/_ml/_predict/sparse_encoding/cleMb4kBJ1eYAeTMFFg4
{
"text_docs":[ "today is sunny"]
}
```
{% include copy-curl.html %}
The response contains the tokens and weights:
```json
{
"inference_results": [
{
"output": [
{
"name": "output",
"dataAsMap": {
"response": [
{
"saturday": 0.48336542,
"week": 0.1034762,
"mood": 0.09698499,
"sunshine": 0.5738209,
"bright": 0.1756877,
...
}
}
}
}
}
```
## Step 5: Use the model for search
To learn how to set up a vector index and use text embedding models for search, see [Neural text search]({{site.url}}{{site.baseurl}}/search-plugins/neural-text-search/).
To learn how to set up a vector index and use sparse encoding models for search, see [Neural sparse search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/).
To learn how to set up a vector index and use multimodal embedding models for search, see [Multimodal search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/).

4
_ml-commons-plugin/extensibility/blueprints.md
View File

@ -7,6 +7,8 @@ parent: Connecting to remote models
---
# Connector blueprints
**Introduced 2.9**
{: .label .label-purple }
All connectors consist of a JSON blueprint created by machine learning (ML) developers. The blueprint allows administrators and data scientists to make connections between OpenSearch and an AI service or model-serving technology.
@ -136,7 +138,7 @@ The `request_body` template must be `${parameters.input}`.
The `connector.pre_process.default.embedding` default preprocessing function parses the neural search request and transforms it into the format that the model expects as input.
The ML Commons [Predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict) provides parameters in the following format:
The ML Commons [Predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/) provides parameters in the following format:
```json
{

4
_ml-commons-plugin/extensibility/connectors.md
View File

@ -8,6 +8,8 @@ parent: Connecting to remote models
---
# Creating connectors for third-party ML platforms
**Introduced 2.9**
{: .label .label-purple }
Connectors facilitate access to remote models hosted on third-party platforms.
@ -265,5 +267,5 @@ POST /_plugins/_ml/connectors/_create
## Next steps
- To learn more about using models in OpenSearch, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
- To learn more about using models in OpenSearch, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
- To learn more about model access control and model groups, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).

22
_ml-commons-plugin/extensibility/index.md
View File

@ -7,6 +7,8 @@ nav_order: 60
---
# Connecting to remote models
**Introduced 2.9**
{: .label .label-purple }
Machine learning (ML) extensibility enables ML developers to create integrations with other ML services, such as Amazon SageMaker or OpenAI. These integrations provide system administrators and data scientists the ability to run ML workloads outside of their OpenSearch cluster.
@ -187,7 +189,7 @@ OpenSearch returns the task ID of the register operation:
}
```
To check the status of the operation, provide the task ID to the [Tasks API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#searching-for-a-task):
To check the status of the operation, provide the task ID to the [Tasks API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/get-task/#get-a-task-by-id):
```bash
GET /_plugins/_ml/tasks/cVeMb4kBJ1eYAeTMFFgj
@ -211,6 +213,8 @@ When the operation is complete, the state changes to `COMPLETED`:
}
```
Take note of the returned `model_id` because you’ll need it to deploy the model.
## Step 4: Deploy the remote model
To deploy the registered model, provide its model ID from step 3 in the following request:
@ -253,9 +257,9 @@ When the operation is complete, the state changes to `COMPLETED`:
}
```
## Step 5: Make predictions
## Step 5 (Optional): Test the remote model
Use the [Predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#predict) to make predictions:
Use the [Predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/) to test the model:
```json
POST /_plugins/_ml/models/cleMb4kBJ1eYAeTMFFg4/_predict
@ -315,12 +319,16 @@ The response contains the inference results provided by the OpenAI model:
}
```
## Step 6: Use the model for search
To learn how to set up a vector index and use text embedding models for search, see [Neural text search]({{site.url}}{{site.baseurl}}/search-plugins/neural-text-search/).
To learn how to set up a vector index and use sparse encoding models for search, see [Neural sparse search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/).
To learn how to set up a vector index and use multimodal embedding models for search, see [Multimodal search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/).
## Next steps
- For more information about connectors, including connector examples, see [Connectors]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/connectors/).
- For more information about connector parameters, see [Connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/blueprints/).
- For more information about managing ML models in OpenSearch, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-serving-framework/).
- For more information about interacting with ML models in OpenSearch, see [Managing ML models in OpenSearch Dashboards]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-dashboard/)

2
_ml-commons-plugin/gpu-acceleration.md
View File

@ -1,7 +1,7 @@
---
layout: default
title: GPU acceleration
parent: Using custom models within OpenSearch
parent: Using ML models within OpenSearch
nav_order: 150
---

6
_ml-commons-plugin/index.md
View File

@ -11,11 +11,11 @@ nav_exclude: true
ML Commons for OpenSearch simplifies the development of machine learning (ML) features by providing a set of ML algorithms through transport and REST API calls. Those calls choose the right nodes and resources for each ML request and monitor ML tasks to ensure uptime. This allows you to use existing open-source ML algorithms and reduce the effort required to develop new ML features.
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.
Interaction with the ML Commons plugin occurs through either the [REST API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/index/) 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#training-the-model) through the ML Commons plugin support model-based algorithms, such as k-means. After you've trained a model to your precision requirements, use the model to [make predictions]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#predict).
[Models trained]({{site.url}}{{site.baseurl}}//ml-commons-plugin/api/train-predict/train/) through the ML Commons plugin support model-based algorithms, such as k-means. After you've trained a model to your precision requirements, use the model to [make predictions]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/).
If you don't want to use a model, you can use the [Train and Predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#train-and-predict) to test your model without having to evaluate the model's performance.
If you don't want to use a model, you can use the [Train and Predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/train-and-predict/) to test your model without having to evaluate the model's performance.
## Using ML Commons

4
_ml-commons-plugin/ml-dashboard.md
View File

@ -11,7 +11,7 @@ The ML dashboard was taken out of experimental status and released as Generally
Administrators of machine learning (ML) clusters can use OpenSearch Dashboards to manage and check the status of ML models running inside a cluster. This can help ML developers provision nodes to ensure their models run efficiently.
As of OpenSearch 2.6, you can only upload models using the API. For more information about how to upload a model to your cluster, see [Upload model to OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-serving-framework#upload-model-to-opensearch).
You can register and deploy models using the API only. For more information, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-serving-framework/).
## Enabling ML in Dashboards
@ -66,4 +66,4 @@ A list of nodes gives you a view of each node the model is running on, including
## Next steps
For more information about how to manage ML models in OpenSearch, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-serving-framework/).
For more information about how to manage ML models in OpenSearch, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-serving-framework/).

310
_ml-commons-plugin/ml-framework.md
View File

@ -1,317 +1,23 @@
---
layout: default
title: Using custom models within OpenSearch
title: Using ML models within OpenSearch
has_children: true
nav_order: 50
redirect_from:
- /ml-commons-plugin/model-serving-framework/
---
ML Framework was taken out of experimental status and released as Generally Available in OpenSearch 2.9.
{: .note}
# Using ML models within OpenSearch
**Generally available 2.9**
{: .label .label-purple }
To integrate machine learning (ML) models into your OpenSearch cluster, you can upload and serve them locally. Choose one of the following options:
# Using custom models within OpenSearch
- **Pretrained models provided by OpenSearch**: To learn more, see [OpenSearch-provided pretrained models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/). For a list of supported models, see [Supported pretrained models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/#supported-pretrained-models).
ML Commons allows you to serve custom models and use those models to make inferences through the OpenSearch Machine Learning (ML) Framework. For those who want to run their PyTorch deep learning model inside an OpenSearch cluster, you can upload and run that model with the ML Commons REST API.
This page outlines the steps required to upload a custom model and run it with the ML Framework.
## Prerequisites
To upload a custom model to OpenSearch, you need to prepare it outside of your OpenSearch cluster. You can use a pretrained model, like one from [Huggingface](https://huggingface.co/), or train a new model in accordance with your needs.
### Model support
As of OpenSearch 2.6, the ML Framework supports text-embedding models.
As of OpenSearch 2.11, the ML framework supports sparse encoding models.
### Model format
To use a model in OpenSearch, you'll need to export the model into a portable format. As of Version 2.5, OpenSearch only supports the [TorchScript](https://pytorch.org/docs/stable/jit.html) and [ONNX](https://onnx.ai/) formats.
Furthermore, files must be saved as zip files before upload. Therefore, to ensure that ML Commons can upload your model, compress your TorchScript file before uploading. You can download an example file [here](https://github.com/opensearch-project/ml-commons/blob/2.x/ml-algorithms/src/test/resources/org/opensearch/ml/engine/algorithms/text_embedding/all-MiniLM-L6-v2_torchscript_sentence-transformer.zip).
### Uploading your own model
For both text embedding and sparse encoding models, you must provide a tokenizer JSON file within the model zip file.
For sparse encoding models, make sure your output format is `{"output":<sparse_vector>}` so that ML Commons can post-process the sparse vector.
If you fine-tune a sparse model on your own dataset, you may also want to use your own sparse tokenizer model. It is preferable to provide your own [IDF](https://en.wikipedia.org/wiki/Tf%E2%80%93idf) JSON file in the tokenizer model zip file because this increases query performance when you use the tokenizer model in the query. Alternatively, you can use an OpenSearch-provided generic [IDF from MSMARCO](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1/1.0.0/torch_script/opensearch-neural-sparse-tokenizer-v1-1.0.0.zip). If the IDF file is not provided, the default weight of each token is set to 1, which may influence sparse neural search performance.
### Model size
Most deep learning models are more than 100 MB, making it difficult to fit them into a single document. OpenSearch splits the model file into smaller chunks to be stored in a model index. When allocating machine learning (ML) or data nodes for your OpenSearch cluster, make sure you correctly size your ML nodes so that you have enough memory when making ML inferences.
- **Custom models** such as PyTorch deep learning models: To learn more, see [Custom models](http://localhost:4000/docs/latest/ml-commons-plugin/custom-local-models/).
## GPU acceleration
To achieve better performance within the ML Framework, you can take advantage of GPU acceleration on your ML node. For more information, see [GPU acceleration]({{site.url}}{{site.baseurl}}/ml-commons-plugin/gpu-acceleration/).
## Upload model to OpenSearch
Use the URL upload operation for models that already exist on another server, such as GitHub or S3.
```
POST /_plugins/_ml/models/_upload
```
The URL upload method requires the following request fields.
Field | Data type | Description
:--- | :--- | :---
`name`| String | The name of the model. |
`version` | String | The version number of the model. Since OpenSearch does not enforce a specific version schema for models, you can choose any number or format that makes sense for your models. |
`model_format` | String | The portable format of the model file. Currently only supports `TORCH_SCRIPT`. |
[`model_config`](#the-model_config-object) | JSON object | The model's configuration, including the `model_type`, `embedding_dimension`, and `framework_type`. |
`url` | string | The URL where the model is located. |
### The `model_config` object
| Field | Data type | Description |
| :--- | :--- | :--- |
| `model_type` | String | The model type, such as `bert`. For a Huggingface model, the model type is specified in `config.json`. For an example, see the [`all-MiniLM-L6-v2` Huggingface model `config.json`](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2/blob/main/config.json#L15).|
| `embedding_dimension` | Integer | The dimension of the model-generated dense vector. For a Huggingface model, the dimension is specified in the model card. For example, in the [`all-MiniLM-L6-v2` Huggingface model card](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2), the statement `384 dimensional dense vector space` specifies 384 as the embedding dimension. |
| `framework_type` | String | The framework the model is using. Currently, we support `sentence_transformers` and `huggingface_transformers` frameworks. The `sentence_transformers` model outputs text embeddings directly, so ML Commons does not perform any post processing. For `huggingface_transformers`, ML Commons performs post processing by applying mean pooling to get text embeddings. See the example [`all-MiniLM-L6-v2` Huggingface model](https://huggingface.co/sentence-transformers/all-MiniLM-L6-v2) for more details. |
| `all_config` _(Optional)_ | String | This field is used for reference purposes. You can specify all model configurations in this field. For example, if you are using a Huggingface model, you can minify the `config.json` file to one line and save its contents in the `all_config` field. Once the model is uploaded, you can use the get model API operation to get all model configurations stored in this field. |
You can further customize a pre-trained sentence transformer model's post-processing logic with the following optional fields in the `model_config` object.
| Field | Data type | Description |
| :--- | :--- | :--- |
| `pooling_mode` | String | The post-process model output, either `mean`, `mean_sqrt_len`, `max`, `weightedmean`, or `cls`.|
| `normalize_result` | Boolean | When set to `true`, normalizes the model output in order to scale to a standard range for the model. |
#### Example request
The following example request uploads version `1.0.0` of a natural language processing (NLP) sentence transformation model named `all-MiniLM-L6-v2`:
```json
POST /_plugins/_ml/models/_upload
{
"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"
}
```
#### Example response
OpenSearch responds with the `task_id` and task `status`:
```json
{
"task_id" : "ew8I44MBhyWuIwnfvDIH",
"status" : "CREATED"
}
```
To see the status of your model upload, pass the `task_id` into the [task API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#getting-task-information).
## Load the model
The load model operation reads the model's chunks from the model index and then creates an instance of the model to load into memory. The bigger the model, the more chunks the model is split into. The more chunks a model index contains, the longer it takes for the model to load into memory.
### Get the `model_id`
To load a model, you need the `model_id`. To find the `model_id`, take the `task_id` from the model's upload operations API response and use the `GET _ml/tasks` API.
This example request uses the `task_id` from the upload example.
```json
GET /_plugins/_ml/tasks/ew8I44MBhyWuIwnfvDIH
```
OpenSearch responds with the `model_id`:
```json
{
"model_id" : "WWQI44MBbzI2oUKAvNUt",
"task_type" : "UPLOAD_MODEL",
"function_name" : "TEXT_EMBEDDING",
"state" : "COMPLETED",
"worker_node" : "KzONM8c8T4Od-NoUANQNGg",
"create_time" : 3455961564003,
"last_update_time" : 3216361373241,
"is_async" : true
}
```
### Load the model from the model index
With the `model_id`, you can now load the model from the model's index in order to deploy the model to ML nodes. The load API reads model chunks from the model index, creates an instance of that model, and saves the model instance in the ML node's cache.
Add the `model_id` to the load API:
```json
POST /_plugins/_ml/models/<model_id>/_load
```
By default, the ML Commons setting `plugins.ml_commons.only_run_on_ml_node` is set to `false`. When `false`, models load on ML nodes first. If no ML nodes exist, models load on data nodes. When running ML models in production, set `plugins.ml_commons.only_run_on_ml_node` to `true` so that models only load on ML nodes.
#### Example request: Load into any available ML node
In this example request, OpenSearch loads the model into all available OpenSearch node:
```json
POST /_plugins/_ml/models/WWQI44MBbzI2oUKAvNUt/_load
```
#### Example request: Load into a specific node
If you want to reserve the memory of other ML nodes within your cluster, you can load your model into a specific node(s) by specifying each node's ID in the request body:
```json
POST /_plugins/_ml/models/WWQI44MBbzI2oUKAvNUt/_load
{
"node_ids": ["4PLK7KJWReyX0oWKnBA8nA"]
}
```
#### Example response
All models load asynchronously. Therefore, the load API responds with a new `task_id` based on the load and responds with a new `status` for the task.
```json
{
"task_id" : "hA8P44MBhyWuIwnfvTKP",
"status" : "CREATED"
}
```
### Check the model load status
With your `task_id` from the load response, you can use the `GET _ml/tasks` API to see the load status of your model. Before a loaded model can be used for inferences, the load task's `state` must be `COMPLETED`.
#### Example request
```json
GET /_plugins/_ml/tasks/hA8P44MBhyWuIwnfvTKP
```
#### Example response
```json
{
"model_id" : "WWQI44MBbzI2oUKAvNUt",
"task_type" : "LOAD_MODEL",
"function_name" : "TEXT_EMBEDDING",
"state" : "COMPLETED",
"worker_node" : "KzONM8c8T4Od-NoUANQNGg",
"create_time" : 1665961803150,
"last_update_time" : 1665961815959,
"is_async" : true
}
```
## Use the loaded model for inferences
After the model has been loaded, you can enter the `model_id` into the [predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api#predict) to perform inferences.
```json
POST /_plugins/_ml/models/<model_id>/_predict
```
### Example request
```json
POST /_plugins/_ml/_predict/text_embedding/WWQI44MBbzI2oUKAvNUt
{
"text_docs":[ "today is sunny"],
"return_number": true,
"target_response": ["sentence_embedding"]
}
```
### Example response
```json
{
"inference_results" : [
{
"output" : [
{
"name" : "sentence_embedding",
"data_type" : "FLOAT32",
"shape" : [
384
],
"data" : [
-0.023315024,
0.08975691,
0.078479774,
...
]
}
]
}
]
}
```
## Unload the model
If you're done making predictions with your model, use the unload operation to remove the model from your memory cache. The model will remain accessible in the model index.
```json
POST /_plugins/_ml/models/<model_id>/_unload
```
### Example request
```json
POST /_plugins/_ml/models/MGqJhYMBbbh0ushjm8p_/_unload
```
### Example response
```json
{
"s5JwjZRqTY6nOT0EvFwVdA": {
"stats": {
"MGqJhYMBbbh0ushjm8p_": "deleted"
}
}
}
```
For better performance, you can take advantage of GPU acceleration on your ML node. For more information, see [GPU acceleration]({{site.url}}{{site.baseurl}}/ml-commons-plugin/gpu-acceleration/).

512
_ml-commons-plugin/model-access-control.md
View File

@ -6,6 +6,8 @@ nav_order: 20
---
# Model access control
**Introduced 2.9**
{: .label .label-purple }
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.
@ -107,512 +109,8 @@ PUT _cluster/settings
```
{% include copy-curl.html %}
## Registering a model group
## Model access control API
To register a model group, send a `POST` request to the `_register` endpoint. You can register a model group in `public`, `private`, or `restricted` access mode.
Model access control is achieved through the Model Group APIs. These APIs include the register, search, update, and delete model group operations.
Each model group name in the cluster must be globally unique.
{: .important}
### 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.
`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. If you specify none of the security parameters (`access_mode`, `backend_roles`, and `add_all_backend_roles`), the default `access_mode` is `private`.
`backend_roles` | Array | A list of the model owner's backend roles to add to the model. Can be specified only if `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",
"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",
"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",
"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",
"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",
"access_mode": "private"
}
```
{% include copy-curl.html %}
If you don't specify any of the `access_mode`, `backend_roles`, or `add_all_backend_roles`, the model will have a `private` access mode:
```json
POST /_plugins/_ml/model_groups/_register
{
"name": "model_group_test",
"description": "This is an example description"
}
```
{% 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 `PUT` request to the `model_groups` endpoint and provide the ID of the model group you want to update.
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 `access_mode` to `restricted`, you must specify either `backend_roles` or `add_all_backend_roles` but not both.
- When updating the `name`, ensure the name is globally unique in the cluster.
### Path and HTTP method
```json
PUT /_plugins/_ml/model_groups/<model_group_id>
```
### Request fields
Refer to [Request fields](#request-fields) for request field descriptions.
#### Example request
```json
PUT /_plugins/_ml/model_groups/<model_group_id>
{
"name": "model_group_test",
"description": "This is the updated 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}
When you delete the last model version in a model group, that model group is automatically deleted from the index.
{: .important}
#### 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
}
```
For information about model access control API, see [Model group APIs]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/model-group-apis/index/).

256
_ml-commons-plugin/pretrained-models.md
View File

@ -1,41 +1,98 @@
---
layout: default
title: Pretrained models
parent: Using custom models within OpenSearch
parent: Using ML models within OpenSearch
nav_order: 120
---
Pretrained models are generally available in OpenSearch 2.9 and later.
Sparse encoding models are generally available in OpenSearch 2.11 and later.
{: .note}
# OpenSearch-provided pretrained models
**Generally available 2.9**
{: .label .label-purple }
# Pretrained models
OpenSearch provides a variety of open-source pretrained models that can assist with a range of machine learning (ML) search and analytics use cases. You can upload any supported model to the OpenSearch cluster and use it locally.
The ML framework supports a variety of open-source pretrained models that can assist with a range of machine learning (ML) search and analytics use cases.
## Prerequisites
## Uploading pretrained models
To get started, select one of the [supported pretrained models](#supported-pretrained-models).
To use a pretrained model in your OpenSearch cluster:
### Cluster settings
1. Select the model you want to upload. For a list of pretrained models, see [supported pretrained models](#supported-pretrained-models).
2. Upload the model using the [upload API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-serving-framework#upload-model-to-opensearch). Because a pretrained model originates from the ML Commons model repository, you only need to provide the `name`, `version`, and `model_format` in the upload API request.
This example uses a simple setup with no dedicated ML nodes and allows running a model on a non-ML node.
On clusters with dedicated ML nodes, specify `"only_run_on_ml_node": "true"` for improved performance. For more information, see [ML Commons cluster settings]({{site.url}}{{site.baseurl}}/ml-commons-plugin/cluster-settings/).
To ensure that this basic local setup works, specify the following cluster settings:
```json
POST /_plugins/_ml/models/_upload
PUT _cluster/settings
{
"name": "huggingface/sentence-transformers/all-MiniLM-L12-v2",
"version": "1.0.1",
"model_format": "TORCH_SCRIPT"
"persistent": {
"plugins": {
"ml_commons": {
"only_run_on_ml_node": "false",
"model_access_control_enabled": "true",
"native_memory_threshold": "99"
}
}
}
}
```
{% include copy-curl.html %}
## Step 1: Register a model group
To register a model, you have the following options:
- You can use `model_group_id` to register a model version to an existing model group.
- If you do not use `model_group_id`, ML Commons creates a model with a new model group.
To register a model group, send the following request:
```json
POST /_plugins/_ml/model_groups/_register
{
"name": "local_model_group",
"description": "A model group for local models"
}
```
{% include copy-curl.html %}
The response contains the model group ID that you'll use to register a model to this model group:
```json
{
"model_group_id": "wlcnb4kBJ1eYAeTMHlV6",
"status": "CREATED"
}
```
Note that for sparse encoding models, you still need to upload the full request body, as shown in the following example:
To learn more about model groups, see [Model access control]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-access-control/).
## Step 2: Register a local OpenSearch-provided model
To register a remote model to the model group created in step 1, provide the model group ID from step 1 in the following request.
Because pretrained **sentence transformer** models originate from the ML Commons model repository, you only need to provide the `name`, `version`, `model_group_id`, and `model_format` in the upload API request:
```json
POST /_plugins/_ml/models/_upload
POST /_plugins/_ml/models/_register
{
"name": "huggingface/sentence-transformers/msmarco-distilbert-base-tas-b",
"version": "1.0.1",
"model_group_id": "Z1eQf4oB5Vm0Tdw8EIP2",
"model_format": "TORCH_SCRIPT"
}
```
{% include copy-curl.html %}
Note that for **sparse encoding** models, you still need to upload the full request body, as shown in the following example:
```json
POST /_plugins/_ml/models/_register
{
"name": "amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v1",
"version": "1.0.0",
"model_group_id": "Z1eQf4oB5Vm0Tdw8EIP2",
"description": "This is a neural sparse encoding model: It transfers text into sparse vector, and then extract nonzero index and value to entry and weights. It serves only in ingestion and customer should use tokenizer model in query.",
"model_format": "TORCH_SCRIPT",
"function_name": "SPARSE_ENCODING",
@ -50,7 +107,168 @@ You can find the `url` and `model_content_hash_value` in the model config link f
Note that the `function_name` parameter in the request corresponds to the `model_task_type` parameter in the model config. When using a pretrained model, make sure to change the name of the parameter from `model_task_type` to `function_name` in the model upload request.
{: .important}
For more information about how to upload and use ML models, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/model-serving-framework/).
OpenSearch returns the task ID of the register operation:
```json
{
"task_id": "cVeMb4kBJ1eYAeTMFFgj",
"status": "CREATED"
}
```
To check the status of the operation, provide the task ID to the [Tasks API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/tasks-apis/get-task/#get-a-task-by-id):
```bash
GET /_plugins/_ml/tasks/cVeMb4kBJ1eYAeTMFFgj
```
{% include copy-curl.html %}
When the operation is complete, the state changes to `COMPLETED`:
```json
{
"model_id": "cleMb4kBJ1eYAeTMFFg4",
"task_type": "REGISTER_MODEL",
"function_name": "REMOTE",
"state": "COMPLETED",
"worker_node": [
"XPcXLV7RQoi5m8NI_jEOVQ"
],
"create_time": 1689793598499,
"last_update_time": 1689793598530,
"is_async": false
}
```
Take note of the returned `model_id` because you’ll need it to deploy the model.
## Step 3: Deploy the model
The deploy operation reads the model's chunks from the model index and then creates an instance of the model to load into memory. The bigger the model, the more chunks the model is split into and longer it takes for the model to load into memory.
To deploy the registered model, provide its model ID from step 3 in the following request:
```bash
POST /_plugins/_ml/models/cleMb4kBJ1eYAeTMFFg4/_deploy
```
{% include copy-curl.html %}
The response contains the task ID that you can use to check the status of the deploy operation:
```json
{
"task_id": "vVePb4kBJ1eYAeTM7ljG",
"status": "CREATED"
}
```
As in the previous step, check the status of the operation by calling the Tasks API:
```bash
GET /_plugins/_ml/tasks/vVePb4kBJ1eYAeTM7ljG
```
{% include copy-curl.html %}
When the operation is complete, the state changes to `COMPLETED`:
```json
{
"model_id": "cleMb4kBJ1eYAeTMFFg4",
"task_type": "DEPLOY_MODEL",
"function_name": "REMOTE",
"state": "COMPLETED",
"worker_node": [
"n-72khvBTBi3bnIIR8FTTw"
],
"create_time": 1689793851077,
"last_update_time": 1689793851101,
"is_async": true
}
```
## Step 4 (Optional): Test the model
Use the [Predict API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/train-predict/predict/) to test the model.
For a text embedding model, send the following request:
```json
POST /_plugins/_ml/_predict/text_embedding/cleMb4kBJ1eYAeTMFFg4
{
"text_docs":[ "today is sunny"],
"return_number": true,
"target_response": ["sentence_embedding"]
}
```
{% include copy-curl.html %}
The response contains text embeddings for the provided sentence:
```json
{
"inference_results" : [
{
"output" : [
{
"name" : "sentence_embedding",
"data_type" : "FLOAT32",
"shape" : [
768
],
"data" : [
0.25517133,
-0.28009856,
0.48519906,
...
]
}
]
}
]
}
```
For a sparse encoding model, send the following request:
```json
POST /_plugins/_ml/_predict/sparse_encoding/cleMb4kBJ1eYAeTMFFg4
{
"text_docs":[ "today is sunny"]
}
```
{% include copy-curl.html %}
The response contains the tokens and weights:
```json
{
"inference_results": [
{
"output": [
{
"name": "output",
"dataAsMap": {
"response": [
{
"saturday": 0.48336542,
"week": 0.1034762,
"mood": 0.09698499,
"sunshine": 0.5738209,
"bright": 0.1756877,
...
}
}
}
}
}
```
## Step 5: Use the model for search
To learn how to set up a vector index and use text embedding models for search, see [Neural text search]({{site.url}}{{site.baseurl}}/search-plugins/neural-text-search/).
To learn how to set up a vector index and use sparse encoding models for search, see [Neural sparse search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/).
## Supported pretrained models
@ -79,6 +297,8 @@ The following table provides a list of sentence transformer models and artifact
| `huggingface/sentence-transformers/paraphrase-mpnet-base-v2` | 1.0.0 | 768-dimensional dense vector space. | Yes | - [model_url](https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/paraphrase-mpnet-base-v2/1.0.0/torch_script/sentence-transformers_paraphrase-mpnet-base-v2-1.0.0-torch_script.zip)<br>- [config_url](https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/paraphrase-mpnet-base-v2/1.0.0/torch_script/config.json) | - [model_url](https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/paraphrase-mpnet-base-v2/1.0.0/onnx/sentence-transformers_paraphrase-mpnet-base-v2-1.0.0-onnx.zip)<br>- [config_url](https://artifacts.opensearch.org/models/ml-models/huggingface/sentence-transformers/paraphrase-mpnet-base-v2/1.0.0/onnx/config.json) |
### Sparse encoding models
**Introduced 2.11**
{: .label .label-purple }
Sparse encoding models transfer text into a sparse vector and convert the vector to a list of `<token: weight>` pairs representing the text entry and its corresponding weight in the sparse vector. You can use these models for use cases such as clustering or sparse neural search.
@ -94,4 +314,4 @@ The following table provides a list of sparse encoding models and artifact links
|---|---|---|
| `amazon/neural-sparse/opensearch-neural-sparse-encoding-v1` | Yes | - [model_url](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-encoding-v1/1.0.0/torch_script/opensearch-neural-sparse-encoding-v1-1.0.0-torch_script.zip)<br>- [config_url](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-encoding-v1/1.0.0/torch_script/config.json) | A neural sparse encoding model. The model transforms text into a sparse vector, identifies the indexes of non-zero elements in the vector, and then converts the vector into `<entry, weight>` pairs, where each entry corresponds to a non-zero element index. |
| `amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v1` | Yes | - [model_url](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v1/1.0.0/torch_script/opensearch-neural-sparse-encoding-doc-v1-1.0.0-torch_script.zip)<br>- [config_url](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-encoding-doc-v1/1.0.0/torch_script/config.json) | A neural sparse encoding model. The model transforms text into a sparse vector, identifies the indexes of non-zero elements in the vector, and then converts the vector into `<entry, weight>` pairs, where each entry corresponds to a non-zero element index. |
| `amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1` | Yes | - [model_url](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1/1.0.0/torch_script/opensearch-neural-sparse-tokenizer-v1-1.0.0.zip)<br>- [config_url](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1/1.0.0/torch_script/config.json) | A neural sparse tokenizer model. The model tokenizes text into tokens and assigns each token a predefined weight, which is the token's IDF (if the IDF file is not provided, the weight defaults to 1). For more information, see [Uploading your own model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/#uploading-your-own-model). |
| `amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1` | Yes | - [model_url](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1/1.0.0/torch_script/opensearch-neural-sparse-tokenizer-v1-1.0.0.zip)<br>- [config_url](https://artifacts.opensearch.org/models/ml-models/amazon/neural-sparse/opensearch-neural-sparse-tokenizer-v1/1.0.0/torch_script/config.json) | A neural sparse tokenizer model. The model tokenizes text into tokens and assigns each token a predefined weight, which is the token's IDF (if the IDF file is not provided, the weight defaults to 1). For more information, see [Preparing a model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/custom-local-models/#preparing-a-model). |

6
_ml-commons-plugin/semantic-search.md
View File

@ -112,7 +112,7 @@ For this tutorial, you'll use the [DistilBERT](https://huggingface.co/docs/trans
#### Advanced: Using a different model
Alternatively, you can choose to use one of the [pretrained language models provided by OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/) or your own custom model. For information about choosing a model, see [Further reading](#further-reading). For instructions on how to set up a custom model, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
Alternatively, you can choose to use one of the [pretrained language models provided by OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/) or your own custom model. For information about choosing a model, see [Further reading](#further-reading). For instructions on how to set up a custom model, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
Take note of the dimensionality of the model because you'll need it when you set up a k-NN index.
{: .important}
@ -332,7 +332,7 @@ POST /_plugins/_ml/models/_register
}
```
For more information, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
For more information, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
### Step 1(d): Deploy the model
@ -421,7 +421,7 @@ The response shows the model state as `DEPLOYED`:
}
```
You can also receive statistics for all deployed models in your cluster by sending a [Models Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/#profile) request:
You can also receive statistics for all deployed models in your cluster by sending a [Models Profile API]({{site.url}}{{site.baseurl}}/ml-commons-plugin/api/profile/) request:
```json
GET /_plugins/_ml/profile/models

2
_search-plugins/neural-multimodal-search.md
View File

@ -13,7 +13,7 @@ Introduced 2.11
Use multimodal search to search text and image data. In neural search, text search is facilitated by multimodal embedding models.
**PREREQUISITE**<br>
Before using text search, you must set up a multimodal embedding model. For more information, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
Before using text search, you must set up a multimodal embedding model. For more information, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/) and [Connecting to remote models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/index/).
{: .note}
## Using multimodal search

24
_search-plugins/neural-search.md
View File

@ -12,14 +12,24 @@ redirect_from:
Neural search transforms text into vectors and facilitates vector search both at ingestion time and at search time. During ingestion, neural search transforms document text into vector embeddings and indexes both the text and its vector embeddings in a vector index. When you use a neural query during search, neural search converts the query text into vector embeddings, uses vector search to compare the query and document embeddings, and returns the closest results.
Neural search supports the following search types:
Before you ingest documents into an index, documents are passed through a machine learning (ML) model, which generates vector embeddings for the document fields. When you send a search request, the query text or image is also passed through the ML model, which generates the corresponding vector embeddings. Then neural search performs a vector search on the embeddings and returns matching documents.
- [Text search]({{site.url}}{{site.baseurl}}/search-plugins/neural-text-search/): Uses dense retrieval based on text embedding models to search text data.
- [Multimodal search]({{site.url}}{{site.baseurl}}/search-plugins/neural-multimodal-search/): Uses vision-language embedding models to search text and image data.
- [Sparse search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/): Uses sparse retrieval based on sparse embedding models to search text data.
## Prerequisite
## Embedding models
Before using neural search, you must set up an ML model. You can either use a pretrained model provided by OpenSearch, upload your own model to OpenSearch, or connect to a foundation model hosted on an external platform. For more information about ML models, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/) and [Connecting to remote models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/index/). For a step-by-step tutorial, see [Semantic search]({{site.url}}{{site.baseurl}}/ml-commons-plugin/semantic-search/).
Before using neural search, you must set up a machine learning (ML) model. You can either use a pretrained model provided by OpenSearch, upload your own model to OpenSearch, or connect to a foundation model hosted on an external platform. For more information about ML models, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/) and [ML Extensibility]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/index/). For a step-by-step tutorial, see [Semantic search]({{site.url}}{{site.baseurl}}/ml-commons-plugin/semantic-search/).
## Set up neural search
Before you ingest documents into an index, documents are passed through the ML model, which generates vector embeddings for the document fields. When you send a search request, the query text or image is also passed through the ML model, which generates the corresponding vector embeddings. Then neural search performs a vector search on the embeddings and returns matching documents.
Once you set up an ML model, choose one of the following neural search types to learn how to use your model for neural search.
### Neural text search
Neural text search uses dense retrieval based on text embedding models to search text data. For detailed setup steps, see [Text search]({{site.url}}{{site.baseurl}}/search-plugins/neural-text-search/).
### Multimodal search
Multimodal search uses multimodal embedding models to search text and image data. For detailed setup steps, see [Multimodal search]({{site.url}}{{site.baseurl}}/search-plugins/neural-multimodal-search/).
### Neural sparse search
Neural sparse search uses sparse retrieval based on sparse embedding models to search text data. For detailed setup steps, see [Sparse search]({{site.url}}{{site.baseurl}}/search-plugins/neural-sparse-search/).

4
_search-plugins/neural-sparse-search.md
View File

@ -6,7 +6,7 @@ has_children: false
parent: Neural search
---
# Sparse search
# Neural sparse search
Introduced 2.11
{: .label .label-purple }
@ -18,7 +18,7 @@ When selecting a model, choose one of the following options:
- Use a sparse encoding model at ingestion time and a tokenizer model at search time (low performance, relatively low latency).
**PREREQUISITE**<br>
Before using sparse search, make sure to set up a [pretrained sparse embedding model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/#sparse-encoding-models) or your own sparse embedding model. For more information, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
Before using sparse search, make sure to set up a [pretrained sparse embedding model]({{site.url}}{{site.baseurl}}/ml-commons-plugin/pretrained-models/#sparse-encoding-models) or your own sparse embedding model. For more information, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/) and [Connecting to remote models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/index/).
{: .note}
## Using sparse search

4
_search-plugins/neural-text-search.md
View File

@ -6,12 +6,12 @@ has_children: false
parent: Neural search
---
# Text search
# Neural text search
Use text search for text data. In neural search, text search is facilitated by text embedding models. Text search creates a dense vector (a list of floats) and ingests data into a k-NN index.
**PREREQUISITE**<br>
Before using text search, you must set up a text embedding model. For more information, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
Before using text search, you must set up a text embedding model. For more information, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/) and [Connecting to remote models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/index/).
{: .note}
## Using text search

2
_search-plugins/search-pipelines/neural-query-enricher.md
View File

@ -9,7 +9,7 @@ grand_parent: Search pipelines
# Neural query enricher processor
The `neural_query_enricher` search request processor is designed to set a default machine learning (ML) model ID at the index or field level for [neural search]({{site.url}}{{site.baseurl}}/search-plugins/neural-search/) queries. To learn more about ML models, see [Using custom models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/).
The `neural_query_enricher` search request processor is designed to set a default machine learning (ML) model ID at the index or field level for [neural search]({{site.url}}{{site.baseurl}}/search-plugins/neural-search/) queries. To learn more about ML models, see [Using ML models within OpenSearch]({{site.url}}{{site.baseurl}}/ml-commons-plugin/ml-framework/) and [Connecting to remote models]({{site.url}}{{site.baseurl}}/ml-commons-plugin/extensibility/index/).
## Request fields