Added ML Model APIs (undeploy, unload), moved test for search model t…

…o models/search.yaml, resolved conflicts and updated CHANGELOG

Signed-off-by: Nathalie Jonathan <[email protected]>

CHANGELOG.md

@@ -45,6 +45,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 - Added `GET /_plugins/_ml/connectors/{connector_id}`, `_search`, `POST /_plugins/_ml/connectors/_search`, and `PUT /_plugins/_ml/connectors/{connector_id}` ([#764](https://github.com/opensearch-project/opensearch-api-specification/pull/764))
 - Added the ability to skip an individual chapter test ([#765](https://github.com/opensearch-project/opensearch-api-specification/pull/765))
 - Added uploading of test spec logs ([#767](https://github.com/opensearch-project/opensearch-api-specification/pull/767))
+- Added `GET /_plugins/_ml/models/{model_id}`, `POST /_plugins/_ml/models/_search`, `PUT /_plugins/_ml/models/{model_id}`, `POST /_plugins/_ml/models/{model_id}/_unload`, `POST /_plugins/_ml/models/_unload`, and `POST /_plugins/_ml/models/_undeploy` ([#733](https://github.com/opensearch-project/opensearch-api-specification/pull/733))
 
 ### Removed
 - Removed unsupported `_common.mapping:SourceField`'s `mode` field and associated `_common.mapping:SourceFieldMode` enum ([#652](https://github.com/opensearch-project/opensearch-api-specification/pull/652))

spec/namespaces/ml.yaml

@@ -126,6 +126,40 @@ paths:
       responses:
         '200':
           $ref: '#/components/responses/ml.undeploy_model@200'
+  /_plugins/_ml/models/_undeploy:
+    post:
+      operationId: ml.undeploy_model.1
+      x-operation-group: ml.undeploy_model
+      description: Undeploys a model.
+      requestBody:
+        $ref: '#/components/requestBodies/ml.undeploy_model'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.undeploy_model@200'
+  /_plugins/_ml/models/{model_id}/_unload:
+    post:
+      operationId: ml.unload_model.0
+      x-operation-group: ml.unload_model
+      deprecated: true
+      x-version-deprecated: 2.7.0
+      x-deprecation-message: Use `undeploy_model` instead.
+      parameters:
+        - $ref: '#/components/parameters/ml.unload_model::path.model_id'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.unload_model@200'
+  /_plugins/_ml/models/_unload:
+    post:
+      operationId: ml.unload_model.1
+      x-operation-group: ml.unload_model
+      deprecated: true
+      x-version-deprecated: 2.7.0
+      x-deprecation-message: Use `undeploy_model` instead.
+      requestBody:
+        $ref: '#/components/requestBodies/ml.unload_model'
+      responses:
+        '200':
+          $ref: '#/components/responses/ml.unload_model@200'
   /_plugins/_ml/tasks/{task_id}:
     get:
       operationId: ml.get_task.0
@@ -156,7 +190,7 @@ paths:
         '200':
           $ref: '#/components/responses/ml.search_models@200'
     post:
-      operationId: ml.search_models.0
+      operationId: ml.search_models.1
       x-operation-group: ml.search_models
       description: Searches for models.
       requestBody:
@@ -429,6 +463,7 @@ components:
                 type: object
                 description: The model interface.
     ml.train:
+    ml.undeploy_model:
       content:
         application/json:
           schema:
@@ -444,6 +479,17 @@ components:
                 items:
                   type: string
     ml.train_predict:
+              node_ids:
+                type: array
+                items:
+                  $ref: '_common.yaml#/components/schemas/Id'
+              model_ids:
+                type: array
+                items:
+                  $ref: '_common.yaml#/components/schemas/Id'
+            required:
+              - model_ids
+    ml.unload_model:
       content:
         application/json:
           schema:
@@ -484,6 +530,16 @@ components:
               interface:
                 type: object
                 description: The model interface.
+              node_ids:
+                type: array
+                items:
+                  $ref: '_common.yaml#/components/schemas/Id'
+              model_ids:
+                type: array
+                items:
+                  $ref: '_common.yaml#/components/schemas/Id'
+            required:
+              - model_ids
     ml.create_connector:
       content:
         application/json:
@@ -660,6 +716,11 @@ components:
         application/json:
           schema:
             $ref: '../schemas/ml._common.yaml#/components/schemas/UndeployModelResponse'
+    ml.unload_model@200:
+      content:
+        application/json:
+          schema:
+            $ref: '../schemas/ml._common.yaml#/components/schemas/UnloadModelResponse'
     ml.delete_model@200:
       content:
         application/json:
@@ -795,6 +856,12 @@ components:
       required: true
       schema:
         type: string
+    ml.unload_model::path.model_id:
+      name: model_id
+      in: path
+      required: true
+      schema:
+        type: string
     ml.delete_task::path.task_id:
       name: task_id
       in: path

spec/schemas/ml._common.yaml

@@ -721,6 +721,7 @@ components:
             - PARTIALLY_DEPLOYED
             - REGISTERED
             - REGISTERING
+            - UNDEPLOYED
         model_content_size_in_bytes:
           type: integer
           format: int64
@@ -891,6 +892,19 @@ components:
     UndeployModelNodeStats:
       type: object
       additionalProperties: true
+    UnloadModelResponse:
+      type: object
+      additionalProperties:
+        title: nodes
+        $ref: '#/components/schemas/UnloadModelNode'
+    UnloadModelNode:
+      type: object
+      properties:
+        stats:
+          $ref: '#/components/schemas/UnloadModelNodeStats'
+    UnloadModelNodeStats:
+      type: object
+      additionalProperties: true
     Credential:
       type: object
       properties:

tests/plugins/ml/ml/models.yaml

@@ -51,20 +51,6 @@ chapters:
         hits:
           hits:
             - _score: 1
-  - synopsis: Search model.
-    path: /_plugins/_ml/models/_search
-    method: POST
-    request:
-      payload:
-        query:
-          match_all: {}
-        size: 1000
-    response:
-      status: 200
-      payload:
-        hits:
-          hits:
-            - _score: 1
   - synopsis: Get model.
     path: /_plugins/_ml/models/{model_id}
     method: GET
@@ -79,7 +65,7 @@ chapters:
       model_id: ${get_completed_task.model_id}
     request:
       payload:
-        name: updated_name
+        name: updated
     response:
       status: 200
   - synopsis: Delete model.

tests/plugins/ml/models/search.yaml

@@ -0,0 +1,34 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test the search of models.
+distributions:
+  excluded:
+    - amazon-managed
+    - amazon-serverless
+version: '>= 2.11'
+prologues:
+  - path: /_plugins/_ml/models/_register
+    id: register_model
+    method: POST
+    request:
+      payload:
+        name: huggingface/sentence-transformers/msmarco-distilbert-base-tas-b
+        version: 1.0.1
+        model_format: TORCH_SCRIPT
+    output:
+      task_id: payload.task_id
+chapters:
+  - synopsis: Search model.
+    path: /_plugins/_ml/models/_search
+    method: POST
+    request:
+      payload:
+        query:
+          match_all: {}
+        size: 1000
+    response:
+      status: 200
+      payload:
+        hits:
+          hits:
+            - _score: 1

tests/plugins/ml/models/undeploy_specific_models.yaml

@@ -0,0 +1,77 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test the undeployment of specific models from specific nodes.
+distributions:
+  excluded:
+    - amazon-managed
+    - amazon-serverless
+version: '>= 2.11'
+warnings:
+  multiple-paths-detected: false
+prologues:
+  - path: /_plugins/_ml/models/_register
+    id: register_model
+    method: POST
+    request:
+      payload:
+        name: huggingface/sentence-transformers/msmarco-distilbert-base-tas-b
+        version: 1.0.1
+        model_format: TORCH_SCRIPT
+    output:
+      task_id: payload.task_id
+epilogues:
+  - path: /_plugins/_ml/models/{model_id}
+    parameters:
+      model_id: ${get_completed_register_model_task.model_id}
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Wait to get completed task.
+    id: get_completed_register_model_task
+    path: /_plugins/_ml/tasks/{task_id}
+    method: GET
+    parameters:
+      task_id: ${register_model.task_id}
+    response:
+      status: 200
+      payload:
+        state: COMPLETED
+    output:
+      model_id: payload.model_id
+    retry:
+      count: 3
+      wait: 10000
+  - synopsis: Deploy a model.
+    id: deploy_model
+    path: /_plugins/_ml/models/{model_id}/_deploy
+    method: POST
+    parameters:
+      model_id: ${get_completed_register_model_task.model_id}
+    output:
+      task_id: payload.task_id
+    response:
+      status: 200
+  - synopsis: Wait to get completed task.
+    id: get_completed_deploy_model_task
+    path: /_plugins/_ml/tasks/{task_id}
+    method: GET
+    parameters:
+      task_id: ${deploy_model.task_id}
+    response:
+      status: 200
+      payload:
+        state: COMPLETED
+    output:
+      model_id: payload.model_id
+    retry:
+      count: 3
+      wait: 10000      
+  - synopsis: Undeploy a model.
+    path: /_plugins/_ml/models/_undeploy
+    method: POST
+    request:
+      payload:
+        model_ids: 
+          - ${get_completed_register_model_task.model_id}
+    response:
+      status: 200

tests/plugins/ml/models/unload.yaml

@@ -0,0 +1,74 @@
+$schema: ../../../../json_schemas/test_story.schema.yaml
+
+description: Test the unload (deprecated) of a model from all ML nodes.
+distributions:
+  excluded:
+    - amazon-managed
+    - amazon-serverless
+warnings:
+  multiple-paths-detected: false
+prologues:
+  - path: /_plugins/_ml/models/_register
+    id: register_model
+    method: POST
+    request:
+      payload:
+        name: huggingface/sentence-transformers/msmarco-distilbert-base-tas-b
+        version: 1.0.1
+        model_format: TORCH_SCRIPT
+    output:
+      task_id: payload.task_id
+epilogues:
+  - path: /_plugins/_ml/models/{model_id}
+    parameters:
+      model_id: ${get_completed_register_model_task.model_id}
+    method: DELETE
+    status: [200, 404]
+chapters:
+  - synopsis: Wait to get completed task.
+    id: get_completed_register_model_task
+    path: /_plugins/_ml/tasks/{task_id}
+    method: GET
+    parameters:
+      task_id: ${register_model.task_id}
+    response:
+      status: 200
+      payload:
+        state: COMPLETED
+    output:
+      model_id: payload.model_id
+    retry:
+      count: 3
+      wait: 10000
+  - synopsis: Deploy a model.
+    id: deploy_model
+    path: /_plugins/_ml/models/{model_id}/_deploy
+    method: POST
+    parameters:
+      model_id: ${get_completed_register_model_task.model_id}
+    output:
+      task_id: payload.task_id
+    response:
+      status: 200
+  - synopsis: Wait to get completed task.
+    id: get_completed_deploy_model_task
+    path: /_plugins/_ml/tasks/{task_id}
+    method: GET
+    parameters:
+      task_id: ${deploy_model.task_id}
+    response:
+      status: 200
+      payload:
+        state: COMPLETED
+    output:
+      model_id: payload.model_id
+    retry:
+      count: 3
+      wait: 10000
+  - synopsis: Unload a model.
+    path: /_plugins/_ml/models/{model_id}/_unload
+    method: POST
+    parameters:
+      model_id: ${get_completed_register_model_task.model_id}
+    response:
+      status: 200