From ce0233985fdb201957aed111c489408dc9607a67 Mon Sep 17 00:00:00 2001
From: MyeonghoeLee <myeonghoelee@MyeonghoeLeeui-MacBookPro.local>
Date: Wed, 25 Mar 2026 22:06:46 +0900
Subject: [PATCH] =?UTF-8?q?README=20=EC=B6=94=EA=B0=80?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 README.md | 79 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 79 insertions(+)
 create mode 100644 README.md

diff --git a/README.md b/README.md
new file mode 100644
index 0000000..dcf261b
--- /dev/null
+++ b/README.md
@@ -0,0 +1,79 @@
+# Qwen3.5 로컬 서빙 + Open WebUI
+
+로컬 Mac에서 Qwen3.5-35B 모델을 서빙하고, Open WebUI로 채팅할 수 있는 환경을 원클릭으로 구축합니다.
+
+텍스트 대화 + 이미지 입력 모두 지원합니다.
+
+---
+
+## 방식 선택
+
+| | Ollama | MLX (vllm-mlx) |
+|---|---|---|
+| 장점 | 간편, 설정 적음 | Mac GPU 최적화, 파라미터 직접 제어 |
+| 이미지 입력 | O | O |
+| 환경 | Homebrew + Docker | Python venv + Docker |
+| 셋업 | `./setup-ollama.sh` | `./setup-mlx.sh` |
+| 종료 | `./stop-ollama.sh` | `./stop-mlx.sh` |
+
+---
+
+## 사전 요구사항
+
+- **Mac** (MLX 방식은 Apple Silicon 필수)
+- **Docker Desktop** 설치 및 실행
+- **Homebrew** (Ollama 방식)
+- **Python 3.10+** (MLX 방식)
+- **RAM 32GB 이상** 권장 (4bit 모델 기준 ~20GB 사용)
+
+---
+
+## 사용법
+
+### Ollama 방식
+
+```bash
+# 셋업 (Ollama 설치 → 모델 다운로드 → Open WebUI 실행)
+./setup-ollama.sh
+
+# 종료
+./stop-ollama.sh
+```
+
+### MLX 방식
+
+```bash
+# 셋업 (venv → vllm-mlx 설치 → 패치 → Open WebUI → 서버 시작)
+./setup-mlx.sh
+
+# 종료
+./stop-mlx.sh
+```
+
+셋업 완료 후 **http://localhost:3000** 접속
+
+첫 접속 시 회원가입 → 첫 번째 계정이 관리자(admin)입니다.
+
+---
+
+## 파일 구조
+
+```
+├── setup-ollama.sh          # Ollama 원클릭 셋업
+├── setup-mlx.sh             # MLX 원클릭 셋업
+├── stop-ollama.sh           # Ollama 종료
+├── stop-mlx.sh              # MLX 종료
+├── docker-compose.yml       # Ollama용 Open WebUI
+├── docker-compose.mlx.yml   # MLX용 Open WebUI
+├── SETUP_OLLAMA.md          # Ollama 상세 가이드
+└── SETUP_MLX.md             # MLX 상세 가이드 (파라미터, 트러블슈팅)
+```
+
+---
+
+## 상세 가이드
+
+수동 설치, 파라미터 조정, 트러블슈팅 등은 아래 문서를 참고하세요.
+
+- [SETUP_OLLAMA.md](SETUP_OLLAMA.md) — Ollama 방식 상세
+- [SETUP_MLX.md](SETUP_MLX.md) — MLX 방식 상세 (파라미터 레퍼런스, 이미지 프로세서 패치 설명 포함)