Skip to content

[Notice] Native MessagePack wire contract for BatchMeta, sample tags, and Controller metadata #222

Open

Description

@0oshowero0

1. Sample Tags (tag / BatchMeta.custom_meta) and _custom_backend_meta

BatchMeta is now serialized on the ZMQ wire as msgpack.Ext(6, ...) instead of falling back to pickle. Any per-sample metadata carried inside BatchMeta must be representable in standard MessagePack:

  • Supported values: dict with UTF-8 str keys (nested dicts are supported), list (nested lists are supported), str, bytes, signed/unsigned 64-bit int, float, bool, and None.
    • Python tuple values are encoded as MessagePack arrays and decode back as list.
  • Unsupported values: torch.Tensor, np.ndarray, NumPy/PyTorch scalar objects (e.g., np.int64, np.float32), integers outside 64-bit range, and custom Python classes/callables.
    • Migration: Convert NumPy or 0-D tensor scalars via .item() (or int(...) / float(...)) before passing them into kv_put(..., tag=...) or BatchMeta.update_custom_meta(...).
    • Avoid "__tq_tensordict__": True in user metadata dicts sent over ZMQ, as MsgpackDecoder reserves that marker for TensorDict reconstruction.
  • Error behavior: To keep the write path free of per-sample validation overhead, unsupported objects are not pre-scanned on write; encoding a BatchMeta containing non-MessagePack values raises RuntimeError: Failed to encode BatchMeta as native MessagePack at serialization time (instead of silently falling back to pickle).

2. BatchMeta.extra_info Stays Python/Ray-Local

  • BatchMeta.extra_info is omitted from the Controller's MessagePack payload and reconstructs as {} on Controller ZMQ replies (GET_META_RESPONSE, GET_PARTITION_META_RESPONSE, KV_RETRIEVE_META_RESPONSE).
  • BatchMeta.__getstate__ / __setstate__ are unchanged for extra_info and custom_meta, so passing BatchMeta across Ray actors (e.g., trainer/rollout workers) or calling copy.deepcopy(batch_meta) continues to preserve arbitrary Python objects in extra_info.
  • BatchMeta.global_indexes and StorageManager.notify_data_update normalize NumPy integer indices via operator.index automatically, so custom BaseSampler subclasses returning np.int64 indices require no changes.

3. Upgrade & Checkpoint Compatibility

  • Upgrade components together: Controller, TransferQueueClient, and StorageManager processes in the same job must run the same TransferQueue version because BatchMeta (Ext(6)) and field_schema / merge_plan ("int64", "bfloat16", etc.) use the new wire format.
  • Legacy checkpoints: The tq.save_checkpoint / tq.load_checkpoint workflow is unchanged. When Controller.load_checkpoint reads an older controller_state.pkl whose FieldMeta stored list shapes or string dtypes (e.g., "torch.int64"), it normalizes them in-place to tuple and torch.dtype and emits a FutureWarning. Re-save restored checkpoints with the current version before string dtype support is removed in the next release.

Related: #220, #221

Activity

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions