SGLang 시뮬레이터

SGLang 시뮬레이터 (SGLang Simulator)

SGLang Simulator는 SGLang의 스케줄러, 요청 수명주기, KV-cache 구현을 재사용하되 모델 포워드 실행을 지연 예측기(latency predictor)로 대체한 도구입니다. 모델 가중치를 불러오지 않고도 타임스탬프 또는 합성 워크로드에서 스케줄링·캐시 설정을 비교할 수 있어요.

출처: 문서

본문

지원 범위 (Supported scope)

SGLang Simulator는 현재 main 브랜치와 최근 SGLang 릴리스를 추적합니다. 현재 통합은 v0.5.16, v0.5.17, v0.5.18, main으로 검증되었습니다.

초기 업스트림 범위는 tp_size=1, ep_size=1, dp_size=1, pp_size=1인 시뮬레이션 워커 하나를 사용합니다. 시뮬레이터 설정은 지연 예측을 위해 더 큰 대상 시스템을 기술할 수 있지만, SGLang 런타임 프로세스 토폴로지는 단일 워커로 유지됩니다.

시뮬레이터가 지원하는 것:

• 합성 요청 속도, ShareGPT 워크로드, 타임스탬프가 있는 Autobench 트레이스;
• OFFLINE 논리 시간 시뮬레이션과 BLOCKING 벽시계(wall-clock) 재생;
• AIConfigurator, ML, 재생 지연 예측기;
• SGLang 프리픽스 캐싱과 HiCache; 그리고
• 서빙 호환 TTFT, TPOT, ITL, 처리량, 캐시 적중 메트릭.

SGLang 저장소에서 설치 (Install from the SGLang repository)

시뮬레이터와 SGLang 소스를 동일한 모노레포 체크아웃에서 사용하세요:

python3 -m pip install -e tools/sglang-simulator
export PYTHONPATH="$PWD/tools/sglang-simulator/src:$PWD/python"

AIConfigurator는 선택 사항입니다. AIConfigurator 예측기를 사용할 때만 검증된 extra를 설치하세요:

python3 -m pip install -e "tools/sglang-simulator[aic]"

시뮬레이터 서버 시작 (Start a simulator server)

매 실행마다 새로운 출력 디렉토리를 선택하세요. 서버가 시뮬레이션 모드를 소유하고 메트릭을 이 디렉토리에 기록합니다.

export SGLANG_USE_CPU_ENGINE=1
export CUDA_VISIBLE_DEVICES=""
export SGLANG_SIMULATOR_OUTPUT_MODE=OFFLINE
export SGLANG_SIMULATOR_OUTPUT_DIR=/tmp/sglang-simulator-quickstart

python3 -m sglang_simulator.simulation.sglang.launch_server \
  --model-path tools/sglang-simulator/test/assets/qwen3-8b \
  --tokenizer-path tools/sglang-simulator/examples/assets/tokenizer \
  --sim-config-path tools/sglang-simulator/examples/sim_configs/replay.json \
  --port 30000

OFFLINE은 잠자지 않고 시뮬레이터의 논리 시계를 진행시킵니다. BLOCKING은 예측된 포워드·캐시 로드 지연 동안 실제로 sleep하기도 하며, 클라이언트가 시뮬레이션된 벽시계 페이싱을 관찰해야 할 때 유용합니다.

워크로드 보내기 (Send a workload)

다른 터미널에서 동일한 출력 디렉토리를 export하고, 저장소 루트에서 시뮬레이터 인식 서빙 벤치마크를 실행하세요:

export PYTHONPATH="$PWD/tools/sglang-simulator/src:$PWD/python"
export SGLANG_SIMULATOR_OUTPUT_DIR=/tmp/sglang-simulator-quickstart

python3 benchmark/simulator/bench_serving.py \
  --simulator-mode offline \
  --backend sglang \
  --base-url http://127.0.0.1:30000 \
  --model tools/sglang-simulator/test/assets/qwen3-8b \
  --tokenizer tools/sglang-simulator/examples/assets/tokenizer \
  --dataset-name sharegpt \
  --dataset-path tools/sglang-simulator/examples/workloads/sharegpt-example.json \
  --sharegpt-output-len 4 \
  --num-prompts 3 \
  --output-file /tmp/sglang-simulator-quickstart/benchmark.json

벤치마크는 각 요청에 논리 도착 메타데이터를 주입하고 서버 측 시뮬레이터 메트릭을 표시합니다. 타임스탬프 트래픽의 경우 시뮬레이터가 소유한 Autobench JSONL 포맷을 사용하고 --use-trace-timestamps를 추가하세요.

결과 읽기 (Read the results)

출력 디렉토리에는 다음이 포함됩니다:

• metrics.json: 지연, 처리량, 캐시 메트릭의 집계;
• request.jsonl: 요청별 타이밍과 캐시 정보; 그리고
• iteration.jsonl: 스케줄러 배치 구성과 예측된 반복 지연.

각 실행마다 고유한 출력 디렉토리를 사용해 서로 다른 실험의 메트릭이 섞이지 않게 하세요. 시뮬레이터 설정 필드, 예측기 예시, 유지되는 테스트는 SGLang Simulator source README를 참고하세요.

더 알아보기 (Learn more)

• SGLang Simulator 소스 README