모델별 실행 레시피

Qwen3-Omni 로컬 실행 조건: 음성·영상 경로 확인

음성과 영상이 된다는 말만으로 내 장비에서 바로 실행되지는 않습니다.

Qwen3-Omni Instruct는 텍스트·오디오·비디오 입력을 받고 텍스트 또는 오디오를 출력할 수 있는 thinker와 talker 구성을 포함합니다. 모델 카드의 기능 지원과 로컬 런타임¹·하드웨어 지원은 별개입니다. 공식 저장소가 안내하는 Transformers 및 vLLM 경로 중 작업에 맞는 구현을 확인하고, 오디오 한 건부터 입출력 모달리티와 메모리를 검증한 뒤 영상으로 확장하세요.

실행 조건과 핵심 내용

Thinker는 지시·인식·추론을 담당하고 talker가 음성 출력 경로를 맡습니다.
모델 카드의 모달리티 지원과 로컬 inference backend의 기능 지원을 구분합니다.
입력 음성, 입력 영상, 텍스트 출력, 음성 출력 경로를 각각 작은 샘플로 확인합니다.
영상 길이와 frame 수가 메모리와 처리 시간에 미치는 영향을 기록합니다.

원하는 대화 입출력 조합부터 고릅니다

Qwen3-Omni를 로컬 음성 비서나 영상 요약에 쓰고 싶다면 우선 입출력 조합을 정해야 합니다. 마이크 음성을 받아 텍스트로 답할지, 음성으로 말하게 할지, 짧은 영상과 질문을 함께 보내 장면을 요약할지에 따라 필요한 모델 경로가 달라집니다. ‘멀티모달 모델’이라는 이름만 보고 모든 런타임에서 이 조합이 지원된다고 가정하면 안 됩니다.

공식 Instruct 구성은 thinker와 talker 계열을 포함합니다. Thinker는 텍스트·오디오·비디오 신호를 이해하고 답변을 구성하는 역할이며, talker 경로는 음성 생성에 관여합니다. 텍스트 입력/출력만 먼저 확인하고 나서 오디오·비디오 토큰² 경로를 추가하면 어느 단계에서 실패하는지 좁히기 쉽습니다.

필요한 것은 모델 카드에 접근할 수 있는 네트워크, 선택한 backend의 설치 환경, 저장공간과 충분한 메모리, 시험용 음성 또는 영상 파일입니다. 실제 작업 파일이나 개인정보가 담긴 녹음을 처음부터 쓰지 말고 짧은 비민감 샘플로 시작하세요. 모델 가중치와 입력 파일을 내려받은 뒤 네트워크 연결을 끊고 테스트할 수 있는지도 별도로 검증하면 데이터가 외부로 전송되지 않는지 확인하는 데 도움이 됩니다.

모델 기능, 실행 경로, 작업 유형을 구분해 테스트 순서를 정합니다.
작업	먼저 확인할 경로	검증 질문
텍스트 대화	Thinker 입력·출력	모델과 템플릿이 로드되는가?
음성 이해	audio input 전처리·인식	질문 내용이 정확히 전사·해석되는가?
음성 응답	Talker 음성 출력	생성된 음성이 저장·재생되는가?
영상 질문	video frame 샘플링·Thinker	시간 정보와 주요 장면이 반영되는가?

모델 기능, 실행 경로, 작업 유형을 구분해 테스트 순서를 정합니다.

텍스트 대화

먼저 확인할 경로: Thinker 입력·출력
검증 질문: 모델과 템플릿이 로드되는가?

음성 이해

먼저 확인할 경로: audio input 전처리·인식
검증 질문: 질문 내용이 정확히 전사·해석되는가?

음성 응답

먼저 확인할 경로: Talker 음성 출력
검증 질문: 생성된 음성이 저장·재생되는가?

영상 질문

먼저 확인할 경로: video frame 샘플링·Thinker
검증 질문: 시간 정보와 주요 장면이 반영되는가?

마이크와 웹캠, 스피커가 연결된 로컬 컴퓨터 책상 — 모델이 지원하는 기능과 내 주변기기·실행 경로 호환성을 구분하세요.

