logo

Qwen 2.5 튜토리얼: 빠른 시작, 배포, 그리고 실제 활용 사례

최신 업데이트: 2025-09-05 12:32:56

인공지능은 이제 텍스트만 처리하는 모델을 넘어, 단어와 이미지, 심지어 비디오까지 이해할 수 있는 멀티모달 시대로 급속히 발전하고 있습니다. 이 변화는 자연스러운 문서 자동화, 지능형 튜터링, 멀티미디어 분석 등 더 직관적이고 강력한 애플리케이션의 문을 열고 있습니다.

알리바바 클라우드에서 개발한 Qwen 2.5는 오늘날 가장 발전된 오픈소스 멀티모달 모델 중 하나입니다. 이 모델은 언어 이해, 고해상도 이미지 처리, 비디오 추론을 한 시스템에서 제공합니다. 많은 폐쇄형 플랫폼과 달리, Qwen 2.5는 연구와 상업적 목적으로 자유롭게 사용할 수 있어, 실용적인 AI 솔루션을 개발하려는 개발자, 스타트업, 기업 모두에게 매력적인 선택입니다.

이 가이드에서는 Qwen 2.5를 어떻게 시작하는지 설명합니다. 설치 방법, 빠른 시작 예시, 다양한 배포 방식, 그리고 실제 활용 사례까지 다루며, 여러분의 프로젝트에 모델을 적용할 수 있도록 돕습니다.

Qwen 2.5-VL이란?

Qwen 2.5-VL은 Tongyi Qianwen 프로젝트에서 나온 최신 비전-언어 모델입니다. 대규모 언어 처리에 고해상도 이미지 분석, 비디오 이해 기능을 결합했습니다. 이 모델군은 3B, 7B, 32B, 72B 파라미터의 다양한 버전으로 구성되어 있습니다. 작은 모델은 로컬 실험에 적합하며, 큰 모델은 엔터프라이즈급 작업에서 최첨단 성능을 보여줍니다. 최대 128,000 토큰의 컨텍스트 길이를 지원해, 책 한 권이나 긴 대화도 처리할 수 있습니다. GPT-4V나 Gemini와 달리 Qwen은 완전 오픈소스로 제공되며, 유연하게 도입이 가능합니다.

설치 및 준비

환경과 라이선스

Qwen 2.5-VL은 아파치 2.0 라이선스로 공개되어 있습니다. 즉, 완전한 오픈소스로 연구와 상업 프로젝트 모두 자유롭게 사용할 수 있습니다.

모델 크기와 컨텍스트 지원

모델군은 3B, 7B, 32B, 72B 등 다양한 파라미터 크기를 지원합니다. 작은 모델은 로컬에서 쉽게 실행 가능하고, 가장 큰 모델은 최고 성능을 제공하지만 서버급 GPU가 필요합니다. 72B 버전을 제외한 모든 모델이 오픈 라이선스 적용을 받습니다. Qwen 2.5-VL은 최대 128,000 토큰까지 긴 컨텍스트 입력을 지원해, 장문의 문서 및 대화 분석에도 적합합니다.

설치 방법

Hugging Face Transformers와 함께 모델을 설정하려면 필요한 패키지를 설치하세요:

pip install git+https://github.com/huggingface/transformers accelerate
pip install qwen-vl-utils[decord]==0.0.8

설치 후에는 몇 줄의 파이썬 코드만으로 모델과 프로세서를 로드할 수 있습니다:

from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessor
model = Qwen2_5_VLForConditionalGeneration.from_pretrained("Qwen/Qwen2.5-VL-7B-Instruct", torch_dtype="auto", device_map="auto")
processor = AutoProcessor.from_pretrained("Qwen/Qwen2.5-VL-7B-Instruct")

하드웨어 및 양자화

  • 3B와 7B 버전은 최신 GPU 한 대에서 실행할 수 있으며, 특히 양자화 모델 사용 시 더욱 원활합니다.
  • 32B와 72B 모델은 더 강력한 멀티 GPU 구성이 필요합니다.
  • INT8 또는 INT4와 같은 양자화 옵션은 메모리 사용량을 줄여 로컬 배포를 더 실용적으로 만드는 동시에 적절한 정확도를 유지합니다.

