멀티모달 언어 모델

멀티모달 언어 모델 (Vision·Audio 지원)

SGLang은 이미지나 오디오 같은 여러 종류의 입력을 함께 받아 텍스트를 내보내는 멀티모달 모델을 폭넓게 지원해요. 이 모델들은 언어 모델에 이미지·오디오 인코더를 덧붙여서, 텍스트만으로는 처리할 수 없는 정보까지 받아들일 수 있게 해 줘요.

출처: 공식문서

서버 띄우는 명령

멀티모달 모델도 일반 LLM처럼 launch_server로 띄우면 돼요. 모델 경로만 자신이 쓰는 VLM으로 바꿔 주면 되죠.

python3 -m sglang.launch_server \
  --model-path meta-llama/Llama-3.2-11B-Vision-Instruct \  # example HF/local path
  --host 0.0.0.0 \
  --port 30000 \

사용법은 OpenAI APIs 비전 문서에서 요청을 어떤 식으로 보내는지 확인할 수 있어요.

지원 모델

어떤 모델이 지원되는지는 아래 표에 정리돼 있어요. 만약 특정 아키텍처가 구현돼 있는지 잘 모르겠다면 GitHub에서 직접 검색해 볼 수 있는데, 예를 들어 Qwen2_5_VLForConditionalGeneration을 찾고 싶다면 GitHub 검색창에 아래 표현을 넣어 보세요.

repo:sgl-project/sglang path:/^python\/sglang\/srt\/models\// Qwen2_5_VLForConditionalGeneration

오디오 전사 (Audio Transcription)

SGLang은 OpenAI 호환 /v1/audio/transcriptions 엔드포인트로 오디오 전용 ASR(음성 인식) 모델을 지원해요. 오디오 파일을 올리면 전사 결과를 받을 수 있죠.

서버 실행 명령

sglang serve \
  --model-path Qwen/Qwen3-ASR-1.7B \
  --served-model-name qwen3-asr \
  --trust-remote-code \
  --host 0.0.0.0 --port 30000

예시 요청

curl http://localhost:30000/v1/audio/transcriptions \
  -F [email protected] \
  -F model=qwen3-asr \
  -F response_format=verbose_json

비디오 입력 지원

SGLang은 비전-언어 모델(VLM)에 비디오 입력도 지원해요. 비디오 질문 답변, 캡셔닝, 전체 장면 이해 같은 시간적 추론 작업이 가능해지죠. 비디오 클립을 디코딩하고, 키 프레임을 샘플링하고, 결과 텐서를 텍스트 프롬프트와 함께 배칭해서 멀티모달 추론이 시각·언어 맥락을 함께 통합하도록 해 줘요.

SGLang 프로그램에서 프롬프트를 만들 때는 sgl.video(path, num_frames)로 클립을 붙이면 돼요.

비디오 클립을 보내는 OpenAI 호환 요청 예시:

import requests

url = "http://localhost:30000/v1/chat/completions"

data = {
    "model": "Qwen/Qwen3-VL-30B-A3B-Instruct",
    "messages": [
        {
            "role": "user",
            "content": [
                {"type": "text", "text": "What’s happening in this video?"},
                {
                    "type": "video_url",
                    "video_url": {
                        "url": "https://github.com/sgl-project/sgl-test-files/raw/refs/heads/main/videos/jobs_presenting_ipod.mp4"
                    },
                },
            ],
        }
    ],
    "max_tokens": 300,
}

response = requests.post(url, json=data)
print(response.text)

Cosmos3 체크포인트의 LLM 타워 서빙하기

nvidia/Cosmos3-Nano와 nvidia/Cosmos3-Edge는 diffusers 레이아웃으로 된 통합 월드 모델 체크포인트라서, sglang serve는 기본적으로 이들을 diffusion 런타임으로 라우팅해요(미디어 생성은 Cosmos3 쿡북 페이지 참고). 이해 타워를 비전-언어 모델로 서빙하고 싶다면 --model-type llm으로 LLM 백엔드를 강제하면 돼요.

sglang serve \
  --model-path nvidia/Cosmos3-Nano \
  --model-type llm \
  --host 0.0.0.0 --port 30000

