Implementation:Bentoml BentoML Serde Framework

Knowledge Sources	Bentoml_BentoML
Domains	Serialization, HTTP, IO
Last Updated	2026-02-13 15:00 GMT

Overview

Implements the serialization and deserialization (serde) framework for BentoML, supporting JSON, multipart form data, and pickle protocols for converting IODescriptor models to and from wire-format payloads.

Description

The serde module defines BentoML's pluggable serialization layer. At its core is the Payload frozen attrs class, which encapsulates chunked byte data with metadata headers. The abstract Serde base class establishes the contract for serializing/deserializing both full IODescriptor models and raw values with schema information.

The module provides three concrete implementations:

• JSONSerde -- Serializes models to JSON using Pydantic's model_dump_json. Supports downloading files from HTTP URLs for multipart root models. Media type: application/json.
• MultipartSerde -- Extends JSONSerde to handle multipart/form-data HTTP requests. Parses form fields, downloads remote file URLs via httpx, and validates against model field annotations for list and union types.
• PickleSerde -- Uses Python's pickle protocol 5 with out-of-band buffer support for efficient binary serialization. Tracks buffer lengths in metadata for proper reconstruction. Media type: application/vnd.bentoml+pickle.

The GenericSerde mixin adds schema-aware encoding/decoding for tensor, dataframe, array, and object types, delegating to TensorSchema and DataframeSchema validators.

All serde implementations are registered in the ALL_SERDE mapping by media type for runtime lookup.

Usage

Use this module when implementing custom API endpoint handling, extending BentoML's serialization for new content types, or when working with the internal request/response pipeline of BentoML services.

Code Reference

Source Location

• Repository: Bentoml_BentoML
• File: src/_bentoml_impl/serde.py
• Lines: 1-291

Signature

@attrs.frozen
class Payload:
    data: t.Iterable[bytes | memoryview]
    metadata: t.Mapping[str, str]

class Serde(abc.ABC):
    media_type: str
    def serialize_model(self, model: IODescriptor) -> Payload: ...
    def deserialize_model(self, payload: Payload, cls: type[T]) -> T: ...
    def serialize(self, obj: t.Any, schema: dict[str, t.Any]) -> Payload: ...
    def deserialize(self, payload: Payload, schema: dict[str, t.Any]) -> t.Any: ...
    async def parse_request(self, request: Request, cls: type[T]) -> T: ...

class JSONSerde(GenericSerde, Serde): ...
class MultipartSerde(JSONSerde): ...
class PickleSerde(GenericSerde, Serde): ...

ALL_SERDE: t.Mapping[str, type[Serde]]

Import

from _bentoml_impl.serde import Payload, Serde, JSONSerde, MultipartSerde, PickleSerde, ALL_SERDE

I/O Contract

Inputs

Name	Type	Required	Description
model	IODescriptor	Yes	Pydantic model instance to serialize
payload	Payload	Yes	Chunked byte data with metadata to deserialize
cls	type[T]	Yes	Target Pydantic model class for deserialization
schema	dict[str, Any]	Yes	JSON schema dict for generic encode/decode of tensors, dataframes, arrays, and objects
request	starlette.Request	Yes	HTTP request object (for parse_request methods)

Outputs

Name	Type	Description
Payload	Payload	Serialized data with metadata including content-length
T	IODescriptor subclass	Deserialized model instance
Any	Any	Deserialized raw value (for schema-based deserialization)

Usage Examples

from _bentoml_impl.serde import JSONSerde, PickleSerde, ALL_SERDE, Payload

# JSON serialization
json_serde = JSONSerde()
payload = json_serde.serialize({"name": "test", "value": 42}, {"type": "object", "properties": {"name": {"type": "string"}, "value": {"type": "integer"}}})

# Pickle serialization with out-of-band buffers
pickle_serde = PickleSerde()
payload = pickle_serde.serialize_value({"key": "value"})

# Look up serde by media type
serde_cls = ALL_SERDE["application/json"]

Related Pages

• Implementation:Bentoml_BentoML_Arrow_Conversion