Transformers로 빠른 시작

환경이 준비되면, Qwen 2.5-VL을 몇 줄의 코드로 바로 사용할 수 있습니다. Hugging Face Transformers 라이브러리는 텍스트, 이미지, 비디오 입력에 간편한 인터페이스를 제공합니다.

모델과 프로세서 로드

from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessorimport torch
model = Qwen2_5_VLForConditionalGeneration.from_pretrained("Qwen/Qwen2.5-VL-7B-Instruct",
   torch_dtype=torch.float16,
   device_map="auto")
processor = AutoProcessor.from_pretrained("Qwen/Qwen2.5-VL-7B-Instruct")

이미지 질의응답

예를 들어, 인보이스 이미지에서 정보를 추출하고 싶을 때:

from PIL import Image
image = Image.open("invoice_sample.png")
question = "이 인보이스의 총액은 얼마입니까?"inputs = processor(text=question, images=image, return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=128)print(processor.batch_decode(outputs, skip_special_tokens=True))

비디오 이해

Qwen 2.5-VL은 비디오 입력도 지원하여, 클립을 요약하거나 분석할 수 있습니다:

video_path = "meeting_clip.mp4"question = "이 비디오의 주요 토론 내용을 요약하세요."inputs = processor(text=question, videos=video_path, return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=256)print(processor.batch_decode(outputs, skip_special_tokens=True))

멀티모달 입력

여러 이미지를 동시에 입력하거나, 이미지와 비디오를 함께 넣어 복잡한 추론을 요청할 수도 있습니다.

웹 데모와 Ollama로 로컬 배포

Qwen 2.5-VL은 API 호출이나 파이썬 스크립트에만 국한되지 않습니다. 친숙한 인터페이스와 가벼운 런타임 환경으로 로컬에서 직접 모델을 실행할 수 있습니다.

로컬 테스트용 웹 데모

공식 저장소에는 간단한 웹 기반 인터페이스를 실행하는 web_demo_mm 스크립트가 포함되어 있습니다. 이 데모를 통해 이미지를 업로드하거나 동영상 파일을 올리고, 챗 형식으로 모델과 상호작용할 수 있습니다. 복잡한 코드를 작성하지 않고도 멀티모달 기능을 빠르게 시험해볼 수 있습니다.

데모를 시작하려면, 프로젝트 디렉터리에서 다음 명령을 실행하세요:

python web_demo_mm.py

앱이 실행되면 브라우저에서 인터페이스에 접근할 수 있고, 프롬프트 입력이나 미디어 업로드가 가능합니다. 빠른 실험과 프로토타이핑에 적합한 환경입니다.

실시간 비디오 채팅 데모

개발자가 제공하는 또 다른 예시는 실시간 비디오 채팅 데모입니다. 이 버전은 웹캠이나 비디오 소스로부터 입력을 스트리밍하며, 실시간으로 영상 내용을 모델에 질문할 수 있습니다. Qwen 2.5-VL의 역동적 환경에서의 강력함을 보여주는 예입니다.

Ollama에서 Qwen 실행하기

더 간편한 환경을 원한다면, Qwen 2.5는 Ollama에서도 지원됩니다. Ollama는 대형 모델을 로컬에서 쉽게 실행할 수 있는 환경을 제공합니다. 설치 후에는 단일 명령어로 Qwen 2.5 모델을 내려받아 곧바로 상호작용할 수 있어 복잡한 설정 없이 사용할 수 있습니다.

이 방법은 파이썬 환경에 익숙하지 않거나, 최소한의 구성으로 노트북이나 데스크톱에서 Qwen을 테스트해보고 싶은 분께 특히 유용합니다.

공통 활용 사례: 제로샷 객체 탐지

