本文為英文版的機器翻譯版本，如內容有任何歧義或不一致之處，概以英文版為準。

使用 ModelBuilder 在 Amazon SageMaker AI 建立模型

準備在 SageMaker AI 端點上部署的模型需要多個步驟，包括選擇模型映像、設定端點組態、編碼序列化和還原序列化函式以在伺服器和用戶端之間傳輸資料、識別模型相依性，以及將它們上傳到 Amazon S3。ModelBuilder 可以降低初始設定和部署的複雜性，協助您在單一步驟中建立可部署模型。

ModelBuilder 會為您執行以下任務：

使用 ModelBuilder 建置模型

ModelBuilder 是一種 Python 類別，採用 XGBoost 或 PyTorch 等架構模型或使用者指定的推論規格，並將其轉換為可部署模型。ModelBuilder 提供建置函式，可產生用於部署的成品。產生的模型成品專屬於模型伺服器，您也可以將其指定為其中一個輸入。如需 ModelBuilder 類別的詳細資訊，請參閱 ModelBuilder。

下圖說明使用 ModelBuilder 時的整體模型建立工作流程。ModelBuilder 接受模型或推論規格以及您的結構描述，以建立可在部署前於本機測試的可部署模型。

ModelBuilder 可以處理您想要套用的任何自訂項目。不過，若要部署架構模型，模型建置器至少需要模型、範例輸入和輸出，以及角色。下列程式碼範例會使用架構模型呼叫 ModelBuilder，並使用最小引數呼叫 SchemaBuilder 執行個體 (以推論用於序列化和還原序列化端點輸入和輸出的對應函式)。未指定容器，也不會傳遞封裝相依性 - 當您建置模型時，SageMaker AI 會自動推論這些資源。

from sagemaker.serve.builder.model_builder import ModelBuilder
from sagemaker.serve.builder.schema_builder import SchemaBuilder

model_builder = ModelBuilder(
    model=model,
    schema_builder=SchemaBuilder(input, output),
    role_arn="execution-role",
)

下列程式碼範例會使用推論規格 (作為 InferenceSpec 執行個體) 和額外的自訂功能調用 ModelBuilder，而非使用模型。在此情況下，對模型建置器的呼叫包含儲存模型成品的路徑，並開啟所有可用相依性的自動擷取。如需進一步了解 InferenceSpec，請參閱 自訂模型載入和請求處理。

model_builder = ModelBuilder(
    mode=Mode.LOCAL_CONTAINER,
    model_path=model-artifact-directory,
    inference_spec=your-inference-spec,
    schema_builder=SchemaBuilder(input, output),
    role_arn=execution-role,
    dependencies={"auto": True}
)

定義序列化和還原序列化方法

調用 SageMaker AI 端點時，資料會透過具不同 MIME 類型的 HTTP 承載傳送。例如，傳送至端點以進行推論的映像需要在用戶端轉換為位元組，並透過 HTTP 承載傳送至端點。當端點收到承載時，它需要將位元組字串還原序列化回模型預期的資料類型 (也稱為伺服器端還原序列化)。模型完成預測後，也需要將結果序列化為可透過 HTTP 承載傳回給使用者或用戶端的位元組。一旦用戶端收到回應位元組資料，則需要執行用戶端還原序列化，將位元組資料轉換回預期的資料格式，例如 JSON。至少需要為以下任務轉換資料：

下圖顯示調用端點時發生的序列化和還原序列化程序。

當您將範例輸入和輸出提供給 SchemaBuilder 時，結構描述建置器會產生對應的封送函式，以序列化和還原序列化輸入和輸出。您可以使用 CustomPayloadTranslator 進一步自訂序列化函式。但是在多數情況下，如下簡單的序列化程式會運作：

input = "How is the demo going?"
output = "Comment la démo va-t-elle?"
schema = SchemaBuilder(input, output)

如需進一步了解 SchemaBuilder，請參閱 SchemaBuilder。

下列程式碼片段範例是您想在用戶端和伺服器端自訂序列化和還原序列化函式的情況。您可以使用 CustomPayloadTranslator 定義自己的請求和回應轉譯器，並將這些轉譯器傳遞給 SchemaBuilder。

