Der Chat läuft auf dem Mac mini (oder später auf mehreren Macs, die sich ein Modell teilen), nicht in der Cloud. Jedes Gerät im Schul-WLAN kann ihn im Browser öffnen, solange in Open WebUI keine Cloud-API eingetragen ist.
Was feststeht, bevor ihr irgendetwas installiert
Das Sprachmodell rechnet auf dem MacOllama oder llama.cpp läuft nativ mit Metal (Apples GPU-Beschleunigung). Nie in Docker auf diesem Rechner, sonst fehlt die GPU.
Nur die Oberfläche darf ins WLANOpen WebUI ist über Port 8080 (uv) oder 3000 (Docker) erreichbar. Ollama bleibt auf 127.0.0.1, also nur für diesen Mac selbst.
Immer nur eine Engine zur ZeitOllama und llama.cpp nie gleichzeitig mit demselben großen Modell laden, sonst wird der Arbeitsspeicher knapp.
So läuft eine Anfrage durchs System
1. Schul-WLANEin Laptop oder Tablet im Schulnetz öffnet die Chat-Adresse im Browser.
2. Open WebUIÜbernimmt Anmeldung, Chatverlauf und Modellwahl. Rechnet selbst nichts, sondern reicht die Frage weiter.
3. Ollama oder später ExoAuf einem Mac erzeugt Ollama die Antwort und bleibt über localhost erreichbar, nie direkt aus dem WLAN. Wenn ein Modell den RAM einer Box sprengt, übernimmt Exo die Gewichte und Open WebUI fragt Port 52415.
i
Wenn unklar ist, welcher Weg passt: zwei Fragen unter Weg wählen. Der Alltagspfad ohne Docker steht unter Einfacher Chat.
Was wir bewusst nicht nutzen
Image open-webui:ollamaPackt Ollama in ein Linux-Image. Auf dem Mac läuft es dann auf der CPU statt auf der GPU, also deutlich langsamer.
llama.cpp in DockerGleiches Problem: Der Container kommt nicht an Metal heran, die GPU bleibt ungenutzt.
llama.cpp als Cluster über RPCDie Knoten sprechen per normales TCP. Mit jedem zusätzlichen Mac wird die Antwort oft langsamer. Ein Modell über mehrere Geräte legen heißt hier Exo, nicht llama.cpp.
LM Studio als SchulserverGut zum Ausprobieren am eigenen Rechner, aber keine App für Dauerbetrieb ohne Aufsicht.
Stand 17. September 2026. Inhalt aus den Anleitungen und der Abwägung im Repo „Lokales RAG System“.
Entscheidung
Welcher Weg?
Drei Fragen. Danach stehen Oberfläche, Engine auf einer Box und ob ein zweiter Mac das Modell mitträgt fest. Ihr richtet zuerst eine Oberfläche ein. Den Cluster erst, wenn die Kabel und die Geräte das hergeben.
Reicht der Katalog, oder braucht ihr eine feste GGUF-Datei?
Soll ein Modell größer werden, als eine Box RAM hat?
Kurzvergleich Oberfläche
uv auf dem Mac
Docker
Nur Chat, Ausbau unklar
nehmen
übertrieben
RAM fürs Modell
fast alles
plus 2–4 GB für die VM
Autostart
ein LaunchAgent
Docker Desktop plus Compose
Authentik / Qdrant später
umziehen
Compose erweitern
Daten
$HOME/.open-webui
data/m4/open-webui
Dokumente in Open WebUI hochladen braucht kein Docker und kein Qdrant. Qdrant lohnt bei viel Material. Authentik lohnt bei zentralen Schul-Accounts, nicht bei drei lokalen Logins.
Hardware
Was der M4 trägt
Unified Memory ist nicht nachrüstbar. Sobald Modell plus Kontext den RAM sprengen, schreibt macOS auf die SSD. Unterrichtstauglich ist das nicht.
Ein 32B auf 24 GB wurde mit 0,28 tok/s gemessen. Docker Desktop zieht oft 2–4 GB extra, das zählt auf 16–24 GB.
Erstes Modell laden
Wenig RAM, schneller Testollama pull llama3.2:3b
Ab 16 GB, alltagstauglichollama pull llama3.1:8b
Ab 24 GB, kräftigerollama pull qwen2.5:14b (Namen ändern sich)
Bei llama.cpp dieselbe Größenordnung, QuantQ4_K_M als üblicher Kompromiss aus Größe und Qualität.
Wenn die Gewichte später über mehrere Macs sollen: die erste Box mit Thunderbolt 5 kaufen (M4 Pro oder Studio). Zwei Minis ohne Pro am Ethernet teilen kein Modell sinnvoll, sie können höchstens dasselbe kleine Modell zweimal vorhalten.
Du brauchst einen Mac mit Apple Silicon, Admin-Rechte, eine feste IPv4-Adresse im Schulnetz und einen Passwortmanager oder eine andere sichere Ablage für den Geheimschlüssel. Keine Passwörter ins Git.
1
Programme → Dienstprogramme → Terminal. Den $ vor Befehlen nicht mitkopieren.
2
uname -m
Erwartet: arm64. x86_64 ist Intel, diese Anleitung gilt dann nicht.
3
Empfohlen: ollama.com/download, App nach Programme ziehen, einmal starten. Oder:
curl -fsSL https://ollama.com/install.sh | sh
Nur ausführen, wenn du ollama.com vertraust. Der Dienst lauscht auf Port 11434.
4
curl http://127.0.0.1:11434/api/tags
JSON ist gut, oft {"models":[]}. „connection refused“: App Ollama starten.
5
Geräte im WLAN sollen Open WebUI sehen, nicht Ollama. In der App prüfen, dass der Dienst nicht im Netz hängt.
launchctl setenv OLLAMA_HOST 127.0.0.1:11434
Ollama vollständig beenden (Quit) und neu starten. Von einem anderen Gerät darf http://<MAC-IP>:11434 nicht gehen.
In der Ollama-App „Launch at Login“ einschalten. Erwartet bei plutil: OK.
16
IP unter Systemeinstellungen → Netzwerk, dann auf dem Lehrer-Laptop http://10.0.0.40:8080 (deine Adresse). Zweiten Account nutzen, nicht den Admin-Alltagschat. Firewall darf Open WebUI, nicht Port 11434.
Wenn alles läuft
Auf dem Mac: http://127.0.0.1:8080
Im WLAN: http://<IP>:8080
http://<IP>:11434 von außen schlägt fehl
Nach Ab- und Anmelden läuft der Chat ohne Terminal
Kein Image-Tag ollama und kein open-webui:ollama. Das packt die Engine in die Linux-VM, Metal fällt aus.
Browser → Mac Port 3000landet im Container auf Port 8080 (Open WebUI)
Open WebUI → host.docker.internal:11434das ist Ollama auf dem Mac, nicht im Container
1
Apple-Silicon-Build von docker.com. Warten auf „Engine running“.
docker version
2
Schritte 3–6 der einfachen Anleitung müssen stehen.
curl http://127.0.0.1:11434/api/tags
Ollama möglichst auf 127.0.0.1 lassen. Schlägt die Container-Verbindung fehl: Ollama kurz auf 0.0.0.0, Firewall so, dass nur dieser Mac Port 11434 sieht.
3
openssl rand -hex 32
4
cd "/Users/DEIN_USER/Projekte/Lokales RAG System"
mkdir -p data/m4/open-webui
Anführungszeichen wegen des Leerzeichens im Pfad. Ohne Repo: beliebiger Ordner, Volume in Compose anpassen.
5
Datei infra/compose/m4/phase-01/compose.yaml. Schlüssel nicht committen.
Warten auf „Application startup complete“. Ctrl+C beendet nur die Log-Ansicht.
7
http://127.0.0.1:3000, Schulnetz http://<IP>:3000. Nicht 8080, der Port existiert nur im Container. Erster Nutzer ist Admin.
8
Falls keine Modelle: Admin → Connections → http://host.docker.internal:11434. Nicht 127.0.0.1 im Container, das wäre der Container selbst.
9
Docker Desktop: Start when you log in. Ollama: Start bei Anmeldung. Compose per LaunchAgent, der kurz wartet und dann docker compose … up -d ruft (siehe Phase-1-Autostart im Repo).
Wechsel von uv zu Docker
Läuft Open WebUI schon per uv und soll auf diesen Docker-Weg umziehen: zuerst Open WebUI stoppen, dann die Daten in den neuen Ordner kopieren. Denselben WEBUI_SECRET_KEY auch in der Compose-Datei setzen.
rsync -a "$HOME/.open-webui/" "/Users/DEIN_USER/Projekte/Lokales RAG System/data/m4/open-webui/"
llama-server spricht dieselbe Schnittstelle wie die OpenAI-API, deshalb kommt der Eintrag unter „OpenAI“, nicht unter „Ollama“. Der API-Key wird oft ignoriert, das Feld muss aber trotzdem gefüllt sein.
5
Datei z. B. local.schule.llamaserver.plist. Argumente einzeln: Pfad zu llama-server, -m, GGUF-Pfad, --host, 127.0.0.1, --port, 8081, --n-gpu-layers, 999.
Eingebaute Mini-UI von llama-server nicht ins LAN hängen. --host 127.0.0.1 belassen.
Zurück zu Ollama
llama-server beenden (Ctrl+C oder LaunchAgentbootout). Ollama-App starten. In Open WebUI wieder http://127.0.0.1:11434 (Docker: host.docker.internal:11434).
Anleitung 04 · mehrere Macs
Ein Modell mit Exo teilen
Exo zerlegt die Gewichte eines MLX-Modells über mehrere Apple-Silicon-Macs. Open WebUI bleibt die Oberfläche für die Schule. Das Exo-Dashboard auf Port 52415 ist nur für die betreuende Person.
!
Ohne Thunderbolt 5 und ohne RDMA (macOS 26.2 oder neuer) fehlt der schnelle Speicherweg zwischen den Geräten. Der Mac mini M4 ohne Pro hat Thunderbolt 4. llama.cpp über RPC ist für diesen Aufbau der falsche Weg.
1
Ein Mac führt Open WebUI (und später vielleicht Authentik). Die anderen rechnen nur. Auf den Workern kein Docker Desktop installieren, der Arbeitsspeicher gehört dem Modell.
2
Herunterfahren, Einschalttaste etwa zehn Sekunden halten, Optionen (Wiederherstellung), Dienstprogramme → Terminal:
rdma_ctl enable
Neu starten. Danach ibv_devices sollte RDMA-Anschlüsse listen. Am Studio den Thunderbolt-5-Anschluss neben Ethernet nicht für RDMA verwenden.
3
Zwei Geräte: ein Kabel. Drei Geräte: drei Kabel. Das Schul-WLAN trägt die Browser zu Open WebUI, nicht die Modellteile zwischen den Macs.
4
brew install --cask exo
Die App darf Netzwerkeinstellungen ändern, das gehört zu RDMA. In den Anmeldeobjekten prüfen, dass sie nach dem Login startet. macOS auf allen Knoten dieselbe Build-Nummer.
5
In den erweiterten Einstellungen der App EXO_LIBP2P_NAMESPACE auf allen Macs auf denselben Schulnamen setzen, zum Beispiel mpz-schule. Sonst kann ein zweiter Versuch im Gebäude denselben Kreis betreten.
6
Auf dem Kopf: http://127.0.0.1:52415. Alle Knoten und Thunderbolt/RDMA sollten sichtbar sein. Diese Adresse nicht ins Schul-WLAN legen.
curl http://127.0.0.1:52415/ollama/api/tags
7
Im Dashboard ein Modell aus der mlx-community wählen, nicht llama3.1:8b aus Ollama. Die Dateien sind andere. Zum ersten Test etwas Kleines. Das Speicherdiagramm muss mehr als einen Mac zeigen, sonst ist das Modell nicht geteilt.
8
uv
Docker
Ollama-URL
http://127.0.0.1:52415/ollama
http://host.docker.internal:52415/ollama
oder OpenAI
http://127.0.0.1:52415/v1
http://host.docker.internal:52415/v1
Kleine Modelle dürfen weiter über Ollama auf 11434 laufen, solange der RAM nicht schon vom geteilten Modell belegt ist. Sonst ollama stop ….
Ausführlich mit Wiederherstellung, Studio-Port und Deinstallation: Anleitung 04 im Markdown unter docs/anleitungen/anleitung_exo-cluster-modell-sharden.md.
Nach der Einrichtung
Alltag
Update bewusst, Daten sichern, Dienst stoppen. Lehrer bekommen die Chat-URL, nicht Port 11434.
cd "/Users/DEIN_USER/Projekte/Lokales RAG System"
docker compose -f infra/compose/m4/phase-01/compose.yaml down
down entfernt den Container, nicht den Datenordner. Ollama über die Menüleiste beenden. Exo über die App deinstallieren (Menü → Erweitert → Deinstallieren), nicht nur das Symbol löschen.
Was Lehrer brauchen
uvhttp://<IP-des-Mac>:8080
Dockerhttp://<IP-des-Mac>:3000
Diagnose
Wenn etwas hakt
Zuerst Logs, dann Port, dann die falsche Adresse zwischen Container und Mac.
Port 8080 belegtAnderen Port, z. B. 3000, in Startbefehl, plist und Browser-URL.
Python 3.13Installation mit --python 3.11 wiederholen.
LaunchAgent startet nichtLogs in $HOME/.open-webui/logs/. Pfad in der plist muss zu which open-webui passen.
Alle nach Neustart ausgeloggtWEBUI_SECRET_KEY fehlt oder hat sich geändert.
Sehr langsamOllama versehentlich im Container, kein Metal bei llama.cpp, oder Modell zu groß (Swap).
Fehler 500 (Docker)Oft Rechte am Datenordner.
Leere llama.cpp-ListeURL ohne /v1, oder im Container localhost statt host.docker.internal.
Exo-Knoten fehlenUnterschiedliche macOS-Builds, ungleicher Namespace, Kabel ohne Thunderbolt 5, Mesh unvollständig, oder RDMA nicht eingeschaltet.
Exo-Liste in Open WebUI leerURL ohne /ollama bzw. ohne /v1, oder im Container localhost statt host.docker.internal.
✓
Kontrolle Inferenz: auf dem Mac ollama ps zeigt das kleine Modell, nicht nur der Container. llama-server-Log erwähnt Metal. Exo-Dashboard auf localhost zeigt alle Knoten. Port 8081, 11434 und 52415 vom Lehrer-Laptop aus zu, Open WebUI offen.
Nachschlagen
Glossar
Kurzerklärungen zu den Fachbegriffen aus diesem Handbuch. Jeder Eintrag sagt, was der Begriff bedeutet und warum er hier überhaupt vorkommt.
Ausbau-Themen
SSO (Single Sign-on)
Einmal anmelden und danach automatisch bei mehreren Diensten eingeloggt sein, statt für jeden Dienst ein eigenes Passwort zu brauchen. Kommt hier ins Spiel, wenn neben dem Chat weitere Schul-Dienste dieselbe Anmeldung nutzen sollen.
Authentik
Ein Open-Source-Programm, das zentrale Logins (SSO) für mehrere Dienste verwaltet. Lohnt sich erst, wenn mehr als der reine Chat über gemeinsame Schul-Accounts laufen soll.
Proxy / Reverse Proxy
Ein Server, der Anfragen aus dem Netz entgegennimmt und an den passenden Dienst dahinter weiterleitet. Wird interessant, sobald Chat, Authentik und weitere Dienste über eine gemeinsame Adresse erreichbar sein sollen.
Qdrant
Eine Vektordatenbank, die Textabschnitte durchsuchbar macht, etwa um eigene Dokumente im Chat wiederzufinden. Lohnt sich erst bei größeren Materialmengen, für den reinen Chat nicht nötig.
RAG (Retrieval-Augmented Generation)
Der Chat durchsucht vorher eigene Dokumente und lässt die Fundstellen in die Antwort einfließen, statt nur aus dem trainierten Wissen zu antworten. Namensgeber dieses Projekt-Repos, für den Grundchat aber kein Muss.
Programme und Werkzeuge
Ollama
Eine App, die Sprachmodelle auf dem Mac lädt und Chat-Anfragen beantwortet. Der Standardweg in diesem Handbuch, läuft nativ mit Metal statt in Docker.
Open WebUI
Die Chat-Oberfläche im Browser mit Anmeldung, Verlauf und Modellwahl. Rechnet selbst nichts, sondern reicht Fragen an Ollama, llama-server oder Exo weiter.
llama.cpp / llama-server
Eine Alternative zu Ollama zum Ausführen von Sprachmodellen, gestartet über das Programm llama-server. Sinnvoll bei einer bestimmten GGUF-Datei oder Start-Flags, die Ollama nicht bietet.
uv
Ein schnelles Python-Werkzeug, mit dem sich Open WebUI ohne Docker installieren und starten lässt. Der einfachere der beiden Einrichtungswege in diesem Handbuch.
Docker
Ein Programm, das Anwendungen in abgeschlossenen Containern laufen lässt. Hier nur für die Oberfläche Open WebUI gedacht, nie für die Inferenz, weil ein Container in diesem Setup nicht an Metal herankommt.
Homebrew
Ein Paketmanager für macOS, mit dem sich Programme wie llama.cpp per Terminal installieren lassen. Manche vorgebauten Pakete (Bottles) fehlt dabei die Metal-Unterstützung.
LaunchAgent
Eine macOS-Konfigurationsdatei (.plist), die einen Dienst beim Login automatisch startet und am Laufen hält. Sorgt dafür, dass Open WebUI oder llama-server einen Neustart des Mac übersteht.
Compose (Docker Compose)
Eine Konfigurationsdatei, mit der mehrere Docker-Container zusammen gestartet werden. Beschreibt hier zum Beispiel Open WebUI mit Port, Umgebungsvariablen und Datenordner.
Exo
Ein Programm, das ein Sprachmodell so auf mehrere Apple-Silicon-Macs verteilt, dass die Gewichte zusammen in den Speicher passen. Es rechnet mit MLX, spricht Port 52415 und ersetzt Ollama nicht auf einer einzelnen Box.
MLX
Apples Bibliothek für Maschinenlernen auf dem Mac. Exo lädt Modelle in diesem Format (oft von der mlx-community auf Hugging Face), nicht die GGUF-Dateien aus Ollama.
Netzwerk und Technik
localhost / 127.0.0.1
Die Adresse, unter der ein Dienst nur für den eigenen Rechner erreichbar ist, nicht für andere Geräte im Netz. Ollama bleibt hier absichtlich, damit niemand im Schul-WLAN direkt darauf zugreift.
Port
Eine Art Zimmernummer für Dienste auf demselben Rechner, zum Beispiel 8080 für Open WebUI oder 11434 für Ollama. Über den Port weiß der Rechner, welches Programm eine Anfrage bekommen soll.
host.docker.internal
Eine besondere Adresse, über die ein Docker-Container den Mac erreicht, auf dem er läuft. Nötig, damit Open WebUI im Container die Ollama-App auf dem Mac findet.
Volume
Ein Ordner auf dem Mac, den Docker in einen Container einblendet, damit Daten den Container-Neustart überleben. Hier liegen zum Beispiel die Open-WebUI-Daten außerhalb des Containers.
WEBUI_SECRET_KEY
Ein selbst erzeugter Geheimwert, mit dem Open WebUI Sitzungen verschlüsselt. Ohne festen Wert wären nach jedem Neustart alle Nutzer abgemeldet.
Rund ums Sprachmodell
Inferenz
Der Rechenschritt, bei dem ein geladenes Sprachmodell aus einer Eingabe eine Antwort erzeugt. Läuft in diesem Setup immer nativ auf dem Mac, nie in Docker.
Engine
Das Programm, das die Inferenz übernimmt, hier Ollama, llama.cpp oder auf mehreren Macs Exo. Große Modelle nicht in zwei Engines gleichzeitig laden, sonst wird der Arbeitsspeicher knapp.
Metal
Apples Schnittstelle, über die Sprachmodelle die GPU des Mac nutzen. Funktioniert nur nativ auf macOS, nicht innerhalb eines Docker-Containers.
GGUF
Ein Dateiformat für Sprachmodelle, das llama.cpp lädt. Wichtig, wenn eine bestimmte Modelldatei oder Quantisierung außerhalb des Ollama-Katalogs gebraucht wird.
Quantisierung (z. B. Q4_K_M)
Ein Verfahren, das ein Sprachmodell verkleinert, indem es Zahlenwerte gröber speichert. Q4_K_M ist in diesem Handbuch der übliche Kompromiss zwischen Speicherbedarf und Antwortqualität.
Kontext / Kontextlänge
Wie viel Text aus Frage und Verlauf ein Sprachmodell auf einmal berücksichtigen kann. Eine längere Kontextlänge braucht spürbar mehr Arbeitsspeicher.
KV-Cache
Zwischengespeicherte Rechendaten, die ein Sprachmodell während des Antwortens wiederverwendet. Wächst mit der Kontextlänge und lässt sich bei llama-server gezielt einstellen.
tok/s (Tokens pro Sekunde)
Ein grobes Tempo-Maß dafür, wie schnell ein Modell Text erzeugt, ein Token ist ungefähr ein Wortstück. Wenige tok/s fühlen sich im Chat spürbar zäh an.
GPU-Offload (--n-gpu-layers)
Wie viele Schichten des Modells auf die GPU statt auf die CPU ausgelagert werden. Der Wert 999 in diesem Handbuch bedeutet: möglichst alles auf die GPU legen.
Chat-Template
Das Format, in dem Fragen und Antworten an ein Sprachmodell übergeben werden. Passt es nicht zum Modell, wirken Antworten wirr oder abgehackt.
Unified Memory
Der gemeinsame Arbeitsspeicher, den sich CPU und GPU im Mac mini M4 teilen. Er ist fest verbaut und lässt sich nachträglich nicht aufrüsten.
Swap (Auslagerung)
Wenn der Arbeitsspeicher voll ist, lagert macOS Daten auf die SSD aus. Für ein Sprachmodell bedeutet das einen deutlichen Tempoverlust.
RDMA
Remote Direct Memory Access: Ein Mac kann den Speicher eines anderen über Thunderbolt 5 ansprechen, ohne den normalen Netzwerkstapel. Ab macOS 26.2, Einschalten in der Wiederherstellung mit rdma_ctl enable.
Sharding
Das Zerlegen der Modellgewichte auf mehrere Geräte, sodass eine Anfrage über alle Knoten läuft. Das ist nicht dasselbe wie zwei unabhängige Kopien desselben kleinen Modells.