요청별 수용 지표

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

스펙큘레이티브 디코딩을 켰다면, 이제 그 게 실제로 얼마나 효과가 있는지 알고 싶어지죠. vLLM은 서버 전체 집계 지표뿐 아니라 요청별 수용 지표(per-request acceptance metrics) 를 응답에 담아 줄 수 있어요. 이 지표로 개별 요청의 평균 수용 길이와 수용된 드래프트 길이 분포를 계산할 수 있습니다. 이 페이지에서 그 설정과 응답 형식을 살펴볼게요.

출처: vLLM 공식 문서 — Per-Request Acceptance Metrics

개요와 주의 (Overview)

metrics.speculative_decoding은 /metrics에서 노출되는 서버 집계 spec-decode 지표를 보완하는, 개별 요청 기준의 지표예요. 다만 실험적(experimental) 이라 향후 릴리스에서 형태가 바뀔 수 있어요. 이 기능에 의존한다면 vLLM 버전을 고정해 두는 걸 권장해요.

활성화 (Enabling)

--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

수집은 소스에서 게이팅돼서, none이면 아무것도 누적되지 않아요.

응답 형식 (Response format)

수용 지표는 타이밍 요청별 지표와 함께 최상위 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일 때 존재해요(요청이 아무것도 드래프트하지 않았다면 all-zero 히스토그램). 그 외에는 null이에요.

스트리밍 (Streaming)

스트리밍 응답에서 metrics(그리고 speculative_decoding)는 마지막 usage 청크에 실려 와요. 이 청크는 usage 보고가 켜져 있을 때만 방출되므로, stream_options.include_usage: true를 설정하거나 --enable-force-include-usage로 서버를 시작해야 해요.

Prometheus 지표와의 관계 (Relationship to Prometheus metrics)

요청별 필드는 /metrics의 서버 집계 spec-decode 카운터의 개별 요청 대응물이에요. 이걸 보고한 단일 시퀀스 요청에 걸쳐 합치면 집계 카운터와 조화돼요(n > 1 요청도 세는 집계 카운터들 때문에 총계는 모든 n == 1 워크로드에서만 일치해요).

더 알아보기 (Learn more)

• 스펙큘레이티브 디코딩
• 요청별 지표 (Per-Request Metrics)
• 적응형 검증 (Adaptive Verification)