백엔드 지원 범위를 먼저 고정합니다

검증 가능한 참조 경로는 Linux NVIDIA GPU³에서 Hugging Face Transformers로 공식 `Qwen3OmniMoeForConditionalGeneration`과 processor를 올려 음성 파일 한 건을 넣는 방법입니다. Qwen 팀은 Transformers 5.2.0 이상, accelerate, qwen-omni-utils, ffmpeg를 안내하며 FlashAttention⁴ 2는 호환 CUDA⁵ GPU와 FP16/BF16에서 선택적으로 사용할 수 있습니다. 큰 serving workload에는 vLLM-Omni도 공식 선택지입니다.

아래 예제는 Apple Silicon 지원 경로가 아닙니다. macOS/MLX 경로의 Qwen3-Omni 공식 지원 여부와 모든 음성·영상 기능 호환은 확인되지 않았으므로 해당 조합으로 실행한다고 가정하지 않습니다. Apple 장비를 목표로 한다면 공식 변환 checkpoint⁶와 processor·audio/video backend 지원이 확인될 때까지 경로를 보류하세요.

모델은 30B-A3B checkpoint이며 로드에 큰 GPU 메모리와 로컬 저장공간이 필요합니다. 공식 메모리 표는 Transformers+FlashAttention 2 BF16⁷ 조건입니다. 설치 전에 GPU, CUDA/PyTorch 조합, checkpoint 저장 공간을 확인하고, 정밀도나 backend를 바꾸면 요구량과 기능이 달라질 수 있음을 염두에 두세요.

공식 Transformers 실행 환경 설치

python -m venv .venv
source .venv/bin/activate
python -m pip install -U 'transformers>=5.2.0' accelerate qwen-omni-utils soundfile
# Install a PyTorch build matched to your CUDA and GPU from the official PyTorch selector.
python -m pip install -U flash-attn --no-build-isolation
ffmpeg -version

공식 예제의 패키지 조건을 맞춘 뒤 짧은 WAV 파일을 준비합니다. Linux CUDA GPU용 경로이며 Mac용 MLX 명령이 아닙니다.

먼저 짧은 오디오 하나를 끝까지 왕복합니다

비민감한 짧은 WAV 파일을 `sample.wav`로 저장한 뒤 아래 코드를 실행합니다. conversation에 로컬 파일 경로를 넣고 `process_mm_info`로 오디오를 준비해 thinker의 텍스트 답을 출력합니다. 첫 실행은 큰 checkpoint를 내려받고 로드하므로 오래 걸리고 큰 GPU 메모리를 쓸 수 있습니다. 파일 오류라면 codec/sample rate, ffmpeg와 `qwen-omni-utils`부터 확인합니다.

다음으로 talker가 포함된 경로에서 음성 출력을 시험합니다. 같은 답변을 text와 audio로 각각 출력할 수 있는지, 생성 파일이 재생되는지 확인합니다. 응답이 텍스트만 나오면 요청 형식·backend 제한·모델 구성 중 어느 쪽이 원인인지 공식 실행 예제와 대조합니다. 모든 오디오 입출력을 한 번에 켜면 입력 인식과 음성 생성 오류를 구분하기 어렵습니다.

실행 시간은 모델 로드와 입력 처리, 첫 텍스트 응답, 전체 응답까지 나눠 기록합니다. cold와 warm 실행을 구분하고 같은 파일에서 반복합니다. 아래 코드는 text response만 요청하며 talker 음성 출력은 포함하지 않습니다.

로컬 WAV 한 개를 입력하고 텍스트 답변 받기

from transformers import Qwen3OmniMoeForConditionalGeneration, Qwen3OmniMoeProcessor
from qwen_omni_utils import process_mm_info

