QwenLM/Qwen3-VL

💜 Qwen Chat | 🤗 Hugging Face | 🤖 ModelScope | 📑 Blog | 📚 Cookbooks | 📑 Paper

🖥️ Demo | 💬 WeChat (微信) | 🫨 Discord | 📑 API | 🖥️ PAI-DSW

Qwen3-VL을 만나보세요 — 현재까지 Qwen 시리즈 중 가장 강력한 시각-언어 모델 (vision-language model)입니다.

이번 세대는 전반에 걸쳐 포괄적인 업그레이드를 제공합니다: 우수한 텍스트 이해 및 생성 (text understanding & generation), 더 깊은 시각적 인지 및 추론 (visual perception & reasoning), 확장된 컨텍스트 길이 (context length), 강화된 공간 및 비디오 역학 이해 (spatial and video dynamics comprehension), 그리고 더 강력한 에이전트 상호작용 (agent interaction) 능력입니다.

에지(edge)부터 클라우드(cloud)까지 확장 가능한 Dense 및 MoE 아키텍처로 제공되며, 유연하고 수요에 따른 배포를 위해 Instruct 및 추론 강화형 Thinking 에디션이 준비되어 있습니다.

시각적 에이전트 (Visual Agent): PC/모바일 GUI를 작동합니다 — 요소를 인식하고, 기능을 이해하며, 도구를 호출하고, 작업을 완료합니다. -
시각적 코딩 부스트 (Visual Coding Boost): 이미지/비디오로부터 Draw.io/HTML/CSS/JS를 생성합니다. -
고급 공간 인지 (Advanced Spatial Perception): 객체의 위치, 관점 및 가려짐 (occlusions)을 판단합니다; 더 강력한 2D 그라운딩 (grounding)을 제공하며 공간 추론 및 Embodied AI를 위한 3D 그라운딩을 가능하게 합니다. -
긴 컨텍스트 및 비디오 이해 (Long Context & Video Understanding): 네이티브 256K 컨텍스트를 지원하며 1M까지 확장 가능합니다; 책과 몇 시간 길이의 비디오를 완전한 회상 (recall) 및 초 단위 인덱싱 (second-level indexing)과 함께 처리합니다. -
강화된 멀티모달 추론 (Enhanced Multimodal Reasoning): STEM/수학 분야에서 탁월합니다 — 인과 분석 및 논리적이고 증거에 기반한 답변을 제공합니다. -
업그레이드된 시각적 인식 (Upgraded Visual Recognition): 더 넓고 고품질인 사전 학습 (pretraining)을 통해 유명인, 애니메이션, 제품, 랜드마크, 동식물 등을

• Interleaved-MRoPE: 견고한 위치 임베딩 (positional embeddings)을 통해 시간, 너비, 높이에 걸쳐 전체 주파수 할당 (Full-frequency allocation)을 수행하며, 이를 통해 장기 비디오 추론 (long-horizon video reasoning) 능력을 향상시킵니다. -
  DeepStack: 다층 ViT 특징 (multi-level ViT features)을 융합하여 미세한 세부 사항을 포착하고 이미지-텍스트 정렬 (image–text alignment)을 날카롭게 만듭니다. -
  Text–Timestamp Alignment: T-RoPE를 넘어 정밀한 타임스탬프 기반 이벤트 로컬라이제이션 (timestamp-grounded event localization)을 구현하여 더욱 강력한 비디오 시간적 모델링 (video temporal modeling)을 제공합니다.

• 2025.11.27: Qwen3-VL에 대한 많은 기술적 세부 사항을 소개하는 **Qwen3-VL 논문 (paper)**을 공개하였으며, 이것이 모든 분께 도움이 되기를 바랍니다. - 2025.10.21: Qwen3-VL-2B(Instruct/Thinking) 및 Qwen3-VL-32B(Instruct/Thinking)를 공개했습니다. 즐겁게 사용해 보세요! - 2025.10.15: Qwen3-VL-4B(Instruct/Thinking) 및 Qwen3-VL-8B(Instruct/Thinking)를 공개했습니다. 즐겁게 사용해 보세요! - 2025.10.4: Qwen3-VL-30B-A3B-Instruct 및 Qwen3-VL-30B-A3B-Thinking을 공개했습니다. 또한 Qwen3-VL 모델의 FP8 버전도 공개하였으며, 이는 HuggingFace 컬렉션과 ModelScope 컬렉션에서 이용 가능합니다.

