openwebui/SETUP_VLLM.md

Qwen3.5 + Open WebUI — vLLM (NVIDIA GPU)

환경: Linux / NVIDIA GPU (VRAM 20GB 이상) / Docker

---

목차

1. 환경 준비
2. 서버 시작
3. Open WebUI 연결
4. 종료 / 재시작
5. 파라미터 레퍼런스
6. 트러블슈팅

---

1. 환경 준비

사전 요구사항

• Linux (Ubuntu 20.04+ 권장)
• NVIDIA GPU (VRAM 20GB 이상 권장, 4bit 모델 기준)
• NVIDIA 드라이버 설치됨
• Docker + nvidia-container-toolkit 설치됨

확인 명령어

# NVIDIA 드라이버 확인
nvidia-smi

# Docker 확인
docker --version

# GPU가 Docker에서 인식되는지 확인
docker run --rm --gpus all nvidia/cuda:12.0.0-base-ubuntu22.04 nvidia-smi

nvidia-container-toolkit 미설치 시

# Ubuntu/Debian
curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg
curl -s -L https://nvidia.github.io/libnvidia-container/stable/deb/nvidia-container-toolkit.list | \
  sed 's#deb https://#deb [signed-by=/usr/share/keyrings/nvidia-container-toolkit-keyring.gpg] https://#g' | \
  sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list
sudo apt-get update
sudo apt-get install -y nvidia-container-toolkit
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker

---

2. 서버 시작

원클릭 셋업

./setup-vllm.sh

이 스크립트가 하는 일:

1. Docker, NVIDIA GPU, nvidia-container-toolkit 확인
2. docker-compose.vllm.yml 자동 생성
3. vLLM 서버 + Open WebUI 컨테이너 실행
4. 서버 준비 대기

수동 실행

docker compose -f docker-compose.vllm.yml up -d

첫 실행 시 Docker 이미지 pull + 모델 다운로드로 시간이 걸립니다.

---

3. Open WebUI 연결

서버 동작 확인

# 모델 목록
curl http://localhost:8090/v1/models

# 채팅 테스트
curl http://localhost:8090/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3.5-35B-A3B",
    "max_tokens": 8192,
    "messages": [{"role": "user", "content": "안녕하세요"}]
  }'

브라우저 접속

http://localhost:3000

1. 첫 접속 시 회원가입 (로컬 전용, 첫 계정 = admin)
2. 설정 → Connections → OpenAI API 연결 확인
   • URL: http://vllm:8000/v1 (Docker 내부 네트워크)
   • API Key: none
3. 상단 모델 선택 후 채팅 시작

---

4. 종료 / 재시작

종료

./stop-vllm.sh

# 또는 수동
docker compose -f docker-compose.vllm.yml down

재시작

./setup-vllm.sh

# 또는 수동
docker compose -f docker-compose.vllm.yml up -d

로그 확인

# vLLM 서버 로그
docker logs -f vllm-server

# Open WebUI 로그
docker logs -f open-webui-vllm

---

5. 파라미터 레퍼런스

토큰 제한

구분	의미	설정
max-model-len (입력)	모델이 받을 수 있는 최대 컨텍스트 길이	--max-model-len 8192
max_tokens (출력)	API 요청 시 최대 생성 토큰 수	요청 body에서 지정

vLLM은 --max-model-len으로 입력 길이를 직접 제한할 수 있습니다.

docker-compose.vllm.yml 주요 설정

command 섹션에서 vLLM 서버 파라미터를 조절합니다:

command: >
  --model Qwen/Qwen3.5-35B-A3B
  --max-model-len 8192
  --max-num-seqs 4
  --gpu-memory-utilization 0.9
  --trust-remote-code  

파라미터 설명

파라미터	기본값	설명
--model	-	HuggingFace 모델 경로
--max-model-len	모델 기본값	최대 컨텍스트 길이 (입력 + 출력 합산)
--max-num-seqs	256	동시 처리 시퀀스 수 (낮추면 VRAM 절약)
--gpu-memory-utilization	0.9	GPU 메모리 사용 비율 (0.0~1.0)
--trust-remote-code	off	HuggingFace 커스텀 코드 허용
--tensor-parallel-size	1	GPU 병렬 수 (멀티 GPU 시)
--quantization	-	양자화 방식 (awq, gptq 등)
--dtype	auto	데이터 타입 (float16, bfloat16, auto)

각 파라미터가 하는 일

--max-model-len (컨텍스트 길이)

입력 + 출력을 합한 최대 토큰 수입니다.

• 낮추면 VRAM을 절약할 수 있음
• Qwen3.5는 최대 262K까지 지원하지만, VRAM에 따라 제한 필요
• 8192 권장 (VRAM 24GB 기준)

--gpu-memory-utilization (GPU 메모리 비율)

GPU 메모리의 몇 %를 vLLM이 사용할지 결정합니다.

0.9  → VRAM의 90% 사용 (기본, 최대 성능)
0.7  → VRAM의 70% 사용 (다른 프로세스와 공유 시)

--max-num-seqs (동시 시퀀스)

동시에 처리할 수 있는 요청 수입니다.

• 낮추면 VRAM 절약, 단일 요청 속도 ↑
• 높이면 동시 사용자 ↑, 요청당 속도 ↓
• VRAM 20~24GB → 4 권장
• VRAM 48GB+ → 16~32 가능

--tensor-parallel-size (GPU 병렬)

멀티 GPU 환경에서 모델을 여러 GPU에 분산합니다.

• GPU 1개 → 1 (기본)
• GPU 2개 → 2
• GPU 4개 → 4

---

6. 트러블슈팅

증상	원인	해결
CUDA out of memory	VRAM 부족	--max-model-len 줄이기, --max-num-seqs 줄이기
nvidia-container-toolkit 에러	toolkit 미설치	환경 준비 참고
모델 다운로드 느림	HuggingFace 네트워크	HUGGING_FACE_HUB_TOKEN 환경변수 설정
컨테이너 재시작 반복	메모리/설정 문제	docker logs vllm-server 확인
모델이 안 보임	서버 미준비	docker logs -f vllm-server로 로딩 상태 확인
Open WebUI에서 연결 안 됨	내부 네트워크 문제	docker compose -f docker-compose.vllm.yml restart

VRAM별 권장 설정

VRAM	max-model-len	max-num-seqs	비고
20~24GB	4096~8192	2~4	4bit 양자화 필요할 수 있음
40~48GB	8192~16384	4~16	bf16 가능
80GB+	32768+	16~64	풀 스펙

HuggingFace 토큰 설정 (비공개 모델 또는 다운로드 속도 개선)

export HUGGING_FACE_HUB_TOKEN="hf_xxxxxxxxxxxx"
docker compose -f docker-compose.vllm.yml up -d

또는 .env 파일에:

HUGGING_FACE_HUB_TOKEN=hf_xxxxxxxxxxxx