|
| 1 | +# Copyright 2017 Amazon.com, Inc. or its affiliates. All Rights Reserved. |
| 2 | +# |
| 3 | +# Licensed under the Apache License, Version 2.0 (the "License"). You |
| 4 | +# may not use this file except in compliance with the License. A copy of |
| 5 | +# the License is located at |
| 6 | +# |
| 7 | +# http://aws.amazon.com/apache2.0/ |
| 8 | +# |
| 9 | +# or in the "license" file accompanying this file. This file is |
| 10 | +# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF |
| 11 | +# ANY KIND, either express or implied. See the License for the specific |
| 12 | +# language governing permissions and limitations under the License. |
| 13 | +from sagemaker.amazon.amazon_estimator import AmazonAlgorithmEstimatorBase, registry |
| 14 | +from sagemaker.amazon.common import numpy_to_record_serializer, record_deserializer |
| 15 | +from sagemaker.amazon.hyperparameter import Hyperparameter as hp # noqa |
| 16 | +from sagemaker.amazon.validation import gt |
| 17 | +from sagemaker.predictor import RealTimePredictor |
| 18 | +from sagemaker.model import Model |
| 19 | +from sagemaker.session import Session |
| 20 | + |
| 21 | + |
| 22 | +class LDA(AmazonAlgorithmEstimatorBase): |
| 23 | + |
| 24 | + repo_name = 'lda' |
| 25 | + repo_version = 1 |
| 26 | + |
| 27 | + num_topics = hp('num_topics', gt(0), 'An integer greater than zero', int) |
| 28 | + alpha0 = hp('alpha0', gt(0), 'A positive float', float) |
| 29 | + max_restarts = hp('max_restarts', gt(0), 'An integer greater than zero', int) |
| 30 | + max_iterations = hp('max_iterations', gt(0), 'An integer greater than zero', int) |
| 31 | + tol = hp('tol', gt(0), 'A positive float', float) |
| 32 | + |
| 33 | + def __init__(self, role, train_instance_type, num_topics, |
| 34 | + alpha0=None, max_restarts=None, max_iterations=None, tol=None, **kwargs): |
| 35 | + """Latent Dirichlet Allocation (LDA) is :class:`Estimator` used for unsupervised learning. |
| 36 | +
|
| 37 | + Amazon SageMaker Latent Dirichlet Allocation is an unsupervised learning algorithm that attempts to describe |
| 38 | + a set of observations as a mixture of distinct categories. LDA is most commonly used to discover |
| 39 | + a user-specified number of topics shared by documents within a text corpus. |
| 40 | + Here each observation is a document, the features are the presence (or occurrence count) of each word, and |
| 41 | + the categories are the topics. |
| 42 | +
|
| 43 | + This Estimator may be fit via calls to |
| 44 | + :meth:`~sagemaker.amazon.amazon_estimator.AmazonAlgorithmEstimatorBase.fit`. It requires Amazon |
| 45 | + :class:`~sagemaker.amazon.record_pb2.Record` protobuf serialized data to be stored in S3. |
| 46 | + There is an utility :meth:`~sagemaker.amazon.amazon_estimator.AmazonAlgorithmEstimatorBase.record_set` that |
| 47 | + can be used to upload data to S3 and creates :class:`~sagemaker.amazon.amazon_estimator.RecordSet` to be passed |
| 48 | + to the `fit` call. |
| 49 | +
|
| 50 | + To learn more about the Amazon protobuf Record class and how to prepare bulk data in this format, please |
| 51 | + consult AWS technical documentation: https://docs.aws.amazon.com/sagemaker/latest/dg/cdf-training.html |
| 52 | +
|
| 53 | + After this Estimator is fit, model data is stored in S3. The model may be deployed to an Amazon SageMaker |
| 54 | + Endpoint by invoking :meth:`~sagemaker.amazon.estimator.EstimatorBase.deploy`. As well as deploying an Endpoint, |
| 55 | + deploy returns a :class:`~sagemaker.amazon.lda.LDAPredictor` object that can be used |
| 56 | + for inference calls using the trained model hosted in the SageMaker Endpoint. |
| 57 | +
|
| 58 | + LDA Estimators can be configured by setting hyperparameters. The available hyperparameters for |
| 59 | + LDA are documented below. |
| 60 | +
|
| 61 | + For further information on the AWS LDA algorithm, |
| 62 | + please consult AWS technical documentation: https://docs.aws.amazon.com/sagemaker/latest/dg/lda.html |
| 63 | +
|
| 64 | + Args: |
| 65 | + role (str): An AWS IAM role (either name or full ARN). The Amazon SageMaker training jobs and |
| 66 | + APIs that create Amazon SageMaker endpoints use this role to access |
| 67 | + training data and model artifacts. After the endpoint is created, |
| 68 | + the inference code might use the IAM role, if accessing AWS resource. |
| 69 | + train_instance_type (str): Type of EC2 instance to use for training, for example, 'ml.c4.xlarge'. |
| 70 | + num_topics (int): The number of topics for LDA to find within the data. |
| 71 | + alpha0 (float): Optional. Initial guess for the concentration parameter |
| 72 | + max_restarts (int): Optional. The number of restarts to perform during the Alternating Least Squares (ALS) |
| 73 | + spectral decomposition phase of the algorithm. |
| 74 | + max_iterations (int): Optional. The maximum number of iterations to perform during the |
| 75 | + ALS phase of the algorithm. |
| 76 | + tol (float): Optional. Target error tolerance for the ALS phase of the algorithm. |
| 77 | + **kwargs: base class keyword argument values. |
| 78 | + """ |
| 79 | + |
| 80 | + # this algorithm only supports single instance training |
| 81 | + super(LDA, self).__init__(role, 1, train_instance_type, **kwargs) |
| 82 | + self.num_topics = num_topics |
| 83 | + self.alpha0 = alpha0 |
| 84 | + self.max_restarts = max_restarts |
| 85 | + self.max_iterations = max_iterations |
| 86 | + self.tol = tol |
| 87 | + |
| 88 | + def create_model(self): |
| 89 | + """Return a :class:`~sagemaker.amazon.LDAModel` referencing the latest |
| 90 | + s3 model data produced by this Estimator.""" |
| 91 | + |
| 92 | + return LDAModel(self.model_data, self.role, sagemaker_session=self.sagemaker_session) |
| 93 | + |
| 94 | + def fit(self, records, mini_batch_size, **kwargs): |
| 95 | + # mini_batch_size is required, prevent explicit calls with None |
| 96 | + if mini_batch_size is None: |
| 97 | + raise ValueError("mini_batch_size must be set") |
| 98 | + super(LDA, self).fit(records, mini_batch_size, **kwargs) |
| 99 | + |
| 100 | + |
| 101 | +class LDAPredictor(RealTimePredictor): |
| 102 | + """Transforms input vectors to lower-dimesional representations. |
| 103 | +
|
| 104 | + The implementation of :meth:`~sagemaker.predictor.RealTimePredictor.predict` in this |
| 105 | + `RealTimePredictor` requires a numpy ``ndarray`` as input. The array should contain the |
| 106 | + same number of columns as the feature-dimension of the data used to fit the model this |
| 107 | + Predictor performs inference on. |
| 108 | +
|
| 109 | + :meth:`predict()` returns a list of :class:`~sagemaker.amazon.record_pb2.Record` objects, one |
| 110 | + for each row in the input ``ndarray``. The lower dimension vector result is stored in the ``projection`` |
| 111 | + key of the ``Record.label`` field.""" |
| 112 | + |
| 113 | + def __init__(self, endpoint, sagemaker_session=None): |
| 114 | + super(LDAPredictor, self).__init__(endpoint, sagemaker_session, serializer=numpy_to_record_serializer(), |
| 115 | + deserializer=record_deserializer()) |
| 116 | + |
| 117 | + |
| 118 | +class LDAModel(Model): |
| 119 | + """Reference LDA s3 model data. Calling :meth:`~sagemaker.model.Model.deploy` creates an Endpoint and return |
| 120 | + a Predictor that transforms vectors to a lower-dimensional representation.""" |
| 121 | + |
| 122 | + def __init__(self, model_data, role, sagemaker_session=None): |
| 123 | + sagemaker_session = sagemaker_session or Session() |
| 124 | + repo = '{}:{}'.format(LDA.repo_name, LDA.repo_version) |
| 125 | + image = '{}/{}'.format(registry(sagemaker_session.boto_session.region_name, LDA.repo_name), repo) |
| 126 | + super(LDAModel, self).__init__(model_data, image, role, predictor_cls=LDAPredictor, |
| 127 | + sagemaker_session=sagemaker_session) |
0 commit comments