OpenSearch ML Commons 通过 REST API 提供机器学习算法。支持同步/异步训练 ML 算法、基于训练好的模型进行预测。为了便于通过 API 训练任务，需要设置以下三个输入：
- Algorithm Name：必须是 FunctionName 中的一种。这里由于我们是自己新创建的算法，因此需要添加一个新的 Function：
- Model hyper parameters：调整超参数可用让模型训练的更好。
- Input Data：模型训练或用于预测的数据输入。可用两种方式指定：
- query against index
- use data frame
权限：opensearch 中 ml_full_access、ml_readonly_access 权限的用户可以使用 ML 功能。
为了防止 opensearch cluster 在运行 ML 任务时失败，可以（但不必要）配置一个 ML node。并且配置的 ML node 如果没有 data node role，ML node 将不会保存任何 shards 并在运行时计算资源需求。为了使用 ML node，在 opensearch.yml 中配置：
node.name: ml-node
node.rules: [ ml ]
以及一些其他相关配置便于用 opensearch 跑 ML 模型：ML Commons cluster settings
模型相关操作
训练模型
举例：分别以同步、异步方式训练 Kmeans 模型
POST /_plugins/_ml/_train/kmeans # 同步
POST /_plugins/_ml/_train/kmeans?async=true # 异步
POST数据：
{
"parameters": {
# 下面的字段是 kmeans 的参数
"centroids": 3,
"iterations": 10,
"distance_type": "COSINE"
},
"input_query": {
# 查询条件
"_source": ["petal_length_in_cm", "petal_width_in_cm"], # 字段
"size": 10000 # 数量
},
"input_index": [
"iris_data" # index：类似于数据库的Table
]
}
对于同步操作，返回 model_id 可用于使用模型：
{
"model_id" : "lblVmX8BO5w8y8RaYYvN",
"status" : "COMPLETED"
}
对于异步操作，返回 task_id。由于是异步，所以需要查询 task 执行结果。
{
"task_id" : "lrlamX8BO5w8y8Ra2otd",
"status" : "CREATED"
}
// 查询 task 信息
GET /_plugins/_ml/tasks/<task_id>
Response：
{
"model_id" : "l7lamX8BO5w8y8Ra2oty",
"task_type" : "TRAINING",
"function_name" : "KMEANS",
"state" : "COMPLETED", // 注意：COMPLETED 后的模型才可以使用！
"input_type" : "SEARCH_QUERY",
"worker_node" : "54xOe0w8Qjyze00UuLDfdA",
"create_time" : 1647545342556,
"last_update_time" : 1647545342587,
"is_async" : true
}
查询模型信息
GET /_plugins/_ml/models/<model-id>
Response：
{
"name" : "KMEANS",
"algorithm" : "KMEANS",
"version" : 1,
"content" : ""
}
上传模型
将自定义模型上传到 model index。通常会把模型切分成更小的chunks，然后再把chunks保存进模型索引。
| 必要字段 | 类型 | 描述 |
|---|---|---|
| name | string | 模型名 |
| version | integer | 模型版本 |
| model_format | string | 目前只支持 TORCH_SCRIPT，(v2.5+后支持)ONNX，上传前需要处理成zip |
| model_config | json | 模型配置参数，包括：model_type、embedding_dimension、framework_type |
| url | string | 保存模型的URL地址 |
- 问题：如果是本地文件呢？url 能直接用 file:// 指定吗？模型文件格式要求是怎样的？
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"
}
Response：
{
"task_id" : "ew8I44MBhyWuIwnfvDIH",
"status" : "CREATED"
}
# 查询 task 信息
GET /_plugins/_ml/tasks/<task_id>
Response：
{
"model_id" : "WWQI44MBbzI2oUKAvNUt",
"task_type" : "UPLOAD_MODEL",
"function_name" : "TEXT_EMBEDDING",
"state" : "COMPLETED",
"worker_node" : "KzONM8c8T4Od-NoUANQNGg",
"create_time" : 1665961344003,
"last_update_time" : 1665961373047,
"is_async" : true
}
加载模型：将模型载入内存
load model 操作从 model index 读取 model chunks，然后在内存中创建模型实例。
POST /_plugins/_ml/models/<model_id>/_load # 在所有 ML nodes 加载模型
# 在特定 ML node 加载模型
POST /_plugins/_ml/models/<model_id>/_load
{
"node_ids": ["4PLK7KJWReyX0oWKnBA8nA"]
}
Response：
{
"task_id" : "hA8P44MBhyWuIwnfvTKP",
"status" : "CREATED"
}
模型卸载：从内存中unload
同上。
POST /_plugins/_ml/models/<model_id>/_unload # 对特定模型从所有nodes卸载
POST /_plugins/_ml/models/_unload # 对特定模型从特定nodes卸载
{
"node_ids": ["sv7-3CbwQW-4PiIsDOfLxQ"],
"model_ids": ["KDo2ZYQB-v9VEDwdjkZ4"]
}
POST /_plugins/_ml/models/_unload
{
# 对特定模型从所有nodes卸载的另一种写法
"model_ids": ["KDo2ZYQB-v9VEDwdjkZ4"]
}
模型搜索
POST /_plugins/_ml/models/_search
{
"query": {
"match_all": {
} # 查询所有模型
},
"size": 1000
}
POST /_plugins/_ml/models/_search
{
"query": {
"term": {
# 查询特定模型
"algorithm": {
"value": "FIT_RCF"
}
}
}
}
模型删除
DELETE /_plugins/_ml/models/<model_id>
Profile
略，请查看doc，主要是关于运行时的信息，用于debug。
模型推理 Predict
OpenSearch 的 ML Commons 可以通过 index data 或 data frame 的数据和训练好的模型来进行推理。
POST /_plugins/_ml/_predict/<algorithm_name>/<model_id>
eg.
POST /_plugins/_ml/_predict/kmeans/<model-id>
{
"input_query": {
"_source": ["petal_length_in_cm", "petal_width_in_cm"],
"size": 10000
},
"input_index": [
"iris_data"
]
}
response:
{
"status" : "COMPLETED",
"prediction_result" : {
"column_metas" : [
{
"name" : "ClusterID",
"column_type" : "INTEGER"
}
],
"rows" : [
{
"values" : [
{
"column_type" : "INTEGER",
"value" : 1
}
]
},
{
"values" : [
{
"column_type" : "INTEGER",
"value" : 0
}
]
},
...
]
}
}
模型服务化 Model-serving
- 根据文档，目前这个还是实验性功能。另外独立于 opensearch 的流程，需要事先准备好训练好的模型。
- 从 OpenSearch 2.4 开始，模型服务框架只支持 text embedding 模型，不支持GPU加速。
- 为了能在 OpenSearch 中使用模型，需要把模型导成可移植的格式(portable format)。
- 从 OpenSearch 2.5 开始支持 TorchScript 和 ONNX 格式。
- 大多数深度学习模型都超过 100 MB，因此很难将其放入单个文档中。OpenSearch将模型文件分割成更小的块，存储在模型索引中。为OpenSearch集群分配机器学习（ML）或数据节点时，请确保正确调整ML节点的大小，以便在进行ML推断时有足够的内存。
如果需要 GPU 加速：GPU acceleration
流程：1. upload model 2. load model 3. predict
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"
}
POST /_plugins/_ml/models/WWQI44MBbzI2oUKAvNUt/_load
POST /_plugins/_ml/_predict/text_embedding/WWQI44MBbzI2oUKAvNUt
{
"text_docs":["today is sunny"],
"return_number": true,
"target_response": ["sentence_embedding"]
}
POST /_plugins/_ml/models/MGqJhYMBbbh0ushjm8p_/_unload