Implementation:LMCache LMCache Safe Serde

Knowledge Sources	LMCache
Domains	Serialization, KV Cache
Last Updated	2026-02-09 00:00 GMT

Overview

Provides a safetensors-based serialization and deserialization implementation for PyTorch tensors that preserves tensor metadata.

Description

The SafeSerializer uses the safetensors library to serialize tensors, which embeds shape and dtype metadata alongside the raw data in a safe, validated format. The tensor is first moved to CPU and made contiguous before serialization. The SafeDeserializer restores tensors from safetensors bytes using safetensors.torch.load and casts the result to the target dtype. This approach is safer than raw-bytes serialization as it validates tensor integrity and preserves metadata, at the cost of slightly more overhead.

Usage

Use SafeSerializer and SafeDeserializer when tensor metadata preservation and data integrity validation are important, such as when storing KV cache data to disk or transferring it over a network where the consumer may not know the shape and dtype.

Code Reference

Source Location

• Repository: LMCache
• File: lmcache/storage_backend/serde/safe_serde.py
• Lines: 1-34

Signature

class SafeSerializer(Serializer):
    def __init__(self): ...
    def to_bytes(self, t: torch.Tensor) -> bytes: ...

class SafeDeserializer(Deserializer):
    def __init__(self, dtype): ...
    def from_bytes_normal(self, b: Union[bytearray, bytes]) -> torch.Tensor: ...
    def from_bytes(self, b: Union[bytearray, bytes]) -> torch.Tensor: ...

Import

from lmcache.storage_backend.serde.safe_serde import SafeSerializer, SafeDeserializer

I/O Contract

Inputs

Name	Type	Required	Description
t	torch.Tensor	Yes (to_bytes)	Tensor to serialize; moved to CPU and made contiguous internally
dtype	torch.dtype	Yes (SafeDeserializer constructor)	Target dtype for the deserialized tensor
b	Union[bytearray, bytes]	Yes (from_bytes)	Safetensors-formatted bytes to deserialize

Outputs

Name	Type	Description
bytes	bytes	Safetensors-formatted byte string including metadata and tensor data
tensor	torch.Tensor	Restored tensor with correct shape, cast to the target dtype

Usage Examples

import torch
from lmcache.storage_backend.serde.safe_serde import SafeSerializer, SafeDeserializer

serializer = SafeSerializer()
deserializer = SafeDeserializer(dtype=torch.float16)

# Serialize with metadata preservation
tensor = torch.randn(32, 128, dtype=torch.float16)
data = serializer.to_bytes(tensor)

# Deserialize (shape is embedded in the safetensors format)
restored = deserializer.from_bytes(data)
assert restored.shape == (32, 128)