파라미터 스윕

파라미터 스윕 (Parameter Sweeps)

vllm bench sweep는 여러 구성에서 벤치마크를 실행하고 결과를 시각화해 비교하는 명령 모음이에요. 하나의 설정만 바꿔가며 최적값을 찾아야 할 때 아주 편리하죠.

온라인 벤치마크 (Online Benchmark)

기본 (Basic)

vllm bench sweep serve는 vllm serve를 시작하고, 각 서버 구성에 대해 vllm bench serve를 반복적으로 실행해요.

!!! tip 단일 서버 구성에 대한 벤치마크만 실행하면 된다면 GuideLLM을 고려해 보세요. 라이브 진행 표시와 자동 리포트 생성을 갖춘 검증된 성능 벤치마킹 프레임워크예요. 데이터셋 로딩, 요청 포맷, 워크로드 패턴 면에서도 vllm bench serve보다 더 유연해요.

스크립트를 실행하려면 다음 단계를 따라요:

  1. vllm serve의 기본 명령을 구성하고, --serve-cmd 옵션에 넘겨요.

  2. vllm bench serve의 기본 명령을 구성하고, --bench-cmd 옵션에 넘겨요.

  3. (선택) vllm serve의 설정을 바꿔가며 테스트하고 싶다면 새 JSON 파일을 만들고 시험할 파라미터 조합을 채운 뒤 파일 경로를 --serve-params에 넘겨요.

    • 예시: --max-num-seqs와 --max-num-batched-tokens 튜닝:
    [
    {
        "max_num_seqs": 32,
        "max_num_batched_tokens": 1024
    },
    {
        "max_num_seqs": 64,
        "max_num_batched_tokens": 1024
    },
    {
        "max_num_seqs": 64,
        "max_num_batched_tokens": 2048
    },
    {
        "max_num_seqs": 128,
        "max_num_batched_tokens": 2048
    },
    {
        "max_num_seqs": 128,
        "max_num_batched_tokens": 4096
    },
    {
        "max_num_seqs": 256,
        "max_num_batched_tokens": 4096
    }
]

  4. (선택) vllm bench serve의 설정을 바꿔가며 테스트하고 싶다면 새 JSON 파일을 만들고 시험할 파라미터 조합을 채운 뒤 파일 경로를 --bench-params에 넘겨요.

    • 예시: 랜덤 데이터셋에서 다른 입력/출력 길이 사용:
    [
    {
        "_benchmark_name": "scenario_A",
        "random_input_len": 128,
        "random_output_len": 32
    },
    {
        "_benchmark_name": "scenario_B",
        "random_input_len": 256,
        "random_output_len": 64
    },
    {
        "_benchmark_name": "scenario_C",
        "random_input_len": 512,
        "random_output_len": 128
    }
]

  5. --output-dir을 설정하고, 선택적으로 --experiment-name으로 결과를 저장할 위치를 정해요.

예시 명령:

vllm bench sweep serve \
    --serve-cmd 'vllm serve meta-llama/Llama-2-7b-chat-hf' \
    --bench-cmd 'vllm bench serve --model meta-llama/Llama-2-7b-chat-hf --backend vllm --endpoint /v1/completions --dataset-name sharegpt --dataset-path benchmarks/ShareGPT_V3_unfiltered_cleaned_split.json' \
    --serve-params benchmarks/serve_hparams.json \
    --bench-params benchmarks/bench_hparams.json \
    --output-dir benchmarks/results \
    --experiment-name demo

기본적으로 각 파라미터 조합은 결과를 더 신뢰할 수 있게 3번씩 벤치마킹돼요. 실행 횟수는 --num-runs로 조정할 수 있어요.

!!! important --serve-params와 --bench-params를 둘 다 넘기면 스크립트는 그 둘 사이의 곱집합(Cartesian product)을 반복해요. 실행할 명령을 미리 보려면 --dry-run을 쓸 수 있어요.

