Per-Request Acceptance Metrics

Per-Request Acceptance Metrics (요청별 수락 지표)

추측 디코딩이 활성화되면 vLLM은 응답의 metrics.speculative_decoding 아래에 요청별 수락 지표를 보고할 수 있어요. 이를 통해 클라이언트는 개별 요청에 대한 평균 수락 길이(mean acceptance length)와 수락된 드래프트 길이 분포를 계산할 수 있고, /metrics에 노출되는 서버 집계 spec-decode 지표를 보완해요.

출처: 문서

본문

실험 기능: metrics.speculative_decoding은 실험 기능이며 향후 릴리스에서 형태가 바뀔 수 있어요. 이 값에 의존한다면 vLLM 버전을 고정(pin)하세요.

활성화

서버를 --per-request-spec-decode-metrics 값을 summary 또는 detailed로 지정해 시작하세요 (기본값은 none):

vllm serve <target-model> \
  --speculative-config '{"method": "ngram", "num_speculative_tokens": 3, "prompt_lookup_min": 1, "prompt_lookup_max": 3}' \
  --per-request-spec-decode-metrics summary

수집은 소스에서 게이트(gate)돼요. none이면 아무것도 누적되지 않아요.

응답 형식

수락 지표는 타이밍 요청별 지표와 최상위 metrics 객체를 공유해요. metrics.speculative_decoding은 타이밍 필드 옆에 위치해요. 타이밍과 마찬가지로 단일 생성 스트림을 설명하므로 단일 시퀀스 요청에만 보고되며 n > 1에서는 null이에요.

summary 응답의 metrics는 다음과 같아요:

{
  "choices": [...],
  "usage": {...},
  "metrics": {
    "speculative_decoding": {
      "mean_acceptance_length": 1.2325581395348837,
      "draft_acceptance_rate": 0.07751937984496124,
      "acceptance_histogram": [39, 1, 0, 3],
      "num_spec_steps": 43,
      "num_accepted_draft_tokens": 10,
      "num_draft_tokens": 129,
      "num_spec_tokens": 3
    }
  }
}

detailed에서는 검증 스텝 하나당 하나씩, 순서 있는 두 배열이 추가돼요:

metrics.speculative_decoding은 --per-request-spec-decode-metrics가 summary/detailed이고, 추측 디코딩이 활성화되어 있으며, n == 1일 때 존재해요 (요청이 아무것도 드래프트하지 않았다면 전부 0인 히스토그램). 그 외에는 null이에요.

스트리밍

스트리밍 응답에서 metrics(스펙큘레이티브 디코딩 포함)는 마지막 usage 청크에 실려 와요. usage 청크는 usage 보고가 활성화될 때만 방출되므로, stream_options.include_usage: true를 설정하거나 서버를 --enable-force-include-usage로 시작하세요.

Prometheus 지표와의 관계

요청별 필드는 /metrics의 서버 집계 spec-decode 카운터에 대응하는 개별 요청 버전이에요. 이를 보고하는 단일 시퀀스 요청에 대해 합하면 집계 카운터와 일치해요 (집계 카운터는 n > 1 요청도 세므로, 합계가 완전히 맞으려면 모든 요청이 n == 1이어야 해요):

더 알아보기 (Learn more)