vLLM 상세 가이드 (SETUP_VLLM.md) 추가

- 환경 준비 (nvidia-container-toolkit 설치 포함)
- 파라미터 레퍼런스 (max-model-len, gpu-memory-utilization 등)
- VRAM별 권장 설정 테이블
- 트러블슈팅

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

README.md

@@ -94,3 +94,4 @@ Qwen3.5-35B 모델을 로컬에서 서빙하고, Open WebUI로 채팅할 수 있
 
 - [SETUP_OLLAMA.md](SETUP_OLLAMA.md) — Ollama 방식 상세
 - [SETUP_MLX.md](SETUP_MLX.md) — MLX 방식 상세 (파라미터 레퍼런스, 이미지 프로세서 패치 설명 포함)
+- [SETUP_VLLM.md](SETUP_VLLM.md) — vLLM 방식 상세 (NVIDIA GPU, VRAM별 권장 설정)

SETUP_VLLM.md

@@ -0,0 +1,249 @@
+# 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
+```