mosec

Model Serving made Efficient in the Cloud.

Mosec is a high-performance and flexible model serving framework for building ML model-enabled backend and microservices. It bridges the gap between any machine learning models you just trained and the efficient online service API.

• Highly performant: web layer and task coordination built with Rust 🦀, which offers blazing speed in addition to efficient CPU utilization powered by async I/O
• Ease of use: user interface purely in Python 🐍, by which users can serve their models in an ML framework-agnostic manner using the same code as they do for offline testing
• Dynamic batching: aggregate requests from different users for batched inference and distribute results back
• Pipelined stages: spawn multiple processes for pipelined stages to handle CPU/GPU/IO mixed workloads
• Cloud friendly: designed to run in the cloud, with the model warmup, graceful shutdown, and Prometheus monitoring metrics, easily managed by Kubernetes or any container orchestration systems
• Do one thing well: focus on the online serving part, users can pay attention to the model optimization and business logic

Mosec requires Python 3.7 or above. Install the latest PyPI package for Linux or macOS with:

pip install -U mosec
# or install with conda
conda install conda-forge::mosec
# or install with pixi
pixi add mosec

To build from the source code, install Rust and run the following command:

make package

You will get a mosec wheel file in the dist folder.

We demonstrate how Mosec can help you easily host a pre-trained stable diffusion model as a service. You need to install diffusers and transformers as prerequisites:

pip install --upgrade diffusers[torch] transformers

from io import BytesIO

import torch  # type: ignore
from diffusers import StableDiffusionPipeline  # type: ignore

from mosec import Server, Worker, get_logger
from mosec.mixin import MsgpackMixin

logger = get_logger()

class StableDiffusion(MsgpackMixin, Worker):
    def __init__(self):
        self.pipe = StableDiffusionPipeline.from_pretrained(
            "sd-legacy/stable-diffusion-v1-5", torch_dtype=torch.float16
        )
        self.pipe.enable_model_cpu_offload()
        self.example = ["useless example prompt"] * 4  # warmup (batch_size=4)

    def forward(self, data: list[str]) -> list[memoryview]:
        logger.debug("generate images for %s", data)
        res = self.pipe(data)
        logger.debug("NSFW: %s", res[1])
        images = []
        for img in res[0]:
            dummy_file = BytesIO()
            img.save(dummy_file, format="JPEG")
            images.append(dummy_file.getbuffer())
        return images

if __name__ == "__main__":
    server = Server()
    # 1) `num` specifies the number of processes that will be spawned to run in parallel.
    # 2) By configuring the `max_batch_size` with the value > 1, the input data in your
    # `forward` function will be a list (batch); otherwise, it's a single item.
    server.append_worker(StableDiffusion, num=1, max_batch_size=4, max_wait_time=10)
    server.run()

python examples/stable_diffusion/server.py --help

python examples/stable_diffusion/server.py --log-level debug --timeout 30000

python examples/stable_diffusion/client.py --prompt "a cute cat playing with a red ball" --output cat.jpg --port 8000

curl http://127.0.0.1:8000/metrics

More ready-to-use examples can be found in the Example section. It includes:

• Pipeline: a simple echo demo even without any ML model.
• Request validation: validate the request with type annotation and generate OpenAPI documentation.
• Multiple route: serve multiple models in one service
• Embedding service: OpenAI compatible embedding service
• Reranking service: rerank a list of passages based on a query
• Shared memory IPC: inter-process communication with shared memory.
• Customized GPU allocation: deploy multiple replicas, each using different GPUs.
• Customized metrics: record your own metrics for monitoring.
• Jax jitted inference: just-in-time compilation speeds up the inference.
• Compression: enable request/response compression.
• PyTorch deep learning models:
  • sentiment analysis: infer the sentiment of a sentence.
  • image recognition: categorize a given image.
  • stable diffusion: generate images based on texts, with msgpack serialization.

