Example: Integrate an Amazon SageMaker model（示例：集成 Amazon SageMaker 模型）

The below documentation provides an example configuration and model adapter for a custom connection to a model hosted in Amazon SageMaker. Review the benefits of external model integration to make sure this is the right fit for your use case.

For a step-by-step guide, refer to the documentation on how to create a model adapter and how to create a connection to an externally hosted model.

Example Amazon SageMaker tabular model adapter

First, publish and tag a model adapter using the model adapter library in the Code Repositories application. The below model adapter configures a connection to a model hosted in Amazon SageMaker using the AWS SDK for Python (Boto3) ↗ and framework. The below code was tested with versions Python 3.8.17, boto3 1.28.1 and pandas 1.5.3.

Note that this model adapter makes the following assumptions:

• This model adapter assumes that data being provided to this model is tabular.
• This model adapter will serialize the input data to JSON and send this data to the hosted Amazon SageMaker model.
• This model adapter assumes that the response is deserializable from JSON to a pandas dataframe
• This model adapter takes four inputs to construct a Boto3 client.
• region_name - Provided as connection configuration
• endpoint_name - Provided as connection configuration
• access_key_id - Provided as credentials
• secret_access_key - Provided as credentials

import palantir_models as pm
import models_api.models_api_executable as executable_api

import boto3
import json
import pandas as pd
import logging
from typing import Optional
from botocore.exceptions import ClientError

logger = logging.getLogger(__name__)


class SageMakerTabularAdapter(pm.ExternalModelAdapter):
    """
    :display-name: SageMaker Tabular Model Adapter
    :description: Default model adapter for SageMaker models that expect tabular input and output tabular data.
    """

    def __init__(self, region_name, endpoint_name, access_key_id, secret_access_key):
        self.endpoint_name = endpoint_name
        self.runtime = boto3.client(
            'runtime.sagemaker',
            aws_access_key_id=access_key_id,
            aws_secret_access_key=secret_access_key,
            region_name=region_name
        )

    @classmethod
    def init_external(cls, external_context) -> "pm.ExternalModelAdapter":
        region_name = external_context.connection_config["region_name"]
        endpoint_name = external_context.connection_config["endpoint_name"]
        access_key_id = external_context.resolved_credentials["access_key_id"]
        secret_access_key = external_context.resolved_credentials["secret_access_key"]
        return cls(
            region_name,
            endpoint_name,
            access_key_id,
            secret_access_key
        )

    @classmethod
    def api(cls):
        inputs = {"df_in": pm.Pandas()}
        outputs = {"df_out": pm.Pandas()}
        return inputs, outputs

    def predict(self, df_in):
        payload = {
            "instances": df_in.apply(lambda row: {"features": row.tolist()}, axis=1).tolist()
        }
        try:
            response = self.runtime.invoke_endpoint(
                EndpointName=self.endpoint_name,
                ContentType="application/json",
                Body=json.dumps(payload)
            )
        except ClientError as error:
            logger.error("SageMaker inference call failed. This can indicate an error with this Model's egress "
                         "policy. Double check your configured egress policy and ensure the remote endpoint is still "
                         "available.")
            raise error
        try:
            # Output from model is assumed to be json serializable
            # if result is too large for executor this deserialization may cause an OOM
            result = json.loads(response['Body'].read().decode())
        except ValueError as error:
            logger.error("This SageMakerTabularAdapter expects results to be json serializable.")
            raise error
        return pd.json_normalize(result)

Amazon SageMaker tabular model configuration

Next, configure an externally hosted model to use this model adapter and provide the required configuration and credentials as expected by the model adapter. In this example, the model is assumed to be hosted in us-east-1, but this is configurable.

Note that the URL is not required by the above SageMakerTabularAdapter and so is left blank; however, the configuration and credentials maps are completed using the same keys as defined in the Model Adapter.

Select an egress policy

The below uses an egress policy that has been configured for runtime.sagemaker.us-east-1.amazonaws.com (Port 443).

Configure model adapter

Choose the published model adapter in the Connect an externally hosted model dialog.

Configure connection configuration

Define connection configurations as required by the example Amazon SageMaker tabular model adapter.

This adapter requires connection configuration of:

• region_name - The AWS region name where the model is hosted.
• endpoint_name - The unique identifier for the externally hosted model.

Configure credential configuration

Define credential configurations as required by the example Amazon SageMaker tabular model adapter.

This adapter requires credential configuration of:

• access_key_id - This is the unique identifier for the user whose credentials will call the SageMaker model.
• secret_access_key - This is the secret key for the user whose credentials will call the SageMaker model.

Amazon SageMaker tabular model usage

Now that the Amazon SageMaker model has been configured, this model can be hosted in a live deployment or Python transform.

The below image shows an example query made to the Amazon SageMaker model in a live deployment.

---

中文翻译

示例：集成 Amazon SageMaker 模型

以下文档提供了自定义连接到 Amazon SageMaker 中托管模型的示例配置和模型适配器（model adapter）。请查阅外部模型集成的好处，以确保这适合您的使用场景。

