fix: address feedbacks

Author: xiaoyi-cheng

src/sagemaker/estimator.py

@@ -1378,6 +1378,7 @@ def deploy(
         model_data_download_timeout=None,
         container_startup_health_check_timeout=None,
         inference_recommendation_id=None,
+        explainer_config=None,
         **kwargs,
     ):
         """Deploy the trained model to an Amazon SageMaker endpoint.
@@ -1458,6 +1459,8 @@ def deploy(
             inference_recommendation_id (str): The recommendation id which specifies the
                 recommendation you picked from inference recommendation job results and
                 would like to deploy the model and endpoint with recommended parameters.
+            explainer_config (sagemaker.explainer.ExplainerConfig): Specifies online explainability
+                configuration for use with Amazon SageMaker Clarify. (default: None)
             **kwargs: Passed to invocation of ``create_model()``.
                 Implementations may customize ``create_model()`` to accept
                 ``**kwargs`` to customize model creation during deploy.
@@ -1516,6 +1519,7 @@ def deploy(
             data_capture_config=data_capture_config,
             serverless_inference_config=serverless_inference_config,
             async_inference_config=async_inference_config,
+            explainer_config=explainer_config,
             volume_size=volume_size,
             model_data_download_timeout=model_data_download_timeout,
             container_startup_health_check_timeout=container_startup_health_check_timeout,

src/sagemaker/explainer/clarify_explainer_config.py

@@ -10,27 +10,25 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
-"""A class for ExplainerConfig
-
-Use ExplainerConfig to activate explainers.
-"""
+"""A member of ``CreateEndpointConfig`` that enables explainers."""
 
 from __future__ import print_function, absolute_import
+from typing import Optional
 from sagemaker.explainer.clarify_explainer_config import ClarifyExplainerConfig
 
 
 class ExplainerConfig(object):
-    """Config object to activate explainers."""
+    """A parameter to activate explainers."""
 
     def __init__(
         self,
-        clarify_explainer_config: ClarifyExplainerConfig = None,
+        clarify_explainer_config: Optional[ClarifyExplainerConfig] = None,
     ):
         """Initializes a config object to activate explainer.
 
         Args:
             clarify_explainer_config (:class:`~sagemaker.explainer.explainer_config.ClarifyExplainerConfig`):
-                A config contains parameters for the SageMaker Clarify explainer. (Default: None)
+                Optional. A config contains parameters for the SageMaker Clarify explainer. (Default: None)
         """  # noqa E501  # pylint: disable=line-too-long
         self.clarify_explainer_config = clarify_explainer_config
 

src/sagemaker/explainer/explainer_config.py

@@ -210,6 +210,7 @@ def deploy(
         model_data_download_timeout=None,
         container_startup_health_check_timeout=None,
         inference_recommendation_id=None,
+        explainer_config=None,
         **kwargs,
     ):
         """Deploy this ``Model`` to an ``Endpoint`` and optionally return a ``Predictor``.
