Registry / ai-ml / mooncake-transfer-engine

mooncake-transfer-engine

JSON →
library0.3.11.post1pypypiunverified

Mooncake Transfer Engine is a Python binding (using pybind11) for the core data transfer component of the Mooncake project. Mooncake itself is a KVCache-centric disaggregated architecture designed to optimize Large Language Model (LLM) inference. The Transfer Engine provides a high-performance, unified interface for batched data movement across various storage devices and network links, supporting protocols like TCP, RDMA, CXL/shared-memory, and NVMe over Fabric. It is actively maintained with frequent updates and integrations into LLM serving frameworks like SGLang and vLLM.

pip install mooncake-transfer-engine
INSTALL
IMPORT
SIG · MOONCAKE-TRANSFER-
M
mooncake-transfer-engine
ai-mlpythonv0.3.11.post1
Install
8.3s avg
Import
Disk
291MB
Pass rate
5/ 10
Env Coverage5 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v0.3.11.post1 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.940 runs
build_error
glibc
py 3.103.940 runs
installs and imports cleanly · install 8.3s · import 0.000s · 294MB
291MB installed
● package 291MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

TransferEngine
from mooncake_transfer_engine.libs import TransferEngine
from mooncake import TransferEngine

This quickstart demonstrates the basic initialization of the Mooncake Transfer Engine. It creates an instance of `TransferEngine` and initializes it with network configuration, then allocates a NumPy buffer. In a real distributed setting, you would typically run a receiver and a sender, with `METADATA_SERVER` pointing to an actual coordination service like etcd. The `protocol` should be set to 'rdma' for high-performance RDMA-capable networks.

import numpy as np import os # In a real distributed setup, a metadata server (e.g., etcd) would be used. # For a simple local demo, 'P2PHANDSHAKE' can be used. METADATA_SERVER = os.environ.get('MC_METADATA_SERVER', 'P2PHANDSHAKE') LOCAL_HOSTNAME = os.environ.get('MC_LOCAL_HOSTNAME', '127.0.0.1:12345') PROTOCOL = os.environ.get('MC_PROTOCOL', 'tcp') # Use 'rdma' for RDMA-capable networks DEVICE_NAME = os.environ.get('MC_DEVICE_NAME', '') # Auto discovery if empty try: from mooncake.engine import TransferEngine # Create transfer engine instance engine = TransferEngine() # Initialize with basic configuration # In a real scenario, local_hostname would be the actual server IP/port # and metadata_server would point to the etcd cluster or similar. engine.initialize( LOCAL_HOSTNAME, METADATA_SERVER, PROTOCOL, DEVICE_NAME ) # Allocate and initialize a buffer (e.g., 1MB) # Note: For GPU memory, specific allocation methods/context would be needed. client_buffer = np.zeros(1024 * 1024, dtype=np.uint8) buffer_address = client_buffer.ctypes.data buffer_length = client_buffer.nbytes print(f"TransferEngine initialized on {LOCAL_HOSTNAME} with {PROTOCOL} protocol.") print(f"Allocated buffer at address: {buffer_address}, length: {buffer_length} bytes.") # Example: Register memory (optional, depending on protocol/usage) # engine.register_memory(buffer_address, buffer_length) # In a full setup, you would then perform transfer operations # e.g., engine.transfer_sync_write(target_hostname, buffer_address, peer_buffer_address, buffer_length) print("Mooncake Transfer Engine basic setup successful (no actual transfer performed).") except ImportError: print("mooncake-transfer-engine not installed or could not be imported.") print("Please ensure you installed the correct version for your CUDA environment.") except Exception as e: print(f"An error occurred: {e}")
Debug
Known issues
gotchaThe `mooncake-transfer-engine` package for CUDA-enabled systems requires CUDA 12.1+ during installation and runtime. For environments without CUDA, use `mooncake-transfer-engine-non-cuda`.
fix
Ensure your CUDA toolkit version is 12.1 or newer. If not, consider building from source with specific CUDA versions or install `mooncake-transfer-engine-non-cuda`.
affects: >=0.3.0
gotchaWhen using RDMA protocol, proper kernel modules (like `nvidia_peermem` for NVIDIA GPUs) and permissions (often requiring `sudo`) are necessary. Issues with `nvidia_peermem` can cause RDMA failures.
fix
Ensure RDMA drivers and `nvidia_peermem` are correctly installed and loaded. Run applications with `sudo` if permission errors persist. Consider `NIXL` as an alternative to `nvidia_peermem` if issues arise.
affects: All
breakingMaintaining strict version consistency of the Transfer Engine between Mooncake itself and integrated inference engines (e.g., SGLang Serving Backend) is crucial for KVCache transport protocol compatibility. Incompatible versions can lead to transfer failures.
fix
When upgrading an inference engine that integrates Mooncake, ensure the `mooncake-transfer-engine` package is updated simultaneously to maintain compatibility.
affects: All
gotchaUsing batch transfer APIs, particularly in multi-node NVLink transfers, has been observed to sometimes affect accuracy in a few inference engines and benchmarks.
fix
Monitor accuracy closely when deploying applications using batch transfer APIs with `mooncake-transfer-engine` in multi-node NVLink configurations.
affects: All
Upgrade
Version history
0.3.11.post1latest on PyPI · released May 24, 2026
Audit
Dependencies
numpyrequiredCommonly used for buffer allocation in Python examples.
zmqoptionalUsed in quickstart examples for inter-process communication.
etcdoptionalOften used as a metadata server backend for cluster coordination.
Agent activity
88 hits · last 30 days
node
86
OpenAI (training)
1
Resources
mooncake-transfer-engine — pip install mooncake-transfer-engine · libregistry