fix(agentic): label KV series by DP rank (#548)

Prefer dp_rank over rank-local engine identifiers and cover both repeated-engine and normal multi-DP exports.

中文：修正 agentic KV 序列的 DP rank 标签。优先使用 dp_rank，并覆盖 engine 标签重复及常规多 DP 导出场景。

Author: cquil11

packages/db/src/etl/compute-chart-series.test.ts

@@ -253,6 +253,12 @@ describe('computeChartSeries', () => {
       { t: 0, value: 0.25 },
       { t: 1, value: 0.5 },
     ]);
+    expect(cs!.kvCacheUsageByEngine.map(({ engineLabel }) => engineLabel)).toEqual([
+      '0',
+      '1',
+      '2',
+      '3',
+    ]);
     // prefillTps = Σ rates = 4 × 100 = 400; then 4 × 200 = 800
     expect(cs!.prefillTps).toEqual([
       { t: 0, value: 400 },
@@ -264,6 +270,29 @@ describe('computeChartSeries', () => {
     ]);
   });
 
+  it('uses dp_rank when engine labels repeat across DEP ranks', async () => {
+    const engines = [0, 1, 2, 3].map((dpRank) => ({
+      labels: { engine: '0', dp_rank: String(dpRank) },
+      timeslices: [{ start_ns: 0, end_ns: 1e9, avg: 0.1 + dpRank * 0.1 }],
+    }));
+    const blob = gzipSync(
+      Buffer.from(
+        JSON.stringify({
+          metrics: { 'vllm:kv_cache_usage_perc': { series: engines } },
+        }),
+      ),
+    );
+
+    const series = await computeChartSeries(blob);
+
+    expect(series?.kvCacheUsageByEngine.map(({ engineLabel }) => engineLabel)).toEqual([
+      '0',
+      '1',
+      '2',
+      '3',
+    ]);
+  });
+
   it('uses the Dynamo adapter to preserve workers and canonical prefill/decode roles', async () => {
     const json = JSON.stringify({
       metrics: {

packages/db/src/etl/compute-chart-series.ts

@@ -67,8 +67,12 @@ import {
  * warmup block are unaffected. (v11 was a short-lived, since-reverted attempt to
  * carry kvCachePoolTokens in chart_series; that value now lives in
  * benchmark_results.metrics, derived from the server log — unrelated to this.)
+ *
+ * v13: prefer `dp_rank` over the per-rank-local `engine` label when naming
+ * KV-cache series. Some DEP exports report engine=0 for every rank, which
+ * made every legend entry read "DP 0" despite distinct dp_rank labels.
  */
-export const CHART_SERIES_VERSION = 12;
+export const CHART_SERIES_VERSION = 13;
 
 export interface TimeSeriesPoint {
   /** Seconds from benchmark start. */
@@ -348,11 +352,11 @@ function buildSeriesFromMetrics(
   // the cluster-average line.
   const kvCacheUsageByEngine: { engineLabel: string; points: TimeSeriesPoint[] }[] = [];
   if (kvSeries && kvSeries.length > 1) {
-    // Sort by numeric engine label when present so rank 0..N renders in
-    // order; fall back to series-array index otherwise.
+    // Sort by numeric DP rank when present so rank 0..N renders in order;
+    // fall back to the engine label, then series-array index otherwise.
     const decorated = kvSeries.map((s, idx) => {
       const raw =
-        s.labels?.['engine'] ?? s.labels?.['engine_idx'] ?? s.labels?.['dp_rank'] ?? String(idx);
+        s.labels?.['dp_rank'] ?? s.labels?.['engine'] ?? s.labels?.['engine_idx'] ?? String(idx);
       const numeric = Number(raw);
       return { series: s, idx, label: raw, sortKey: Number.isFinite(numeric) ? numeric : idx };
     });