같은 명령에서 모델 경로만 바꾸면 nvidia/Cosmos3-Edge도 서빙돼요. 둘 다 OpenAI 호환 API로 이미지·비디오 입력을 받아요.

curl http://localhost:30000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "nvidia/Cosmos3-Nano",
    "messages": [{
      "role": "user",
      "content": [
        {"type": "text", "text": "Describe this image."},
        {"type": "image_url", "image_url": {"url": "https://raw.githubusercontent.com/sgl-project/sglang/main/examples/assets/example_image.png"}}
      ]
    }],
    "max_tokens": 128
  }'

텍스트 모델만 서빙하고 싶다면(비전 타워를 완전히 건너뜀) --language-model-only를 추가하세요. 이 모드에선 /model_info가 has_image_understanding: false를 보고하고, 이미지나 비디오 입력을 담은 요청은 거부돼요.

sglang serve \
  --model-path nvidia/Cosmos3-Nano \
  --model-type llm \
  --language-model-only \
  --host 0.0.0.0 --port 30000

사용 시 참고사항

성능 최적화

멀티모달 모델에선 --keep-mm-feature-on-device 플래그로 지연 시간을 최적화할 수 있어요. 단 GPU 메모리 사용량은 늘어나죠.

• 기본 동작: 처리 후 멀티모달 피처 텐서를 CPU로 옮겨서 GPU 메모리를 아껴요.
• --keep-mm-feature-on-device 사용 시: 피처 텐서가 GPU에 남아 device-to-host 복사 오버헤드를 줄여 지연을 개선하지만 GPU 메모리를 더 써요.

GPU 메모리가 충분하고 멀티모달 추론 지연을 최소화하고 싶을 때 이 플래그를 쓰면 돼요.

멀티모달 입력 제한

• --mm-process-config '{"image":{"max_pixels":1048576},"video":{"fps":3,"max_pixels":602112,"max_frames":60}}'를 사용하세요: image, video, audio 입력 한도를 설정할 수 있어요.

이렇게 하면 GPU 메모리 사용을 줄이고 추론 속도를 높여 OOM을 피하는 데 도움이 되지만, 모델 성능에 영향을 줄 수 있어요. 플래그 설정은 HuggingFace 프로세서에 images_kwargs, videos_kwargs, audio_kwargs로 전달되므로 각 모달리티의 설정이 서로 겹치지 않고 분리돼요. 모델 프로세서의 가용 파라미터는 HuggingFace 문서를 참고하세요.

멀티모달 모델 서빙에서의 양방향 어텐션

Gemma-3 멀티모달 모델 서빙 시 참고:

Hugging Face 블로그에서 언급하듯, Gemma-3는 프리필 단계에서 이미지 토큰 사이에 양방향 어텐션을 사용해요. 현재 SGLang은 Triton 어텐션 백엔드를 쓸 때만 양방향 어텐션을 지원하는데, CUDA Graph나 Chunked Prefill과는 호환되지 않아요.

양방향 어텐션을 켜려면 TritonAttnBackend를 쓰면서 CUDA Graph와 Chunked Prefill을 꺼야 해요. 예시 실행 명령:

python -m sglang.launch_server \
  --model-path google/gemma-3-4b-it \
  --host 0.0.0.0 --port 30000 \
  --enable-multimodal \
  --dtype bfloat16 --triton-attention-reduce-in-fp32 \
  --attention-backend triton \ # Use Triton attention backend
  --disable-cuda-graph \ # Disable Cuda Graph
  --chunked-prefill-size -1 # Disable Chunked Prefill

더 높은 서빙 성능이 필요하고 어느 정도의 정확도 손실을 감수할 수 있다면 다른 어텐션 백엔드를 쓰고 CUDA Graph나 Chunked Prefill 같은 기능도 켤 수 있어요. 다만 모델이 양방향 어텐션 대신 인과 어텐션(causal attention) 으로 폴백한다는 점을 유의하세요.

더 알아보기 (Learn more)

• OpenAI APIs - Vision
• Query VLM with Offline Engine