`--serve-params`마다 서버를 한 번만 시작하고, 여러 `--bench-params`에 대해 그 서버를 계속 실행해요.
각 벤치마크 실행 사이에 모든 `/reset_*_cache` 엔드포인트를 호출해 다음 실행을 위해 깨끗한 상태로 만들어요.
커스텀 `--serve-cmd`를 쓴다면 `--after-bench-cmd`로 상태 리셋에 사용할 명령을 덮어쓸 수 있어요.

!!! note 변수가 많은 파라미터 조합에는 사람이 읽기 좋은 이름을 제공하기 위해 _benchmark_name을 설정해야 해요. 파일 이름이 파일시스템의 최대 경로 길이를 초과할 경우 이는 필수가 돼요.

!!! tip 예상치 못한 오류(예: HF Hub 연결 타임아웃)가 생겨도 --resume 옵션으로 파라미터 스윕을 이어갈 수 있어요.

워크로드 탐색기 (Workload Explorer)

vllm bench sweep serve_workload는 vllm bench sweep serve의 변형으로, 지연과 처리량 사이의 트레이드오프를 찾기 위해 다양한 워크로드 수준을 탐색해요. 결과는 시각화해서 달성 가능한 SLA를 판단할 수도 있어요.

워크로드는 요청률 또는 동시성으로 표현할 수 있어요(--workload-var로 선택).

예시 명령:

vllm bench sweep serve_workload \
    --serve-cmd 'vllm serve meta-llama/Llama-2-7b-chat-hf' \
    --bench-cmd 'vllm bench serve --model meta-llama/Llama-2-7b-chat-hf --backend vllm --endpoint /v1/completions --dataset-name sharegpt --dataset-path benchmarks/ShareGPT_V3_unfiltered_cleaned_split.json --num-prompts 100' \
    --workload-var max_concurrency \
    --serve-params benchmarks/serve_hparams.json \
    --bench-params benchmarks/bench_hparams.json \
    --num-runs 1 \
    --output-dir benchmarks/results \
    --experiment-name demo

다양한 워크로드 수준을 탐색하는 알고리즘은 다음과 같이 요약할 수 있어요:

  1. 요청을 한 번에 하나씩 보내 벤치마크를 실행해요(직렬 추론, 최저 워크로드). 이는 가능한 최저 지연과 처리량을 만들어요.
  2. 요청을 한 번에 모두 보내 벤치마크를 실행해요(배치 추론, 최고 워크로드). 이는 가능한 최고 지연과 처리량을 만들어요.
  3. 2단계에 해당하는 workload_var 값을 추정해요.
  4. 나머지 반복으로 workload_var의 중간 값들에 대해 균일하게 벤치마크를 실행해요.

--workload-iters로 알고리즘의 반복 수를 덮어쓸 수 있어요.

!!! tip 이는 GuideLLM의 --profile sweep에 해당하는 vLLM의 기능이에요.

일반적으로 `--workload-var max_concurrency`가 더 신뢰할 수 있는 결과를 만들어요. vLLM 엔진에 가해지는 워크로드를 직접 제어하기 때문이죠.
하지만 GuideLLM과 비슷한 동작을 유지하기 위해 기본값은 `--workload-var request_rate`로 해 두었어요.

스타트업 벤치마크 (Startup Benchmark)

vllm bench sweep startup은 파라미터 조합에 걸쳐 vllm bench startup을 실행해 다른 엔진 설정의 콜드/워밍 시작 시간을 비교해요.

스크립트를 실행하려면 다음 단계를 따라요:

  1. (선택) vllm bench startup의 기본 명령을 구성하고 --startup-cmd(기본값: vllm bench startup)에 넘겨요.
  2. (선택) vllm bench sweep serve의 --serve-params JSON을 재사용해 엔진 설정을 바꿔요. vllm bench startup이 지원하는 파라미터만 적용돼요.
  3. (선택) 반복 수 같은 시작 전용 옵션을 바꾸려면 --startup-params JSON을 만들어요.
  4. 결과를 저장할 위치를 정해 --output-dir에 넘겨요.

예시 --serve-params:

