[Doc] Add document for integrating Mooncake Store to LMCache V1

[XucSh]

See #378.

This doc introduces how to integrate Mooncake Store to LMCache V1.

[zhenwei-intel]

Hi @XucSh,

Thanks for sharing this doc, I tried it, but encountered an error Failed to initialize/re-establish remote connection: Please install mooncake by following the instructions
I installed mooncake by pip3 install mooncake-transfer-engine

INFO 05-21 02:31:20 [factory.py:73] Creating v1 connector with name: LMCacheConnectorV1
WARNING 05-21 02:31:20 [base.py:61] Initializing KVConnectorBase_V1. This API is experimental and subject to change in the future as we iterate
 the design.
[2025-05-21 02:31:20,115] LMCache INFO: Loading LMCache config file /datadisk/zhenwei/pd_disagg/mooncake/prefill.yaml (utils.py:56:lmcache.inte
gration.vllm.utils)
[2025-05-21 02:31:20,115] LMCache INFO: LMCache Configuration: {'chunk_size': 256, 'local_cpu': False, 'max_local_cpu_size': '10 GB', 'local_di
sk': None, 'max_local_disk_size': '5 GB', 'remote_url': 'mooncakestore://localhost:50001/', 'remote_serde': 'naive', 'save_decode_cache': False
, 'enable_blending': False, 'blend_recompute_ratio': 0.15, 'blend_min_tokens': 256, 'enable_p2p': False, 'lookup_url': None, 'distributed_url':
 None, 'error_handling': False, 'enable_controller': False, 'lmcache_instance_id': 'lmcache_default_instance', 'enable_nixl': False, 'nixl_role
': None, 'nixl_receiver_host': None, 'nixl_receiver_port': None, 'nixl_buffer_size': None, 'nixl_buffer_device': None, 'nixl_enable_gc': False}
 (config.py:518:lmcache.experimental.config)
[2025-05-21 02:31:20,116] LMCache INFO: Creating LMCacheEngine instance vllm-instance (cache_engine.py:748:lmcache.experimental.cache_engine)
[2025-05-21 02:31:24,017] LMCache INFO: Creating LMCacheEngine with config: LMCacheEngineConfig(chunk_size=256, local_cpu=False, max_local_cpu_
size=10, local_disk=None, max_local_disk_size=5, remote_url='mooncakestore://localhost:50001/', remote_serde='naive', save_decode_cache=False,
enable_blending=False, blend_recompute_ratio=0.15, blend_min_tokens=256, blend_special_str=' # # ', enable_p2p=False, lookup_url=None, distribu
ted_url=None, error_handling=False, enable_controller=False, lmcache_instance_id='lmcache_default_instance', controller_url=None, lmcache_worke
r_port=None, enable_nixl=False, nixl_role=None, nixl_receiver_host=None, nixl_receiver_port=None, nixl_buffer_size=None, nixl_buffer_device=Non
e, nixl_enable_gc=False, audit_actual_remote_url=None) (cache_engine.py:74:lmcache.experimental.cache_engine)
[2025-05-21 02:31:24,036] LMCache WARNING: Failed to initialize/re-establish remote connection: Please install mooncake by following the instru
ctions at https://github.com/kvcache-ai/Mooncake/blob/main/doc/en/build.md to run vLLM with MooncakeConnector. (remote_backend.py:106:lmcache.e
xperimental.storage_backend.remote_backend)
[2025-05-21 02:31:24,037] LMCache INFO: Connected to remote storage at mooncakestore://localhost:50001/ (remote_backend.py:76:lmcache.experimen
tal.storage_backend.remote_backend)
[2025-05-21 02:31:24,037] LMCache INFO: Initializing usage context. (usage_context.py:249:lmcache.usage_context)
WARNING 05-21 02:31:35 [topk_topp_sampler.py:58] FlashInfer is not available. Falling back to the PyTorch-native implementation of top-p & top-
k sampling. For the best performance, please install FlashInfer.
INFO 05-21 02:31:35 [gpu_model_runner.py:1503] Starting to load model Qwen/Qwen3-0.6B...
INFO 05-21 02:31:35 [cuda.py:216] Using Flash Attention backend on V1 engine.
INFO 05-21 02:31:37 [weight_utils.py:291] Using model weights format ['*.safetensors']
INFO 05-21 02:31:38 [weight_utils.py:341] No model.safetensors.index.json found in remote.
Loading safetensors checkpoint shards:   0% Completed | 0/1 [00:00<?, ?it/s]



[2025-05-21 02:34:13,201] LMCache WARNING: Failed to initialize/re-establish remote connection: Please install mooncake by following the instru
ctions at https://github.com/kvcache-ai/Mooncake/blob/main/doc/en/build.md to run vLLM with MooncakeConnector. (remote_backend.py:106:lmcache.e
xperimental.storage_backend.remote_backend)
[2025-05-21 02:34:13,201] LMCache WARNING: Connection is None in contains, returning False (remote_backend.py:125:lmcache.experimental.storage_
backend.remote_backend)
[2025-05-21 02:34:13,201] LMCache INFO: Storing KV cache for 4 out of 4 tokens for request cmpl-a9817d5fa90244f9aa26d335c623d24e-0 (vllm_v1_ada
pter.py:638:lmcache.integration.vllm.vllm_v1_adapter)

[XucSh]

Hi，zhenwei，the error indicates that mooncake is not installed correctly, you can install it by hand.

git clone https://github.com/kvcache-ai/Mooncake.git && cd Mooncake && sh dependencies.sh && mkdir build && cd build && cmake .. -DUSE_ETCD=1 -DUSE_ETCD_LEGACY=1 && make install

[zhenwei-intel]

Thanks for your reply, I will try.

BTW, does LMCache with mooncake backend not rely on the CUDA env and can it also run on other AI accelerators?

[XucSh]

You are right. Now LMCache V1 only works with CUDA.

[cicirori]

@XucSh hello, wanna check if DUSE_ETCD_LEGACY=1 is necessary, it's hard to compile when enable this on my env.

[XucSh]

@cicirori hi，this is not necessary. Regardless of how it's done, the key is to get the etcd service running. :)