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

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

---

# 목차

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

---

# 1. 환경 준비

## 사전 요구사항

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

## 확인 명령어

```bash
# 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 미설치 시

```bash
# 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. 서버 시작

## 원클릭 셋업

```bash
./setup-vllm.sh
```

이 스크립트가 하는 일:
1. Docker, NVIDIA GPU, nvidia-container-toolkit 확인
2. `docker-compose.vllm.yml` 자동 생성
3. vLLM 서버 + Open WebUI 컨테이너 실행
4. 서버 준비 대기

## 수동 실행

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

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

---

# 3. Open WebUI 연결

### 서버 동작 확인

```bash
# 모델 목록
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. 종료 / 재시작

### 종료

```bash
./stop-vllm.sh

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

### 재시작

```bash
./setup-vllm.sh

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

### 로그 확인

```bash
# 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 서버 파라미터를 조절합니다:

```yaml
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 미설치 | [환경 준비](#nvidia-container-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 토큰 설정 (비공개 모델 또는 다운로드 속도 개선)

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

또는 `.env` 파일에:

```
HUGGING_FACE_HUB_TOKEN=hf_xxxxxxxxxxxx
```