# Qwen3.5 로컬 서빙 + Open WebUI

Qwen3.5-35B 모델을 로컬에서 서빙하고, Open WebUI로 채팅할 수 있는 환경을 원클릭으로 구축합니다.

텍스트 대화 + 이미지 입력 모두 지원합니다.

---

## 빠른 시작

```bash
# 시스템 환경을 자동 감지하여 최적의 방식을 선택합니다
./setup.sh

# 종료 (실행 중인 서비스를 자동 감지하여 종료)
./stop.sh
```

셋업 완료 후 **http://localhost:3000** 접속

첫 접속 시 회원가입 → 첫 번째 계정이 관리자(admin)입니다.

---

## 자동 감지 기준

| 조건 | 선택 | 이유 |
|------|------|------|
| NVIDIA GPU 있음 | **vLLM** | CUDA 가속, 가장 빠름 |
| Apple Silicon + RAM 32GB↑ | **MLX** | Mac GPU 최적화 |
| Apple Silicon + RAM 부족 | **Ollama** | 메모리 관리 우수 |
| 그 외 | **Ollama** | 범용, CPU에서도 동작 |

---

## 방식별 비교

| | Ollama | MLX (vllm-mlx) | vLLM |
|---|---|---|---|
| 환경 | Mac / Linux | Apple Silicon Mac | NVIDIA GPU (Linux) |
| 장점 | 간편, 설정 적음 | Mac GPU 최적화 | CUDA 가속, 고성능 |
| 이미지 입력 | O | O | O |
| 개별 셋업 | `./setup-ollama.sh` | `./setup-mlx.sh` | `./setup-vllm.sh` |
| 개별 종료 | `./stop-ollama.sh` | `./stop-mlx.sh` | `./stop-vllm.sh` |

---

## 사전 요구사항

**공통:**
- Docker Desktop (또는 Docker Engine) 설치 및 실행

**Ollama:**
- Homebrew

**MLX:**
- Apple Silicon Mac (M1/M2/M3/M4)
- Python 3.10+
- RAM 32GB 이상 권장

**vLLM:**
- NVIDIA GPU (VRAM 20GB 이상 권장)
- nvidia-container-toolkit

---

## 파일 구조

```
├── setup.sh                 # 통합 셋업 (자동 감지)
├── stop.sh                  # 통합 종료 (자동 감지)
│
├── setup-ollama.sh          # Ollama 셋업
├── setup-mlx.sh             # MLX 셋업
├── setup-vllm.sh            # vLLM 셋업
│
├── stop-ollama.sh           # Ollama 종료
├── stop-mlx.sh              # MLX 종료
├── stop-vllm.sh             # vLLM 종료
│
├── docker-compose.yml       # Ollama용
├── docker-compose.mlx.yml   # MLX용
├── docker-compose.vllm.yml  # vLLM용 (자동 생성)
│
├── SETUP_OLLAMA.md          # Ollama 상세 가이드
└── SETUP_MLX.md             # MLX 상세 가이드
```

---

## 상세 가이드

수동 설치, 파라미터 조정, 트러블슈팅 등은 아래 문서를 참고하세요.

- [SETUP_OLLAMA.md](SETUP_OLLAMA.md) — Ollama 방식 상세
- [SETUP_MLX.md](SETUP_MLX.md) — MLX 방식 상세 (파라미터 레퍼런스, 이미지 프로세서 패치 설명 포함)
- [SETUP_VLLM.md](SETUP_VLLM.md) — vLLM 방식 상세 (NVIDIA GPU, VRAM별 권장 설정)