[
    {
        "_benchmark_name": "tp1",
        "model": "Qwen/Qwen3-0.6B",
        "tensor_parallel_size": 1,
        "gpu_memory_utilization": 0.9
    },
    {
        "_benchmark_name": "tp2",
        "model": "Qwen/Qwen3-0.6B",
        "tensor_parallel_size": 2,
        "gpu_memory_utilization": 0.9
    }
]

예시 --startup-params:

[
    {
        "_benchmark_name": "qwen3-0.6",
        "num_iters_cold": 2,
        "num_iters_warmup": 1,
        "num_iters_warm": 2
    }
]

예시 명령:

vllm bench sweep startup \
    --startup-cmd 'vllm bench startup --model Qwen/Qwen3-0.6B' \
    --serve-params benchmarks/serve_hparams.json \
    --startup-params benchmarks/startup_hparams.json \
    --output-dir benchmarks/results \
    --experiment-name demo

!!! important 기본적으로 --serve-params나 --startup-params의 미지원 파라미터는 경고와 함께 무시돼요. 알 수 없는 키에 대해 빠르게 실패하려면 --strict-params를 쓰세요.

시각화 (Visualization)

기본 (Basic)

vllm bench sweep plot은 파라미터 스윕 결과로 성능 곡선을 그릴 수 있어요.

그릴 변수는 --var-x와 --var-y로 제어하고, 선택적으로 값에 --filter-by와 --bin-by를 적용해요. 그림은 --fig-by, --row-by, --col-by, --curve-by에 따라 구성돼요.

워크로드 탐색기 결과를 시각화하는 예시 명령:

EXPERIMENT_DIR=${1:-"benchmarks/results/demo"}

# Latency increases as the workload increases
vllm bench sweep plot $EXPERIMENT_DIR \
    --var-x max_concurrency \
    --var-y median_ttft_ms \
    --col-by _benchmark_name \
    --curve-by max_num_seqs,max_num_batched_tokens \
    --fig-name latency_curve

# Throughput saturates as workload increases
vllm bench sweep plot $EXPERIMENT_DIR \
    --var-x max_concurrency \
    --var-y total_token_throughput \
    --col-by _benchmark_name \
    --curve-by max_num_seqs,max_num_batched_tokens \
    --fig-name throughput_curve

# Tradeoff between latency and throughput
vllm bench sweep plot $EXPERIMENT_DIR \
    --var-x total_token_throughput \
    --var-y median_ttft_ms \
    --col-by _benchmark_name \
    --curve-by max_num_seqs,max_num_batched_tokens \
    --fig-name latency_throughput

!!! tip 그릴 그림을 미리 보려면 --dry-run을 쓸 수 있어요.

파레토 차트 (Pareto chart)

vllm bench sweep plot_pareto는 사용자별·GPU별 처리량을 균형 있게 맞추는 구성을 고르는 데 도움을 줘요.

높은 동시성·배치 크기는 GPU 효율(per-GPU)을 높일 수 있지만 사용자당 지연을 늘릴 수 있고, 낮은 동시성은 사용자당 속도를 높이지만 GPU를 덜 사용해요. 파레토 프론티어는 실행들에서 달성 가능한 최선의 쌍을 보여줘요.

  • x축: tokens/s/user = output_throughput ÷ concurrency(--user-count-var, 기본 max_concurrency, 폴백 max_concurrent_requests).
  • y축: tokens/s/GPU = output_throughput ÷ GPU 수(--gpu-count-var가 설정되면 그것을, 아니면 gpu_count = TP×PP×DP).
  • 출력: OUTPUT_DIR/pareto/PARETO.png에 단일 그림.
  • 각 데이터 포인트에 사용된 구성을 표시 --label-by(기본값: max_concurrency,gpu_count).

예시:

EXPERIMENT_DIR=${1:-"benchmarks/results/demo"}

vllm bench sweep plot_pareto $EXPERIMENT_DIR \
  --label-by max_concurrency,tensor_parallel_size,pipeline_parallel_size

!!! tip 그릴 그림을 미리 보려면 --dry-run을 쓸 수 있어요.

출처: 공식문서

더 알아보기 (Learn more)