2026년 Qwen2.5-VL과 Qwen3-VL 로컬 실행 방법: 문서 OCR 및 비전 가이드

어떤 Qwen 비전 모델을 실행해야 합니까?

Qwen3-VL과 Qwen2.5-VL의 Ollama 태그, 크기, 라이선스

Qwen 비전 모델의 하드웨어 요구사항

• 다운로드 크기는 가중치만 포함합니다: Qwen3-VL 8B는 6.2 GB, Qwen2.5-VL 7B는 6.0 GB입니다. 컨텍스트 캐시와 이미지 인코더에는 컨텍스트 길이와 이미지 크기에 따라 늘어나는 추가 메모리가 필요하므로 다운로드 크기보다 여유를 두십시오.
• 더 작은 선택지: Qwen3-VL 2B(1.9 GB)와 4B(3.3 GB), Qwen2.5-VL 3B(3.2 GB)는 작은 GPU와 노트북에 적합하며, 7B–8B 모델보다 정확도가 낮을 것으로 예상하십시오.
• 더 큰 선택지: Qwen3-VL 30B-A3B(20 GB), Qwen3-VL 32B와 Qwen2.5-VL 32B(21 GB), Qwen2.5-VL 72B(49 GB)는 대형 GPU, 다중 GPU 또는 통합 메모리가 큰 Apple Silicon이 필요합니다.
• 부분 오프로드: 모델이 VRAM에 들어가지 않으면 Ollama가 일부를 시스템 RAM에 둘 수 있습니다. 동작은 하지만 눈에 띄게 느려집니다.
• 소프트웨어: Ollama 라이브러리 페이지에 따라 Qwen3-VL은 Ollama 0.12.7 이상, Qwen2.5-VL은 0.7.0 이상이 필요합니다.

Ollama로 Qwen2.5-VL과 Qwen3-VL 설정하기

1. 1
   Ollama 설치 또는 업데이트
   Why it matters: Qwen2.5-VL은 Ollama 0.7.0 이상, Qwen3-VL은 0.12.7 이상이 필요합니다. `ollama --version`으로 확인하고 필요하면 업데이트하십시오. Ollama는 macOS, Linux, Windows에서 사용할 수 있습니다.
2. 2
   명시적인 태그로 모델 받기
   Why it matters: `qwen3-vl:8b` 또는 `qwen2.5vl:7b`를 사용하십시오. `qwen2-vl:7b`는 Ollama 공식 라이브러리에 없으므로 받기에 실패합니다.
3. 3
   모델을 실행하고 이미지 첨부
   Why it matters: 대화형 모드에서 프롬프트 안에 이미지 파일 경로를 입력하십시오. Ollama가 경로를 감지해 이미지를 불러옵니다.
4. 4
   API로 이미지 전송
   Why it matters: /api/generate 엔드포인트는 data: 접두사가 없는 base64 인코딩 `images` 배열을 받습니다. 애플리케이션(PromptQuorum 포함)은 이렇게 프로그래밍 방식으로 이미지를 전송합니다.
5. 5
   다국어 OCR 확인
   Why it matters: 중국어 또는 일본어 문서 스캔을 전송하고, 추출된 텍스트를 원본과 대조한 뒤에 본격적으로 사용하십시오.

# Step 1 — Install or update Ollama (Qwen3-VL needs 0.12.7+, Qwen2.5-VL needs 0.7.0+)
# macOS
brew install ollama

# Linux
curl -fsSL https://ollama.com/install.sh | sh

# Windows — download from https://ollama.com/download
ollama --version

# Step 2 — Pull a Qwen vision model (explicit tag)
ollama pull qwen3-vl:8b          # 6.2 GB
# or: ollama pull qwen2.5vl:7b   # 6.0 GB

# Step 3 — Run and attach an image (interactive)
ollama run qwen3-vl:8b
>>> Extract every line of text from ./invoice-jp.png

# Step 4 — Send an image through the API
# Encode the image first:  base64 -i scan.png   (macOS)
curl http://localhost:11434/api/generate -d '{
  "model": "qwen3-vl:8b",
  "prompt": "Extract every line of text from this document. Preserve line breaks.",
  "images": ["<base64-encoded-image>"],
  "stream": false
}'

# Step 5 — Verify multilingual OCR
ollama run qwen3-vl:8b
>>> Extract all text from this image: ./contract-zh.png

LM Studio로 Qwen 비전 모델 설정하기

1. 1
   LM Studio 다운로드 및 설치
   Why it matters: 로컬 모델 추론을 위한 크로스 플랫폼 GUI입니다. 터미널이 필요 없습니다.
2. 2
   Qwen 비전 모델 검색
   Why it matters: 모델 브라우저에서 "Qwen3-VL" 또는 "Qwen2.5-VL"을 검색하고, 모델 카드에 비전 지원이 표시된 빌드를 선택하십시오. 양자화는 메모리에 맞추십시오.
3. 3
   모델 로드 및 이미지 첨부
   Why it matters: 채팅 입력창의 이미지 버튼으로 사진이나 스캔을 업로드하십시오. LM Studio가 이를 비전 인코더에 전달합니다.
4. 4
   로컬 서버 시작
   Why it matters: "Start Server" 옵션은 localhost:1234에 OpenAI 호환 API를 제공합니다. 비전 요청은 표준 image_url 콘텐츠 형식을 사용합니다.

