Qwen3-VL

KO | EN

gitlite — search

#javascript #python #hacktoberfest #react #ai #typescript #llm #go #golang #android #machine-learning #rust #deep-learning #linux

★ 19,793 Open GitHub ↗

Qwen3-VL은 Alibaba Cloud의 Qwen 팀에서 개발한 멀티모달 대형 언어 모델(LLM) 시리즈입니다.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Qwen3-VL

![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/qwen3vllogo.png)

💜 [**Qwen Chat**](https://chat.qwenlm.ai/)   |   🤗 [Hugging Face](https://huggingface.co/collections/Qwen/qwen3-vl-68d2a7c1b8a8afce4ebd2dbe)   |   🤖 [ModelScope](https://modelscope.cn/collections/Qwen3-VL-5c7a94c8cb144b)   |   📑 [Blog](https://qwen.ai/blog?id=99f0335c4ad9ff6153e517418d48535ab6d8afef&from=research.latest-advancements-list)   |   📚 [Cookbooks](https://github.com/QwenLM/Qwen3-VL/tree/main/cookbooks)   |   📑 [Paper](https://arxiv.org/pdf/2511.21631)  
  
🖥️ [Demo](https://huggingface.co/spaces/Qwen/Qwen3-VL-Demo)   |   💬 [WeChat (微信)](https://github.com/QwenLM/Qwen/blob/main/assets/wechat.png)   |   🫨 [Discord](https://discord.gg/CV4E9rpNSD)   |   📑 [API](https://help.aliyun.com/zh/model-studio/developer-reference/qwen-vl-api)   |   🖥️ [PAI-DSW](https://gallery.pai-ml.com/#/preview/deepLearning/cv/qwen2.5-vl)

## 소개 (Introduction)
Qwen3-VL을 소개합니다 — 지금까지 Qwen 시리즈 중 가장 강력한 시각-언어 모델(vision-language model)입니다.
이번 세대에서는 전반적인 대대적인 업그레이드가 이루어졌습니다. 뛰어난 텍스트 이해 및 생성, 더 깊이 있는 시각적 인지 및 추론, 확장된 컨텍스트 길이, 향상된 공간 및 비디오 동적 이해, 그리고 더 강력한 에이전트 상호작용 능력을 제공합니다.
엣지(edge)부터 클라우드까지 확장 가능한 Dense 및 MoE 아키텍처로 제공되며, 유연하고 온디맨드 배포가 가능한 Instruct 및 추론 강화 Thinking 에디션을 지원합니다.

#### 주요 개선 사항:
\* \*\*시각적 에이전트(Visual Agent)\*\*: PC 및 모바일 GUI를 조작합니다 — 요소를 인식하고, 기능을 이해하며, 도구를 호출하고, 작업을 완료합니다.
\* \*\*비주얼 코딩 강화(Visual Coding Boost)\*\*: 이미지와 비디오로부터 Draw.io/HTML/CSS/JS를 생성합니다.
\* \*\*고급 공간 지각(Advanced Spatial Perception)\*\*: 객체의 위치, 시점, 가림(occlusion)을 판단합니다; 더 강력한 2D 그라운딩(grounding)을 제공하며 공간 추론 및 체화된 AI(embodied AI)를 위한 3D 그라운딩을 활성화합니다.
\* \*\*긴 컨텍스트 및 비디오 이해(Long Context & Video Understanding)\*\*: 네이티브 256K 컨텍스트 지원 및 1M까지 확장 가능; 완전한 회상 및 초 단위 인덱싱을 통해 책과 몇 시간 분량의 비디오를 처리합니다.
\* \*\*향상된 멀티모달 추론(Enhanced Multimodal Reasoning)\*\*: STEM 및 수학 분야에서 탁월함 — 인과 관계 분석 및 논리적이고 증거에 기반한 답변을 제공합니다.
\* \*\*업그레이드된 시각 인식(Upgraded Visual Recognition)\*\*: 더 넓고 높은 품질의 사전 학습을 통해 “모든 것을 인식”할 수 있습니다 — 유명인, 애니메이션, 제품, 랜드마크, 동식물 등.
\* \*\*확장된 OCR(Expanded OCR)\*\*: 32개 언어 지원 (기존 10개에서 증가); 저조도, 흐림, 기울어진 환경에서도 견고함; 희귀 문자/고대 문자 및 전문 용어 처리 능력 향상; 긴 문서 구조 파싱 기능 개선.
\* \*\*순수 LLM 수준의 텍스트 이해력(Text Understanding on par with pure LLMs)\*\*: 손실 없는 통합 이해를 위한 매끄러운 텍스트-비전 융합.

#### 모델 아키텍처 업데이트:

![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/qwen3vl_arc.jpg)

1. \*\*Interleaved-MRoPE\*\*: 견고한 위치 임베딩을 통해 시간, 너비, 높이에 걸쳐 전주파수 할당을 수행하여, 장기 비디오 추론 능력을 향상시킵니다.
2. \*\*DeepStack\*\*: 다중 수준 ViT 피처를 융합하여 세밀한 디테일을 포착하고 이미지와 텍스트의 정렬을 선명하게 만듭니다.
3. \*\*Text–Timestamp Alignment:\*\* T-RoPE를 넘어, 더욱 강력한 비디오 시계열 모델링을 위해 정밀하고 타임스탬프 기반의 이벤트 지역화를 제공합니다.
## News
\* 2025.11.27: Qwen3-VL에 대한 많은 기술적 세부 정보를 담은 [\*\*Qwen3-VL paper\*\*](https://arxiv.org/pdf/2511.21631)를 공개했으며, 이것이 모든 분께 도움이 되기를 바랍니다.
\* 2025.10.21: \*\*Qwen3-VL-2B\*\* ([Instruct](https://huggingface.co/Qwen/Qwen3-VL-2B-Instruct)/[Thinking](https://huggingface.co/Qwen/Qwen3-VL-2B-Thinking)) 및 \*\*Qwen3-VL-32B\*\* ([Instruct](https://huggingface.co/Qwen/Qwen3-VL-32B-Instruct)/[Thinking](https://huggingface.co/Qwen/Qwen3-VL-32B-Thinking))를 출시했습니다. 유용하게 사용해 보세요!
\* 2025.10.15: \*\*Qwen3-VL-4B\*\* ([Instruct](https://huggingface.co/Qwen/Qwen3-VL-4B-Instruct)/[Thinking](https://huggingface.co/Qwen/Qwen3-VL-4B-Thinking)) 및 \*\*Qwen3-VL-8B\*\* ([Instruct](https://huggingface.co/Qwen/Qwen3-VL-8B-Instruct)/[Thinking](https://huggingface.co/Qwen/Qwen3-VL-8B-Thinking))를 출시했습니다. 유용하게 사용해 보세요!
\* 2025.10.4: [Qwen3-VL-30B-A3B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-30B-A3B-Instruct)와 [Qwen3-VL-30B-A3B-Thinking](https://huggingface.co/Qwen/Qwen3-VL-30B-A3B-Thinking)을 출시했습니다. 또한 Qwen3-VL 모델의 FP8 버전도 공개했으며, [HuggingFace collection](https://huggingface.co/collections/Qwen/qwen3-vl-68d2a7c1b8a8afce4ebd2dbe) 및 [ModelScope collection](https://modelscope.cn/collections/Qwen3-VL-5c7a94c8cb144b)에서 확인하실 수 있습니다.
\* 2025.09.23: [Qwen3-VL-235B-A22B-Instruct](https://huggingface.co/Qwen/Qwen3-VL-235B-A22B-Instruct)와 [Qwen3-VL-235B-A22B-Thinking](https://huggingface.co/Qwen/Qwen3-VL-235B-A22B-Thinking)을 출시했습니다. 자세한 내용은 [blog](https://qwen.ai/blog?id=99f0335c4ad9ff6153e517418d48535ab6d8afef&from=research.latest-advancements-list)를 확인해 주세요!
\* 2025.04.08: Qwen2-VL 및 Qwen2.5-VL 파인튜닝을 위한 [code](https://github.com/QwenLM/Qwen2.5-VL/tree/main/qwen-vl-finetune)를 제공합니다.
\* 2025.03.25: [Qwen2.5-VL-32B](https://huggingface.co/Qwen/Qwen2.5-VL-32B-Instruct)를 출시했습니다. 더 똑똑해졌으며 응답이 인간의 선호도와 더 잘 일치합니다. 자세한 내용은 [blog](https://qwenlm.github.io/blog/qwen2.5-vl-32b/)를 확인해 주세요!
\* 2025.02.20: [Qwen2.5-VL Technical Report](https://arxiv.org/abs/2502.13923)를 공개했습니다. 보고서와 함께 세 가지 서로 다른 크기의 Qwen2.5-VL용 AWQ 양자화 모델인 [3B](https://huggingface.co/Qwen/Qwen2.5-VL-3B-Instruct-AWQ), [7B](https://huggingface.co/Qwen/Qwen2.5-VL-7B-Instruct-AWQ), [72B](https://huggingface.co/Qwen/Qwen2.5-VL-72B-Instruct-AWQ) 파라미터 모델도 함께 출시했습니다.
\* 2025.01.28: [Qwen2.5-VL series](https://huggingface.co/Qwen)를 출시했습니다. 자세한 내용은 [blog](https://qwenlm.github.io/blog/qwen2.5-vl/)를 확인해 주세요!
\* 2024.12.25: [QvQ-72B-Preview](https://huggingface.co/Qwen/QVQ-72B-Preview)를 출시했습니다. QvQ-72B-Preview는 시각적 추론 능력 향상에 초점을 맞춘 실험적 연구 모델입니다. 자세한 내용은 [blog](https://qwenlm.github.io/blog/qvq-72b-preview/)를 확인해 주세요!
\* 2024.09.19: 지시 튜닝된 [Qwen2-VL-72B model](https://huggingface.co/Qwen/Qwen2-VL-72B-Instruct) 및 그 양자화 버전([[AWQ](https://huggingface.co/Qwen/Qwen2-VL-72B-Instruct-AWQ), [GPTQ-Int4](https://huggingface.co/Qwen/Qwen2-VL-72B-Instruct-GPTQ-Int4), [GPTQ-Int8](https://huggingface.co/Qwen/Qwen2-VL-72B-Instruct-GPTQ-Int8)])을 이제 이용하실 수 있습니다. 또한 [Qwen2-VL paper](https://arxiv.org/pdf/2409.12191)도 동시에 공개했습니다.
\* 2024.08.30: [Qwen2-VL series](https://huggingface.co/collections/Qwen/qwen2-vl-6

6cee7455501d7126940800d). 2B 및 7B 모델이 이제 출시되었으며, 오픈 소스용 72B 모델도 곧 공개될 예정입니다. 자세한 내용은 저희 [블로그](https://qwenlm.github.io/blog/qwen2-vl/)를 확인해 주세요!
## Performance
### Visual Tasks

![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/table_nothinking_vl.jpg)
![](https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen3-VL/table_thinking_vl_.jpg)
![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/table_nothinking_vl-30a3.jpg)
![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/table_thinking_vl_30A3.jpg)

![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/qwen3vl_2b_32b_vl_instruct.jpg)
![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/qwen3vl_2b_32b_vl_thinking.jpg)

### 텍스트 중심 태스크 (Text-Centric Tasks)

![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/table_nothinking_text.jpg)
![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/table_thinking_text.jpg)
![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/table_nothinking_text-30a3.jpg)

![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/qwen3vl_4b_8b_text_instruct.jpg)
![](https://qianwen-res.oss-accelerate.aliyuncs.com/Qwen3-VL/qwen3vl_4b_8b_text_thinking.jpg)

## Cookbooks
인식, 위치 파악, 문서 파싱, 비디오 이해, 핵심 정보 추출 등 다양한 기능을 위한 [cookbooks](https://github.com/QwenLM/Qwen3-VL/tree/main/cookbooks)를 준비하고 있습니다. 자세한 내용을 확인해 보세요!
| Cookbook | 설명 | 열기 |
| -------- | ----------- | ---- |
| [Omni Recognition](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/omni\_recognition.ipynb) | 동물, 식물, 사람, 명소를 식별할 뿐만 아니라 자동차 및 상품과 같은 다양한 객체를 인식합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/omni\_recognition.ipynb) |
| [Powerful Document Parsing Capabilities](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/document\_parsing.ipynb) | 텍스트뿐만 아니라 레이아웃 위치 정보 및 Qwen HTML 형식을 포함하여 문서 파싱 능력이 한 단계 더 높아졌습니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/document\_parsing.ipynb) |
| [Precise Object Grounding Across Formats](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/2d\_grounding.ipynb) | 상대 위치 좌표를 사용하여 박스와 포인트 모두 지원하며, 다양한 위치 지정 및 라벨링 작업 조합이 가능합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/2d\_grounding.ipynb) |
| [General OCR and Key Information Extraction](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/ocr.ipynb) | 자연 장면 및 다국어에서 더 강력한 텍스트 인식 기능을 제공하며, 다양한 핵심 정보 추출 요구를 지원합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/ocr.ipynb) |
| [Video Understanding](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/video\_understanding.ipynb) | 향상된 비디오 OCR, 장편 비디오 이해 및 비디오 그라운딩을 제공합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/video\_understanding.ipynb) |
| [Mobile Agent](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/mobile\_agent.ipynb) | 휴대전화 제어를 위한 위치 파악 및 추론 기능을 제공합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/mobile\_agent.ipynb) |
| [Computer-Use Agent](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/computer\_use.ipynb) | 컴퓨터와 웹 제어를 위한 위치 파악 및 추론 기능을 제공합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/computer\_use.ipynb) |
| [3D Grounding](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/3d\_grounding.ipynb) | 실내 및 실외 객체 모두에 대해 정확한 3D 바운딩 박스를 제공합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/3d\_grounding.ipynb) |
| [Thinking with Images](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/think\_with\_images.ipynb) | image\_zoom\_in\_tool과 search\_tool을 활용하여 모델이 이미지 내의 세밀한 시각적 세부 정보를 정확하게 이해하도록 돕습니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/think\_with\_images.ipynb) |
| [MultiModal Coding](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/mmcode.ipynb) | 멀티모달 정보에 대한 엄격한 이해를 바탕으로 정확한 코드를 생성합니다. | [![Colab](https://colab.research.google.com/assets/colab-bad

ge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/mmcode.ipynb) |
| [Long Document Understanding](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/long\_document\_understanding.ipynb) | 초장문 문서에 대한 엄밀한 시의적/의미적 이해를 달성합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/long\_document\_understanding.ipynb) |
| [Spatial Understanding](https://github.com/QwenLM/Qwen3-VL/blob/main/cookbooks/spatial\_understanding.ipynb) | 공간 정보를 보고, 이해하고 추론합니다. | [![Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/QwenLM/Qwen3-VL/blob/main/cookbooks/spatial\_understanding.ipynb) |
## 빠른 시작 (Quickstart)
아래에서는 🤖 ModelScope와 🤗 Transformers를 사용하여 Qwen3-VL을 사용하는 방법을 보여주는 간단한 예제를 제공합니다.
```
# The Qwen3-VL model requires transformers >= 4.57.0
pip install "transformers>=4.57.0"
```
### 🤖 ModelScope
중국 본토에 거주하는 사용자 등은 특히 ModelScope를 사용하는 것을 강력히 권장합니다. `snapshot\_download`를 사용하면 체크포인트 다운로드와 관련된 문제를 해결할 수 있습니다.
### 🤗 Transformers를 사용하여 채팅하기
다음은 `transformers`를 사용하여 챗 모델을 사용하는 방법을 보여주는 코드 스니펫입니다.
```python
from transformers import AutoModelForImageTextToText, AutoProcessor
# default: Load the model on the available device(s)
model = AutoModelForImageTextToText.from\_pretrained(
"Qwen/Qwen3-VL-235B-A22B-Instruct", dtype="auto", device\_map="auto"
)
# We recommend enabling flash\_attention\_2 for better acceleration and memory saving, especially in multi-image and video scenarios.
# model = AutoModelForImageTextToText.from\_pretrained(
# "Qwen/Qwen3-VL-235B-A22B-Instruct",
# dtype=torch.bfloat16,
# attn\_implementation="flash\_attention\_2",
# device\_map="auto",
# )
processor = AutoProcessor.from\_pretrained("Qwen/Qwen3-VL-235B-A22B-Instruct")
messages = [
{
"role": "user",
"content": [
{
"type": "image",
"image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg",
},
{"type": "text", "text": "Describe this image."},
],
}
]
# Preparation for inference
inputs = processor.apply\_chat\_template(
messages,
tokenize=True,
add\_generation\_prompt=True,
return\_dict=True,
return\_tensors="pt"
)
inputs = inputs.to(model.device)
# Inference: Generation of the output
generated\_ids = model.generate(\*\*inputs, max\_new\_tokens=128)
generated\_ids\_trimmed = [
out\_ids[len(in\_ids) :] for in\_ids, out\_ids in zip(inputs.input\_ids, generated\_ids)
]
output\_text = processor.batch\_decode(
generated\_ids\_trimmed, skip\_special\_tokens=True, clean\_up\_tokenization\_spaces=False
)
print(output\_text)
```

다중 이미지 추론
```python
# Messages containing multiple images and a text query
messages = [
{
"role": "user",
"content": [
{"type": "image", "image": "file:///path/to/image1.jpg"},
{"type": "image", "image": "file:///path/to/image2.jpg"},
{"type": "text", "text": "Identify the similarities between these images."},
],
}
]
# Preparation for inference
inputs = processor.apply\_chat\_template(
messages,
tokenize=True,
add\_generation\_prompt=True,
return\_dict=True,
return\_tensors="pt"
)
inputs = inputs.to(model.device)
# Inference: Generation of the output
generated\_ids = model.generate(\*\*inputs, max\_new\_tokens=128)
generated\_ids\_trimmed = [
out\_ids[len(in\_ids) :] for in\_ids, out\_ids in zip(inputs.input\_ids, generated\_ids)
]
output\_text = processor.batch\_decode(
generated\_ids\_trimmed, skip\_special\_tokens=True, clean\_up\_tokenization\_spaces=False
)
print(output\_text)
```

비디오 추론
```python
# Messages containing a video url(or a local path) and a text query
messages = [
{
"role": "user",
"content": [
{
"type": "video",
"video": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen2-VL/space\_woaudio.mp4",
},
{"type": "text", "text": "Describe this video."},
],
}
]
# Preparation for inference
inputs = processor.apply\_chat\_template(
messages,
tokenize=True,
add\_generation\_prompt=True,
return\_dict=True,
return\_tensors="pt"
)
inputs = inputs.to(model.device)
# Inference: Generation of the output
generated\_ids = model.generate(\*\*inputs, max\_new\_tokens=128)
generated\_ids\_trimmed = [
out\_ids[len(in\_ids) :] for in\_ids, out\_ids in zip(inputs.input\_ids, generated\_ids)
]
output\_text = processor.batch\_decode(
generated\_ids\_trimmed, skip\_special\_tokens=True, clean\_up\_tokenization\_spaces=False
)
print(output\_text)
```

배치 추론
```python
# for batch generation, padding\_side should be set to left!
processor.tokenizer.padding\_side = 'left'
# Sample messages for batch inference
messages1 = [
{
"role": "user",
"content": [
{"type": "image", "image": "file:///path/to/image1.jpg"},
{"type": "image", "image": "file:///path/to/image2.jpg"},
{"type": "text", "text": "What are the common elements in these pictures?"},
],
}
]
messages2 = [
{"role": "system", "content": [{"type": "text", "text": "You are a helpful assistant."}]},
{"role": "user", "content": [{"type": "text", "text": "Who are you?"}]},
]
# Combine messages for batch processing
messages = [messages1, messages2]
# Preparation for inference
inputs = processor.apply\_chat\_template(
messages,
tokenize=True,
add\_generation\_prompt=True,
return\_dict=True,
return\_tensors="pt",
padding=True # padding should be set for batch generation!
)
inputs = inputs.to(model.device)
# Inference: Generation of the output
generated\_ids = model.generate(\*\*inputs, max\_new\_tokens=128)
generated\_ids\_trimmed = [
out\_ids[len(in\_ids) :] for in\_ids, out\_ids in zip(inputs.input\_ids, generated\_ids)
]
output\_text = processor.batch\_decode(
generated\_ids\_trimmed, skip\_special\_tokens=True, clean\_up\_tokenization\_spaces=False
)
print(output\_text)
```

공식 Processor를 통한 픽셀 제어
공식 HF processor를 사용하여 시각적 토큰의 예산을 편리하게 제어할 수 있습니다. Qwen3-VL processor는 이미지와 비디오 처리를 분리하므로, 각 모달리티별 픽셀 예산을 독립적으로 구성할 수 있습니다.
- \*\*이미지 processor의 경우\*\*:
파라미터 `size['longest\_edge']`는 원래 `max\_pixels`에 해당하며, 이미지에 허용되는 최대 픽셀 수를 정의합니다(즉, 높이가 H이고 너비가 W인 이미지의 경우, H × W는 `max\_pixels`를 초과할 수 없습니다. 단순화를 위해 이미지 채널은 무시됩니다).
마찬가지로 `size['shortest\_edge']`는 `min\_pixels`에 해당하며, 이미지에 허용되는 최소 픽셀 수를 지정합니다.
- \*\*비디오 processor의 경우\*\*:
해석이 약간 다릅니다. `size['longest\_edge']`는 비디오의 모든 프레임에 걸친 최대 총 픽셀 수를 나타냅니다. 크기가 T×H×W인 비디오의 경우, 곱 T×H×W는 `size['longest\_edge']`를 초과할 수 없습니다.
마찬가지로 `size['shortest\_edge']`는 비디오의 최소 총 픽셀 예산을 설정합니다.
```python
processor = AutoProcessor.from\_pretrained("Qwen/Qwen3-VL-235B-A22B-Instruct")
# budget for image processor, since the compression ratio is 32 for Qwen3-VL, we can set the number of visual tokens of a single image to 256-1280 (32× spatial compression)
processor.image\_processor.size = {"longest\_edge": 1280\*32\*32, "shortest\_edge": 256\*32\*32}
# budget for video processor, we can set the number of visual tokens of a single video to 256-16384 (32× spatial compression + 2× temporal compression)
processor.video\_processor.size = {"longest\_edge": 16384\*32\*32\*2, "shortest\_edge": 256\*32\*32\*2}
```
- 아래와 같이 비디오의 \*\*sample fps\*\* 또는 \*\*sample frames\*\*를 추가로 제어할 수 있습니다.
```python
messages = [
{
"role": "user",
"content": [
{
"type": "video",
"video": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen2-VL/space\_woaudio.mp4",
},
{"type": "text", "text": "Describe this video."},
],
}
]
# for video input, we can further control the fps or num\_frames. \
# defaultly, fps is set to 2
# set fps = 4
inputs = processor.apply\_chat\_template(
messages,
tokenize=True,
add\_generation\_prompt=True,
return\_dict=True,
return\_tensors="pt",
fps=4
)
inputs = inputs.to(model.device)
# set num\_frames = 128 and overwrite the fps to None!
# inputs = processor.apply\_chat\_template(
# messages,
# tokenize=True,
# add\_generation\_prompt=True,
# return\_dict=True,
# return\_tensors="pt",
# num\_frames=128,
# fps=None,
# )
# inputs = inputs.to(model.device)
# Inference: Generation of the output
generated\_ids = model.generate(\*\*inputs, max\_new\_tokens=128)
generated\_ids\_trimmed = [
out\_ids[len(in\_ids) :] for in\_ids, out\_ids in zip(inputs.input\_ids, generated\_ids)
]
output\_text = processor.batch\_decode(
generated\_ids\_trimmed, skip\_special\_tokens=True, clean\_up\_tokenization\_spaces=False
)
print(output\_text)
```
### 새로운 `qwen-vl-utils` 사용법
최신 `qwen-vl-utils` 툴킷(Qwen2.5-VL과 하위 호환됨)을 사용하면 시각적 입력별로 픽셀 제약을 제어할 수 있습니다.
```bash
pip install qwen-vl-utils==0.0.14
# It's highly recommended to use `[decord]` feature for faster video loading.
# 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 전용): 새로운 비디오 processor로 인해, True일 경우 각 비디오가 (video\_tensor, video\_metadata) 형태로 반환됩니다. 기본값은 `False`로 설정됩니다.
```python
# for Qwen2.5VL, you can simply call
images, videos, video\_kwargs = process\_vision\_info(messages, return\_video\_kwargs=True)
# For Qwen3VL series, you should call
images, videos, video\_kwargs = process\_vision\_info(messages, image\_patch\_size=16, return\_video\_kwargs=True, return\_video\_metadata=True)
```
📌 참고: `qwen-vl-utils`가 이미 이미지/비디오의 크기를 조절하므로, 중복을 피하려면 processor에 `do\_resize=False`를 전달하세요.

중복 리사이징.
이미지 처리
입력 이미지의 경우 로컬 파일, base64 및 URL을 지원합니다.
```python
# You can directly insert a local file path, a URL, or a base64-encoded image into the position where you want in the text.
## Local file path
messages = [
{
"role": "user",
"content": [
{"type": "image", "image": "file:///path/to/your/image.jpg"},
{"type": "text", "text": "Describe this image."},
],
}
]
## Image URL
messages = [
{
"role": "user",
"content": [
{"type": "image", "image": "http://path/to/your/image.jpg"},
{"type": "text", "text": "Describe this image."},
],
}
]
## Base64 encoded image
messages = [
{
"role": "user",
"content": [
{"type": "image", "image": "data:image;base64,/9j/..."},
{"type": "text", "text": "Describe this image."},
],
}
]
```
모델에 입력되는 이미지 크기를 세밀하게 제어하기 위해 두 가지 방법을 제공합니다:
- 정확한 크기 지정: resized\_height와 resized\_width를 직접 설정합니다. 이 값들은 32의 가장 가까운 배수로 반올림됩니다(Qwen3VL의 경우 32, Qwen2.5VL의 경우 28).
- min\_pixels 및 max\_pixels 정의: 이미지가 min\_pixels와 max\_pixels 범위 내에서 종횡비를 유지하도록 리사이징됩니다.
```python
from transformers import AutoModelForImageTextToText, AutoProcessor
from qwen\_vl\_utils import process\_vision\_info
model = AutoModelForImageTextToText.from\_pretrained(
"Qwen/Qwen3-VL-235B-A22B-Instruct", dtype="auto", device\_map="auto"
)
processor = AutoProcessor.from\_pretrained("Qwen/Qwen3-VL-235B-A22B-Instruct")
# resized\_height and resized\_width
messages = [
{
"role": "user",
"content": [
{
"type": "image",
"image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg",
"resized\_height": 280,
"resized\_width": 420,
},
{"type": "text", "text": "Describe this image."},
],
}
]
# min\_pixels and max\_pixels
messages = [
{
"role": "user",
"content": [
{
"type": "image",
"image": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen-VL/assets/demo.jpeg",
"min\_pixels": 50176,
"max\_pixels": 50176,
},
{"type": "text", "text": "Describe this image."},
],
}
]
# Preparation for inference with qwen-vl-utils
text = processor.apply\_chat\_template(messages, tokenize=False, add\_generation\_prompt=True)
images, videos = process\_vision\_info(messages, image\_patch\_size=16)
# since qwen-vl-utils has resize the images/videos, \
# we should pass do\_resize=False to avoid duplicate operation in processor!
inputs = processor(text=text, images=images, videos=videos, do\_resize=False, return\_tensors="pt")
inputs = inputs.to(model.device)
# Inference: Generation of the output
generated\_ids = model.generate(\*\*inputs, max\_new\_tokens=128)
generated\_ids\_trimmed = [
out\_ids[len(in\_ids) :] for in\_ids, out\_ids in zip(inputs.input\_ids, generated\_ids)
]
output\_text = processor.batch\_decode(
generated\_ids\_trimmed, skip\_special\_tokens=True, clean\_up\_tokenization\_spaces=False
)
print(output\_text)
```

비디오 처리
입력 비디오의 경우, 이미지 리스트, 로컬 경로 및 URL을 지원합니다.
```python
# Messages containing a images list as a video and a text query
messages = [
{
"role": "user",
"content": [
{
"type": "video",
"video": [
"file:///path/to/frame1.jpg",
"file:///path/to/frame2.jpg",
"file:///path/to/frame3.jpg",
"file:///path/to/frame4.jpg",
],
'sample\_fps':'1', # sample\_fps: frame sampling rate (frames per second), used to determine timestamps for each frame
},
{"type": "text", "text": "Describe this video."},
],
}
]
# Messages containing a local video path and a text query
messages = [
{
"role": "user",
"content": [
{
"type": "video",
"video": "file:///path/to/video1.mp4",
"max\_pixels": 360 \* 420,
"fps": 1.0,
},
{"type": "text", "text": "Describe this video."},
],
}
]
# Messages containing a video url and a text query
messages = [
{
"role": "user",
"content": [
{
"type": "video",
"video": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen2-VL/space\_woaudio.mp4",
"min\_pixels": 4 \* 32 \* 32,
"max\_pixels": 256 \* 32 \* 32,
"total\_pixels": 20480 \* 32 \* 32,
},
{"type": "text", "text": "Describe this video."},
],
}
]
```
사용 가능한 GPU 메모리와 특정 애플리케이션 시나리오에 따라 `min\_pixels` 및 `max\_pixels` 매개변수에 적절한 값을 설정하여 비디오 내 개별 프레임의 해상도를 제한하는 것이 좋습니다.
또는 `total\_pixels` 매개변수를 사용하여 비디오의 총 토큰 수를 제한할 수 있습니다(입력 시퀀스가 지나치게 길어지는 것을 방지하기 위해 이 값을 24576 \* 32 \* 32 미만으로 설정하는 것이 좋습니다). 매개변수 사용법 및 처리 로직에 대한 자세한 내용은 `qwen\_vl\_utils/vision\_process.py`의 `fetch\_video` 함수를 참조하세요.
```python
from transformers import AutoModelForImageTextToText, AutoProcessor
from qwen\_vl\_utils import process\_vision\_info
model = AutoModelForImageTextToText.from\_pretrained(
"Qwen/Qwen3-VL-235B-A22B-Instruct", dtype="auto", device\_map="auto"
)
processor = AutoProcessor.from\_pretrained("Qwen/Qwen3-VL-235B-A22B-Instruct")
messages = [
{
"role": "user",
"content": [
{
"type": "video",
"video": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen2-VL/space\_woaudio.mp4",
"min\_pixels": 4 \* 32 \* 32,
"max\_pixels": 256 \* 32 \* 32,
"total\_pixels": 20480 \* 32 \* 32,
},
{"type": "text", "text": "Describe this video."},
],
}
]
text = processor.apply\_chat\_template(messages, tokenize=False, add\_generation\_prompt=True)
images, videos, video\_kwargs = process\_vision\_info(messages, image\_patch\_size=16, return\_video\_kwargs=True, return\_video\_metadata=True)
# split the videos and according metadatas
if videos is not None:
videos, video\_metadatas = zip(\*videos)
videos, video\_metadatas = list(videos), list(video\_metadatas)
else:
video\_metadatas = None
# since qwen-vl-utils has resize the images/videos, \
# we should pass do\_resize=False to avoid duplicate operation in processor!
inputs = processor(text=text, images=images, videos=videos, video\_metadata=video\_metadatas, return\_tensors="pt", do\_resize=False, \*\*video\_kwargs)
inputs = inputs.to(model.device)
# Inference: Generation of the output
generated\_ids = model.generate(\*\*inputs, max\_new\_tokens=128)
generated\_ids\_trimmed = [
out\_ids[len(in\_ids) :] for in\_ids, out\_ids in zip(inputs.input\_ids, generated\_ids)
]
output\_text = processor.batch\_decode(
generated\_ids\_trimmed, skip\_special\_tokens=True, clean\_up\_tokenization\_spaces=False
)
print(output\_text)
```

Video Backends and URL Compatibility
현재 `qwen-vl-utils`는 `torchvision`, `decord`, `torchcodec`의 세 가지 비디오 디코딩 백엔드를 지원합니다. `decord`와 `torchcodec`은 일반적으로 `torchvision`에 비해 훨씬 빠른 디코딩 속도를 제공하지만, `torchcodec` 사용을 권장합니다. 이는 `decord`의 경우 디코딩 멈춤 현상과 같은 알려진 문제가 있으며, 해당 프로젝트가 더 이상 활발하게 유지보수되지 않기 때문입니다.
- `decord`의 경우, Linux를 사용하고 있지 않다면 PyPI를 통해 `decord`를 설치하지 못할 수도 있습니다. 이 경우 `pip install qwen-vl-utils`를 사용하면 비디오 처리를 위해 torchvision을 대체로 사용하게 됩니다. 하지만 여전히 [install decord from source](https://github.com/dmlc/decord?tab=readme-ov-file#install-from-source)를 통해 decord를 설치하여 비디오를 로드할 때 사용할 수 있습니다.
- 비디오 디코딩 백엔드로 `torchcodec`을 사용하려면, 공식 [torchcodec repository](https://github.com/pytorch/torchcodec/tree/main?tab=readme-ov-file#installing-torchcodec)에 있는 설치 지침에 따라 수동으로 설치하세요. `torchcodec`은 디코딩 기능을 위해 FFmpeg에 의존한다는 점에 유의하세요.
비디오 URL 호환성은 주로 사용 중인 서드파티 라이브러리의 버전에 따라 결정됩니다. 자세한 내용은 아래 표를 참조하세요. 기본 백엔드를 사용하지 않으려면 `FORCE\_QWENVL\_VIDEO\_READER`를 `torchvision`, `decord` 또는 `torchcodec`으로 설정하여 전환할 수 있습니다.
| Backend | HTTP | HTTPS |
|-------------|------|-------|
| torchvision >= 0.19.0 | ✅ | ✅ |
| torchvision < 0.19.0 | ❌ | ❌ |
| decord | ✅ | ❌ |
| torchcodec | ✅ | ✅ |
### More Usage Tips
#### Add ids for Multiple Visual Inputs
기본적으로 이미지와 비디오 콘텐츠는 대화에 직접 포함됩니다. 여러 개의 이미지를 처리할 때, 더 나은 참조를 위해 이미지와 비디오에 라벨을 추가하면 유용합니다. 사용자는 다음 설정을 통해 이 동작을 제어할 수 있습니다:
Add vision ids
```python
conversation = [
{
"role": "user",
"content": [{"type": "image"}, {"type": "text", "text": "Hello, how are you?"}],
},
{
"role": "assistant",
"content": "I'm doing well, thank you for asking. How can I assist you today?",
},
{
"role": "user",
"content": [
{"type": "text", "text": "Can you describe these images and video?"},
{"type": "image"},
{"type": "image"},
{"type": "video"},
{"type": "text", "text": "These are from my vacation."},
],
},
{
"role": "assistant",
"content": "I'd be happy to describe the images and video for you. Could you please provide more context about your vacation?",
},
{
"role": "user",
"content": "It was a trip to the mountains. Can you see the details in the images and video?",
},
]
# default:
prompt\_without\_id = processor.apply\_chat\_template(
conversation, add\_generation\_prompt=True
)
# Excepted output: '<|im\_start|>system\nYou are a helpful assistant.<|im\_end|>\n<|im\_start|>user\n<|vision\_start|><|image\_pad|><|vision\_end|>Hello, how are you?<|im\_end|>\n<|im\_start|>assistant\nI'm doing well, thank you for asking. How can I assist you today?<|im\_end|>\n<|im\_start|>user\nCan you describe these images and video?<|vision\_start|><|image\_pad|><|vision\_end|><|vision\_start|><|image\_pad|><|vision\_end|><|vision\_start|><|video\_pad|><|vision\_end|>These are from my vacation.<|im\_end|>\n<|im\_start|>assistant\nI'd be happy to describe the images and video for you. Could you please provide more context about your vacation?<|im\_end|>\n<|im\_start|>user\nIt was a trip to the mountains. Can you see the details in the images and video?<|im\_end|>\n<|im\_start|>assistant\n'
# add ids
prompt\_with\_id = processor.apply\_chat\_template(
conversation, add\_generation\_prompt=True, add\_vision\_id=True
)
# Excepted output: '<|im\_start|>system\nYou are a helpful assistant.<|im\_end|>\n<|im\_start|>user\nPicture 1: <|vision\_start|><|image\_pad|><|vision\_end|>Hello, how are you?<|im\_end|>\n<|im\_start|>assistant\nI'm doing well, thank you for asking. How can I assist you today?<|im\_end|>\n<|im\_start|>user\nCan you describe

이 이미지와 비디오인가요? Picture 2: <|vision\_start|><|image\_pad|><|vision\_end|> Picture 3: <|vision\_start|><|image\_pad|><|vision\_end|> Video 1: <|vision\_start|><|video\_pad|><|video\_end|> 제 휴가 때 찍은 사진들입니다.<|im\_end|>\n<|im\_start|>assistant\n이미지와 비디오에 대해 기꺼이 설명해 드리겠습니다. 휴가에 대한 더 자세한 맥락을 제공해 주시겠어요?<|im\_end|>\n<|im\_start|>user\n산으로 떠난 여행이었어요. 이미지와 비디오에서 세부적인 내용들이 보이시나요?<|im\_end|>\n<|im\_start|>assistant\n'
```
#### 생성 속도 향상을 위한 Flash-Attention 2
먼저, 최신 버전의 Flash Attention 2를 설치해야 합니다:
```bash
pip install -U flash-attn --no-build-isolation
```
또한, Flash-Attention 2와 호환되는 하드웨어를 사용하고 있어야 합니다. [flash attention 저장소](https://github.com/Dao-AILab/flash-attention)의 공식 문서에서 자세한 내용을 확인하세요. FlashAttention-2는 모델이 `torch.float16` 또는 `torch.bfloat16`으로 로드된 경우에만 사용할 수 있습니다.
Flash Attention-2를 사용하여 모델을 로드하고 실행하려면, 모델을 로드할 때 다음과 같이 단순히 `attn\_implementation="flash\_attention\_2"`를 추가하면 됩니다:
```python
import torch
from transformers import AutoModelForImageTextToText
model = AutoModelForImageTextToText.from\_pretrained(
"Qwen/Qwen3-VL-235B-A22B-Instruct",
torch\_dtype=torch.bfloat16,
attn\_implementation="flash\_attention\_2",
)
```
#### 긴 텍스트 처리
현재 `config.json`은 최대 256K 토큰의 컨텍스트 길이에 맞춰 설정되어 있습니다.
256K 토큰을 초과하는 광범위한 입력을 처리하기 위해, 긴 텍스트에서도 최적의 성능을 보장하도록 모델의 길이 외삽(extrapolation) 성능을 향상시키는 기법인 [YaRN](https://arxiv.org/abs/2309.00071)을 활용합니다.
지원되는 프레임워크(현재 transformers 및 vLLM)의 경우, YaRN을 활성화하기 위해 `config.json`에서 `max\_position\_embeddings`와 `rope\_scaling`을 수정할 수 있습니다:
```
{
"max\_position\_embeddings": 1000000,
...,
"rope\_scaling": {
"rope\_type": "yarn",
"mrope\_section": [
24,
20,
20
],
"mrope\_interleaved": true,
"factor": 3.0,
"original\_max\_position\_embeddings": 262144
},
...
}
```
서빙을 위해 vLLM을 사용할 때도 추가 인수인 `--rope-scaling`과 `--max-model-len`을 추가하여 YaRN을 활성화할 수 있습니다.
```
vllm serve Qwen/Qwen3-VL-235B-A22B-Instruct --rope-scaling '{"rope\_type":"yarn","factor":3.0,"original\_max\_position\_embeddings": 262144,"mrope\_section":[24,20,20],"mrope\_interleaved": true}' --max-model-len 1000000
```
> Interleaved-MRoPE의 위치 ID는 기본(vanilla) RoPE보다 더 천천히 증가하므로, \*\*더 작은 스케일링 팩터(scaling factor)\*\*를 사용하세요. 예를 들어, 256K 컨텍스트 길이로 1M 컨텍스트를 지원하려면 4가 아닌 factor=2 또는 3을 설정하세요.
### API로 Qwen3-VL-235B-A22를 체험해 보세요!
더욱 매력적인 멀티모달 모델인 Qwen3-VL-235B-A22를 탐색해 보실 수 있도록 최첨단 API 서비스를 테스트해 보시기를 권장합니다. 지금 바로 흥미진진한 여정을 시작해 보세요!
```python
from openai import OpenAI
# 여기에 DASHSCOPE\_API\_KEY를 설정하세요
DASHSCOPE\_API\_KEY = ""
client = OpenAI(
api\_key=DASHSCOPE\_API\_KEY,
base\_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
)
completion = client.chat.completions.create(
model="qwen3-vl-235b-a22b-instruct",
messages=[{"role": "user", "content": [
{"type": "image\_url",
"image\_url": {"url": "https://dashscope.oss-cn-beijing.aliyuncs.com/images/dog\_and\_girl.jpeg"}},
{"type": "text", "text": "这是什么"},
]}]
)
print(completion.model\_dump\_json())
```
더 많은 사용법은 [aliyun](https://help.aliyun.com/zh/model-studio/developer-reference/qwen-vl-api)의 튜토리얼을 참조하시기 바랍니다.
### 웹 UI 예제
이 섹션에서는 사용자가 웹 기반 사용자 인터페이스(UI) 데모를 빌드하는 방법을 안내합니다. 이 UI 데모를 통해 사용자는 웹 브라우저를 통해 미리 정의된 모델이나 애플리케이션과 상호작용할 수 있습니다. 시작하려면 아래 단계를 따르세요.
다음 명령어를 실행하여 필수 종속성을 설치합니다:
```bash
pip install -r requirements\_web\_demo.txt
```
브라우저 기반 UI를 실행하여 모델과 상호작용합니다:
```bash
python web\_demo\_mm.py -c /your/path/to/qwen3vl/weig

```
After running the command, you’ll see a link generated in the terminal similar to this:
```
Running on local: http://127.0.0.1:7860/
```
브라우저에서 해당 링크를 열어 모델과 상호작용할 수 있습니다. 텍스트, 이미지 또는 기타 기능을 시도해 보세요. 빠른 시작을 위해 사전 구축된 Docker 이미지를 사용할 수도 있습니다:
```
cd docker && bash run\_web\_demo.sh -c /your/path/to/qwen3vl/weight --port 8881
```
## Deployment
빠른 Qwen3-VL 배포 및 추론을 위해 vLLM 사용을 권장합니다. Qwen3-VL 지원을 활성화하려면 `vllm>=0.11.0`을 설치해야 합니다. 또한 [공식 docker 이미지](#-docker)를 사용할 수도 있습니다.
멀티모달 모델의 온라인 서빙 및 오프라인 추론에 대한 자세한 내용은 [vLLM official documentation](https://docs.vllm.ai/en/latest/serving/multimodal\_inputs.html)을 확인하세요.
### Installation
```bash
pip install accelerate
pip install qwen-vl-utils==0.0.14
# Install the latest version of vLLM 'vllm>=0.11.0'
uv pip install -U vllm
```
### Online Serving
vLLM 또는 SGLang 서버를 시작하여 LLM을 효율적으로 서빙한 다음, OpenAI 스타일 API를 사용하여 접근할 수 있습니다.
다음 실행 명령어는 H100/H200에 적용됩니다. 더 효율적인 배포나 다른 GPU에서의 배포는 [vLLM community guide](https://docs.vllm.ai/projects/recipes/en/latest/Qwen/Qwen3-VL.html)를 참고해 주세요.
\* vLLM server
```shell
# Efficient inference with FP8 checkpoint
# Requires NVIDIA H100+ and CUDA 12+
vllm serve Qwen/Qwen3-VL-235B-A22B-Instruct-FP8 \
--tensor-parallel-size 8 \
--mm-encoder-tp-mode data \
--enable-expert-parallel \
--async-scheduling \
--media-io-kwargs '{"video": {"num\_frames": -1}}' \
--host 0.0.0.0 \
--port 22002
```
\* SGLang server
```
python -m sglang.launch\_server \
--model-path Qwen/Qwen3-VL-235B-A22B-Instruct \
--host 0.0.0.0 \
--port 22002 \
--tp 4
```
\* Image Request Example
```python
import time
from openai import OpenAI
client = OpenAI(
api\_key="EMPTY",
base\_url="http://127.0.0.1:22002/v1",
timeout=3600
)
messages = [
{
"role": "user",
"content": [
{
"type": "image\_url",
"image\_url": {
"url": "https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png"
}
},
{
"type": "text",
"text": "Read all the text in the image."
}
]
}
]
start = time.time()
response = client.chat.completions.create(
model="Qwen/Qwen3-VL-235B-A22B-Instruct-FP8",
messages=messages,
max\_tokens=2048
)
print(f"Response costs: {time.time() - start:.2f}s")
print(f"Generated text: {response.choices[0].message.content}")
```
\* Video Request Example
```python
import time
from openai import OpenAI
client = OpenAI(
api\_key="EMPTY",
base\_url="http://127.0.0.1:22002/v1",
timeout=3600
)
messages = [
{
"role": "user",
"content": [
{
"type": "video\_url",
"video\_url": {
"url": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen2-VL/space\_woaudio.mp4"
}
},
{
"type": "text",
"text": "How long is this video?"
}
]
}
]
start = time.time()
# When vLLM is launched with `--media-io-kwargs '{"video": {"num\_frames": -1}}'`,
# video frame sampling can be configured via `extra\_body` (e.g., by setting `fps`).
# This feature is currently supported only in vLLM.
#
# By default, `fps=2` and `do\_sample\_frames=True`.
# With `do\_sample\_frames=True`, you can customize the `fps` value to set your desired video sampling rate.
response = client.chat.completions.create(
model="Qwen/Qwen3-VL-235B-A22B-Instruct-FP8",
messages=messages,
max\_tokens=2048,
extra\_body={"mm\_processor\_kwargs": {"fps": 2, "do\_sample\_frames": True}}
)
print(f"Response costs: {time.time() - start:.2f}s")
print(f"Generated text: {response.choices[0].message.content}")
```
### Offline Inference
vLLM 또는 SGLang을 사용하여 로컬에서 Qwen3-VL 추론을 수행할 수도 있습니다:
\* vLLM Examples
``` python
# -\*- coding: utf-8 -\*-
import torch
from qwen\_vl\_utils import process\_vision\_info
from transformers import AutoProcessor
from vllm import LLM, SamplingParams
import os
os.environ['VLLM\_WORKER\_MULTIPROC\_METHOD'] = 'spawn'
def prepare\_inputs\_for\_vl
```

lm(messages, processor):
text = processor.apply\_chat\_template(messages, tokenize=False, add\_generation\_prompt=True)
# qwen\_vl\_utils 0.0.14+ reqired
image\_inputs, video\_inputs, video\_kwargs = process\_vision\_info(
messages,
image\_patch\_size=processor.image\_processor.patch\_size,
return\_video\_kwargs=True,
return\_video\_metadata=True
)
print(f"video\_kwargs: {video\_kwargs}")
mm\_data = {}
if image\_inputs is not None:
mm\_data['image'] = image\_inputs
if video\_inputs is not None:
mm\_data['video'] = video\_inputs
return {
'prompt': text,
'multi\_modal\_data': mm\_data,
'mm\_processor\_kwargs': video\_kwargs
}
if \_\_name\_\_ == '\_\_main\_\_':
# messages = [
# {
# "role": "user",
# "content": [
# {
# "type": "video",
# "video": "https://qianwen-res.oss-cn-beijing.aliyuncs.com/Qwen2-VL/space\_woaudio.mp4",
# },
# {"type": "text", "text": "这段视频有多长"},
# ],
# }
# ]
messages = [
{
"role": "user",
"content": [
{
"type": "image",
"image": "https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png",
},
{"type": "text", "text": "Read all the text in the image."},
],
}
]
# TODO: change to your own checkpoint path
checkpoint\_path = "Qwen/Qwen3-VL-235B-A22B-Instruct-FP8"
processor = AutoProcessor.from\_pretrained(checkpoint\_path)
inputs = [prepare\_inputs\_for\_vllm(message, processor) for message in [messages]]
llm = LLM(
model=checkpoint\_path,
mm\_encoder\_tp\_mode="data",
enable\_expert\_parallel=True,
tensor\_parallel\_size=torch.cuda.device\_count(),
seed=0
)
sampling\_params = SamplingParams(
temperature=0,
max\_tokens=1024,
top\_k=-1,
stop\_token\_ids=[],
)
for i, input\_ in enumerate(inputs):
print()
print('=' \* 40)
print(f"Inputs[{i}]: {input\_['prompt']=!r}")
print('\n' + '>' \* 40)
outputs = llm.generate(inputs, sampling\_params=sampling\_params)
for i, output in enumerate(outputs):
generated\_text = output.outputs[0].text
print()
print('=' \* 40)
print(f"Generated text: {generated\_text!r}")
```
\* SGLang 예제
```python
import time
from PIL import Image
from sglang import Engine
from qwen\_vl\_utils import process\_vision\_info
from transformers import AutoProcessor, AutoConfig
if \_\_name\_\_ == "\_\_main\_\_":
# TODO: change to your own checkpoint path
checkpoint\_path = "Qwen/Qwen3-VL-235B-A22B-Instruct"
processor = AutoProcessor.from\_pretrained(checkpoint\_path)
messages = [
{
"role": "user",
"content": [
{
"type": "image",
"image": "https://ofasys-multimodal-wlcb-3-toshanghai.oss-accelerate.aliyuncs.com/wpf272043/keepme/image/receipt.png",
},
{"type": "text", "text": "Read all the text in the image."},
],
}
]
text = processor.apply\_chat\_template(
messages,
tokenize=False,
add\_generation\_prompt=True
)
image\_inputs, \_ = process\_vision\_info(messages, image\_patch\_size=processor.image\_processor.patch\_size)
llm = Engine(
model\_path=checkpoint\_path,
enable\_multimodal=True,
mem\_fraction\_static=0.8,
tp\_size=4,
attention\_backend="fa3",
context\_length=10240,
disable\_cuda\_graph=True,
)
start = time.time()
sampling\_params = {"max\_new\_tokens": 1024}
response = llm.generate(prompt=text, image\_data=image\_inputs, sampling\_params=sampling\_params)
print(f"Response costs: {time.time() - start:.2f}s")
print(f"Generated text: {response['text']}")
```
## 평가 재현
보고된 결과의 충실한 재현을 돕기 위해, 공식 평가 설정은 다음과 같습니다.
- 추론 런타임: [vLLM](https://github.com/vllm-project/vllm)
- 평가 프레임워크: [VLMEvalKit](https://github.com/open-compass/VLMEvalKit), [lmms-eval](https://github.com/EvolvingLMMs-Lab/lmms-eval)
- 참고 사항:
- 일부 벤치마크의 경우 평가 프롬프트를 약간 수정했으며, 자세한 변경 사항은 향후 기술 보고서에 문서화될 예정입니다.
- 소수의 벤치마크는 내부적으로 구축되었으며, 코드 및 재현 자산은 추후 공개할 예정입니다.
### 생성 하이퍼파라미터
#### Instruct 모델
```bash
export greedy='false'
expo

rt seed=3407
export top\_p=0.8
export top\_k=20
export temperature=0.7
export repetition\_penalty=1.0
export presence\_penalty=1.5
export out\_seq\_length=32768
```
#### Thinking models
```bash
export greedy='false'
export seed=1234
export top\_p=0.95
export top\_k=20
export repetition\_penalty=1.0
export presence\_penalty=0.0
export temperature=0.6
export out\_seq\_length=40960
```
## 🐳 Docker
배포 과정을 간소화하기 위해 미리 빌드된 환경이 포함된 docker 이미지를 제공합니다: [qwenllm/qwenvl](https://hub.docker.com/r/qwenllm/qwenvl). 데모를 실행하려면 드라이버를 설치하고 모델 파일만 다운로드하면 됩니다.
```bash
docker run --gpus all --ipc=host --network=host --rm --name qwen3vl -it qwenllm/qwenvl:qwen3vl-cu128 bash
```
## Citation
저희의 논문과 코드가 연구에 유용하다고 생각되신다면, star :star:와 citation :pencil:을 남겨주세요 :)
```BibTeX
@article{Qwen3-VL,
title={Qwen3-VL Technical Report},
author={Shuai Bai and Yuxuan Cai and Ruizhe Chen and Keqin Chen and Xionghui Chen and Zesen Cheng and Lianghao Deng and Wei Ding and Chang Gao and Chunjiang Ge and Wenbin Ge and Zhifang Guo and Qidong Huang and Jie Huang and Fei Huang and Binyuan Hui and Shutong Jiang and Zhaohai Li and Mingsheng Li and Mei Li and Kaixin Li and Zicheng Lin and Junyang Lin and Xuejing Liu and Jiawei Liu and Chenglong Liu and Yang Liu and Dayiheng Liu and Shixuan Liu and Dunjie Lu and Ruilin Luo and Chenxu Lv and Rui Men and Lingchen Meng and Xuancheng Ren and Xingzhang Ren and Sibo Song and Yuchong Sun and Jun Tang and Jianhong Tu and Jianqiang Wan and Peng Wang and Pengfei Wang and Qiuyue Wang and Yuxuan Wang and Tianbao Xie and Yiheng Xu and Haiyang Xu and Jin Xu and Zhibo Yang and Mingkun Yang and Jianxin Yang and An Yang and Bowen Yu and Fei Zhang and Hang Zhang and Xi Zhang and Bo Zheng and Humen Zhong and Jingren Zhou and Fan Zhou and Jing Zhou and Yuanzhi Zhu and Ke Zhu},
journal={arXiv preprint arXiv:2511.21631},
year={2025}
}
@article{Qwen2.5-VL,
title={Qwen2.5-VL Technical Report},
author={Bai, Shuai and Chen, Keqin and Liu, Xuejing and Wang, Jialin and Ge, Wenbin and Song, Sibo and Dang, Kai and Wang, Peng and Wang, Shijie and Tang, Jun and Zhong, Humen and Zhu, Yuanzhi and Yang, Mingkun and Li, Zhaohai and Wan, Jianqiang and Wang, Pengfei and Ding, Wei and Fu, Zheren and Xu, Yiheng and Ye, Jiabo and Zhang, Xi and Xie, Tianbao and Cheng, Zesen and Zhang, Hang and Yang, Zhibo and Xu, Haiyang and Lin, Junyang},
journal={arXiv preprint arXiv:2502.13923},
year={2025}
}
@article{Qwen2-VL,
title={Qwen2-VL: Enhancing Vision-Language Model's Perception of the World at Any Resolution},
author={Wang, Peng and Bai, Shuai and Tan, Sinan and Wang, Shijie and Fan, Zhihao and Bai, Jinze and Chen, Keqin and Liu, Xuejing and Wang, Jialin and Ge, Wenbin and Fan, Yang and Dang, Kai and Du, Mengfei and Ren, Xuancheng and Men, Rui and Liu, Dayiheng and Zhou, Chang and Zhou, Jingren and Lin, Junyang},
journal={arXiv preprint arXiv:2409.12191},
year={2024}
}
@article{Qwen-VL,
title={Qwen-VL: A Versatile Vision-Language Model for Understanding, Localization, Text Reading, and Beyond},
author={Bai, Jinze and Bai, Shuai and Yang, Shusheng and Wang, Shijie and Tan, Sinan and Wang, Peng and Lin, Junyang and Zhou, Chang and Zhou, Jingren},
journal={arXiv preprint arXiv:2308.12966},
year={2023}
}
```

Qwen3-VL

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README