透過以轉譯器包含輸入和輸出，模型建置器可以擷取模型預期的資料格式。例如，假設範例輸入是原始映像，您的自訂轉譯器會裁切映像，並將裁切映像以張量形式傳送至伺服器。ModelBuilder 需要原始輸入和任何自訂預處理或後處理程式碼，才能衍生方法，在用戶端和伺服器端轉換資料。

from sagemaker.serve import CustomPayloadTranslator

# request translator
class MyRequestTranslator(CustomPayloadTranslator):
    # This function converts the payload to bytes - happens on client side
    def serialize_payload_to_bytes(self, payload: object) -> bytes:
        # converts the input payload to bytes
        ... ...
        return  //return object as bytes

    # This function converts the bytes to payload - happens on server side
    def deserialize_payload_from_stream(self, stream) -> object:
        # convert bytes to in-memory object
        ... ...
        return //return in-memory object

# response translator
class MyResponseTranslator(CustomPayloadTranslator):
    # This function converts the payload to bytes - happens on server side
    def serialize_payload_to_bytes(self, payload: object) -> bytes:
        # converts the response payload to bytes
        ... ...
        return //return object as bytes

    # This function converts the bytes to payload - happens on client side
    def deserialize_payload_from_stream(self, stream) -> object:
        # convert bytes to in-memory object
        ... ...
        return //return in-memory object

建立 SchemaBuilder 物件時，您會一併傳遞範例輸入和輸出與先前定義的自訂轉譯器，如下範例所示：

my_schema = SchemaBuilder(
    sample_input=image,
    sample_output=output,
    input_translator=MyRequestTranslator(),
    output_translator=MyResponseTranslator()
)

然後，請將範例輸入和輸出以及先前定義的自訂轉譯器傳遞至 SchemaBuilder 物件。

my_schema = SchemaBuilder(
    sample_input=image,
    sample_output=output,
    input_translator=MyRequestTranslator(),
    output_translator=MyResponseTranslator()
)

下列章節詳細說明如何使用 ModelBuilder 建置模型，並使用其支援類別來自訂使用案例的體驗。

自訂模型載入和請求處理

透過 InferenceSpec 提供您的自有推論程式碼，即可提供額外的自訂層。您可以透過 InferenceSpec 自訂模型的載入方式，以及模型處理傳入推論請求的方式，同時略過其預設載入和推論處理機制。使用非標準模型或自訂推論管道時，這種彈性方式格外有用。您可以自訂 invoke 方法，以控制模型如何預處理和後處理傳入的請求。invoke 方法會確保模型正確處理推論請求。下列範例使用 InferenceSpec 來產生具 HuggingFace 管道的模型。如需進一步了解 InferenceSpec，請參閱 InferenceSpec。

from sagemaker.serve.spec.inference_spec import InferenceSpec
from transformers import pipeline

class MyInferenceSpec(InferenceSpec):
    def load(self, model_dir: str):
        return pipeline("translation_en_to_fr", model="t5-small")

    def invoke(self, input, model):
        return model(input)

inf_spec = MyInferenceSpec()

model_builder = ModelBuilder(
    inference_spec=your-inference-spec,
    schema_builder=SchemaBuilder(X_test, y_pred)
)

下列範例說明先前範例的自訂變化。模型是以具相依性的推論規格定義。在此情況下，推論規格中的程式碼取決於 lang-segment 套件。dependencies 的引數包含使用 Git 指示建置器安裝 lang-segment 的陳述式。由於模型建置器是由使用者指示來自訂安裝相依性，因此 auto 關鍵是 False，以關閉相依性自動擷取。

model_builder = ModelBuilder(
    mode=Mode.LOCAL_CONTAINER,
    model_path=model-artifact-directory,
    inference_spec=your-inference-spec,
    schema_builder=SchemaBuilder(input, output),
    role_arn=execution-role,
    dependencies={"auto": False, "custom": ["-e git+https://github.com/luca-medeiros/lang-segment-anything.git#egg=lang-sam"],}
)

建置您的模型和部署