model_id = 'Qwen/Qwen3-Omni-30B-A3B-Instruct'
model = Qwen3OmniMoeForConditionalGeneration.from_pretrained(
    model_id, dtype='auto', device_map='auto', attn_implementation='flash_attention_2'
)
processor = Qwen3OmniMoeProcessor.from_pretrained(model_id)
messages = [{'role': 'user', 'content': [
    {'type': 'audio', 'audio': './sample.wav'},
    {'type': 'text', 'text': 'Summarize the spoken message in one sentence.'},
]}]
text = processor.apply_chat_template(messages, add_generation_prompt=True, tokenize=False)
audios, images, videos = process_mm_info(messages, use_audio_in_video=False)
inputs = processor(text=text, audio=audios, images=images, videos=videos,
                    return_tensors='pt', padding=True, use_audio_in_video=False)
inputs = inputs.to(model.device).to(model.dtype)
text_ids, _ = model.generate(**inputs, return_audio=False, thinker_return_dict_in_generate=True)
answer = processor.batch_decode(
    text_ids.sequences[:, inputs['input_ids'].shape[1]:],
    skip_special_tokens=True, clean_up_tokenization_spaces=False
)
print(answer)

sample.wav는 로컬 파일 경로입니다. 공식 Transformers 예제로 짧은 음성 파일을 읽고 텍스트 답변이 나오는지 확인합니다.

영상 클립, 음성 파형, 문서 페이지가 로컬 AI 처리 화면에 입력되는 모습 — 입력 모달리티를 한 번에 섞기보다 한 경로씩 시험합니다.

영상은 길이와 프레임 수를 기록하며 늘립니다

오디오 테스트가 성공한 뒤 5초 정도의 짧은 영상에 질문을 보냅니다. 영상은 디코딩된 프레임⁸을 모델에 전달하는 경로와 시간 정보가 함께 중요합니다. 영상 파일 크기만 같아도 초당 sampling frame 수와 해상도가 다르면 입력량이 달라집니다. 먼저 공식 예제가 사용하는 영상 전처리와 frame sampling을 그대로 따라 짧은 클립을 확인합니다.

공식 모델 카드의 메모리 수치는 BF16 Transformers와 FlashAttention 2를 사용한 이론적 조건입니다. 카드 예시에서 15초 영상에 약 78.85GB, 120초 영상에 약 144.81GB를 제시합니다. 이 값은 모든 backend의 실제 최소 메모리도 아니고 작은 quantized 모델의 결과도 아닙니다. 다만 긴 영상을 무심코 입력하는 작업은 메모리 요구량이 크게 커질 수 있다는 경고로 읽어야 합니다.

클립 길이만 늘리기보다 frame rate와 해상도를 하나씩 바꾸고 입력 frame 수와 peak memory를 기록합니다. 답에 시간 흐름이 필요하다면 ‘마지막 프레임에 무엇이 있나요?’만 묻지 말고 사건 순서를 묻는 질문도 추가합니다. frame sampling이 바뀌면 모델이 본 내용도 달라지므로 결과의 속도와 정답률을 한 조건처럼 비교할 수 없습니다.

짧은 영상 시험에서는 입력량과 응답 품질을 함께 적습니다.
변경할 항목	기록할 값	품질 확인
클립 길이	초·입력 frame 수	사건 순서와 시작/종료 장면
해상도	원본 및 processor 크기	작은 글자·물체 구분
프레임 샘플링	frame 간격	중간 행동 누락 여부
질문	고정 prompt	영상에 없는 내용 생성 여부

짧은 영상 시험에서는 입력량과 응답 품질을 함께 적습니다.

클립 길이

기록할 값: 초·입력 frame 수
품질 확인: 사건 순서와 시작/종료 장면

해상도

기록할 값: 원본 및 processor 크기
품질 확인: 작은 글자·물체 구분

프레임 샘플링

기록할 값: frame 간격
품질 확인: 중간 행동 누락 여부

질문

기록할 값: 고정 prompt
품질 확인: 영상에 없는 내용 생성 여부

그래픽 처리 장치와 메모리 여유 표시를 갖춘 로컬 PC 작업 공간 — 영상 길이와 프레임 수를 늘릴 때 메모리 여유를 함께 살핍니다.

대기 시간과 메모리에서 병목을 찾습니다