• 2025.09.23: Qwen3-VL-235B-A22B-Instruct 및 Qwen3-VL-235B-A22B-Thinking을 공개했습니다. 더 자세한 내용은 저희 블로그를 확인해 주세요!

• 2025.04.08: Qwen2-VL 및 Qwen2.5-VL의 미세 조정 (fine-tuning)을 위한 코드를 제공합니다.

• 2025.03.25: Qwen2.5-VL-32B를 공개했습니다. 이 모델은 더 똑똑하며 응답이 인간의 선호도와 더 밀접하게 일치합니다. 더 자세한 내용은 저희 블로그를 확인해 주세요!

• 2025.02.20: Qwen2.5-VL 기술 보고서 (Technical Report)를 공개했습니다. 보고서와 함께 3B, 7B, 72B 파라미터의 세 가지 다른 크기로 구성된 Qwen2.5-VL용 AWQ 양자화 (AWQ-quantized) 모델도 공개했습니다.

• 2025.01.28: Qwen2.5-VL 시리즈를 공개했습니다. 더 자세한 내용은 저희 블로그를 확인해 주세요!

• 2024.12.25: QvQ-72B-Preview를 공개했습니다. QvQ-72B-Preview는 시각적 추론 (visual reasoning) 능력 향상에 집중하는 실험적 연구 모델입니다. 더 자세한 내용은 저희 블로그를 확인해 주세요!

• 2024.09.19: 지시어 튜닝 (instruction-tuned)된 Qwen2-VL-72B 모델과 그 양자화 (quantized) 버전 [AWQ, GPTQ-Int4, GPTQ-Int8]을 이제 사용할 수 있습니다. 이와 동시에 Qwen2-VL 논문도 함께 공개했습니다.

• 2024.08.30: Qwen2-VL 시리즈를 공개했습니다. 2B 및 7B 모델을 현재 사용할 수 있으며, 오픈 소스용 72B 모델도 곧 출시될 예정입니다. 자세한 내용은 저희 블로그를 확인해 주세요!

저희는 인식 (recognition), 지역화 (localization), 문서 파싱 (document parsing), 비디오 이해 (video understanding), 핵심 정보 추출 (key information extraction) 등을 포함한 다양한 기능에 대한 쿡북 (cookbooks)을 준비하고 있습니다. 더 많은 내용을 확인해 보세요!

쿡북 (Cookbook)	설명	공개 여부
Omni Recognition	동물, 식물, 사람, 명소를 식별할 뿐만 아니라 자동차 및 상품과 같은 다양한 객체도 인식합니다.
...

아래에 🤖 ModelScope 및 🤗 Transformers를 사용하여 Qwen3-VL을 사용하는 방법을 보여주는 간단한 예시를 제공합니다.

# Qwen3-VL 모델은 transformers >= 4.57.0 버전이 필요합니다
pip install "transformers>=4.57.0"

사용자들, 특히 중국 본토에 계신 분들께는 ModelScope를 사용할 것을 강력히 권장합니다. snapshot_download는 체크포인트 (checkpoints) 다운로드와 관련된 문제를 해결하는 데 도움이 될 수 있습니다.

여기서는 transformers를 사용하여 채팅 모델 (chat model)을 사용하는 방법을 보여주는 코드 스니펫 (code snippet)을 제시합니다:

