멀티모달 인코더와 torch.compile

멀티모달 인코더와 torch.compile (torch.compile with Multimodal Encoders)

vLLM은 이제 멀티모달 인코더와 기타 nn 모듈(LLaMA 4, Qwen-VL 같은 비전-언어 모델과 그와 유사한 인코더 기반 아키텍처)에 torch.compile을 적용할 수 있습니다. 이 문서는 vLLM에서 멀티모달 인코더용 torch.compile 통합이 어떻게 동작하는지와, 성능 개선을 위해 새 모델에 데코레이터를 적용하는 방법을 다룹니다.

출처: 문서

본문

torch.compile을 이제 vLLM의 멀티모달 인코더와 기타 nn 모듈(LLaMA 4, Qwen-VL 같은 비전-언어 모델 및 유사한 인코더 기반 아키텍처)에 적용할 수 있습니다. 이 문서는 vLLM에서 멀티모달 인코더용 torch.compile 통합의 기본 원리와, 성능 향상을 위해 새 모델에 데코레이터를 적용하는 방법을 다룹니다.

Note: vLLM에서 torch.compile 통합에 대한 일반 정보는 torch.compile 설계 문서를 참고하세요.

개요 (Overview)

최근 @support_torch_compile 데코레이터가 모델 타입 내의 여러 nn 모듈 컴포넌트에 동작하도록 활성화했습니다. 이로써 멀티모달 인코더에서도 compile을 켤 수 있게 되어 스택의 추가 컴포넌트에 성능 개선을 가져옵니다.

Qwen2_5_vl의 비전 블록에 적용하면 컴파일 시간은 다소 늘어나지만 종단 간(e2e) 약 4.5%의 성능 개선을 관찰했습니다.

이 기능은 기본적으로 꺼져 있으며, @support_torch_compile 데코레이터가 있는 모델에 대해 컴파일 설정에서 compile_mm_encoder: true를 지정하면 활성화할 수 있습니다.

멀티모달 컴포넌트의 컴파일 방식 (How Compilation Works for Multimodal Components)

활성화 API (APIs for Enablement)

인코더 같은 멀티모달 컴포넌트를 컴파일하려면 LLM 텍스트 백본과 같은 메커니즘을 따르되, 몇 가지 추가 스캐폴딩이 필요합니다.

  • @support_torch_compile 데코레이터에 enable_if=should_torch_compile_mm_encoder를 포함해야 합니다. 이렇게 하면 컴파일이 compile_mm_encoder 설정 뒤로 게이트됩니다.
  • 인코더 컴포넌트에는 @support_torch_compile 데코레이터에 is_encoder=True를 포함해야 합니다. 이는 컴파일 범위 통합(Compile Range Integration)에 필요합니다. 데코레이터는 클래스 이름을 캐시 디렉토리 프리픽스로 자동 사용해, 독립적으로 컴파일되는 서브모듈(비전 인코더 컴포넌트와 텍스트 백본 등) 사이의 충돌을 피합니다.

CompilationConfig

compile_mm_encoder: true를 제외하면 멀티모달 인코더는 텍스트 LLM과 동일한 컴파일 설정을 상속합니다. 향후 더 많은 설정으로 확장할 수 있습니다.

새 멀티모달 모델/컴포넌트에 torch.compile 적용하기 (Applying torch.compile to a New Multimodal Model/Component)

새로운 일반 nn.Module에 support_torch_compile을 적용하려면 debug_vllm_compile의 절차를 따르는 것을 권장합니다. 여기에는 다음이 포함됩니다.

  • 처음에는 작은 모듈(기본 MLP 레이어 등)에 support_torch_compile을 적용하고, 좋은 성능 트레이드오프에 도달할 때까지 더 일반적인 모듈로 단계적으로 올리기
  • tlparse를 활용해 재컴파일(recompile)과 그래프 브레이크(graph break)의 원인을 식별하고 제거하기
  • dynamic_arg_dims와 적절한 dynamic_shapes_config로 다이내미즘(dynamism) 처리하기

VllmBackend 기능 지원 (VllmBackend Feature Support)

컴파일 범위 (Compile ranges)

torch.compile 통합은 동적 형상의 컴파일 범위를 추론하기 위해 max_batch_size에 의존하려 합니다. 하지만 인코더에 사용되는 모듈의 경우, 인코더가 입력으로 받을 수 있는 형상의 범위가 명시되지 않아 이 형상 추론이 어려울 수 있습니다. 그래서 @support_torch_compile 데코레이터의 is_encoder=True에 의존해 torch.compile에 이 범위를 추론할 수 없음을 알리고, 기본적으로 (1, MAX_INT) 범위로 설정합니다.

Note: 성능을 위해 향후 이 범위를 더 좁힐 수도 있습니다.

Cudagraphs

아직 멀티모달 인코더를 CUDAGraph 통합으로 컴파일하는 것은 탐구되지 않았으며, 동작은 현재 명시되지 않습니다.

문제 해결 (Troubleshooting)

비전 인코더의 그래프 브레이크 (Graph Breaks in Vision Encoders)

일부 비전 인코더 연산은 그래프 브레이크를 일으킬 수 있습니다. 이를 식별하려면:

TORCH_LOGS="+dynamo" vllm serve <MODEL>

멀티모달 모델에서 그래프 브레이크의 일반적인 원인:

  • 동적 이미지 크기: 가변 해상도를 처리하려면 dynamic_shapes_config 사용
  • 추적 불가능한 연산: 일부 연산(예: to_list)은 Dynamo가 지원하지 않을 수 있음
  • 조건부 처리: 이미지 속성에 따른 데이터 의존적 분기

컴파일 오류 (Compilation Errors)

멀티모달 모델에서 컴파일이 실패하면:

  • 비활성화하고 테스트: 먼저 컴파일 없이 모델이 동작하는지 확인합니다.
vllm serve <model> --compilation-config='{"mode":0,"compile_mm_encoder":"false"}'
  • 로그 확인: 디버그 로깅을 켜서 컴파일 세부사항을 봅니다.
VLLM_LOGGING_LEVEL=DEBUG vllm serve <model> --compilation-config='{"compile_mm_encoder":"true"}'
  • 이슈 보고: 버그를 발견하면 GitHub에 이슈를 등록합니다.

함께 보기 (See Also)

  • torch.compile 통합 — 핵심 설계 문서
  • torch.compile 디버깅 — 상세 디버깅 가이드
  • 멀티모달 입력 — 멀티모달 데이터 전달 방법
  • Disaggregated Encoder — 비전 인코더 스케일링
  • 지원되는 멀티모달 모델 — 모델 호환성

더 알아보기 (Learn more)