有关分步指南，请参阅如何创建模型适配器和如何创建外部托管模型的连接的文档。

示例 Amazon SageMaker 表格模型适配器

首先，使用代码仓库（Code Repositories）应用程序中的模型适配器库（model adapter library）发布并标记一个模型适配器。下面的模型适配器使用 AWS SDK for Python (Boto3) ↗ 和框架配置了与 Amazon SageMaker 中托管模型的连接。以下代码已在 Python 3.8.17、boto3 1.28.1 和 pandas 1.5.3 版本上测试通过。

请注意，此模型适配器做了以下假设：

• 此模型适配器假设提供给该模型的数据是表格形式（tabular）的。
• 此模型适配器会将输入数据序列化为 JSON，并将此数据发送到托管的 Amazon SageMaker 模型。
• 此模型适配器假设响应可以从 JSON 反序列化为 pandas 数据框（dataframe）。
• 此模型适配器需要四个输入来构建 Boto3 客户端。
• region_name - 作为连接配置（connection configuration）提供
• endpoint_name - 作为连接配置（connection configuration）提供
• access_key_id - 作为凭据（credentials）提供
• secret_access_key - 作为凭据（credentials）提供

import palantir_models as pm
import models_api.models_api_executable as executable_api

import boto3
import json
import pandas as pd
import logging
from typing import Optional
from botocore.exceptions import ClientError

logger = logging.getLogger(__name__)


class SageMakerTabularAdapter(pm.ExternalModelAdapter):
    """
    :display-name: SageMaker Tabular Model Adapter
    :description: Default model adapter for SageMaker models that expect tabular input and output tabular data.
    """

    def __init__(self, region_name, endpoint_name, access_key_id, secret_access_key):
        self.endpoint_name = endpoint_name
        self.runtime = boto3.client(
            'runtime.sagemaker',
            aws_access_key_id=access_key_id,
            aws_secret_access_key=secret_access_key,
            region_name=region_name
        )

    @classmethod
    def init_external(cls, external_context) -> "pm.ExternalModelAdapter":
        region_name = external_context.connection_config["region_name"]
        endpoint_name = external_context.connection_config["endpoint_name"]
        access_key_id = external_context.resolved_credentials["access_key_id"]
        secret_access_key = external_context.resolved_credentials["secret_access_key"]
        return cls(
            region_name,
            endpoint_name,
            access_key_id,
            secret_access_key
        )

    @classmethod
    def api(cls):
        inputs = {"df_in": pm.Pandas()}
        outputs = {"df_out": pm.Pandas()}
        return inputs, outputs

    def predict(self, df_in):
        payload = {
            "instances": df_in.apply(lambda row: {"features": row.tolist()}, axis=1).tolist()
        }
        try:
            response = self.runtime.invoke_endpoint(
                EndpointName=self.endpoint_name,
                ContentType="application/json",
                Body=json.dumps(payload)
            )
        except ClientError as error:
            logger.error("SageMaker inference call failed. This can indicate an error with this Model's egress "
                         "policy. Double check your configured egress policy and ensure the remote endpoint is still "
                         "available.")
            raise error
        try:
            # Output from model is assumed to be json serializable
            # if result is too large for executor this deserialization may cause an OOM
            result = json.loads(response['Body'].read().decode())
        except ValueError as error:
            logger.error("This SageMakerTabularAdapter expects results to be json serializable.")
            raise error
        return pd.json_normalize(result)

Amazon SageMaker 表格模型配置

接下来，配置一个外部托管模型以使用此模型适配器，并提供模型适配器所需的配置和凭据。在此示例中，假设模型托管在 us-east-1 区域，但这是可配置的。

请注意，上述 SageMakerTabularAdapter 不需要 URL，因此留空；但是，配置和凭据映射使用模型适配器中定义的相同键来完成。

选择出站策略（egress policy）

以下使用了已为 runtime.sagemaker.us-east-1.amazonaws.com（端口 443）配置的出站策略。

配置模型适配器

在连接外部托管模型对话框中选择已发布的模型适配器。

配置连接配置

根据示例 Amazon SageMaker 表格模型适配器的要求定义连接配置。

此适配器需要以下连接配置：

• region_name - 托管模型的 AWS 区域名称。
• endpoint_name - 外部托管模型的唯一标识符。

配置凭据配置

根据示例 Amazon SageMaker 表格模型适配器的要求定义凭据配置。

此适配器需要以下凭据配置：

• access_key_id - 将使用其凭据调用 SageMaker 模型的用户的唯一标识符。
• secret_access_key - 将使用其凭据调用 SageMaker 模型的用户的密钥。

Amazon SageMaker 表格模型使用

现在 Amazon SageMaker 模型已配置完成，该模型可以托管在实时部署（live deployment）或 Python 转换（Python transform）中。

下图显示了在实时部署中对 Amazon SageMaker 模型执行的示例查询。