dev-ucm-v1 merge main

.github/CODEOWNERS

@@ -0,0 +1,38 @@
+# See https://help.github.com/articles/about-codeowners/
+# for more info about CODEOWNERS file
+
+* @mag1c-h @ygwpz @FangRun2 @Tarrei
+/.github @Wwwzff @hek14 @ygwpz @mag1c-h @FangRun2 @Tarrei
+
+/ucm/sparse @wuhuxiao @wangwenxin0312 @hek14 @ygwpz @mag1c-h
+/ucm/sparse/cache_blend @wuhuxiao @hek14 @ygwpz @mag1c-h
+/ucm/sparse/esa @wangwenxin0312 @hek14 @ygwpz @mag1c-h
+/ucm/sparse/gsa @Zbm1996 @zbb200819 @yxkyong @HaoLi980405  @wuhuxiao @hek14 @ygwpz @mag1c-h
+/ucm/sparse/kvcomp @leideng @pengwwang @wuhuxiao @hek14 @ygwpz @mag1c-h
+/ucm/sparse/kvstar @saki-daisuki @summer-ai007 @xwLearnsLLM @wuhuxiao @hek14 @ygwpz @mag1c-h
+
+/ucm/store @mag1c-h @ygwpz
+/ucm/store/dramstore @harrisonyhq @mag1c-h @ygwpz
+/ucm/store/localstore @mag1c-h @ygwpz
+/ucm/store/mooncakestore @chinesezyc @mag1c-h @ygwpz
+/ucm/store/nfsstore @mag1c-h @ygwpz
+
+/ucm/integration @qyh111 @harrisonyhq @ygwpz @mag1c-h @hek14
+
+/ucm/pd @flesher0813 @ygwpz @mag1c-h
+
+/ucm/sandbox @Wwwzff @hek14 @ygwpz @mag1c-h @FangRun2 @Tarrei
+
+/benchmarks @flesher0813 @ygwpz @mag1c-h
+
+/docker @harrisonyhq @ygwpz @mag1c-h
+
+/docs @flesher0813 @ygwpz @mag1c-h @FangRun2 @Tarrei @hek14
+/docs/source/user-guide/sparse-attention/esa.md @wangwenxin0312 @hek14 @flesher0813 @ygwpz @mag1c-h @FangRun2 @Tarrei
+/docs/source/user-guide/sparse-attention/gsa.md @Zbm1996 @zbb200819 @yxkyong @HaoLi980405 @flesher0813 @ygwpz @mag1c-h @FangRun2 @Tarrei
+/docs/source/user-guide/sparse-attention/kvcomp.md @leideng @pengwwang @flesher0813 @ygwpz @mag1c-h @FangRun2 @Tarrei
+/docs/source/user-guide/sparse-attention/kvstar.md @saki-daisuki @summer-ai007 @flesher0813 @ygwpz @mag1c-h @FangRun2 @Tarrei
+
+/examples @harrisonyhq @ygwpz @mag1c-h @hek14
+
+/test @Wwwzff @ygwpz @mag1c-h

.github/workflows/cpp-linter.yml

@@ -0,0 +1,34 @@
+name: cpp-linter
+
+on:
+  push:
+    branches: [ "*" ]
+  pull_request:
+    branches: [ "dev*", "main", "*release" ]
+
+
+jobs:
+  cpp-linter:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@1af3b93b6815bc44a9784bd300feb67ff0d1eeb3  # v6.0.0
+        with:
+          persist-credentials: false
+      - uses: cpp-linter/cpp-linter-action@main
+        id: linter
+        continue-on-error: true
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        with:
+          style: file
+          tidy-checks: '-*'
+          files-changed-only: true
+          lines-changed-only: diff
+          format-review: true
+          thread-comments: ${{ github.event_name == 'pull_request' && 'update' }}
+
+      - name: Fail fast?!
+        if: steps.linter.outputs.checks-failed != 0
+        run: |
+          echo "some linter checks failed. ${{ steps.linter.outputs.checks-failed }}"
+          exit 1

.github/workflows/unifiedcache_test.yml

@@ -49,7 +49,9 @@ jobs:
               set -euo pipefail
               pip install -v -e . --no-build-isolation
               cd \$(pip show vllm | grep Location | awk '{print \$2}') &&
-              git apply /workspace/unified-cache-management/ucm/integration/vllm/patch/0.9.2/vllm-adapt.patch
+              git apply /workspace/unified-cache-management/ucm/integration/vllm/patch/0.9.2/vllm-adapt-pc.patch
+              git apply /workspace/unified-cache-management/ucm/integration/vllm/patch/0.9.2/vllm-adapt-aggre.patch
+              git apply /workspace/unified-cache-management/ucm/integration/vllm/patch/0.9.2/vllm-adapt-sparse.patch
               cd /workspace/unified-cache-management
               python3 -m unittest discover -s test
             "

.gitignore

