트레이스 재생

트레이스 재생 (Trace Replay)

트레이스 재생(trace replay)은 디코딩 중에 엔진이 미리 정해진 토큰 시퀀스를 강제로 방출하도록 하면서, 모델의 수정되지 않은 logit 분포에서 실제 logprob을 계산하는 기능이에요. 서로 다른 설정에서 logprob 분포를 비교할 때 주로 활용돼요. 이 페이지에서 사용법을 알아볼게요.

출처: vLLM 공식 문서 — serving/online_serving/trace_replay

트레이스 재생은 디코딩 중 엔진이 미리 정해진 토큰 시퀀스를 방출하도록 강제하면서, 모델의 수정되지 않은 logit 분포에서 실제 logprob을 계산해요. 주요 사용 사례는 구성(configuration)에 따른 logprob 분포 비교예요.

추론 설정 비교 (Inference config diff): 같은 모델의 양자화 방식, tensor parallel 레이아웃, 어텐션 백엔드 간 logprob을 비교.
학습 vs 추론 비교 (Train vs inference diff): 학습 시점의 토큰 시퀀스를 추론 엔진을 통해 재생해서, 학습·서빙 프레임워크의 수치적 차이로 인한 logprob 발산을 감지.

요구사항 (Requirements)

트레이스 재생은 요청별 트레이스 버퍼를 예약하므로 기본적으로 꺼져 있어요. --enable-trace-replay(또는 LLM(..., enable_trace_replay=True))로 활성화해요. model runner V2에서만 지원되며, 두 조건 중 하나라도 충족되지 않으면 요청이 거부돼요.

사용법 (Usage)

from vllm import LLM, SamplingParams

llm = LLM(model="Qwen/Qwen3-0.6B", enable_trace_replay=True)

# Token sequence captured from a previous run or training log
trace_tokens = [15, 284, 1026, 374]

params = SamplingParams(
    trace_decode_token_ids=trace_tokens,
    logprobs=5,
)
outputs = llm.generate(["Once upon a time"], sampling_params=params)

for token, logprob in zip(
    outputs[0].outputs[0].token_ids,
    outputs[0].outputs[0].logprobs,
):
    print(f"token={token}  logprob={logprob[token].logprob:.4f}")

출력 토큰은 항상 [15, 284, 1026, 374]이에요. logprob은 현재 추론 구성에서 각 강제 토큰에 대한 모델의 실제 확률을 반영해요.

구성을 비교하려면 같은 트레이스를 두 엔진 설정에 대해 실행하고 per-token logprob의 차이를 확인하면 돼요.

동작 (Behavior)

trace_decode_token_ids가 설정되면:

max_tokens가 자동으로 트레이스 길이로 설정돼요.
트레이스가 프롬프트 길이를 감안한 max_model_len에 맞지 않으면 잘려요(truncate).
모든 중지 조건(EOS, stop strings, stop token IDs)이 비활성화돼요.
생성은 정확히 트레이스 토큰을 만든 뒤 멈춰요.

제한사항 (Limitations)

trace_decode_token_ids는 다음 기능과 호환되지 않아요 (ValueError 발생):

기능	이유
`n > 1`	트레이스 재생은 단일 결정적 시퀀스를 생성.
`prompt_logprobs`	확장된 logit 레이아웃이 트레이스 커널 인덱싱과 충돌.
Speculative decoding	멀티토큰 추측이 싱글토큰 트레이스 스텝과 충돌.
Structured outputs	문법 제약이 강제 토큰 주입과 충돌.
`repetition_detection`	트레이스의 반복 패턴에서 요청을 종료하게 됨.
`thinking_token_budget`	Logit 마스킹이 트레이스 토큰의 logprob을 손상.
`bad_words`	Logit 마스킹이 트레이스 토큰의 logprob을 손상.

트레이스 재생