@@ -286,6 +287,8 @@ def deploy(
             inference_recommendation_id (str): The recommendation id which specifies the
                 recommendation you picked from inference recommendation job results and
                 would like to deploy the model and endpoint with recommended parameters.
+            explainer_config (sagemaker.explainer.ExplainerConfig): Specifies online explainability
+                configuration for use with Amazon SageMaker Clarify. (default: None)
         Raises:
              ValueError: If arguments combination check failed in these circumstances:
                 - If no role is specified or
@@ -322,6 +325,7 @@ def deploy(
             model_data_download_timeout=model_data_download_timeout,
             container_startup_health_check_timeout=container_startup_health_check_timeout,
             inference_recommendation_id=inference_recommendation_id,
+            explainer_config=explainer_config,
         )
 
     def register(

src/sagemaker/huggingface/model.py

@@ -215,6 +215,7 @@ def _update_params(
         accelerator_type = kwargs["accelerator_type"]
         async_inference_config = kwargs["async_inference_config"]
         serverless_inference_config = kwargs["serverless_inference_config"]
+        explainer_config = kwargs["explainer_config"]
         inference_recommendation_id = kwargs["inference_recommendation_id"]
         inference_recommender_job_results = kwargs["inference_recommender_job_results"]
         if inference_recommendation_id is not None:
@@ -225,6 +226,7 @@ def _update_params(
                 async_inference_config=async_inference_config,
                 serverless_inference_config=serverless_inference_config,
                 inference_recommendation_id=inference_recommendation_id,
+                explainer_config=explainer_config,
             )
         elif inference_recommender_job_results is not None:
             inference_recommendation = self._update_params_for_right_size(
@@ -233,6 +235,7 @@ def _update_params(
                 accelerator_type,
                 serverless_inference_config,
                 async_inference_config,
+                explainer_config,
             )
         return inference_recommendation or (instance_type, initial_instance_count)
 
@@ -243,6 +246,7 @@ def _update_params_for_right_size(
         accelerator_type=None,
         serverless_inference_config=None,
         async_inference_config=None,
+        explainer_config=None,
     ):
         """Validates that Inference Recommendation parameters can be used in `model.deploy()`
 
@@ -262,6 +266,8 @@ def _update_params_for_right_size(
                 whether serverless_inference_config has been passed into `model.deploy()`.
             async_inference_config (sagemaker.model_monitor.AsyncInferenceConfig):
                 whether async_inference_config has been passed into `model.deploy()`.
+            explainer_config (sagemaker.explainer.ExplainerConfig): whether explainer_config
+                has been passed into `model.deploy()`.
 
         Returns:
             (string, int) or None: Top instance_type and associated initial_instance_count
@@ -285,6 +291,11 @@ def _update_params_for_right_size(
                 "serverless_inference_config is specified. Overriding right_size() recommendations."
             )
             return None
+        if explainer_config:
+            LOGGER.warning(
+                "explainer_config is specified. Overriding right_size() recommendations."
+            )
+            return None
 
         instance_type = self.inference_recommendations[0]["EndpointConfiguration"]["InstanceType"]
         initial_instance_count = self.inference_recommendations[0]["EndpointConfiguration"][
@@ -300,6 +311,7 @@ def _update_params_for_recommendation_id(
         async_inference_config,
         serverless_inference_config,
         inference_recommendation_id,
+        explainer_config,
     ):
         """Update parameters with inference recommendation results.
 
@@ -332,6 +344,8 @@ def _update_params_for_recommendation_id(
                 the recommendation you picked from inference recommendation job
                 results and would like to deploy the model and endpoint with
                 recommended parameters.
+            explainer_config (sagemaker.explainer.ExplainerConfig): Specifies online explainability
+                configuration for use with Amazon SageMaker Clarify. Default: None.
         Raises:
             ValueError: If arguments combination check failed in these circumstances:
                 - If only one of instance type or instance count specified or
@@ -367,6 +381,8 @@ def _update_params_for_recommendation_id(
             raise ValueError(
                 "serverless_inference_config is not compatible with inference_recommendation_id."
             )
+        if explainer_config is not None:
+            raise ValueError("explainer_config is not compatible with inference_recommendation_id.")
 
         # Validate recommendation id
         if not re.match(r"[a-zA-Z0-9](-*[a-zA-Z0-9]){0,63}\/\w{8}$", inference_recommendation_id):

src/sagemaker/inference_recommender/inference_recommender_mixin.py

@@ -1077,11 +1077,11 @@ def deploy(
         data_capture_config=None,
         async_inference_config=None,
         serverless_inference_config=None,
-        explainer_config=None,
         volume_size=None,
         model_data_download_timeout=None,
         container_startup_health_check_timeout=None,
         inference_recommendation_id=None,
+        explainer_config=None,
         **kwargs,
     ):
         """Deploy this ``Model`` to an ``Endpoint`` and optionally return a ``Predictor``.
@@ -1147,8 +1147,6 @@ def deploy(
                 empty object passed through, will use pre-defined values in
                 ``ServerlessInferenceConfig`` class to deploy serverless endpoint. Deploy an
                 instance based endpoint if it's None. (default: None)
-            explainer_config (sagemaker.explainer.ExplainerConfig): Specifies online explainability
-                configuration for use with Amazon SageMaker Clarify. Default: None.
             volume_size (int): The size, in GB, of the ML storage volume attached to individual
                 inference instance associated with the production variant. Currenly only Amazon EBS
                 gp2 storage volumes are supported.
@@ -1162,6 +1160,8 @@ def deploy(
             inference_recommendation_id (str): The recommendation id which specifies the
                 recommendation you picked from inference recommendation job results and
                 would like to deploy the model and endpoint with recommended parameters.
+            explainer_config (sagemaker.explainer.ExplainerConfig): Specifies online explainability
+                configuration for use with Amazon SageMaker Clarify. Default: None.
         Raises:
              ValueError: If arguments combination check failed in these circumstances:
                 - If no role is specified or

src/sagemaker/model.py

@@ -127,7 +127,6 @@ def predict(
         target_model=None,
         target_variant=None,
         inference_id=None,
-        enable_explanations=None,
     ):
         """Return the inference from the specified endpoint.
 
@@ -148,8 +147,6 @@ def predict(
                 model you want to host and the resources you want to deploy for hosting it.
             inference_id (str): If you provide a value, it is added to the captured data
                 when you enable data capture on the endpoint (Default: None).
-            enable_explanations (str): An optional JMESPath expression used to override the
-                EnableExplanations parameter of the ClarifyExplainerConfig. (Default: None).
 
         Returns:
             object: Inference for the given input. If a deserializer was specified when creating
@@ -159,7 +156,7 @@ def predict(
         """
 
         request_args = self._create_request_args(
-            data, initial_args, target_model, target_variant, inference_id, enable_explanations
+            data, initial_args, target_model, target_variant, inference_id
         )
         response = self.sagemaker_session.sagemaker_runtime_client.invoke_endpoint(**request_args)
         return self._handle_response(response)
@@ -177,7 +174,6 @@ def _create_request_args(
         target_model=None,
         target_variant=None,
         inference_id=None,
-        enable_explanations=None,
     ):
         """Placeholder docstring"""
         args = dict(initial_args) if initial_args else {}
@@ -200,9 +196,6 @@ def _create_request_args(
         if inference_id:
             args["InferenceId"] = inference_id
 
-        if enable_explanations:
-            args["EnableExplanations"] = enable_explanations
-
         data = self.serializer.serialize(data)
 
         args["Body"] = data

src/sagemaker/predictor.py

@@ -3660,10 +3660,10 @@ def create_endpoint_config(
         tags=None,
         kms_key=None,
         data_capture_config_dict=None,
-        explainer_config_dict=None,
         volume_size=None,
         model_data_download_timeout=None,
         container_startup_health_check_timeout=None,
+        explainer_config_dict=None,
     ):
         """Create an Amazon SageMaker endpoint configuration.
 
@@ -3687,8 +3687,6 @@ def create_endpoint_config(
                 attached to the instance hosting the endpoint.
             data_capture_config_dict (dict): Specifies configuration related to Endpoint data
                 capture for use with Amazon SageMaker Model Monitoring. Default: None.
-            explainer_config_dict (dict): Specifies configuration to enable explainers.
-                Default: None.
             volume_size (int): The size, in GB, of the ML storage volume attached to individual
                 inference instance associated with the production variant. Currenly only Amazon EBS
                 gp2 storage volumes are supported.
@@ -3699,6 +3697,8 @@ def create_endpoint_config(
                 inference container to pass health check by SageMaker Hosting. For more information
                 about health check see:
                 https://docs.aws.amazon.com/sagemaker/latest/dg/your-algorithms-inference-code.html#your-algorithms-inference-algo-ping-requests
+            explainer_config_dict (dict): Specifies configuration to enable explainers.
+                Default: None.
 
         Example:
             >>> tags = [{'Key': 'tagname', 'Value': 'tagvalue'}]
@@ -3767,8 +3767,8 @@ def create_endpoint_config_from_existing(
         new_tags=None,
         new_kms_key=None,
         new_data_capture_config_dict=None,
-        new_explainer_config_dict=None,
         new_production_variants=None,
+        new_explainer_config_dict=None,
     ):
         """Create an Amazon SageMaker endpoint configuration from an existing one.
 
@@ -3793,12 +3793,12 @@ def create_endpoint_config_from_existing(
                 capture for use with Amazon SageMaker Model Monitoring (default: None).
                 If not specified, the data capture configuration of the existing
                 endpoint configuration is used.
-            new_explainer_config_dict (dict): Specifies configuration to enable explainers.
-                (default: None). If not specified, the explainer configuration of the existing
-                endpoint configuration is used.
             new_production_variants (list[dict]): The configuration for which model(s) to host and
                 the resources to deploy for hosting the model(s). If not specified,
                 the ``ProductionVariants`` of the existing endpoint configuration is used.
+            new_explainer_config_dict (dict): Specifies configuration to enable explainers.
+                (default: None). If not specified, the explainer configuration of the existing
+                endpoint configuration is used.
 
         Returns:
             str: Name of the endpoint point configuration created.
@@ -4407,7 +4407,7 @@ def endpoint_from_production_variants(
             async_inference_config_dict (dict) : specifies configuration related to async endpoint.
                 Use this configuration when trying to create async endpoint and make async inference
                 (default: None)
-            explainer_config_dict (dict) : specifies configuration related to explainer.
+            explainer_config_dict (dict) : Specifies configuration related to explainer.
                 Use this configuration when trying to use online explainability.
                 (default: None)
         Returns:

src/sagemaker/session.py

@@ -324,6 +324,7 @@ def deploy(
         model_data_download_timeout=None,
         container_startup_health_check_timeout=None,
         inference_recommendation_id=None,
+        explainer_config=None,
     ):
         """Deploy a Tensorflow ``Model`` to a SageMaker ``Endpoint``."""
 
@@ -349,6 +350,7 @@ def deploy(
             container_startup_health_check_timeout=container_startup_health_check_timeout,
             update_endpoint=update_endpoint,
             inference_recommendation_id=inference_recommendation_id,
+            explainer_config=explainer_config,
         )
 
     def _eia_supported(self):

src/sagemaker/tensorflow/model.py

@@ -42,7 +42,9 @@
 
 CLARIFY_SHAP_BASELINE_CONFIG = ClarifyShapBaselineConfig(shap_baseline=SHAP_BASELINE)
 CLARIFY_SHAP_CONFIG = ClarifyShapConfig(shap_baseline_config=CLARIFY_SHAP_BASELINE_CONFIG)
-CLARIFY_EXPLAINER_CONFIG = ClarifyExplainerConfig(shap_config=CLARIFY_SHAP_CONFIG)
+CLARIFY_EXPLAINER_CONFIG = ClarifyExplainerConfig(
+    shap_config=CLARIFY_SHAP_CONFIG, enable_explanations="`true`"
+)
 EXPLAINER_CONFIG = ExplainerConfig(clarify_explainer_config=CLARIFY_EXPLAINER_CONFIG)
 
 
@@ -107,3 +109,23 @@ def test_invoke_explainer_enabled_endpoint(sagemaker_session, endpoint_name):
         assert response_body_json.get("predictions")
     finally:
         response_body_stream.close()
+
+
+def test_invoke_endpoint_with_on_demand_explanations(sagemaker_session, endpoint_name):
+    response = sagemaker_session.sagemaker_runtime_client.invoke_endpoint(
+        EndpointName=endpoint_name,
+        EnableExplanations="`false`",
+        Body=TEST_CSV_DATA,
+        ContentType="text/csv",
+        Accept="text/csv",
+    )
+    assert response
+    response_body_stream = response["Body"]
+    try:
+        response_body_json = json.load(codecs.getreader("utf-8")(response_body_stream))
+        assert response_body_json
+        # no records are explained when EnableExplanations="`false`"
+        assert response_body_json.get("explanations") == {}
+        assert response_body_json.get("predictions")
+    finally:
+        response_body_stream.close()

tests/integ/test_explainer.py

@@ -10,6 +10,7 @@
 )
 from sagemaker.async_inference import AsyncInferenceConfig
 from sagemaker.serverless import ServerlessInferenceConfig
+from sagemaker.explainer import ExplainerConfig
 
 import pytest
 
@@ -667,5 +668,34 @@ def test_deploy_right_size_async_override(sagemaker_session, default_right_sized
     )
 
 
+@patch("sagemaker.utils.name_from_base", MagicMock(return_value=MODEL_NAME))
+def test_deploy_right_size_explainer_config_override(sagemaker_session, default_right_sized_model):
+    default_right_sized_model.name = MODEL_NAME
+    mock_clarify_explainer_config = MagicMock()
+    mock_clarify_explainer_config_dict = {
+        "EnableExplanations": "`false`",
+    }
+    mock_clarify_explainer_config._to_request_dict.return_value = mock_clarify_explainer_config_dict
+    explainer_config = ExplainerConfig(clarify_explainer_config=mock_clarify_explainer_config)
+    explainer_config_dict = {"ClarifyExplainerConfig": mock_clarify_explainer_config_dict}
+
+    default_right_sized_model.deploy(
+        instance_type="ml.c5.2xlarge",
+        initial_instance_count=1,
+        explainer_config=explainer_config,
+    )
+
+    sagemaker_session.endpoint_from_production_variants.assert_called_with(
+        name=MODEL_NAME,
+        production_variants=[ANY],
+        tags=None,
+        kms_key=None,
+        wait=True,
+        data_capture_config_dict=None,
+        async_inference_config_dict=None,
+        explainer_config_dict=explainer_config_dict,
+    )
+
+
 # TODO -> cover inference_recommendation_id cases
 # ...