// LM Studio — OpenAI-compatible vision request (localhost:1234)
{
  "model": "<model-id-shown-in-LM-Studio>",
  "messages": [
    {
      "role": "user",
      "content": [
        { "type": "text", "text": "Extract all text from this document." },
        {
          "type": "image_url",
          "image_url": { "url": "data:image/png;base64,<base64-encoded-image>" }
        }
      ]
    }
  ]
}

중국어, 일본어 및 다국어 혼합 문서 OCR

• 일반 텍스트 추출: "이 이미지의 모든 텍스트 줄을 추출하십시오. 줄 바꿈과 읽는 순서를 유지하십시오."
• 구조화된 필드: "이것은 일본 송장입니다. 공급업체, 날짜, 소계, 세금, 합계를 key: value 쌍으로 반환하십시오."
• 표 추출: "이 표를 CSV로 추출하십시오. 첫 행을 헤더로 처리하십시오."
• 추출과 번역을 한 번에: "이 이미지에서 중국어 텍스트를 추출한 뒤 영어로 번역하십시오. 둘 다 보여 주십시오."

# Japanese invoice -> structured fields
ollama run qwen3-vl:8b
>>> This is a Japanese invoice. Extract vendor name, invoice date,
    subtotal, consumption tax, and total. Return as key: value pairs.
    ./invoice-jp.png

# Illustrative output format (not a measured result):
# vendor: <vendor name>
# date: <invoice date>
# subtotal: <amount> JPY
# tax: <amount> JPY
# total: <amount> JPY

이미지 Q&A, 스크린샷 분석, 차트 읽기

• 이미지 Q&A: 사진에 대해 "이 이미지에 무엇이 있습니까?"처럼 자유롭게 질문하고, 답변을 이미지와 대조해 확인하십시오.
• 스크린샷 및 UI 분석: UI 스크린샷, 오류 대화상자, 앱 상태를 읽는 것부터 시작하십시오. 두 모델의 카드에는 GUI 에이전트 기능도 설명되어 있지만 이 가이드에서는 다루지 않습니다.
• 차트 및 그래프 읽기: 차트의 구조와 추세를 설명하는 것이 정확한 수치를 추출하는 것보다 잘 작동합니다. 정확한 값은 원본 데이터로 확인하십시오.
• 여러 이미지 비교: 한 번의 요청에 여러 이미지를 보내 버전을 비교하거나 묶음을 설명할 수 있습니다. 몇 장까지 가능한지는 메모리와 컨텍스트 크기에 달려 있습니다.

Qwen2-VL, Qwen2.5-VL, Qwen3-VL 비교

로컬 Qwen 비전 모델을 PromptQuorum에 연결하기

Qwen 비전 모델 문제 해결

• "pull model manifest: file does not exist" 또는 알 수 없는 모델: 해당 태그가 공식 라이브러리에 없습니다. `qwen2-vl:7b`는 사용할 수 없으므로 `ollama pull qwen3-vl:8b` 또는 `ollama pull qwen2.5vl:7b`를 사용하십시오.
• 받기는 성공했지만 모델이 로드되지 않음: Ollama를 업데이트하십시오. Qwen2.5-VL은 0.7.0 이상, Qwen3-VL은 0.12.7 이상이 필요합니다.
• 이미지가 무시되고 모델이 이미지가 없는 것처럼 답함: 파일 경로가 올바르고 읽을 수 있는지 확인하십시오. Ollama API에서는 `images` 배열에 `data:` 접두사가 *없는* 원시 base64를 넣어야 합니다. `data:` 접두사는 LM Studio와 OpenAI 형식 전용입니다.
• CJK 문자가 깨지거나 누락됨: 스캔 해상도가 너무 낮을 수 있습니다. 150–300 DPI로 다시 스캔하고 결과를 비교하십시오.
• 메모리 부족: 더 작은 태그(예: `qwen3-vl:4b` 또는 `qwen2.5vl:3b`)를 선택하거나, 컨텍스트 크기나 이미지 해상도를 줄이거나, CPU와 GPU가 통합 메모리를 공유하는 Apple Silicon을 사용하십시오.
• 송장이나 차트에서 잘못된 숫자가 추출됨: 잡음이 많은 입력에서는 로컬 비전 모델이 숫자를 잘못 읽을 수 있습니다. 스캔 품질을 높이고 숫자 결과는 항상 원본과 대조하십시오.
• PDF가 로드되지 않음: Ollama API는 이미지를 받으며 PDF 파일은 받지 않습니다. 페이지를 먼저 PNG 또는 JPEG로 변환(pdf2image 또는 pypdfium2 사용)한 뒤 각 페이지를 별도 이미지로 전송하십시오.
• LM Studio에 "failed to load model"이 표시됨: 메모리가 부족하거나 비전을 지원하지 않는 빌드를 받았을 수 있습니다. 모델 카드에 비전 지원이 표시되어 있는지 확인하고 더 작은 양자화를 시도하십시오.

관련 자료

• Qwen 3 로컬 실행 방법 — 텍스트 모델 편: Qwen 언어 모델의 Ollama 및 LM Studio 설정.
• 로컬 비전 모델 비교: LLaVA, Llama 3.2 Vision, MiniCPM-V — 다른 로컬 비전 모델의 전체 개요.
• 멀티모달 로컬 LLM: 비전, 오디오, 텍스트 — 멀티모달 모델을 로컬에서 실행하는 방법에 대한 폭넓은 개요.
• Qwen vs Llama vs Mistral — Qwen 텍스트 모델과 대안의 비교.
• 로컬 LLM 하드웨어 가이드 — 로컬 추론에 필요한 VRAM과 GPU.
• 로컬 LLM 가이드 전체 보기

자주 묻는 질문