문제 해결과 자주 묻는 질문

문제 해결과 자주 묻는 질문

SGLang 서버를 실제로 돌리다 보면 CUDA OOM부터 서버가 멈추는 일까지 다양한 문제를 마주치게 돼요. 그럴 때마다 "이게 왜 이러지?" 하면서 문서를 뒤지게 되는데, 이 페이지는 흔히 겪는 오류들과 해결 팁을 한곳에 모아둔 거예요. 문제 상황에서 바로 꺼내 볼 수 있도록 강사 목소리로 정리해 드릴게요. 기술 값과 명령어는 원문 그대로 보존했어요.

출처: 공식문서 - Troubleshooting and Frequently Asked Questions

문제 해결 (Troubleshooting)

CUDA Out of Memory

OOM(out-of-memory) 에러를 만나면 다음 파라미터를 조정해 볼 수 있어요.

  • prefill 중에 OOM이 나면 --chunked-prefill-size를 4096이나 2048로 줄여보세요. 메모리는 아끼지만 긴 프롬프트의 prefill 속도가 느려져요.
  • decoding 중에 OOM이 나면 --max-running-requests를 낮춰보세요.
  • --mem-fraction-static을 0.8이나 0.7 같은 더 작은 값으로 줄일 수도 있어요. KV 캐시 메모리 풀의 메모리 사용량이 줄어 prefill과 decoding 양쪽에서 OOM을 막아주지만, 최대 동시성이 제한되고 최고 처리량도 줄어들어요.
  • OOM의 또 다른 흔한 원인은 긴 프롬프트에 대해 입력 logprobs를 요청하는 경우예요. 상당한 메모리가 필요하기 때문이죠. 이 경우 샘플링 파라미터의 logprob_start_len을 필요한 부분만 포함하도록 설정해 주세요. 정말 긴 프롬프트에 입력 logprobs가 필요하다면 --mem-fraction-static을 줄여보는 것도 방법이에요.

CUDA Error: Illegal Memory Access Encountered

이 에러는 커널 오류 또는 메모리 부족 문제에서 비롯될 수 있어요.

  • 커널 오류라면 해결하기 어려울 수 있어요. GitHub에 이슈(issue)를 올려주세요.
  • 메모리 부족 문제라면 "Out of Memory." 대신 이 오류로 나타나기도 해요. 위 섹션의 OOM 회피 가이드를 참고하세요.

서버가 멈추는 경우 (The server hangs)

  • 서버가 초기화 중이거나 실행 중에 멈춘다면, 메모리 문제(메모리 부족), 네트워크 문제(nccl 에러), 또는 sglang의 다른 버그일 수 있어요.
    • 메모리 부족이라면 초기화 중이나 초기화 직후에 avail mem이 매우 낮게 보일 거예요. 이 경우 --mem-fraction-static을 줄이거나, --cuda-graph-max-bs-decode를 줄이거나, --chunked-prefill-size를 줄여보세요.
  • 다른 버그라면 GitHub에 이슈를 올려주세요.

자주 묻는 질문 (Frequently Asked Questions)

temperature를 0으로 해도 결과가 결정적이지 않은 경우

같은 요청을 두 번 보냈을 때 temperature가 0으로 설정돼 있어도 엔진의 결과가 조금씩 달라지는 걸 눈치챘을 거예요.

초기 조사에 따르면 이 비결정성은 주로 동적 배칭(dynamic batching) 과 프리픽스 캐싱(prefix caching) 이라는 두 요소에서 비롯돼요. 대략적으로 말하면 동적 배칭이 비결정성의 약 95%를 차지하고, 프리픽스 캐싱이 나머지를 차지해요. 서버는 내부적으로 동적 배칭을 돌리고 있는데, 배치 크기가 달라지면 PyTorch/CuBLAS가 서로 다른 CUDA 커널로 dispatch될 수 있고, 이로 인해 약간의 수치 차이가 생겨요. 이 차이가 많은 레이어를 거치며 누적되다 보면 배치 크기가 바뀔 때 최종 출력이 비결정적으로 나오는 거예요. 마찬가지로 프리픽스 캐싱이 켜져 있을 때도 서로 다른 커널로 dispatch될 수 있는데, 비록 계산적으로는 동일하더라도 커널 구현마다 생기는 작은 수치 차이가 최종 비결정적 출력으로 이어지는 거예요.

현재 코드에서 좀 더 결정적인 출력을 얻으려면 --disable-radix-cache를 추가하고 한 번에 하나의 요청만 보내보세요. 이 설정에서는 결과가 대부분 결정적으로 나와요.

업데이트:

최근에는 결정적 모드를 도입했어요. --enable-deterministic-inference로 켤 수 있어요. 자세한 내용은 이 블로그 포스트를 참고해 주세요: https://lmsys.org/blog/2025-09-22-sglang-deterministic/

더 알아보기 (Learn more)