From 5644cabe471da4d98c4019c3712d2aad054cbd00 Mon Sep 17 00:00:00 2001 From: Nathalie Jonathan <143617992+nathaliellenaa@users.noreply.github.com> Date: Wed, 5 Feb 2025 15:58:46 -0800 Subject: [PATCH] Add ML Execute Algorithm API (#811) * Added Execute Algorithm ML API. Signed-off-by: Nathalie Jonathan * Changed version in test execute API. Signed-off-by: Nathalie Jonathan * Change execute test version. Signed-off-by: Nathalie Jonathan * Add execute schema property. Signed-off-by: Nathalie Jonathan --------- Signed-off-by: Nathalie Jonathan --- CHANGELOG.md | 1 + spec/namespaces/ml.yaml | 85 +++++++++++++++++++++++++++++++- spec/schemas/ml._common.yaml | 75 +++++++++++++++++++++++++++- tests/plugins/ml/ml/execute.yaml | 67 +++++++++++++++++++++++++ 4 files changed, 226 insertions(+), 2 deletions(-) create mode 100644 tests/plugins/ml/ml/execute.yaml diff --git a/CHANGELOG.md b/CHANGELOG.md index 126abb1f9..e42ff3447 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -57,6 +57,7 @@ Inspired from [Keep a Changelog](https://keepachangelog.com/en/1.0.0/) - Added `time` field to the `GetStats` schema in `_common.yml` ([#803](https://github.com/opensearch-project/opensearch-api-specification/pull/803)) - Added version for `POST /_plugins/_ml/_train/{algorithm_name}`, `_predict/{algorithm_name}/{model_id}`, and `_train_predict/{algorithm_name}` ([#763](https://github.com/opensearch-project/opensearch-api-specification/pull/763)) - Added `POST _plugins/_security/api/internalusers/{username}` response `201` ([#810](https://github.com/opensearch-project/opensearch-api-specification/pull/810)) +- Added `POST /_plugins/_ml/_execute/{algorithm_name}` ([#811](https://github.com/opensearch-project/opensearch-api-specification/pull/811)) ### 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)) diff --git a/spec/namespaces/ml.yaml b/spec/namespaces/ml.yaml index d0062aed7..e278373af 100644 --- a/spec/namespaces/ml.yaml +++ b/spec/namespaces/ml.yaml @@ -827,6 +827,19 @@ paths: responses: '200': $ref: '#/components/responses/ml.get_tool@200' + /_plugins/_ml/_execute/{algorithm_name}: + post: + operationId: ml.execute_algorithm.0 + x-operation-group: ml.execute_algorithm + x-version-added: '2.0' + description: Execute an algorithm. + parameters: + - $ref: '#/components/parameters/ml.execute_algorithm::path.algorithm_name' + requestBody: + $ref: '#/components/requestBodies/ml.execute_algorithm' + responses: + '200': + $ref: '#/components/responses/ml.execute_algorithm@200' components: requestBodies: ml.register_model_group: @@ -1483,6 +1496,62 @@ components: application/json: schema: $ref: '../schemas/ml._common.yaml#/components/schemas/ProfileRequest' + ml.execute_algorithm: + content: + application/json: + schema: + type: object + properties: + operation: + type: string + description: The calculator operation. + enum: + - max + - min + - sum + input_data: + type: array + items: + type: number + description: The input data. + index_name: + type: string + description: The index name. + attribute_field_names: + type: array + items: + type: string + description: The attribute field names + aggregations: + type: array + items: + $ref: '../schemas/ml._common.yaml#/components/schemas/Aggregation' + time_field_name: + type: string + description: The time field name. + start_time: + type: integer + format: int64 + description: The start time. + end_time: + type: integer + format: int64 + description: The end time. + min_time_interval: + type: integer + format: int64 + description: The minimum time interval. + num_outputs: + type: integer + format: int64 + description: The number of outputs. + metrics: + type: array + items: + type: array + items: + type: number + description: The metrics input. responses: ml.register_model_group@200: content: @@ -1918,6 +1987,11 @@ components: application/json: schema: $ref: '../schemas/ml._common.yaml#/components/schemas/Tool' + ml.execute_algorithm@200: + content: + application/json: + schema: + $ref: '../schemas/ml._common.yaml#/components/schemas/ExecuteAlgorithmResponse' parameters: ml.get_all_memories::query.max_results: name: max_results @@ -2260,4 +2334,13 @@ components: - SearchIndexTool - SearchMonitorsTool - VectorDBTool - - VisualizationTool \ No newline at end of file + - VisualizationTool + ml.execute_algorithm::path.algorithm_name: + name: algorithm_name + in: path + required: true + schema: + type: string + enum: + - anomaly_localization + - local_sample_calculator \ No newline at end of file diff --git a/spec/schemas/ml._common.yaml b/spec/schemas/ml._common.yaml index 9348d2eeb..5ec2bc0f5 100644 --- a/spec/schemas/ml._common.yaml +++ b/spec/schemas/ml._common.yaml @@ -1418,6 +1418,8 @@ components: $ref: '#/components/schemas/ModelStats' train_predict: $ref: '#/components/schemas/ModelStats' + execute: + $ref: '#/components/schemas/ModelStats' PredictRequestStats: type: object properties: @@ -1560,6 +1562,8 @@ components: $ref: '#/components/schemas/ModelStats' train_predict: $ref: '#/components/schemas/ModelStats' + execute: + $ref: '#/components/schemas/ModelStats' ModelStats: type: object properties: @@ -1580,6 +1584,8 @@ components: properties: sum: $ref: '#/components/schemas/Aggregation' + max: + $ref: '#/components/schemas/Aggregation' field: type: string description: The field name. @@ -1596,4 +1602,71 @@ components: type: string description: The tool type. version: - $ref: '_common.yaml#/components/schemas/VersionString' \ No newline at end of file + $ref: '_common.yaml#/components/schemas/VersionString' + ExecuteAlgorithmResponse: + oneOf: + - $ref: '#/components/schemas/ExecuteLocalSampleCalculatorResponse' + - type: object + properties: + results: + type: array + items: + $ref: '#/components/schemas/ExecuteAnomalyLocalizationResponse' + ExecuteLocalSampleCalculatorResponse: + type: object + properties: + result: + type: number + description: The result. + ExecuteAnomalyLocalizationResponse: + type: object + properties: + name: + type: string + result: + $ref: '#/components/schemas/Result' + Result: + type: object + properties: + buckets: + type: array + items: + $ref: '#/components/schemas/Buckets' + Buckets: + type: object + properties: + start_time: + type: integer + format: int64 + description: The start time. + end_time: + type: integer + format: int64 + description: The end time. + overall_aggregate_value: + type: number + format: double + description: The overall aggregate value. + entities: + type: array + items: + $ref: '#/components/schemas/Entity' + Entity: + type: object + properties: + key: + type: array + items: + type: string + contribution_value: + type: number + format: double + description: The contribution value. + base_value: + type: number + format: double + description: The base value. + new_value: + type: number + format: double + description: The new value. \ No newline at end of file diff --git a/tests/plugins/ml/ml/execute.yaml b/tests/plugins/ml/ml/execute.yaml new file mode 100644 index 000000000..88ae6002f --- /dev/null +++ b/tests/plugins/ml/ml/execute.yaml @@ -0,0 +1,67 @@ +$schema: ../../../../json_schemas/test_story.schema.yaml + +description: Test the execution of algorithms. +version: '>= 2.19' +prologues: + - path: /_cluster/settings + method: PUT + request: + payload: + persistent: + plugins.ml_commons.only_run_on_ml_node: false + - path: /{index} + method: PUT + request: + payload: + mappings: + properties: + timestamp: + type: date + attribute: + type: keyword + value: + type: float + parameters: + index: test-index +epilogues: + - path: /{index} + method: DELETE + status: [200, 404] + parameters: + index: test-index +chapters: + - synopsis: Execute local sample calculator algorithm. + path: /_plugins/_ml/_execute/{algorithm_name} + method: POST + parameters: + algorithm_name: local_sample_calculator + request: + payload: + operation: max + input_data: + - 1 + - 2 + - 3 + response: + status: 200 + - synopsis: Execute anomaly localization algorithm. + path: /_plugins/_ml/_execute/{algorithm_name} + method: POST + parameters: + algorithm_name: anomaly_localization + request: + payload: + index_name: test-index + attribute_field_names: + - attribute + aggregations: + - max: + max: + field: value + time_field_name: timestamp + start_time: 1620630000000 + end_time: 1620975600000 + min_time_interval: 86400000 + num_outputs: 10 + response: + status: 200 \ No newline at end of file