openwebui/README.md

Qwen3.5 로컬 서빙 + Open WebUI

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

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

---

빠른 시작

# 시스템 환경을 자동 감지하여 최적의 방식을 선택합니다
./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 — Ollama 방식 상세
• SETUP_MLX.md — MLX 방식 상세 (파라미터 레퍼런스, 이미지 프로세서 패치 설명 포함)
• SETUP_VLLM.md — vLLM 방식 상세 (NVIDIA GPU, VRAM별 권장 설정)