250 lines
6.4 KiB
Markdown
250 lines
6.4 KiB
Markdown
# 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
|
|
```
|