Add guardrails for remote model (#6750)

* guardrails for remote model Signed-off-by: Jing Zhang <[email protected]> * Doc review Signed-off-by: Fanit Kolchina <[email protected]> * Add guardrails dedicated page Signed-off-by: Fanit Kolchina <[email protected]> * Reword and reformat Signed-off-by: Fanit Kolchina <[email protected]> * Add prerequisites Signed-off-by: Fanit Kolchina <[email protected]> * Change example Signed-off-by: Fanit Kolchina <[email protected]> * Add a link to query string query Signed-off-by: Fanit Kolchina <[email protected]> * Add regex and responses Signed-off-by: Fanit Kolchina <[email protected]> * Add a sentence about regex Signed-off-by: Fanit Kolchina <[email protected]> * Apply suggestions from code review Co-authored-by: Nathan Bower <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> * Apply suggestions from code review Signed-off-by: kolchfa-aws <[email protected]> * Add type to guardrails Signed-off-by: Fanit Kolchina <[email protected]> --------- Signed-off-by: Jing Zhang <[email protected]> Signed-off-by: Fanit Kolchina <[email protected]> Signed-off-by: kolchfa-aws <[email protected]> Co-authored-by: Fanit Kolchina <[email protected]> Co-authored-by: kolchfa-aws <[email protected]> Co-authored-by: Nathan Bower <[email protected]>
opensearch-project · Mar 28, 2024 · 26c53ab · 26c53ab
1 parent 4c507b5
commit 26c53ab
Show file tree

Hide file tree

Showing 4 changed files with 398 additions and 3 deletions.
diff --git a/_ml-commons-plugin/api/model-apis/register-model.md b/_ml-commons-plugin/api/model-apis/register-model.md
@@ -183,8 +183,9 @@ Field | Data type | Required/Optional | Description
 `description` | String | Optional| The model description. |
 `model_group_id` | String | Optional | The model group ID of the model group to register this model to. 
 `is_enabled`| Boolean | Specifies whether the model is enabled. Disabling the model makes it unavailable for Predict API requests, regardless of the model's deployment status. Default is `true`.
+`guardrails`| Object | Optional | The guardrails for the model input. For more information, see [Guardrails](#the-guardrails-parameter).|
 
-#### Example request: Remote model with a standalone connector
+#### Example request: Externally hosted with a standalone connector
 
 ```json
 POST /_plugins/_ml/models/_register
@@ -198,7 +199,7 @@ POST /_plugins/_ml/models/_register
 ```
 {% include copy-curl.html %}
 
-#### Example request: Remote model with a connector specified as part of the model
+#### Example request: Externally hosted with a connector specified as part of the model
 
 ```json
 POST /_plugins/_ml/models/_register
@@ -248,6 +249,70 @@ OpenSearch responds with the `task_id` and task `status`.
 }
 ```
 
+### The `guardrails` parameter
+
+Guardrails are safety measures for large language models (LLMs). They provide a set of rules and boundaries that control how an LLM behaves and what kind of output it generates. 
+
+To register an externally hosted model with guardrails, provide the `guardrails` parameter, which supports the following fields. All fields are optional.
+
+Field | Data type | Description
+:---  | :--- | :---
+`type` | String | The guardrail type. Currently, only `local_regex` is supported.
+`input_guardrail`| Object |  The guardrail for the model input. |
+`output_guardrail`| Object |  The guardrail for the model output. |
+`stop_words`| Object | The list of indexes containing stopwords used for the model input/output validation. If the model prompt/response contains a stopword contained in any of the indexes, the predict request on this model is rejected. |
+`index_name`| Object | The name of the index storing the stopwords. |
+`source_fields`| Object | The name of the field storing the stopwords. |
+`regex`| Object |  A regular expression used for input/output validation. If the model prompt/response matches the regular expression, the predict request on this model is rejected. |
+
+#### Example request: Externally hosted model with guardrails
+
+```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",
+  "guardrails": {
+    "type": "local_regex",
+    "input_guardrail": {
+      "stop_words": [
+        {
+          "index_name": "stop_words_input",
+          "source_fields": ["title"]
+        }
+      ],
+      "regex": ["regex1", "regex2"]
+    },
+    "output_guardrail": {
+      "stop_words": [
+        {
+          "index_name": "stop_words_output",
+          "source_fields": ["title"]
+        }
+      ],
+      "regex": ["regex1", "regex2"]
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
+For a complete example, see [Guardrails]({{site.url}}{{site.baseurl}}/ml-commons-plugin/remote-models/guardrails/).
+
+#### 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:

diff --git a/_ml-commons-plugin/api/model-apis/update-model.md b/_ml-commons-plugin/api/model-apis/update-model.md
@@ -36,6 +36,7 @@ Field | Data type |  Description
 `rate_limiter` | Object | Limits the number of times any user can call the Predict API on the model. For more information, see [Rate limiting inference calls]({{site.url}}{{site.baseurl}}/ml-commons-plugin/integrating-ml-models/#rate-limiting-inference-calls).
 `rate_limiter.limit` | Integer | The maximum number of times any user can call the Predict API on the model per `unit` of time. By default, there is no limit on the number of Predict API calls. Once you set a limit, you cannot reset it to no limit. As an alternative, you can specify a high limit value and a small time unit, for example, 1 request per nanosecond.
 `rate_limiter.unit` | String | The unit of time for the rate limiter. Valid values are `DAYS`, `HOURS`, `MICROSECONDS`, `MILLISECONDS`, `MINUTES`, `NANOSECONDS`, and `SECONDS`.
+`guardrails`| Object | The guardrails for the model.
 
 #### Example request: Disabling a model
 
@@ -62,6 +63,35 @@ PUT /_plugins/_ml/models/T_S-cY0BKCJ3ot9qr0aP
 ```
 {% include copy-curl.html %}
 
+#### Example request: Updating the guardrails
+
+```json
+PUT /_plugins/_ml/models/MzcIJX8BA7mbufL6DOwl
+{
+  "guardrails": {
+    "input_guardrail": {
+      "stop_words": [
+        {
+          "index_name": "updated_stop_words_input",
+          "source_fields": ["updated_title"]
+        }
+      ],
+      "regex": ["updated_regex1", "updated_regex2"]
+    },
+    "output_guardrail": {
+      "stop_words": [
+        {
+          "index_name": "updated_stop_words_output",
+          "source_fields": ["updated_title"]
+        }
+      ],
+      "regex": ["updated_regex1", "updated_regex2"]
+    }
+  }
+}
+```
+{% include copy-curl.html %}
+
 #### Example response
 
 ```json
@@ -78,4 +108,5 @@ PUT /_plugins/_ml/models/T_S-cY0BKCJ3ot9qr0aP
   "_seq_no": 48,
   "_primary_term": 4
 }
-```
+```
+