How zhengjiahong-ai/llm-kv-cache-optimization works
KVopt is a research scaffold for cost-aware KV-cache eviction in LLM serving, with Continuum-style retention and scheduling as supporting system mechanisms. The principal workflow is workload/request handling, cache-pressure victim selection, and block allocation or eviction; the vLLM path adapts policy decisions to native cache structures. Continuum coordinates lifecycle observations, histories, TTL-based retention, and scheduling candidates. The README documents broader capabilities than the sampled source confirms; unsampled wiring is shown only where documented, and the proposed cost-aware policy itself has no identifiable implementation in this tree.
Main entry points: observer.py Runtime Hooks · runtime.py Runtime Coordinator · simulator.py Simulator · manager.py Cache Manager
Components 25
Requests and Simulation
- Workload
src/kvopt/workload/base.py - Request Model
src/kvopt/scheduler/request.py - FIFO Scheduler
src/kvopt/scheduler/scheduler.py - Simulator
src/kvopt/runtime/simulator.py
Eviction and Cache
- Eviction Policy
src/kvopt/kv_cache/policy.py - Cache Manager
src/kvopt/kv_cache/manager.py - Cache State
src/kvopt/kv_cache/state.py - Dummy Policy
src/kvopt/policies/dummy.py
Continuum Coordination
- Runtime Coordinator
src/kvopt/continuum/runtime.py - Retention Manager
src/kvopt/continuum/retention.py - Lifecycle Histories
src/kvopt/continuum/history.py - Dynamic TTL
src/kvopt/continuum/ttl.py - Scheduling Policy
src/kvopt/continuum/selection.py - Prefill Profile
src/kvopt/continuum/prefill_profile.py
vLLM Integration
- Runtime Hooks
src/kvopt/runtime/vllm/observer.py - Observation Extractors
src/kvopt/runtime/vllm/continuum_observation.py - Eviction Bridge
src/kvopt/runtime/vllm/bridge.py - Policy Adapter
src/kvopt/runtime/vllm/adapter.py - Retention Adapter
src/kvopt/runtime/vllm/retention_integration.py
Metrics
- Metrics Collector
src/kvopt/metrics/collector.py
Other components
- Workload Input
- vLLM Runtime
- vLLM Scheduler
- Native Block Pool
- GPU APC Cache
Connections 24
- Workload Input → Workload: supplies trace
- Workload → Request Model: yields requests
- Simulator → FIFO Scheduler: schedules via
- Simulator → Cache Manager: allocates blocks
- Simulator → Metrics Collector: records events
- FIFO Scheduler → Request Model: updates status
- Cache Manager → Cache State: reads state
- Cache Manager → Eviction Policy: requests victims
- Dummy Policy → Eviction Policy: implements
- Runtime Coordinator → Retention Manager: coordinates
- Runtime Coordinator → Lifecycle Histories: records observations
- Runtime Coordinator → Dynamic TTL: derives TTL
- Runtime Coordinator → Prefill Profile: estimates reload
- Runtime Coordinator → Scheduling Policy: provides candidates
- vLLM Runtime → Runtime Hooks: installs hooks
- Runtime Hooks → Eviction Bridge: selects blocks through
- Eviction Bridge → Policy Adapter: adapts policy
- Policy Adapter → Eviction Policy: uses policy
- Runtime Hooks → Observation Extractors: snapshots native state
- Runtime Hooks → vLLM Scheduler: orders waiting requests
- Runtime Hooks → Native Block Pool: hooks eviction
- Retention Adapter → Runtime Coordinator: applies retention
- Runtime Hooks → Retention Adapter: invokes integration
- Native Block Pool → GPU APC Cache: manages blocks