From 118c3daa3e117e8ad27e89d42ef7e65f252bfc4c Mon Sep 17 00:00:00 2001 From: Sicheng Song Date: Wed, 24 Jul 2024 21:56:31 +0000 Subject: [PATCH 1/9] Add predefined model interface doc Signed-off-by: Sicheng Song --- .../api/model-apis/register-model.md | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index ec830a7821..c6171f57fd 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -367,6 +367,20 @@ Field | Data type | Description The input and output fields will be evaluated against the separately provided JSON schema. You do not necessarily need to provide both input and output fields simultaneously. +Specifically, for users' convenience, we have provided a set of predefined model interface that can be generated automatically during model registration, if the user choose to follow the [connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). +The predefined model interface is generated based on the connector blueprint and the model's metadata, so user needs to follow the blueprint to create the connector strictly in order to avoid exceptions. +The list of connector blueprints we currently support predefined model interface are: + +- [amazon comprehend connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_comprehend_connector_blueprint.md) +- [amazon textract connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_textract_connector_blueprint.md) (Please note that predefined model interface is only available for the `DetectDocumentText` API, `DetectEnities` API is not supported currently) +- [bedrock connector ai21labs jurassic blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_ai21labs_jurassic_blueprint.md) +- [bedrock connector anthropic claude3 blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_anthropic_claude3_blueprint.md) +- [bedrock connector anthropic claude blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_anthropic_claude_blueprint.md) +- [bedrock connector cohere.embed-english-v3 blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_cohere_cohere.embed-english-v3_blueprint.md) +- [bedrock connector cohere.embed-multilingual-v3 blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_cohere_cohere.embed-multilingual-v3_blueprint.md) +- [bedrock connector titan embedding blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_titan_embedding_blueprint.md) +- [bedrock connector titan multimodal embedding blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_titan_multimodal_embedding_blueprint.md) + To learn more about the JSON schema syntax, see [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/). #### Example request: Externally hosted model with an interface From 4369ee1cad57dc5acbf434ede1aed1bfcac74a71 Mon Sep 17 00:00:00 2001 From: Sicheng Song Date: Fri, 26 Jul 2024 21:56:03 -0700 Subject: [PATCH 2/9] Update _ml-commons-plugin/api/model-apis/register-model.md Co-authored-by: Nathan Bower Signed-off-by: Sicheng Song --- _ml-commons-plugin/api/model-apis/register-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index c6171f57fd..e9a3dd8a11 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -372,7 +372,7 @@ The predefined model interface is generated based on the connector blueprint and The list of connector blueprints we currently support predefined model interface are: - [amazon comprehend connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_comprehend_connector_blueprint.md) -- [amazon textract connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_textract_connector_blueprint.md) (Please note that predefined model interface is only available for the `DetectDocumentText` API, `DetectEnities` API is not supported currently) +- [Amazon Textract connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_textract_connector_blueprint.md) (Note that a predefined model interface is only available for the `DetectDocumentText` API; the `DetectEnities` API is not currently supported). - [bedrock connector ai21labs jurassic blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_ai21labs_jurassic_blueprint.md) - [bedrock connector anthropic claude3 blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_anthropic_claude3_blueprint.md) - [bedrock connector anthropic claude blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_anthropic_claude_blueprint.md) From 70e3c6db42d484e6df82633ea2a3f65f8b9471b9 Mon Sep 17 00:00:00 2001 From: Sicheng Song Date: Fri, 26 Jul 2024 21:56:11 -0700 Subject: [PATCH 3/9] Update _ml-commons-plugin/api/model-apis/register-model.md Co-authored-by: Nathan Bower Signed-off-by: Sicheng Song --- _ml-commons-plugin/api/model-apis/register-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index e9a3dd8a11..adeb677bc6 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -371,7 +371,7 @@ Specifically, for users' convenience, we have provided a set of predefined model The predefined model interface is generated based on the connector blueprint and the model's metadata, so user needs to follow the blueprint to create the connector strictly in order to avoid exceptions. The list of connector blueprints we currently support predefined model interface are: -- [amazon comprehend connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_comprehend_connector_blueprint.md) +- [Amazon Comprehend connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_comprehend_connector_blueprint.md) - [Amazon Textract connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_textract_connector_blueprint.md) (Note that a predefined model interface is only available for the `DetectDocumentText` API; the `DetectEnities` API is not currently supported). - [bedrock connector ai21labs jurassic blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_ai21labs_jurassic_blueprint.md) - [bedrock connector anthropic claude3 blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_anthropic_claude3_blueprint.md) From 682d1a0add4c72cdbab118171ea0b305ee47bb7d Mon Sep 17 00:00:00 2001 From: Sicheng Song Date: Fri, 26 Jul 2024 21:56:19 -0700 Subject: [PATCH 4/9] Update _ml-commons-plugin/api/model-apis/register-model.md Co-authored-by: Nathan Bower Signed-off-by: Sicheng Song --- _ml-commons-plugin/api/model-apis/register-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index adeb677bc6..316c228226 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -369,7 +369,7 @@ The input and output fields will be evaluated against the separately provided JS Specifically, for users' convenience, we have provided a set of predefined model interface that can be generated automatically during model registration, if the user choose to follow the [connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). The predefined model interface is generated based on the connector blueprint and the model's metadata, so user needs to follow the blueprint to create the connector strictly in order to avoid exceptions. -The list of connector blueprints we currently support predefined model interface are: +The following are the currently supported connector blueprints for creating predefined model interfaces: - [Amazon Comprehend connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_comprehend_connector_blueprint.md) - [Amazon Textract connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_textract_connector_blueprint.md) (Note that a predefined model interface is only available for the `DetectDocumentText` API; the `DetectEnities` API is not currently supported). From 8cc08991660c03c3e46388a852313a5feea7578c Mon Sep 17 00:00:00 2001 From: Sicheng Song Date: Fri, 26 Jul 2024 21:56:24 -0700 Subject: [PATCH 5/9] Update _ml-commons-plugin/api/model-apis/register-model.md Co-authored-by: Nathan Bower Signed-off-by: Sicheng Song --- _ml-commons-plugin/api/model-apis/register-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index 316c228226..64b6952bee 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -367,7 +367,7 @@ Field | Data type | Description The input and output fields will be evaluated against the separately provided JSON schema. You do not necessarily need to provide both input and output fields simultaneously. -Specifically, for users' convenience, we have provided a set of predefined model interface that can be generated automatically during model registration, if the user choose to follow the [connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). +Specifically, for users' convenience, we have provided a set of predefined model interfaces that can be generated automatically during model registration if the user chooses to follow the [connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). The predefined model interface is generated based on the connector blueprint and the model's metadata, so user needs to follow the blueprint to create the connector strictly in order to avoid exceptions. The following are the currently supported connector blueprints for creating predefined model interfaces: From 9692f3f8eb9bd677202e76992d4e3c4b04cead57 Mon Sep 17 00:00:00 2001 From: Sicheng Song Date: Fri, 26 Jul 2024 21:56:30 -0700 Subject: [PATCH 6/9] Update _ml-commons-plugin/api/model-apis/register-model.md Co-authored-by: Nathan Bower Signed-off-by: Sicheng Song --- _ml-commons-plugin/api/model-apis/register-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index 64b6952bee..acd7a8c241 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -368,7 +368,7 @@ Field | Data type | Description The input and output fields will be evaluated against the separately provided JSON schema. You do not necessarily need to provide both input and output fields simultaneously. Specifically, for users' convenience, we have provided a set of predefined model interfaces that can be generated automatically during model registration if the user chooses to follow the [connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). -The predefined model interface is generated based on the connector blueprint and the model's metadata, so user needs to follow the blueprint to create the connector strictly in order to avoid exceptions. +The predefined model interface is generated based on the connector blueprint and the model's metadata, so the user must strictly follow the blueprint when creating the connector in order to avoid exceptions. The following are the currently supported connector blueprints for creating predefined model interfaces: - [Amazon Comprehend connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_comprehend_connector_blueprint.md) From 8c01340f81dfad8b6df767b6ee6780449c09bd0d Mon Sep 17 00:00:00 2001 From: Sicheng Song Date: Sat, 27 Jul 2024 05:41:32 +0000 Subject: [PATCH 7/9] Address comments Signed-off-by: Sicheng Song --- _ml-commons-plugin/api/model-apis/register-model.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index acd7a8c241..c1cb9cfe06 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -367,8 +367,8 @@ Field | Data type | Description The input and output fields will be evaluated against the separately provided JSON schema. You do not necessarily need to provide both input and output fields simultaneously. -Specifically, for users' convenience, we have provided a set of predefined model interfaces that can be generated automatically during model registration if the user chooses to follow the [connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). -The predefined model interface is generated based on the connector blueprint and the model's metadata, so the user must strictly follow the blueprint when creating the connector in order to avoid exceptions. +Specifically, for your convenience, we have provided a set of predefined model interfaces that can be generated automatically during model registration if you choose to follow the [connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). +The predefined model interface is generated based on the connector blueprint and the model's metadata, so you must strictly follow the blueprint when creating the connector in order to avoid exceptions. The following are the currently supported connector blueprints for creating predefined model interfaces: - [Amazon Comprehend connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_comprehend_connector_blueprint.md) From 33f16e951012d4ff8c354a32b8c7c0d95bb1df6a Mon Sep 17 00:00:00 2001 From: Fanit Kolchina Date: Tue, 30 Jul 2024 10:25:55 -0400 Subject: [PATCH 8/9] Doc review Signed-off-by: Fanit Kolchina --- .../Vocab/OpenSearch/Products/accept.txt | 1 + .../api/model-apis/register-model.md | 33 ++++++++++--------- 2 files changed, 19 insertions(+), 15 deletions(-) diff --git a/.github/vale/styles/Vocab/OpenSearch/Products/accept.txt b/.github/vale/styles/Vocab/OpenSearch/Products/accept.txt index 9be8da79a9..4ea310a086 100644 --- a/.github/vale/styles/Vocab/OpenSearch/Products/accept.txt +++ b/.github/vale/styles/Vocab/OpenSearch/Products/accept.txt @@ -86,6 +86,7 @@ RPM Package Manager Ruby Simple Schema for Observability Tableau +Textract TorchScript Tribuo VisBuilder diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index c1cb9cfe06..62287e16df 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -357,7 +357,8 @@ OpenSearch responds with the `task_id`, task `status`, and `model_id`: ### The `interface` parameter -The model interface provides a highly flexible way to add arbitrary metadata annotations to all local deep learning models and remote models in a JSON schema syntax. This annotation initiates a validation check on the input and output fields of the model during the model's invocation. The validation check ensures that the input and output fields are in the correct format both before and after the model performs a prediction. +The model interface provides a highly flexible way to add arbitrary metadata annotations to all local deep learning models and externally hosted models in a JSON schema syntax. This annotation initiates a validation check on the input and output fields of the model during the model's invocation. The validation check ensures that the input and output fields are in the correct format both before and after the model performs inference. + To register a model with a model interface, provide the `interface` parameter, which supports the following fields. Field | Data type | Description @@ -365,23 +366,25 @@ Field | Data type | Description `input`| Object | The JSON schema for the model input. | `output`| Object | The JSON schema for the model output. | -The input and output fields will be evaluated against the separately provided JSON schema. You do not necessarily need to provide both input and output fields simultaneously. +The input and output fields are evaluated against the provided JSON schema. You do not need to provide both input and output fields simultaneously. + +#### Connector model interfaces + +To simplify your workflow, you can register an externally hosted model using a connector in one of the [connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/) formats. If you do so, a predefined model interface for this connector is generated automatically during model registration. The predefined model interface is generated based on the connector blueprint and the model's metadata, so you must strictly follow the blueprint when creating the connector in order to avoid errors. -Specifically, for your convenience, we have provided a set of predefined model interfaces that can be generated automatically during model registration if you choose to follow the [connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). -The predefined model interface is generated based on the connector blueprint and the model's metadata, so you must strictly follow the blueprint when creating the connector in order to avoid exceptions. -The following are the currently supported connector blueprints for creating predefined model interfaces: +The following connector blueprints currently support creating predefined model interfaces: -- [Amazon Comprehend connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_comprehend_connector_blueprint.md) -- [Amazon Textract connector blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/amazon_textract_connector_blueprint.md) (Note that a predefined model interface is only available for the `DetectDocumentText` API; the `DetectEnities` API is not currently supported). -- [bedrock connector ai21labs jurassic blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_ai21labs_jurassic_blueprint.md) -- [bedrock connector anthropic claude3 blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_anthropic_claude3_blueprint.md) -- [bedrock connector anthropic claude blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_anthropic_claude_blueprint.md) -- [bedrock connector cohere.embed-english-v3 blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_cohere_cohere.embed-english-v3_blueprint.md) -- [bedrock connector cohere.embed-multilingual-v3 blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_cohere_cohere.embed-multilingual-v3_blueprint.md) -- [bedrock connector titan embedding blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_titan_embedding_blueprint.md) -- [bedrock connector titan multimodal embedding blueprint]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/bedrock_connector_titan_multimodal_embedding_blueprint.md) +- [Amazon Comprehend](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/amazon_comprehend_connector_blueprint.md) +- [Amazon Textract](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/amazon_textract_connector_blueprint.md) (Note that a predefined model interface is only available for the `DetectDocumentText` API; the `DetectEnities` API is not currently supported). +- [Amazon Bedrock AI21 Labs Jurassic](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/bedrock_connector_ai21labs_jurassic_blueprint.md) +- [Amazon Bedrock Anthropic Claude 3](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/bedrock_connector_anthropic_claude3_blueprint.md) +- [Amazon Bedrock Anthropic Claude](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/bedrock_connector_anthropic_claude_blueprint.md) +- [Amazon Bedrock Cohere Embed English v3](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/bedrock_connector_cohere_cohere.embed-english-v3_blueprint.md) +- [Amazon Bedrock Cohere Embed Multilingual v3](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/bedrock_connector_cohere_cohere.embed-multilingual-v3_blueprint.md) +- [Amazon Bedrock Titan Text Embeddings](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/bedrock_connector_titan_embedding_blueprint.md) +- [Amazon Bedrock Titan Multimodal Embeddings](https://github.com/opensearch-project/ml-commons/blob/2.x/docs/remote_inference_blueprints/bedrock_connector_titan_multimodal_embedding_blueprint.md) -To learn more about the JSON schema syntax, see [Understanding JSON Schema](https://json-schema.org/understanding-json-schema/). +To learn more about connector blueprints, see [Connector blueprints]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/blueprints/). #### Example request: Externally hosted model with an interface From 4c3366d838c2337df2a35db3d36260d5b65371b6 Mon Sep 17 00:00:00 2001 From: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> Date: Tue, 30 Jul 2024 10:42:16 -0400 Subject: [PATCH 9/9] Apply suggestions from code review Co-authored-by: Nathan Bower Signed-off-by: kolchfa-aws <105444904+kolchfa-aws@users.noreply.github.com> --- _ml-commons-plugin/api/model-apis/register-model.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md index 62287e16df..2a0e9706e9 100644 --- a/_ml-commons-plugin/api/model-apis/register-model.md +++ b/_ml-commons-plugin/api/model-apis/register-model.md @@ -366,7 +366,7 @@ Field | Data type | Description `input`| Object | The JSON schema for the model input. | `output`| Object | The JSON schema for the model output. | -The input and output fields are evaluated against the provided JSON schema. You do not need to provide both input and output fields simultaneously. +The input and output fields are evaluated against the provided JSON schema. You do not need to provide both fields simultaneously. #### Connector model interfaces