vLLM v0.30.0 업그레이드: 엔드포인트와 모델 길이 점검
vLLM v0.29에서 v0.30.0으로 올릴 때 엔드포인트, 모델 길이, 제거된 설정과 기본값을 확인하는 방법을 정리한다.
2026-09-29
엔드포인트가 필요한 실행 명령부터 확인한다
vLLM v0.30.0에서 일반 vllm serve는 /render, /derender, /inference/v1/generate를 기본으로 등록하지 않는다. 이 엔드포인트를 사용하는 서비스라면 실행 명령에 --enable-scale-out이 있는지 확인해야 한다. 이전에 사용하던 VLLM_ENABLE_SCALE_OUT_ENDPOINTS 환경변수는 제거됐다. 반면 vllm launch render와 vllm serve --tokens-only는 해당 엔드포인트를 항상 등록한다.
실행 방식에 따라 등록 조건이 갈린다는 점을 먼저 확인하면, 컨테이너를 교체한 뒤 요청 경로가 사라지는 문제를 좁혀 볼 수 있다.
배포 설정에서는 이미지 태그뿐 아니라 실제 실행 명령을 함께 대조한다. 특히 제거된 환경변수만 남아 있다면 엔드포인트를 켜는 설정으로 간주해서는 안 된다. 등록 조건과 변경 범위는 vLLM v0.30.0 릴리스 노트의 Breaking Changes & Deprecations에 명시돼 있다.
YaRN을 쓰는 모델은 최대 길이를 다시 확인한다
이번 릴리스는 YaRN 처리를 Transformers에 맞췄다. vendor YaRN 별칭이 max_position_embeddings에 factor를 한 번 더 곱하지 않으므로, 일부 모델에서 산출되는 max_model_len이 줄어든다. attn_factor와 extrapolation_factor도 무시하고 mscale과 attention_factor를 사용한다.
릴리스 노트에 제시된 길이 변화는 다음과 같다. 업그레이드 대상 모델이 해당한다면 기존 설정값을 기준으로 판단하지 말고, 새 버전에서 산출되는 길이를 확인해야 한다.
| 모델 | 변경 전 max_model_len |
변경 후 max_model_len |
|---|---|---|
| TeleChat3-36B-Thinking | 131072 | 32768 |
| sarvam-105b | 5242880 | 131072 |
두 모델 모두 산출 길이가 줄지만 감소 폭은 다르다. 다음 비교 그림은 모델별 변경 전후 값을 같은 축에 놓아, 길이 제한에 의존하는 요청을 어디서 재검토할지 보여 준다.
제거된 설정과 동작을 배포 구성에서 찾는다
v0.29에서 제거가 예고된 항목 중 일부가 v0.30.0에서 실제로 제거됐다. 배포 환경변수, 모델 설정, 하드웨어별 실행 환경을 검색해 아래 항목이 남아 있는지 확인한다. 대체 설정의 구체적인 필드명은 릴리스 노트에 적힌 범위에서만 적용한다.
| 기존 항목 | v0.30.0의 동작 | 확인할 곳 |
|---|---|---|
VLLM_PREFIX_CACHE_RETENTION_INTERVAL |
제거됨. 설정 필드를 사용 | 배포 환경변수 |
VLLM_MM_HASHER_ALGORITHM |
제거됨. 설정 필드를 사용 | 배포 환경변수 |
use_fp4_indexer_cache |
별칭 제거. indexer_kv_dtype 사용 |
모델·양자화 설정 |
ROCm의 CUDA_VISIBLE_DEVICES 대체 사용 |
fallback 제거. HIP_VISIBLE_DEVICES 사용 |
ROCm 실행 환경 |
seq_lens_cpu, num_computed_tokens_cpu |
attention metadata 속성 제거 | 해당 속성을 참조하는 코드 |
GPTQ group/dynamic activation ordering도 별도로 점검해야 한다. g_idx는 무시되며 관련 Marlin, GPTQ, CPU, RDNA3 커널이 제거됐다. 해당 구성을 쓰는 모델이라면 업그레이드 후 결과를 확인할 대상으로 잡는다.
기존 실행 방식이 새 경로를 요구하는지 살핀다
python -m vllm.entrypoints.grpc_server는 deprecated 상태다. gRPC 서버를 실행하는 구성은 릴리스 노트가 제시한 vllm serve --grpc 경로로 옮길 대상을 찾는다. Mamba 캐시의 all 모드 역시 deprecated이며 Model Runner V1으로 fallback한다.
분산·KV 캐시 구성을 쓰는 배포에는 추가 조건이 있다. Attention 구현체는 DCP 지원을 명시적으로 선언해야 하며, ROCm standard attention, Triton, FlexAttention, TurboQuant에서 DCP를 사용하면 백엔드 선택 단계에서 실패한다. MoRI-IO connector의 WRITE 모드와 hybrid KV cache groups를 함께 쓴다면 --disable-hybrid-kv-cache-manager가 필요하다. 릴리스 노트가 제시한 다른 선택지는 READ 모드다. 이 기능을 쓰는 배포에 한해 조합을 확인하면 된다.
성능 차이가 나면 바뀐 기본값과 대조한다
v0.30.0에는 하드웨어와 기능 조합별 기본값 변경이 묶여 있다. 업그레이드 후 성능 차이를 조사할 때는 실행 환경이 어느 변경에 해당하는지 먼저 대조한다.
| 해당 환경 | 새 기본값 | 릴리스 노트에 명시된 제어 |
|---|---|---|
| SM100/103 | FlashInfer CuTeDSL NVFP4 W4A16이 Marlin보다 우선 | 별도 제어값 언급 없음 |
| SM120/121 | W4A4 NVFP4가 weight-only 커널보다 우선 | 별도 제어값 언급 없음 |
| SM100 | BF16x3 router GEMM 사용 | 별도 제어값 언급 없음 |
| DeepEP v2 | combine overlap 켜짐 | VLLM_DEEPEP_V2_COMBINE_OVERLAP=0으로 끔 |
| DP attention과 TP experts를 함께 쓰는 ROCm | AITER custom AG/RS 켜짐 | VLLM_ROCM_USE_AITER_CUSTOM_AR=0으로 끔 |
| SM100의 Kimi-K3 | native CUDA AttnRes 사용 | 별도 제어값 언급 없음 |
표의 환경 조건과 기본값을 연결해 보면, 전체 배포에 같은 변경을 적용했다고 가정하지 않고 성능 차이가 난 구성을 좁힐 수 있다. 다음 그림은 릴리스 노트가 명시한 두 가지 끄기 설정을 해당 기능에 연결한다.
게이트웨이 앞단의 요청 검증도 업그레이드 확인 대상이다
릴리스 노트의 Security 항목에는 요청 처리 경계의 수정이 포함돼 있다. validation error 응답 본문에 상한을 두어 약 5,300배의 응답 증폭을 막았고, 클라이언트가 보낸 sparse embedding은 dense 형태로 바꾸기 전에 크기를 제한한다. GLMGA와 Qwen-VL 백엔드에서는 요청으로 제어되는 비디오 샘플링에 상한을 뒀다.
cache_salt는 LMCache에 전달되기 전에 검증하고, scale-out의 멀티모달 기능은 엔진에 넘기기 전에 검증한다. 관련 요청을 받는 서비스라면 정상 요청뿐 아니라 검증 오류가 응답으로 처리되는지도 확인할 근거다. 업그레이드 점검은 컨테이너가 시작되는지에서 끝나지 않는다. 실행 명령이 필요한 엔드포인트를 등록하는지, 대상 모델의 산출 길이가 요청과 맞는지, 사용 중인 설정과 요청 경로가 새 동작에 맞는지까지 확인해야 한다.