from transformers import AutoModelForImageTextToText, AutoProcessor
# 기본값: 사용 가능한 장치(s)에 모델을 로드합니다
model = AutoModelForImageTextToText.from_pretrained(
...

다중 이미지 추론 (Multi image inference)

# 여러 이미지와 텍스트 쿼리 (text query)를 포함하는 메시지
messages = [
{
...

비디오 추론 (Video inference)

# 비디오 URL(또는 로컬 경로)과 텍스트 쿼리를 포함하는 메시지
messages = [
{
...

배치 추론 (Batch inference)

# 배치 생성 (batch generation)을 위해 padding_side는 'left'로 설정해야 합니다!
processor.tokenizer.padding_side = 'left'
# 배치 추론을 위한 샘플 메시지
...

공식 프로세서 (Official Processor)를 통한 픽셀 제어 (Pixel Control)

공식 HF 프로세서 (HF processor)를 사용하면 시각적 토큰 (visual tokens)의 예산 (budget)을 편리하게 제어할 수 있습니다. Qwen3-VL 프로세서는 이미지와 비디오 처리를 분리하므로, 각 모달리티 (modality)에 대한 픽셀 예산을 독립적으로 구성할 수 있습니다.

이미지 프로세서 (image processor)의 경우:

size['longest_edge'] 파라미터는 원래 max_pixels에 대응하며, 이는 이미지에 허용되는 최대 픽셀 수를 정의합니다 (즉, 높이 H와 너비 W인 이미지의 경우, H × W는 max_pixels를 초과할 수 없습니다. 단순화를 위해 이미지 채널은 무시됩니다).

마찬가지로, size['shortest_edge']는 min_pixels에 대응하며, 이미지에 허용되는 최소 픽셀 수를 지정합니다.

비디오 프로세서 (video processor)의 경우:

해석이 약간 다릅니다. size['longest_edge']는 비디오 내 모든 프레임에 걸친 최대 총 픽셀 수를 나타냅니다. 즉, T×H×W 형태의 비디오의 경우, T×H×W의 곱이 size['longest_edge']를 초과할 수 없습니다.

마찬가지로, size['shortest_edge']는 비디오의 최소 총 픽셀 예산을 설정합니다.

processor = AutoProcessor.from_pretrained("Qwen/Qwen3-VL-235B-A22B-Instruct")
# 이미지 프로세서 예산: Qwen3-VL의 압축률은 32이므로, 단일 이미지의 시각적 토큰 수를 256-1280(32 × 공간 압축)으로 설정할 수 있습니다.
processor.image_processor.size = {"longest_edge": 1280*32*32, "shortest_edge": 256*32*32}
...

아래에 표시된 것처럼 비디오의 샘플 FPS (sample fps) 또는 **샘플 프레임 (sample frames)**을 추가로 제어할 수 있습니다.

messages = [
{
"role": "user",
...

최신 qwen-vl-utils 툴킷 (Qwen2.5-VL과 하위 호환 가능)을 사용하면 시각적 입력별로 픽셀 제약 조건을 제어할 수 있습니다.

pip install qwen-vl-utils==0.0.14
# 더 빠른 비디오 로딩을 위해 `[decord]` 기능을 사용하는 것을 강력히 권장합니다.
# pip install qwen-vl-utils[decord]

이전 버전에 비해 새로운 qwen-vl-utils는 다음을 도입했습니다:

"image_patch_size": Qwen2.5-VL의 경우 14, Qwen3-VL의 경우 16. 기본값은 14로 설정됩니다.

• "return_video_metadata" (Qwen3-VL 전용): 새로운 비디오 프로세서(video processor)로 인해, 이 값이 True인 경우 각 비디오는 (video_tensor, video_metadata) 형태로 반환됩니다. 기본값은 False로 설정됩니다.

# Qwen2.5VL의 경우, 다음과 같이 간단히 호출할 수 있습니다.
images, videos, video_kwargs = process_vision_info(messages, return_video_kwargs=True)
# Qwen3VL 시리즈의 경우, 다음과 같이 호출해야 합니다.
...

📌 참고: qwen-vl-utils가 이미 이미지/비디오의 크기를 조정(resize)하므로, 중복된 크기 조정을 피하기 위해 프로세서(processor)에 do_resize=False를 전달하세요.

이미지 처리 (Process Images)

입력 이미지의 경우, 로컬 파일, base64, URL을 지원합니다.

# 텍스트 내 원하는 위치에 로컬 파일 경로, URL 또는 base64로 인코딩된 이미지를 직접 삽입할 수 있습니다.
## 로컬 파일 경로
messages = [
...

모델에 입력되는 이미지 크기를 세밀하게 제어하기 위해 두 가지 방법을 제공합니다:

• 정확한 치수 지정: resized_height와 resized_width를 직접 설정합니다. 이 값들은 가장 가까운 32의 배수로 반올림됩니다 (Qwen3VL은 32, Qwen2.5VL은 28).

• min_pixels 및 max_pixels 정의: 이미지는 min_pixels와 max_pixels 범위 내에서 종횡비(aspect ratio)를 유지하도록 크기가 조정됩니다.

from transformers import AutoModelForImageTextToText, AutoProcessor
from qwen_vl_utils import process_vision_info
model = AutoModelForImageTextToText.from_pretrained(
...

비디오 처리 (Process Videos)

입력 비디오의 경우, 이미지 리스트, 로컬 경로 및 URL을 지원합니다.

# 비디오로서 이미지 리스트와 텍스트 쿼리를 포함하는 메시지
messages = [
{
...

비디오 내 개별 프레임의 해상도를 제한하기 위해, 사용 가능한 GPU 메모리와 특정 애플리케이션 시나리오를 기반으로 min_pixels 및 max_pixels 파라미터에 적절한 값을 설정하는 것을 권장합니다.

또는, total_pixels 파라미터를 사용하여 비디오의 총 토큰(token) 수를 제한할 수 있습니다 (과도하게 긴 입력 시퀀스를 방지하기 위해 이 값을 24576 * 32 * 32 미만으로 설정하는 것을 권장합니다). 파라미터 사용법 및 처리 로직에 대한 자세한 내용은 fetch_video를 참조하십시오.

qwen_vl_utils/vision_process.py의 function.

.

from transformers import AutoModelForImageTextToText, AutoProcessor
from qwen_vl_utils import process_vision_info
model = AutoModelForImageTextToText.from_pretrained(
...

비디오 백엔드 (Video Backends) 및 URL 호환성

현재 qwen-vl-utils는 torchvision, decord, torchcodec 세 가지 비디오 디코딩 (decoding) 백엔드를 지원합니다. decord와 torchcodec은 일반적으로 torchvision에 비해 현저히 빠른 디코딩 속도를 제공하지만, 저희는 torchcodec 사용을 권장합니다. 이는 decord에 디코딩 중 멈춤(hangs) 현상과 같은 알려진 문제들이 있으며, 해당 프로젝트가 더 이상 활발하게 유지보수되지 않기 때문입니다.

• decord의 경우, Linux를 사용하지 않는다면 PyPI를 통해 decord를 설치하지 못할 수도 있습니다. 이 경우 pip install qwen-vl-utils를 사용하면 비디오 처리를 위해 torchvision을 사용하는 방식으로 폴백 (fallback)됩니다. 하지만 비디오를 로드할 때 decord가 사용되도록 하려면 소스(source)로부터 직접 decord를 설치할 수 있습니다.
• 비디오 디코딩 백엔드로 torchcodec을 사용하려면, torchcodec 공식 저장소(repository)에서 제공하는 설치 지침을 따라 수동으로 설치하십시오. torchcodec은 디코딩 기능을 위해 FFmpeg에 의존한다는 점에 유의하십시오.

비디오 URL 호환성은 주로 사용 중인 제3자 라이브러리 (third-party library)의 버전에 의해 결정됩니다. 자세한 내용은 아래 표를 참조하십시오. 기본 백엔드를 사용하고 싶지 않다면, FORCE_QWENVL_VIDEO_READER를 torchvision, decord, 또는 torchcodec으로 설정하여 전환할 수 있습니다.

백엔드 (Backend)	HTTP	HTTPS
torchvision >= 0.19.0	✅	✅
...

기본적으로 이미지와 비디오 콘텐츠는 대화에 직접 포함됩니다. 여러 이미지를 처리할 때는 더 나은 참조를 위해 이미지와 비디오에 라벨 (labels)을 추가하는 것이 도움이 됩니다. 사용자는 다음 설정을 통해 이 동작을 제어할 수 있습니다:

비전 ID 추가 (Add vision ids)

conversation = [
{
"role": "user",
...

먼저, 최신 버전의 Flash Attention 2가 설치되어 있는지 확인하십시오:

pip install -U flash-attn --no-build-isolation

또한, Flash-Attention 2와 호환되는 하드웨어를 보유하고 있어야 합니다. 이에 대한 자세한 내용은 flash-attention 저장소의 공식 문서에서 확인하십시오. FlashAttention-2는 모델이 torch.float16 또는 torch.bfloat16으로 로드될 때만 사용할 수 있습니다.

Flash Attention-2를 사용하여 모델을 로드하고 실행하려면, 다음과 같이 모델을 로드할 때 attn_implementation="flash_attention_2"를 추가하기만 하면 됩니다:

import torch
from transformers import AutoModelForImageTextToText
model = AutoModelForImageTextToText.from_pretrained(
...

현재 config.json은 최대 256K 토큰의 컨텍스트 길이 (context length)를 지원하도록 설정되어 있습니다.
256K 토큰을 초과하는 방대한 입력을 처리하기 위해, 우리는 모델의 길이 외삽 (length extrapolation) 능력을 향상시키는 기술인 YaRN을 활용하여 긴 텍스트에서도 최적의 성능을 보장합니다.

지원되는 프레임워크 (현재 transformers 및 vLLM)의 경우, config.json에서 max_position_embeddings와 rope_scaling을 수정하여 YaRN을 활성화할 수 있습니다:

{
"max_position_embeddings": 1000000,
...,
...,
...
}