@@ -49,4 +49,15 @@
 **/output/**
 .venv/**
 **/__pycache__/**
-*.egg-info/**
+*.egg-info/**
+reports/
+dataset/
+logs/
+.*
+*.log
+result_outputs/
+results/
+.cache/
+backup/
+$null
+*__pycache__/

CMakeLists.txt

@@ -9,7 +9,10 @@ set(CMAKE_EXPORT_COMPILE_COMMANDS ON)
 option(BUILD_UCM_STORE "build ucm store module." ON)
 option(BUILD_UCM_SPARSE "build ucm sparse module." ON)
 option(BUILD_UNIT_TESTS "build all unit test suits." OFF)
-set(RUNTIME_ENVIRONMENT "simu" CACHE STRING "runtime: simu, ascend or cuda.")
+option(BUILD_NUMA "build numactl library." OFF)
+option(DOWNLOAD_DEPENDENCE "download dependence by cmake." ON)
+set(RUNTIME_ENVIRONMENT "simu" CACHE STRING "runtime: simu, ascend, musa or cuda.")
+set(LOGGER_BACKEND "spdlog" CACHE STRING "backend: spdlog or flux.")
 
 execute_process(COMMAND git rev-parse HEAD OUTPUT_VARIABLE UCM_COMMIT_ID OUTPUT_STRIP_TRAILING_WHITESPACE)
 add_compile_definitions(UCM_PROJECT_NAME="${PROJECT_NAME}")

README.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-| <a href="docs/source/index.md"><b>Documentation</b></a> | <a href="https://modelengine-ai.net/#/ucm"><b>Website</b></a> | <a href="https://github.com/ModelEngine-Group/unified-cache-management/issues/78"><b>RoadMap</b></a> | <a href="https://github.com/ModelEngine-Group/unified-cache-management/blob/main/README_zh.md"><b>中文</b></a> |
+| <a href="https://ucm.readthedocs.io/en/latest"><b>Documentation</b></a> | <a href="https://modelengine-ai.net/#/ucm"><b>Website</b></a> | <a href="https://github.com/ModelEngine-Group/unified-cache-management/issues/78"><b>RoadMap</b></a> | <a href="README_zh.md"><b>中文</b></a> |
 </p>
 
 ---
@@ -82,9 +82,10 @@ please refer to [Quick Start](./docs/source/getting-started/quick_start.md).
 ---
 
 ## Contact Us
+1. For technical questions and feature requests, please use GitHub [Issues](https://github.com/ModelEngine-Group/unified-cache-management/issues).
+2. WeChat technical discussion group: Scan the QR code below.
 
-For technical questions and feature requests, please use
-GitHub [Issues](https://github.com/ModelEngine-Group/unified-cache-management/issues).
+<img src="docs/source/_static/images/qrcode_for_wechat.png" alt="wechat-gh" width="40%">
 
 ## License
 

README_zh.md

@@ -6,7 +6,7 @@
 </p>
 
 <p align="center">
-| <a href="docs/source/index.md"><b>文档</b></a> | <a href="https://modelengine-ai.net/#/ucm"><b>网站</b></a> | <a href="https://github.com/ModelEngine-Group/unified-cache-management/issues/78"><b>发展路线图</b></a> | <a href="https://github.com/ModelEngine-Group/unified-cache-management"><b>EN</b></a> |
+| <a href="https://ucm.readthedocs.io/en/latest"><b>文档</b></a> | <a href="https://modelengine-ai.net/#/ucm"><b>网站</b></a> | <a href="https://github.com/ModelEngine-Group/unified-cache-management/issues/78"><b>发展路线图</b></a> | <a href="https://github.com/ModelEngine-Group/unified-cache-management"><b>EN</b></a> |
 </p>
 
 ---
@@ -62,7 +62,10 @@ KVStoreBase有助于实现稀疏算法与外部存储的解耦。它定义了与
 ---
 
 ## 联系我们
-如需技术咨询或功能请求，请提交 GitHub [Issues](https://github.com/ModelEngine-Group/unified-cache-management/issues).
+1. 如需技术咨询或功能请求，请提交 GitHub [Issues](https://github.com/ModelEngine-Group/unified-cache-management/issues)。
+2. 微信技术交流群：扫描下方二维码。
+
+<img src="docs/source/_static/images/qrcode_for_wechat.png" alt="wechat-gh" width="40%">
 
 ## 许可协议
 

benchmarks/README.md

@@ -0,0 +1,128 @@
+# TraceReplay Benchmark Tool
+
+It accurately replays real-world request traces with original timing or dynamically generates requests using popular datasets. The tool delivers comprehensive performance metrics—including Time to First Token (TTFT), Time Per Output Token (TPOT), Inter-Token Latency (ITL), End-to-End Latency, Goodput, etc.
+
+---
+
+## 1.  Overview
+
+The Trace Replay feature mainly includes request generation, request sending and response receiving, as well as result calculation and saving. It can reproduce historical requests based on MoonCake's trace file and strictly send the requests according to the timestamps recorded in the trace. After execution, Trace Replay calculates key performance metrics such as Time to First Token (TTFT) and Time Per Output Token (TPOT), then outputs the results to the terminal and saves them to an Excel file.
+
+[Mooncake traces](https://github.com/kvcache-ai/Mooncake/tree/main/FAST25-release/traces) consist of two types of trace data：
+* Conversation and Tool&Agent trace: Sampled from one hour of online request data from different clusters.
+* Synthetic trace: Generated synthetically from other publicly available datasets.
+
+For more information, please refer to the Mooncake paper: [Mooncake-FAST25.pdf](https://github.com/kvcache-ai/Mooncake/blob/main/FAST25-release/Mooncake-FAST25.pdf) .
+
+Trace Replay supports two request-generation methods:
+* Hash ID-based: Input tokens are generated based on the input_length and hash_ids recorded in the trace file. Each hash_id corresponds to a block, with each block containing 512 tokens. The same hash_id always maps to the identical token sequence.
+* Dataset-based: Prompts are generated by invoking vLLM's benchmark module using the input_length from the trace file and the user-specified dataset name. This approach does not rely on the hash_ids present in the trace file.
+
+Depending on the request generation method, Trace Replay offers two modes: Trace Mode and Benchmark Mode, which can be configured by the user via the --trace-mode parameter.
+
+---
+
+## 2.  Parameter
+
+| Argument | Default | Help |
+|-----------|---------|---------|
+| --backend  | None |  backend framework type |
+| --model    | None |  model path    |
+| --host| localhost |  IP address of the inference server     |
+| --port     | None |  Port number of the inference server    |
+| --trace-path   |  None  | trace jsonl file path  |
+| --trace-mode   | trace   | 'trace' to replay requests from cached trace files, 'benchmark' to generate requests dynamically using the benchmark module   |
+| --dataset-name | sharegpt | if enable benchmark mode, you must specify a dataset， refer to the [vLLM benchmark documentation](https://github.com/vllm-project/vllm/blob/releases/v0.9.1/benchmarks/README.md )|
+| --save-prompts |  False  | save generated prompts with timestamp for reuse  |
+| --save-result  | False | save the benchmark metrics to excel file |
+| --result-dir | None | path to save results |
+
+---
+
+## 3.  Example
+
+### 1. Download example trace
+
+You need to download the trace jsonl file from [Mooncake traces](https://github.com/kvcache-ai/Mooncake/tree/main/FAST25-release/traces ). In the trace, each line is a JSON object representing a single request:
+
+```
+{
+  "timestamp": 1696000000123,   // ms since epoch
+  "input_length": 512,          // number of input tokens
+  "output_length": 128,         // expected output tokens
+  "hash_ids": [123, 456, 789]   // seed list for deterministic prompt generation
+}
+```
+
+### 2. Set environment variable
+
+Trace Replay depends on [vLLM's benchmark](https://github.com/vllm-project/vllm/tree/main/benchmarks) module, which you need to download separately. Before running Trace Replay, you must set the path to the benchmark module via an environment variable.:
+
+```bash
+export BENCHMARK_PATH="/vllm-workspace/benchmarks"
+```
+
+### 3.Basic Usage
+
+Execute the Python script to replay a trace against a local vLLM instance:
+
+```bash
+python3 /trace_replay.py \
+  --model  /home/models/dsv2-lite \
+  --backend vllm \
+  --trace-path /conversation_trace.jsonl \
+  --trace-mode trace \
+  --host 127.0.0.1 \
+  --port 8000 \
+  --save-result \
+  --save-prompts
+```
+
+### 4.Results
+
+Successful execution results in output similar to the following:
+
+```
+============ Serving Benchmark Result ============
+Successful requests:                     510       
+Benchmark duration (s):                  301.46    
+Total input tokens:                      7201515   
+Total generated tokens:                  185502    
+Request throughput (req/s):              1.69      
+Output token throughput (tok/s):         615.34    
+Total Token throughput (tok/s):          24504.02  
+---------------Time to First Token----------------
+Mean TTFT (ms):                          20931.33  
+Median TTFT (ms):                        19119.63  
+Std TTFT (ms):                           17324.45  
+P25 TTFT (ms):                           4057.98   
+P50 TTFT (ms):                           19119.63  
+P75 TTFT (ms):                           33284.55  
+P99 TTFT (ms):                           64592.68  
+-----Time per Output Token (excl. 1st token)------
+Mean TPOT (ms):                          187.71    
+Median TPOT (ms):                        200.69    
+Std TPOT (ms):                           63.08     
+P25 TPOT (ms):                           144.17    
+P50 TPOT (ms):                           200.69    
+P75 TPOT (ms):                           234.55    
+P99 TPOT (ms):                           312.87    
+---------------Inter-token Latency----------------
+Mean ITL (ms):                           181.20    
+Median ITL (ms):                         169.18    
+Std ITL (ms):                            133.70    
+P25 ITL (ms):                            86.63     
+P50 ITL (ms):                            169.18    
+P75 ITL (ms):                            230.91    
+P99 ITL (ms):                            647.04    
+----------------End-to-end Latency----------------
+Mean E2EL (ms):                          86656.79  
+Median E2EL (ms):                        89218.82  
+Std E2EL (ms):                           43454.94  
+P25 E2EL (ms):                           53935.13  
+P50 E2EL (ms):                           89218.82  
+P75 E2EL (ms):                           120761.34 
+P99 E2EL (ms):                           171262.27 
+==================================================
+```
+