Qwen 2.5-VL을 실용적으로 활용할 수 있는 대표적인 방법은 제로샷 객체 탐지입니다. 기존 컴퓨터 비전 시스템은 라벨링된 학습 데이터가 필요하지만, Qwen은 찾아야 할 사물에 대한 자연어 설명만으로도 객체를 탐지할 수 있습니다.

예를 들어 “테이블 위의 모든 컵” 또는 “이 사진에서 모든 신호등”을 찾으라고 요청할 수 있으며, 별도 데이터셋이 없어도 동작합니다. 모델은 심지어 JSON과 같은 구조화된 형식으로 바운딩 박스 좌표를 출력할 수 있어, 자동화 파이프라인에서 바로 활용 가능합니다.

예시 워크플로우

  • 이미지를 입력합니다.
  • Qwen에게 찾고 싶은 객체를 텍스트로 설명해 요청합니다.
  • 모델이 JSON 형태로 좌표와 라벨을 반환합니다.
  • 결과를 시각화하거나 추가 애플리케이션에 통합할 수 있습니다.

예시 코드

from transformers import Qwen2_5_VLForConditionalGeneration, AutoProcessorfrom PIL import Imageimport torch, json
# 모델 및 프로세서 로드model = Qwen2_5_VLForConditionalGeneration.from_pretrained("Qwen/Qwen2.5-VL-7B-Instruct", torch_dtype=torch.float16, device_map="auto")
processor = AutoProcessor.from_pretrained("Qwen/Qwen2.5-VL-7B-Instruct")
# 입력 이미지image = Image.open("street_scene.jpg")
prompt = "이 이미지에서 모든 자동차와 신호등을 탐지하고 JSON으로 결과를 반환하세요."
# 전처리 및 생성inputs = processor(text=prompt, images=image, return_tensors="pt").to("cuda")
outputs = model.generate(**inputs, max_new_tokens=256)
result = processor.batch_decode(outputs, skip_special_tokens=True)
# 출력 파싱 (JSON 형식일 경우)
try:
   parsed = json.loads(result[0])print(parsed)except:print(result)

왜 중요한가?

이 접근법은 값비싼 데이터 라벨링 작업을 줄여줍니다. 개발자는 소매 분석, 교통 모니터링, 로보틱스, 스마트 시티 등 다양한 분야에 Qwen 2.5-VL을 간단히 적용할 수 있습니다.

성능 및 파인튜닝

벤치마크 성능

Qwen 2.5-VL은 문서 질의응답(DocVQA), 광학 문자 인식, 장문 컨텍스트 추론 등 다양한 멀티모달 작업에서 강력한 성능을 검증받았습니다. 많은 오픈소스 대안과 비교해, 복잡한 문서나 비디오 입력 처리에서 특히 좋은 결과를 보입니다.

128K 토큰까지 입력을 지원해, 책이나 보고서, 긴 대화도 컨텍스트를 잃지 않고 대규모 분석이 가능합니다. 이는 장문 추론에 적합한 최고의 오픈소스 모델 중 하나입니다.

파인튜닝 옵션

기본 모델만으로도 충분한 성능을 보여주지만, 많은 개발자는 Qwen 2.5-VL을 특정 도메인에 맞춰서 활용하고 싶어합니다. 파인튜닝 옵션으로는 다음과 같은 방법이 있습니다:

  • 전체 파인튜닝: 모든 모델 파라미터를 업데이트하여 최대한 맞춤화할 수 있는 방식으로, 대규모 컴퓨팅 자원을 가진 조직에 가장 적합합니다.
  • 파라미터 효율적 파인튜닝: LoRA 또는 QLoRA와 같은 기술을 사용해 훨씬 적은 파라미터만 변경하는 방식입니다. 비용이 적게 들고, 실제 환경에서 널리 사용됩니다.
  • 도메인 적응: 의료 이미지, 금융 보고서, 법률 계약서 등 전문 분야의 데이터셋으로 모델을 학습시켜 좁은 분야에서 정확도를 높일 수 있습니다.

양자화 및 최적화

