1. 개요

Qwen3.5-9B는 알리바바 클라우드에서 개발한 최신 다중모달 대규모 언어 모델로, 고성능 추론과 다양한 응용 시나리오를 지원합니다. 본 문서는 app.py 스크립트를 통해 이 모델의 웹 서비스를 로컬 환경에 구동하는 방법을 단계별로 안내합니다.

주요 사양

• 모델 경로: unsloth/Qwen3.5-9B
• 인터페이스 프레임워크: Gradio 기반 UI
• 기본 포트: 7860
• 필수 장비: CUDA 호환 GPU

2. 실행 환경 설정

2.1 하드웨어 요구사항

원활한 모델 로딩 및 추론을 위해 다음 사양을 권장합니다:

• GPU: NVIDIA A10, T4 이상 (FP16 지원 필수)
• VRAM: 최소 16GB
• RAM: 32GB 이상
• 디스크 공간: 50GB 이상 (모델 파일 포함)

2.2 파이썬 패키지 설치

프로젝트 루트 디렉터리에서 다음 명령어로 종속성 설치:

pip install torch==2.1.0+cu118 transformers==4.36 gradio accelerate bitsandbytes -U --extra-index-url https://download.pytorch.org/whl/cu118

추가로 LoRA 또는 양자화를 사용할 경우:

pip install peft unsloth

3. 서비스 실행 방법

3.1 기본 실행

프로젝트 폴더 내부에서 아래 명령어로 서버 시작:

python app.py

정상 작동 시 출력 메시지 예시:

Running on local URL: http://127.0.0.1:7860

3.2 커스텀 옵션 설정

다음과 같이 인자를 추가하여 동작 방식 조정 가능:

python app.py \
  --host 0.0.0.0 \
  --port 8080 \
  --device cuda \
  --dtype float16 \
  --enable-lora

지원되는 인자 목록

옵션	설명	기본값
--port	웹 서비스 포트 지정	7860
--host	바인딩 IP 주소	127.0.0.1
--device	실행 장치 (cuda/cpu)	cuda
--dtype	데이터 타입 (float16/bfloat16)	float16
--share	Gradio 공유 링크 활성화	False

4. 동작 확인 절차

4.1 웹 인터페이스 테스트

1. 브라우저에서 http://localhost:7860 접속
2. 입력창에 질의 입력 예: "블록체인의 합의 알고리즘을 설명하시오"
3. 응답 생성 시간 및 정확도 확인

4.2 API 호출 예제

외부 애플리케이션에서 HTTP 요청을 통한 접근도 가능:

import requests

url = "http://localhost:7860/api/predict/"
payload = {
    "data": [
        "머신러닝에서 과적합을 방지하는 방법은 무엇인가요?"
    ]
}

response = requests.post(url, json=payload)
result = response.json()["data"][0]
print(result)

5. 주요 오류 해결법

5.1 Out of Memory 문제

• 해결책 1: --dtype float16 옵션 사용
• 해결책 2: load_in_4bit=True 설정으로 양자화 로딩
• 해결책 3: 배치 크기를 줄이거나 입력 길이 제한

5.2 포트 충돌

기존에 7860번 포트가 사용 중일 경우 다른 번호로 변경:

python app.py --port 9000

5.3 모델 다운로드 실패

다음 항목 점검:

1. Hugging Face 인증 토큰 설정 여부
2. ~/.cache/huggingface/ 경로 용량 확보
3. 네트워크 방화벽 설정 확인

6. 성능 튜닝 전략

6.1 추론 속도 향상 기법

Flash Attention v2 적용 코드:

from transformers import AutoModelForCausalLM

model = AutoModelForCausalLM.from_pretrained(
    "unsloth/Qwen3.5-9B",
    device_map="auto",
    torch_dtype="auto",
    use_flash_attention_2=True
)

vLLM 기반 고속 서빙:

pip install vllm
python -m vllm.entrypoints.openai.api_server --model unsloth/Qwen3.5-9B --dtype half

6.2 리소스 모니터링

GPU 상태 실시간 확인:

nvidia-smi --query-gpu=utilization.gpu,memory.used,memory.total --format=csv -l 2

7. 마무리

본 문서를 통해 Qwen3.5-9B 모델을 로컬 서버에 성공적으로 배포하고, 사용자 정의 설정을 적용하며, 일반적인 문제를 해결하는 방법을 익혔습니다. 초보자는 기본 구성부터 시작한 후, 점진적으로 고급 기능(예: LoRA 미세조정, REST API 확장)을 도입하는 것이 좋습니다. 또한, 멀티모달 입력(이미지, 오디오 등)은 app.py 내 입력 파이프라인을 수정하여 지원 가능합니다.