呼叫 build 函式來建立可部署模型。此步驟會在您的工作目錄中使用必要程式碼來建立推論程式碼 (作為 inference.py)，以建立結構描述、執行輸入和輸出的序列化和還原序列化，以及執行其他使用者指定的自訂邏輯。

作為完整性檢查，SageMaker AI 會封裝並挑選部署所需的檔案，作為 ModelBuilder 建置函式的一部分。在此過程中，SageMaker AI 也會為 pickle 檔案建立 HMAC 簽署，並在 deploy (或 create) 期間將 CreateModel API 中的私密金鑰新增為環境變數。端點啟動會使用環境變數來驗證 pickle 檔案的完整性。

# Build the model according to the model server specification and save it as files in the working directory
model = model_builder.build()

使用模型的現有 deploy 方法部署模型。在此步驟中，SageMaker AI 會設定端點，在模型開始對傳入請求進行預測時託管模型。雖然 ModelBuilder 會推論部署模型所需的端點資源，但您可以使用自有參數值覆寫這些預估值。下列範例指示 SageMaker AI 在單一 ml.c6i.xlarge 執行個體上部署模型。由 ModelBuilder 建構的模型會在部署期間啟用即時記錄，以作為新增功能。

predictor = model.deploy(
    initial_instance_count=1,
    instance_type="ml.c6i.xlarge"
)

如果您要更詳盡地控制指派給模型的端點資源，您可以使用 ResourceRequirements 物件。您可以使用 ResourceRequirements 物件，請求要部署模型的 CPU、加速器和複本數量下限。您也可以請求記憶體下上限 (以 MB 為單位)。若要使用此功能，您需要將端點類型指定為 EndpointType.INFERENCE_COMPONENT_BASED。下列範例會請求四個加速器，記憶體大小下限為 1024 MB，以及要部署至端點類型 EndpointType.INFERENCE_COMPONENT_BASED 的模型複本。

resource_requirements = ResourceRequirements(
    requests={
        "num_accelerators": 4,
        "memory": 1024,
        "copies": 1,
    },
    limits={},
)
predictor = model.deploy(
    mode=Mode.SAGEMAKER_ENDPOINT,
    endpoint_type=EndpointType.INFERENCE_COMPONENT_BASED,
    resources=resource_requirements,
    role="role"
)

使用自有容器 (BYOC)

如果您要使用自有容器 (從 SageMaker AI 容器擴充)，您也可以指定映像 URI，如下範例所示。您也需要識別與 ModelBuilder 映像對應的模型伺服器，以產生特定於模型伺服器的成品。

model_builder = ModelBuilder(
    model=model,
    model_server=ModelServer.TORCHSERVE,
    schema_builder=SchemaBuilder(X_test, y_pred),
    image_uri="123123123123.dkr.ecr.ap-southeast-2.amazonaws.com/byoc-image:xgb-1.7-1")
)

在本機模式中使用 ModelBuilder

您可以使用 mode 引數，在本機測試和部署之間切換到端點，以在本機部署模型。您需要將模型成品儲存在工作目錄中，如下程式碼片段所示：

model = XGBClassifier()
model.fit(X_train, y_train)
model.save_model(model_dir + "/my_model.xgb")

傳遞模型物件、SchemaBuilder 執行個體，並將模式設為 Mode.LOCAL_CONTAINER。當您呼叫 build 函式時，ModelBuilder 會自動識別支援的架構容器，並掃描相依性。下列範例示範在本機模式中使用 XGBoost 模型建立模型。

model_builder_local = ModelBuilder(
    model=model,
    schema_builder=SchemaBuilder(X_test, y_pred),
    role_arn=execution-role,
    mode=Mode.LOCAL_CONTAINER
)
xgb_local_builder = model_builder_local.build()

呼叫 deploy 函式以在本機進行部署，如下程式碼片段所示。如果您為執行個體類型或數量指定了參數，則會忽略這些引數。

predictor_local = xgb_local_builder.deploy()

故障診斷本機模式

根據個別本機設定不同，您可能難以在環境中順暢執行 ModelBuilder。請參閱下列清單，了解您可能遇到的問題以及解決方式。

ModelBuilder 範例

如需更多使用 ModelBuilder 來建置模型的範例，請參閱 ModelBuilder 範例筆記本。