배포를 더욱 실용적으로 만들기 위해, 개발자는 모델을 INT8 또는 INT4 정밀도의 양자화 버전으로 사용할 수 있습니다. 이를 통해 GPU 메모리 사용량이 줄고 추론 속도가 빨라지며, 정확도도 만족할 만한 수준으로 유지됩니다. 이러한 최적화는 Qwen 2.5를 로컬이나 클라우드 환경의 한정된 자원에서 실행할 때 특히 중요합니다.

문제 해결과 팁

디코딩 반복 방지

모델이 때로는 반복적이거나 끝나지 않은 출력을 생성할 수 있습니다. 이를 막기 위해 온도(temperature), top_p, max_new_tokens 등 디코딩 파라미터를 조절하세요. 균형 잡힌 설정은 더 안정적인 응답을 얻을 수 있습니다.

하드웨어 제약

32B나 72B와 같은 대형 모델을 실행하려면 상당한 GPU 메모리가 필요합니다. 메모리 부족 오류가 발생한다면 3B 또는 7B와 같은 작은 모델을 사용하거나, 양자화(INT8 또는 INT4)를 적용하세요. 이 방법들은 VRAM 요구사항을 줄이면서도 실용적인 성능을 제공합니다.

디코더 선택

비디오 입력 작업 시 특정 디코더로 인해 문제가 발생할 수 있습니다. decord 대신 torchcodec 또는 최적화된 다른 라이브러리를 사용하면 안정성과 속도가 개선될 수 있습니다. 필요한 패키지는 최신 버전으로 설치하세요.

프롬프트 엔지니어링

객체 감지나 문서 분석 같은 작업에서는 명확하게 지시하세요. 예를 들어 모델에 "결과를 JSON 형식으로 반환" 또는 "요점을 목록으로 요약"하도록 요청하세요. 명확한 프롬프트는 모호함을 줄이고 결과의 유용성을 높여줍니다.

배치 처리

여러 이미지를 또는 비디오를 처리할 때 입력을 묶어서(batch) 처리하면 시간과 자원을 절약할 수 있습니다. 각각의 파일을 따로 실행하지 말고, 프로세서의 내장 배치 기능을 활용하세요. 이렇게 하면 모델이 연관된 입력 간의 맥락도 잘 유지할 수 있습니다.

결론

Qwen 2.5-VL은 오픈소스 모델이 멀티모달 AI 분야에서 클로즈드 시스템과 견줄 수 있음을 보여줍니다. 강력한 OCR, 비디오 추론, 긴 문맥 처리 능력으로 개발자와 기업 모두에게 실용적인 도구입니다. Apache 2.0 라이선스로 유연하게 사용할 수 있고, 다양한 크기의 모델이 여러 상황에 맞춰 선택할 수 있습니다. 앞으로 오디오와 3D 지원이 추가될 예정이라, Qwen은 최첨단 멀티모달 AI를 구축하는 모든 사용자를 위한 강력한 선택지로 남을 것입니다.

FAQ 및 확장 주제

Qwen 2.5-VL을 API로 사용할 수 있나요?
네. 로컬 배포 외에도 Qwen 2.5-VL은 클라우드 API를 통해 접속할 수 있어 웹 또는 모바일 앱과 쉽게 연동할 수 있습니다.

Qwen 2.5는 어떤 플랫폼을 지원하나요?
모델은 로컬 컴퓨터, 기업 서버, 주요 클라우드 플랫폼에서 배포할 수 있습니다. Docker 이미지도 제공되어 쉽게 설정할 수 있습니다.

적합한 모델 크기는 어떻게 선택하나요?
실험 또는 가벼운 응용에는 3B나 7B 버전을 추천합니다. 더 강력한 하드웨어 자원을 갖춘 기업에서는 32B 또는 72B 버전으로 최대 성능을 누릴 수 있습니다.

Qwen 2.5가 구조화된 출력을 지원하나요?
네. 프롬프트에 따라 JSON, 테이블, 키-값 형식 등 구조화된 결과를 생성할 수 있어 데이터 추출이나 자동 보고에 유용합니다.