class bentoml.service.BentoService(artifacts=None, env=None)

BentoService packs a list of artifacts and exposes service APIs for BentoAPIServer and BentoCLI to execute. By subclassing BentoService, users can customize the artifacts and environments required for a ML service.

>>>  from bentoml import BentoService, env, api, artifacts, ver
>>>  from bentoml.handlers import DataframeHandler
>>>  @ver(major=1, minor=4)
>>>  @artifacts([PickleArtifact('clf')])
>>>  @env(conda_dependencies: [ 'scikit-learn' ])
>>>  class MyMLService(BentoService):
>>>     @api(DataframeHandler)
>>>     def predict(self, df):
>>>         return self.artifacts.clf.predict(df)
>>>  bento_service = MyMLService.pack(clf=my_trained_clf_object)
>>>, './export')
classmethod name()

return bento service name


return bento service version str


Return a list of user defined API functions

Returns:List of user defined API functions
Return type:list(BentoServiceAPI)
class bentoml.service.BentoServiceAPI(service, name, doc, handler, func)

BentoServiceAPI defines abstraction for an API call that can be executed with BentoAPIServer and BentoCLI

  • service (BentoService) – ref to service containing this API
  • name (str) – API name, by default this is the python function name
  • handler (bentoml.handlers.BentoHandler) – A BentoHandler class that transforms HTTP Request and/or CLI options into expected format for the API func
  • func (function) – API func contains the actual API callback, this is typically the ‘predict’ method on a model


bentoml.api(handler_cls, *args, **kwargs)

Decorator for adding api to a BentoService

  • handler_cls (bentoml.handlers.BentoHandler) – The handler class for the API function.
  • api_name (str, optional) – API name to replace function name
  • api_doc (str, optional) – Docstring for API function
  • **kwargs – Additional keyword arguments for handler class. Please reference to what arguments are available for the particular handler

ValueError – API name must contains only letters

>>> from bentoml import BentoService, api
>>> from bentoml.handlers import JsonHandler, DataframeHandler
>>> class FraudDetectionAndIdentityService(BentoService):
>>>     @api(JsonHandler)
>>>     def fraud_detect(self, parsed_json):
>>>         # do something
>>>     @api(DataframeHandler, input_json_orient='records')
>>>     def identity(self, df):
>>>         # do something



Define environment spec for BentoService

  • setup_sh (str) – User defined shell script to run before running BentoService. It could be local file path or the shell script content.
  • requirements_text (str) – User defined requirement text to install before running BentoService.
  • pip_dependencies (str or list(str)) – User defined python modules to install.
  • conda_channels (list(str)) – User defined conda channels
  • conda_dependencies (list(str)) – Defined dependencies to be installed with conda environment.
  • conda_pip_dependencies (list(str)) – Additional pip modules to be install with conda



Define artifact spec for BentoService

  • artifact_specs (list(bentoml.artifact.ArtifactSpec)) – A list of desired artifacts for initializing this BentoService
  • initializing this BentoService being decorated (for) –


bentoml.ver(major, minor)

Decorator for specifying the version of a custom BentoService.

  • major (int) – Major version number for Bento Service
  • minor (int) – Minor version number for Bento Service

BentoML uses semantic versioning for BentoService distribution:

  • MAJOR is incremented when you make breaking API changes
  • MINOR is incremented when you add new functionality without breaking the existing API or functionality
  • PATCH is incremented when you make backwards-compatible bug fixes

‘Patch’ is provided(or auto generated) when calling BentoService#save, while ‘Major’ and ‘Minor’ can be defined with @ver’ decorator

>>>  @ver(major=1, minor=4)
>>>  @artifacts([PickleArtifact('model')])
>>>  class MyMLService(BentoService):
>>>     pass
>>>  svc = MyMLService.pack(model="my ML model object")
>>>'/path_to_archive', version="2019-08.iteration20")
>>>  # The final produced BentoArchive version will be "1.4.2019-08.iteration20"

save, dst, version=None)

Save given BentoService along with all its artifacts, source code and dependencies to target path

  • bento_service (bentoml.service.BentoService) – a Bento Service instance
  • dst (str) – Destination of where the bento service will be saved. It could be a local file path or a s3 path
  • version (str, optional) – version text to use for saved archive

The complete path of saved Bento service.

Return type:




Load bento service from local file path or s3 path

Parameters:archive_path (str) – The path that contains archived bento service. It could be local file path or aws s3 path
Returns:The loaded bento service.
Return type:bentoml.service.BentoService



BentoML configuration parser

:param default_config string - serve as default value when conf key not presented in
environment var or user local config file