• Dynamic batching
  • max_batch_size and max_wait_time (millisecond) are configured when you call append_worker.
  • Make sure inference with the max_batch_size value won't cause the out-of-memory in GPU.
  • Normally, max_wait_time should be less than the batch inference time.
  • If enabled, it will collect a batch either when the number of accumulated requests reaches max_batch_size or when max_wait_time has elapsed. The service will benefit from this feature when the traffic is high.
• Check the arguments doc for other configurations.

• If you're looking for a GPU base image with mosec installed, you can check the official image mosecorg/mosec. For the complex use case, check out envd.
• This service doesn't need Gunicorn or NGINX, but you can certainly use the ingress controller when necessary.
• This service should be the PID 1 process in the container since it controls multiple processes. If you need to run multiple processes in one container, you will need a supervisor. You may choose Supervisor or Horust.
• Remember to collect the metrics.
  • mosec_service_batch_size_bucket shows the batch size distribution.
  • mosec_service_batch_duration_second_bucket shows the duration of dynamic batching for each connection in each stage (starts from receiving the first task).
  • mosec_service_process_duration_second_bucket shows the duration of processing for each connection in each stage (including the IPC time but excluding the mosec_service_batch_duration_second_bucket).
  • mosec_service_remaining_task shows the number of currently processing tasks.
  • mosec_service_throughput shows the service throughput.
• Stop the service with SIGINT (CTRL+C) or SIGTERM (kill {PID}) since it has the graceful shutdown logic.

• Find out the best max_batch_size and max_wait_time for your inference service. The metrics will show the histograms of the real batch size and batch duration. Those are the key information to adjust these two parameters.
• Try to split the whole inference process into separate CPU and GPU stages (ref DistilBERT). Different stages will be run in a data pipeline, which will keep the GPU busy.
• You can also adjust the number of workers in each stage. For example, if your pipeline consists of a CPU stage for preprocessing and a GPU stage for model inference, increasing the number of CPU-stage workers can help to produce more data to be batched for model inference at the GPU stage; increasing the GPU-stage workers can fully utilize the GPU memory and computation power. Both ways may contribute to higher GPU utilization, which consequently results in higher service throughput.
• For multi-stage services, note that the data passing through different stages will be serialized/deserialized by the serialize_ipc/deserialize_ipc methods, so extremely large data might make the whole pipeline slow. The serialized data is passed to the next stage through rust by default, you could enable shared memory to potentially reduce the latency (ref RedisShmIPCMixin).
• You should choose appropriate serialize/deserialize methods, which are used to decode the user request and encode the response. By default, both are using JSON. However, images and embeddings are not well supported by JSON. You can choose msgpack which is faster and binary compatible (ref Stable Diffusion).
• Configure the threads for OpenBLAS or MKL. It might not be able to choose the most suitable CPUs used by the current Python process. You can configure it for each worker by using the env (ref custom GPU allocation).
• Enable HTTP/2 from client side. mosec automatically adapts to user's protocol (e.g., HTTP/2) since v0.8.8.

Here are some of the companies and individual users that are using Mosec:

• Modelz: Serverless platform for ML inference.
• MOSS: An open sourced conversational language model like ChatGPT.
• TencentCloud: Tencent Cloud Machine Learning Platform, using Mosec as the core inference server framework.
• TensorChord: Cloud native AI infrastructure company.
• OAT: Serving reward models for online LLM alignment.

If you find this software useful for your research, please consider citing

@software{yang2021mosec,
  title = {{MOSEC: Model Serving made Efficient in the Cloud}},
  author = {Yang, Keming and Liu, Zichen and Cheng, Philip},
  howpublished = {https://github.com/mosecorg/mosec},
  year = {2021}
}

We welcome any kind of contribution. Please give us feedback by raising issues or discussing on Discord. You could also directly contribute your code and pull request!

To start develop, you can use envd to create an isolated and clean Python & Rust environment. Check the envd-docs or build.envd for more information.