본문으로 건너뛰기

[SGLang] flush_cache API에 timeout 파라미터 추가

PR 링크: sgl-project/sglang#21413 상태: Merged | 변경: +167 / -9

들어가며

SGLang의 /flush_cache API는 radix cache를 비우는 관리자 엔드포인트다. 그러나 HiCache 비동기 작업이 진행 중이면 스케줄러가 idle 상태가 아니라 flush가 즉시 실패(400)를 반환한다. 운영 환경에서 모델 가중치 업데이트 후 캐시를 비워야 할 때 이 문제가 자주 발생했다.

이 PR은 timeout 쿼리 파라미터를 추가하여 스케줄러가 idle이 될 때까지 지정된 시간만큼 대기한 후 flush를 수행하도록 한다.

핵심 코드 분석

API 엔드포인트 변경

Before:

@app.api_route("/flush_cache", methods=["GET", "POST"])
async def flush_cache():
    ret = await _global_state.tokenizer_manager.flush_cache()

After:

@app.api_route("/flush_cache", methods=["GET", "POST"])
async def flush_cache(timeout: float = Query(0.0, ge=0.0)):
    ret = await _global_state.tokenizer_manager.flush_cache(timeout_s=timeout)

스케줄러의 Deferred Flush 메커니즘

핵심은 스케줄러가 즉시 flush할 수 없을 때 pending 큐에 요청을 넣고, 매 입력 처리 사이클마다 idle 여부를 확인하는 것이다.

def flush_cache_wrapped(self, recv_req: FlushCacheReqInput):
    timeout_s = float(recv_req.timeout_s or 0.0)
    if timeout_s <= 0.0:
        return FlushCacheReqOutput(success=self.flush_cache())

    if self.is_fully_idle():
        return FlushCacheReqOutput(success=self.flush_cache())

    # idle이 아니면 deadline과 함께 큐에 추가
    self._pending_flush.append((recv_req, time.monotonic() + timeout_s))
    return None  # 응답 보류

Timeout 만료 처리

def _expire_timed_out_pending_flushes(self, now: float):
    remaining = deque()
    while self._pending_flush:
        pending_req, deadline = self._pending_flush.popleft()
        if now >= deadline:
            logging.warning("Deferred flush_cache timed out.")
            self.send_to_tokenizer.send_output(
                FlushCacheReqOutput(success=False), pending_req
            )
        else:
            remaining.append((pending_req, deadline))
    self._pending_flush = remaining

왜 이게 좋은가

  1. 하위 호환성: timeout=0(기본값)이면 기존과 동일한 fail-fast 동작을 유지한다.
  2. Non-blocking 설계: 별도 스레드나 sleep 없이, 스케줄러의 기존 이벤트 루프 사이클에 _check_pending_flush를 끼워넣어 자연스럽게 대기한다.
  3. 테스트 포함: 즉시 flush, idle 시 즉시 성공, busy 시 enqueue, timeout 만료 등 핵심 시나리오를 단위 테스트로 검증했다.

정리

간단한 timeout 파라미터 하나로 HiCache 환경에서의 운영 안정성이 크게 향상된다. 스케줄러 루프에 자연스럽게 통합된 deferred flush 패턴은 추가 스레드 없이도 비동기 대기를 구현하는 좋은 예시다.

참고 자료

이 글은 AI(Claude)의 도움을 받아 작성되었습니다. 코드 분석과 해석에서 오류가 있을 수 있으니, 정확한 내용은 원본 PR을 참고해주세요.

댓글

관련 포스트

PR Analysis 의 다른글