대상 : Mac Mini M4 · 통합 메모리 24GB · macOS
스택 : Ollama (네이티브 앱) + Open WebUI (Docker)
외부 API : OpenAI · Anthropic · Gemini 등 선택적 연동 (LiteLLM 불필요)
목표 : 로컬 모델과 외부 API 를 UI 드롭다운에서 선택적 사용
| 결정 | 근거 |
|---|---|
| Ollama 네이티브 설치 (Docker 미사용) | Docker Desktop for Mac 은 Linux VM 기반으로 Metal GPU/MLX 가속을 직접 활용할 수 없음. Ollama 공식도 macOS 네이티브 앱 권장. MLX 백엔드 자동 사용 |
| Open WebUI 는 Docker | macOS 네이티브 설치는 Python 의존성·업데이트 부담. Docker 는 토큰 처리·UI만 담당하므로 VM 오버헤드 무시 가능 |
| LiteLLM 제외 | 1인 사용에 Virtual Key·팀 스펜드 추적 불필요. Open WebUI 의 Direct Connections 로 외부 API 다중 등록 가능 |
| 14B 이하 모델 상한 | M4 24GB 통합메모리 → OS·앱 ~6GB 점유 후 실용 1618GB → 14B Q4_K_M(약 9GB) 가 안정적 상한 |
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
공식 사이트에서 Apple Silicon 용 .dmg 다운로드 후 설치 : https://www.docker.com/products/docker-desktop/
또는 Homebrew :
brew install --cask docker
open -a Docker # 최초 1회 실행하여 초기화
Docker Desktop 리소스 권장치 (Settings → Resources):
| 항목 | 권장 |
|---|---|
| CPU | 4 core |
| Memory | 4 GB |
| Swap | 1 GB |
| Disk image size | 64 GB 이상 |
Ollama 는 네이티브라 Docker 자원과 무관. 위 값은 Open WebUI 컨테이너용.
옵션 A — 공식 설치 파일 (권장)
https://ollama.com/download/mac 에서 Ollama.dmg 다운로드 → 드래그 설치 → 앱 실행
옵션 B — Homebrew
brew install --cask ollama
open -a Ollama
앱 실행 시 메뉴바에 라마 아이콘이 뜨고 11434 포트에서 자동 기동합니다.
curl http://localhost:11434/api/tags
# 정상: {"models":[]}
ollama --version
launchctl setenv 로 설정 후 Ollama 앱 재시작 필요. macOS 재부팅 시 초기화되므로 영구 적용은 LaunchAgent 등록이 필요합니다.
launchctl setenv OLLAMA_KEEP_ALIVE "30m" # 모델 메모리 유지 시간
launchctl setenv OLLAMA_NUM_PARALLEL "2" # 동시 요청 처리
launchctl setenv OLLAMA_MAX_LOADED_MODELS "2" # 동시 로드 모델 수
launchctl setenv OLLAMA_HOST "0.0.0.0:11434" # Docker 컨테이너에서 접근 허용
# Ollama 앱 재시작
osascript -e 'quit app "Ollama"'
open -a Ollama
~/Library/LaunchAgents/com.ollama.env.plist 생성 :
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN"
"http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
<key>Label</key>
<string>com.ollama.env</string>
<key>ProgramArguments</key>
<array>
<string>/bin/sh</string>
<string>-c</string>
<string>
launchctl setenv OLLAMA_KEEP_ALIVE "30m"
launchctl setenv OLLAMA_NUM_PARALLEL "2"
launchctl setenv OLLAMA_MAX_LOADED_MODELS "2"
launchctl setenv OLLAMA_HOST "0.0.0.0:11434"
</string>
</array>
<key>RunAtLoad</key>
<true/>
</dict>
</plist>
등록 :
launchctl load ~/Library/LaunchAgents/com.ollama.env.plist
기본: ~/.ollama/models — 외장 SSD 등으로 옮기려면 OLLAMA_MODELS 를 절대경로로 설정.
launchctl setenv OLLAMA_MODELS "/Volumes/ExtSSD/ollama-models"
| 용도 | 모델 | 크기 | 속도(대략) | 비고 |
|---|---|---|---|---|
| 일상 QA, 빠른 응답 | llama3.2:3b-instruct-q4_K_M |
2.0 GB | 매우 빠름 | 메모리 여유 큼 |
| 한국어 균형 | qwen2.5:7b-instruct-q4_K_M |
4.7 GB | 빠름 | 한국어 품질 양호 |
| 고품질 추론 | qwen2.5:14b-instruct-q4_K_M |
9.0 GB | 보통 | 상한급 모델 |
| 코딩 전용 | qwen2.5-coder:7b-instruct-q4_K_M |
4.7 GB | 빠름 | Fill-in-Middle 지원 |
| 이미지 인식 | llama3.2-vision:11b-instruct-q4_K_M |
7.9 GB | 보통 | 멀티모달 |
| RAG 임베딩 | nomic-embed-text |
274 MB | 매우 빠름 | 문서 검색용 |
ollama pull llama3.2:3b-instruct-q4_K_M
ollama pull qwen2.5:7b-instruct-q4_K_M
ollama pull qwen2.5:14b-instruct-q4_K_M
ollama pull qwen2.5-coder:7b-instruct-q4_K_M
ollama pull nomic-embed-text
# 필요 시 비전 모델
ollama pull llama3.2-vision:11b-instruct-q4_K_M
# 확인
ollama list
ollama run qwen2.5:7b-instruct-q4_K_M "한국어로 자기소개 해줘."
# /bye 로 종료
# Secret 생성 (WEBUI_SECRET_KEY - 세션/JWT 서명용)
export OWUI_SECRET=$(openssl rand -hex 32)
docker run -d \
--name open-webui \
--restart unless-stopped \
-p 3000:8080 \
-e OLLAMA_BASE_URL=http://host.docker.internal:11434 \
-e WEBUI_SECRET_KEY="${OWUI_SECRET}" \
-e WEBUI_URL=http://localhost:3000 \
-e ENABLE_SIGNUP=false \
-v open-webui:/app/backend/data \
ghcr.io/open-webui/open-webui:v0.8.6
host.docker.internal : Docker Desktop for Mac 이 호스트 OS(Ollama 네이티브) 로 접근할 때 쓰는 특수 DNSENABLE_SIGNUP=false : 첫 가입자=admin 이므로 본인 가입 후 다른 사람 가입 차단 (1인 사용 전제)open-webui : 채팅 히스토리·파일 업로드·설정 영속화http://localhost:3000 → 관리자 계정 생성 (이메일은 로컬 더미 가능)
~/llm-stack/docker-compose.yml :
services:
open-webui:
image: ghcr.io/open-webui/open-webui:v0.8.6
container_name: open-webui
restart: unless-stopped
ports:
- "3000:8080"
environment:
OLLAMA_BASE_URL: http://host.docker.internal:11434
WEBUI_SECRET_KEY: ${WEBUI_SECRET_KEY}
WEBUI_URL: http://localhost:3000
ENABLE_SIGNUP: "false"
# 외부 API 키는 UI 에서 추가하므로 여기서는 비워둠
volumes:
- openwebui-data:/app/backend/data
extra_hosts:
- "host.docker.internal:host-gateway" # 일부 환경 보정
volumes:
openwebui-data:
~/llm-stack/.env :
WEBUI_SECRET_KEY=$GENERATED_64HEX
.env는 절대 git 에 커밋 금지. 권한chmod 600 .env.
cd ~/llm-stack
docker compose up -d
docker compose logs -f
Open WebUI 의 Admin Panel → Settings → Connections 에서 복수 API 엔드포인트 등록 가능. 드롭다운에서 로컬 Ollama 모델과 외부 모델을 토글 선택하면 됩니다.
| 항목 | 값 |
|---|---|
| API Base URL | https://api.openai.com/v1 |
| API Key | sk-... (본인 발급) |
| Model IDs | gpt-4o, gpt-4o-mini, o1-mini 등 |
Anthropic 이 제공하는 OpenAI 호환 엔드포인트 사용.
| 항목 | 값 |
|---|---|
| API Base URL | https://api.anthropic.com/v1/ |
| API Key | sk-ant-... |
| Model IDs | claude-sonnet-4-5, claude-opus-4-7 등 |
Open WebUI 버전에 따라 Anthropic 네이티브 연결이 추가되어 있을 수 있습니다. 미지원 시 위 OpenAI 호환 엔드포인트 사용.
| 항목 | 값 |
|---|---|
| API Base URL | https://generativelanguage.googleapis.com/v1beta/openai/ |
| API Key | Google AI Studio 발급 키 |
| Model IDs | gemini-2.5-pro, gemini-2.5-flash 등 |
| 용도 | 권장 모델 |
|---|---|
| 민감 정보 / 오프라인 작업 | 로컬 Ollama (qwen2.5:14b) |
| 일상 빠른 Q&A | 로컬 Ollama (llama3.2:3b) |
| 고난도 추론 / 긴 컨텍스트 | Claude Opus 4.7, GPT-5 |
| 이미지 분석 (외부 허용 시) | Claude / Gemini (멀티모달 우수) |
| 이미지 분석 (로컬 유지) | Ollama llama3.2-vision:11b |
| 코드 생성 | qwen2.5-coder:7b (로컬) · Claude Sonnet (외부) |
Ollamanomic-embed-text대용량 문서는 임베딩에 시간 소요. RAG 품질은 문서 정제가 핵심.
Admin Panel → Settings → Web Search 에서 SearXNG/Brave/Tavily 등 설정 가능. 개인 SearXNG 인스턴스가 가장 사생활 보호에 유리.
Admin Panel → Settings → Audio 에서 Whisper (로컬 / OpenAI API) 및 TTS 엔진 설정 가능.
ComfyUI / Automatic1111 / DALL-E / Gemini Imagen 등 연결 가능 (Settings → Images).
# Ollama (네이티브) — 메뉴바 아이콘 → Update, 또는:
brew upgrade --cask ollama # Homebrew 설치 시
# Open WebUI
cd ~/llm-stack
docker compose pull
docker compose up -d
Open WebUI 는 메이저 업그레이드 시 DB migration 이 발생합니다. 업그레이드 전 8.2 의 백업 필수.
# Open WebUI 데이터 (채팅 히스토리 · 설정 · 업로드 파일)
docker run --rm \
-v open-webui:/data \
-v "$HOME/backup":/backup \
alpine tar czf /backup/openwebui-$(date +%Y%m%d).tar.gz -C /data .
# 복구
docker run --rm \
-v open-webui:/data \
-v "$HOME/backup":/backup \
alpine sh -c "cd /data && tar xzf /backup/openwebui-YYYYMMDD.tar.gz"
Ollama 모델은 재다운로드 가능하므로 백업 우선순위 낮음.
# 활성 모델 확인 (메모리 점유)
ollama ps
# 실시간 통계
ollama run qwen2.5:7b-instruct-q4_K_M --verbose
# 실행 후 응답에 tok/s 표시됨
# macOS 메모리 압력
memory_pressure
vm_stat
# Docker 컨테이너 자원
docker stats open-webui
# 목록
ollama list
# 디스크 사용량
du -sh ~/.ollama/models
# 삭제
ollama rm <model_name>
# 실행중인 모델 강제 종료 (메모리 반환)
ollama stop <model_name>
| 증상 | 원인 / 조치 |
|---|---|
| Open WebUI 에서 Ollama 모델이 안 보임 | OLLAMA_HOST=0.0.0.0:11434 설정 누락 또는 Ollama 재시작 안 함. curl http://localhost:11434/api/tags 로 확인 |
컨테이너에서 host.docker.internal 접속 실패 |
extra_hosts: [host.docker.internal:host-gateway] 추가. 또는 --network host (Mac 에서는 제한적) |
| 14B 모델 응답 매우 느림 / 멈춤 | 24GB 에서 다른 앱이 메모리 점유. Safari/Chrome 탭 정리. ollama ps 에서 로드된 모델 수 확인 |
| Swap 과다 발생 | OLLAMA_MAX_LOADED_MODELS 1 로 낮춤. 14B 와 7B 를 번갈아 쓰되 동시 로드 금지 |
| 응답 생성 중 연결 끊김 | Open WebUI Docker 네트워크 타임아웃. 기본값으로 충분하나 장문 응답은 로컬 페이지 새로고침 시 중단됨 (정상) |
| Anthropic 연결 401 | API Base URL 끝에 / 포함 여부 확인. https://api.anthropic.com/v1/ 형태 |
| macOS 재부팅 후 Ollama 환경변수 초기화 | 3.3 의 LaunchAgent 등록 |
| Docker Desktop CPU 과다 | Docker Desktop → Settings → Resources 에서 CPU 제한 강화 |
WEBUI_SECRET_KEY 는 재설치 시에도 동일값 유지해야 기존 세션·DB 호환ENABLE_SIGNUP=false 로 고정하여 개인 PC 에서 불필요한 계정 생성 차단docker-compose.yml 평문 주입 금지localhost:3000 외 네트워크에 노출시키지 말 것 (포트 포워딩 주의)docker compose up -d)http://localhost:3000 접속 & 관리자 계정 생성공식 문서
참고 (Priority 2~4)
문서 버전 : v1.0 · 기준일 : 2026-04
주의 : Ollama / Open WebUI 릴리즈 노트 확인 후 이미지·앱 버전 재pin 권장