[PR #1248] [CLOSED] [Misc] add mooncake-conductor control-panel #2104

New issue

Closed

opened 2026-10-29 21:32:48 +00:00 by bsakaguchi · 0 comments

bsakaguchi commented

2026-10-29 21:32:48 +00:00

Owner

📋 Pull Request Information

Original PR: https://github.com/kvcache-ai/Mooncake/pull/1248
Author: @yejj710
Created: 12/21/2025
Status: ❌ Closed

Base: main ← Head: conductor

📝 Commits (10+)

0d1de66 add conductor indexer & using example
d4d10c3 support zmq subscribe & readme
f9f62ae fix some ci bugs
230b6db update readme & fix AI review
2d1f885 bugfix: parse_uint64 must return 64bit length
3238680 make code clean & remove some log
959540f add ut for zmq package
7b99a69 remove some useless log & add some todo
efcd9c8 bugfix: support moocake kv-event
0cf1146 add ci-test for mooncake conductor & update docs

📊 Changes

21 files changed (+3651 additions, -0 deletions)

View changed files

📝 .github/workflows/ci.yml (+7 -0)
📝 CMakeLists.txt (+7 -0)
➕ mooncake-conductor/CMakeLists.txt (+17 -0)
➕ mooncake-conductor/README.md (+167 -0)
➕ mooncake-conductor/build.sh (+33 -0)
➕ mooncake-conductor/conductor-ctrl/common/sync_map.go (+82 -0)
➕ mooncake-conductor/conductor-ctrl/common/types.go (+32 -0)
➕ mooncake-conductor/conductor-ctrl/common/utils.go (+100 -0)
➕ mooncake-conductor/conductor-ctrl/go.mod (+9 -0)
➕ mooncake-conductor/conductor-ctrl/kvevent/event_handler.go (+105 -0)
➕ mooncake-conductor/conductor-ctrl/kvevent/event_manager.go (+243 -0)
➕ mooncake-conductor/conductor-ctrl/main.go (+119 -0)
➕ mooncake-conductor/conductor-ctrl/prefixindex/prefix_indexer.go (+356 -0)
➕ mooncake-conductor/conductor-ctrl/zmq/event_type.go (+101 -0)
➕ mooncake-conductor/conductor-ctrl/zmq/msg_decoder.go (+638 -0)
➕ mooncake-conductor/conductor-ctrl/zmq/msg_decoder_test.go (+178 -0)
➕ mooncake-conductor/conductor-ctrl/zmq/types.go (+58 -0)
➕ mooncake-conductor/conductor-ctrl/zmq/zmq_client.go (+359 -0)
➕ mooncake-conductor/conductor-ctrl/zmq/zmq_client_test.go (+663 -0)
➕ mooncake-conductor/example/cache_aware_disagg_proxy.py (+355 -0)

...and 1 more files

📄 Description

Description

motivation: https://github.com/kvcache-ai/Mooncake/issues/977
add conductor control-panel, it's a cache aware indexer based on kv-event. co-work with @Liziqi-77 @Asher-XunZhang
mooncake_conductor is mainly divided into four components, which are:

EventManager
Manages the subscription and lifecycle of all services
- Starts/stops all ZMQ clients
- Handles service connections and reconnections
- Provides HTTP API interfaces
ZMQClient
Establishes ZMQ connections with AI inference services & mooncake_mastaer
KVEventHandler
Handles specific KV events
- BlockStoredEvent: Block storage events
- BlockRemovedEvent: Block removal events
PrefixCacheTable
Provides prefix block_hash-based cache indexing
- Calculates prefix hashes for token sequences
- Tracks cache block distribution across different engines
- Provides cache hit ratio calculation

Type of Change

Types
- Bug fix
- New feature
  - Transfer Engine
  - Mooncake Store
  - Mooncake EP
  - Integration
  - P2P Store
  - Python Wheel
- Breaking change
- CI/CD
- Documentation update
- Other

How Has This Been Tested?

first, set WITH_CONDUCTOR to ON, then compile mooncake project.

usage example:

export CONDUCTOR_CONFIG_PATH=“set your json config path”
# after execute make install
mooncake_conductor

Checklist

I have performed a self-review of my own code.
I have updated the documentation.
I have added tests to prove my changes are effective.

_{🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.}

## 📋 Pull Request Information **Original PR:** https://github.com/kvcache-ai/Mooncake/pull/1248 **Author:** [@yejj710](https://github.com/yejj710) **Created:** 12/21/2025 **Status:** ❌ Closed **Base:** `main` ← **Head:** `conductor` --- ### 📝 Commits (10+) - [`0d1de66`](https://github.com/kvcache-ai/Mooncake/commit/0d1de66737a769c1544394758ee67c99e8ead04d) add conductor indexer & using example - [`d4d10c3`](https://github.com/kvcache-ai/Mooncake/commit/d4d10c388471dcea2c6ec3a0a080e2057c27beaf) support zmq subscribe & readme - [`f9f62ae`](https://github.com/kvcache-ai/Mooncake/commit/f9f62aea2f5678d21ef127a94157a0f0c379faa8) fix some ci bugs - [`230b6db`](https://github.com/kvcache-ai/Mooncake/commit/230b6db4ef324bd82851916e8cf9593641cfa5ba) update readme & fix AI review - [`2d1f885`](https://github.com/kvcache-ai/Mooncake/commit/2d1f8855361fd184aee3a090d632660a05dc6c85) bugfix: parse_uint64 must return 64bit length - [`3238680`](https://github.com/kvcache-ai/Mooncake/commit/32386808d708807c6504266c44e25a1dce41a92a) make code clean & remove some log - [`959540f`](https://github.com/kvcache-ai/Mooncake/commit/959540f7518dee1ddd797b587e35f1456428945a) add ut for zmq package - [`7b99a69`](https://github.com/kvcache-ai/Mooncake/commit/7b99a6960c3191ae4ce7bf3bfeda4d2a8f51379d) remove some useless log & add some todo - [`efcd9c8`](https://github.com/kvcache-ai/Mooncake/commit/efcd9c8439dcb337e6a2b64294facbd6a051d99a) bugfix: support moocake kv-event - [`0cf1146`](https://github.com/kvcache-ai/Mooncake/commit/0cf11466079d1e5a881276802a20e3c25180d17f) add ci-test for mooncake conductor & update docs ### 📊 Changes **21 files changed** (+3651 additions, -0 deletions) <details> <summary>View changed files</summary> 📝 `.github/workflows/ci.yml` (+7 -0) 📝 `CMakeLists.txt` (+7 -0) ➕ `mooncake-conductor/CMakeLists.txt` (+17 -0) ➕ `mooncake-conductor/README.md` (+167 -0) ➕ `mooncake-conductor/build.sh` (+33 -0) ➕ `mooncake-conductor/conductor-ctrl/common/sync_map.go` (+82 -0) ➕ `mooncake-conductor/conductor-ctrl/common/types.go` (+32 -0) ➕ `mooncake-conductor/conductor-ctrl/common/utils.go` (+100 -0) ➕ `mooncake-conductor/conductor-ctrl/go.mod` (+9 -0) ➕ `mooncake-conductor/conductor-ctrl/kvevent/event_handler.go` (+105 -0) ➕ `mooncake-conductor/conductor-ctrl/kvevent/event_manager.go` (+243 -0) ➕ `mooncake-conductor/conductor-ctrl/main.go` (+119 -0) ➕ `mooncake-conductor/conductor-ctrl/prefixindex/prefix_indexer.go` (+356 -0) ➕ `mooncake-conductor/conductor-ctrl/zmq/event_type.go` (+101 -0) ➕ `mooncake-conductor/conductor-ctrl/zmq/msg_decoder.go` (+638 -0) ➕ `mooncake-conductor/conductor-ctrl/zmq/msg_decoder_test.go` (+178 -0) ➕ `mooncake-conductor/conductor-ctrl/zmq/types.go` (+58 -0) ➕ `mooncake-conductor/conductor-ctrl/zmq/zmq_client.go` (+359 -0) ➕ `mooncake-conductor/conductor-ctrl/zmq/zmq_client_test.go` (+663 -0) ➕ `mooncake-conductor/example/cache_aware_disagg_proxy.py` (+355 -0) _...and 1 more files_ </details> ### 📄 Description ## Description motivation: https://github.com/kvcache-ai/Mooncake/issues/977 add conductor control-panel, it's a cache aware indexer based on kv-event. co-work with @Liziqi-77 @Asher-XunZhang **`mooncake_conductor`** is mainly divided into four components, which are: * **EventManager** Manages the subscription and lifecycle of all services - Starts/stops all ZMQ clients - Handles service connections and reconnections - Provides HTTP API interfaces * **ZMQClient** Establishes ZMQ connections with AI inference services & mooncake_mastaer * **KVEventHandler** Handles specific KV events - `BlockStoredEvent`: Block storage events - `BlockRemovedEvent`: Block removal events * **PrefixCacheTable** Provides prefix block_hash-based cache indexing - Calculates prefix hashes for token sequences - Tracks cache block distribution across different engines - Provides cache hit ratio calculation ## Type of Change * Types - [ ] Bug fix - [x] New feature - [ ] Transfer Engine - [ ] Mooncake Store - [ ] Mooncake EP - [ ] Integration - [ ] P2P Store - [ ] Python Wheel - [ ] Breaking change - [x] CI/CD - [x] Documentation update - [ ] Other ## How Has This Been Tested? first, set `WITH_CONDUCTOR` to ON, then compile mooncake project. usage example: ```sh export CONDUCTOR_CONFIG_PATH=“set your json config path” # after execute make install mooncake_conductor ``` ## Checklist - [x] I have performed a self-review of my own code. - [ ] I have updated the documentation. - [x] I have added tests to prove my changes are effective. --- <sub>🔄 This issue represents a GitHub Pull Request. It cannot be merged through Gitea due to API limitations.</sub>

bsakaguchi

2026-10-29 21:32:48 +00:00