멀티모달 대화는 파일을 읽는 전처리, vision/audio encoder, thinker의 prefill⁹, 생성 decode¹⁰, talker 출력이 이어질 수 있습니다. 전체 시간이 늘어도 어느 단계가 원인인지 확인하지 않으면 ‘모델이 느리다’는 결론만 남습니다. 실행 로그에서 확인 가능한 세부 시간을 기록하고, 지원되지 않는 모니터링 값을 추측해 채우지 마세요.

메모리가 부족하면 모델 가중치와 입력 길이, 영상 frame 수, 동시에 살아 있는 대화 수, 다른 앱 점유를 나눠 봅니다. 영상 길이를 줄였을 때 안정화되는지 먼저 시험하고, 음성 입력과 영상 입력을 동시에 쓸 필요가 없다면 각각 처리하는 경로와 비교하세요. 모델 카드의 이론적 메모리 조건과 실행 중 실제 메모리 사용량을 같은 값으로 취급하지 않습니다.

목표가 실시간 대화라면 첫 반응 시간과 음성 출력이 시작되는 시점을 우선 봅니다. 긴 녹음 요약처럼 배치 작업이라면 전체 처리 시간과 메모리 안정성에 더 큰 비중을 둡니다. 특정 하드웨어나 backend에서 작업이 실패한다면 unsupported path로 표시하고, 더 작은 모델이나 공식 지원 serving 환경을 검토합니다.

공식 모델·실행 문서와 라이선스

모달리티와 backend 지원은 모델과 런타임의 release에 따라 달라질 수 있습니다. 실제 배포 전 공식 저장소와 모델 카드에서 요구 버전, 사용 조건, 제한 사항을 다시 확인하세요. 이 안내는 로컬 장비 성능을 측정하지 않았습니다.

용어 각주

런타임 — 프로그램이 실행될 때 필요한 기능을 제공하는 소프트웨어 환경입니다. 로컬 AI에서는 모델을 실행하는 엔진을 가리키기도 하며, GPU 런타임 라이브러리와 완성된 서빙 앱은 서로 다른 구성요소입니다.
본문으로 돌아가기
토큰 — 모델이 입력이나 출력을 나누어 처리하는 단위입니다. 토큰 하나가 글자 하나나 일정한 시간 길이에 해당하지는 않습니다.
본문으로 돌아가기
GPU — 많은 계산을 병렬로 처리하는 프로세서입니다. AI 모델 실행에서는 모델 계산을 맡습니다.
본문으로 돌아가기
FlashAttention — 어텐션 계산에서 메모리 접근을 효율화하는 구현입니다. 사용 가능 여부와 효과는 하드웨어, 모델, 실행 환경에 따라 다릅니다.
본문으로 돌아가기
CUDA — NVIDIA GPU에서 범용 계산을 실행하기 위한 소프트웨어 플랫폼입니다. CUDA용으로 만든 프로그램은 다른 GPU에서 그대로 동작한다고 보장되지 않습니다.
본문으로 돌아가기
체크포인트 — 학습된 모델의 가중치 등을 저장한 파일입니다. 같은 모델 계열도 버전이나 용도에 따라 다른 체크포인트를 쓸 수 있습니다.
본문으로 돌아가기
BF16 — 모델의 수를 저장하고 계산하는 16비트 부동소수점 형식입니다. 사용 가능 여부는 하드웨어와 실행 프로그램에 달려 있습니다.
본문으로 돌아가기
프레임 — 영상의 한 장면을 이루는 단일 이미지입니다. 초당 프레임 수와 프레임 해상도는 서로 다른 속성입니다.
본문으로 돌아가기
프리필 — LLM이 입력 프롬프트를 읽고 각 토큰의 내부 표현을 계산하는 단계입니다. 입력이 길수록 처리할 토큰이 많아집니다.
본문으로 돌아가기
디코드 — LLM에서는 입력 처리 뒤 출력 토큰을 생성하는 단계를 뜻합니다. VAE나 오디오 코덱에서는 압축 표현이나 인코딩 데이터를 원래 형식으로 복원하는 처리를 가리킬 수 있습니다.
본문으로 돌아가기