Skip to content

doc: Add xgboost doc on bring your own model #1727

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 12 commits into from
Jul 29, 2020
51 changes: 50 additions & 1 deletion doc/frameworks/xgboost/using_xgboost.rst
Original file line number Diff line number Diff line change
Expand Up @@ -390,6 +390,56 @@ The function should return a byte array of data serialized to ``content_type``.
The default implementation expects ``prediction`` to be a NumPy array and can serialize the result to JSON, CSV, or NPY.
It accepts response content types of "application/json", "text/csv", and "application/x-npy".

Bring Your Own Model
--------------------

You can deploy an XGBoost model that you trained outside of SageMaker by using the Amazon SageMaker XGBoost container.
Typically, you save an XGBoost model by pickling the ``Booster`` object or calling ``booster.save_model``.
The XGBoost `built-in algorithm mode <https://docs.aws.amazon.com/sagemaker/latest/dg/xgboost.html#xgboost-modes>`_
supports both a pickled ``Booster`` object and a model produced by ``booster.save_model``.
You can also deploy an XGBoost model by using XGBoost as a framework.
By using XGBoost as a framework, you have more flexibility.
To deploy an XGBoost model by using XGBoost as a framework, you need to:

- Write an inference script.
- Create the XGBoostModel object.

Write an Inference Script
^^^^^^^^^^^^^^^^^^^^^^^^^

You must create an inference script that implements (at least) the ``model_fn`` function that calls the loaded model to get a prediction.

Optionally, you can also implement ``input_fn`` and ``output_fn`` to process input and output,
and ``predict_fn`` to customize how the model server gets predictions from the loaded model.
For information about how to write an inference script, see `SageMaker XGBoost Model Server <#sagemaker-xgboost-model-server>`_.
Pass the filename of the inference script as the ``entry_point`` parameter when you create the `XGBoostModel` object.

Create an XGBoostModel Object
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

To create a model object, call the ``sagemaker.xgboost.model.XGBoostModel`` constructor,
and then call its ``deploy()`` method to deploy your model for inference.

.. code:: python

xgboost_model = XGBoostModel(
model_data="s3://my-bucket/my-path/model.tar.gz",
role="my-role",
entry_point="inference.py",
framework_version="1.0-1"
)

predictor = xgboost_model.deploy(
instance_type='ml.c4.xlarge',
initial_instance_count=1
)

# If payload is a string in LIBSVM format, we need to change serializer.
predictor.serializer = str
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what is str supposed to be here?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We've been using serializer = str in our XGBoost notebook examples because the most natural format for XGBoost is libsvm and there is no default libsvm serializer. My understanding is predictor expects a byte sequence like a numpy array by default, so I've been using serializer = str when I have a payload in libsvm string format. Is there a better way (other than writing a custom serializer)?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah, gotcha. no, the only other way would be to write a custom serializer.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The predictor is an XGBoost model - couldn't we override the default serializer to str for it?

Copy link
Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes, we could override it here: https://github.com/aws/sagemaker-python-sdk/blob/master/src/sagemaker/xgboost/model.py#L45. But I guess the question is if it's going to break any customers who were assuming a different default.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

if it makes sense to change it, you can make another PR against the "zwei" branch - that's where our v2 work is happening right now

Copy link
Author

@edwardjkim edwardjkim Jul 29, 2020

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool, thanks for the pointer! And also for reminding me that our team needs to revisit the xgboost and sklearn estimator before v2 for issues like this.

predictor.predict("<label> <index1>:<value1> <index2>:<value2>")

To get predictions from your deployed model, you can call the ``predict()`` method.

Host Multiple Models with Multi-Model Endpoints
-----------------------------------------------

Expand All @@ -401,7 +451,6 @@ in the AWS documentation.
For a sample notebook that uses Amazon SageMaker to deploy multiple XGBoost models to an endpoint, see the
`Multi-Model Endpoint XGBoost Sample Notebook <https://github.com/awslabs/amazon-sagemaker-examples/blob/master/advanced_functionality/multi_model_xgboost_home_value/xgboost_multi_model_endpoint_home_value.ipynb>`_.


*************************
SageMaker XGBoost Classes
*************************
Expand Down