LocalAI (mudler/LocalAI, aktuell v4.11) ist eine quelloffene KI-Engine, die aus einem Docker-Container Text-LLMs, Embeddings, Bildgenerierung sowie Audio (TTS und STT) über eine OpenAI-kompatible API bereitstellt. Bestehende OpenAI-Tools lenken Sie meist ohne Codeänderung um, indem Sie die Base-URL gegen http://SERVER-IP:8080/v1 tauschen.

Kurzfassung: Image localai/localai in passender Variante wählen (CPU: latest bzw. fester Tag wie v4.11.0), Port 8080 mappen, Volumes für /models, /backends, /configuration und /data mounten und einen API-Key setzen. Die drei Kernbefehle:

docker run -ti --name local-ai -p 8080:8080 localai/localai:latest  # Schnelltest (CPU)
docker compose up -d                        # Stack im Hintergrund starten
docker compose pull && docker compose up -d # Update einspielen

Danach Web-UI unter http://SERVER-IP:8080 öffnen, im Bereich Models ein Modell installieren und die OpenAI-kompatible API unter http://SERVER-IP:8080/v1 nutzen.

Voraussetzungen

Der Hardwarebedarf hängt von CPU- oder GPU-Betrieb und der Modellgröße ab:

Betriebssystem: Linux-Server (x86_64 oder ARM64) mit Docker und Docker Compose, z. B. Debian 12 oder Ubuntu 24.04.
CPU-Betrieb: funktioniert ohne GPU, ist bei LLMs aber deutlich langsamer. Richtwert: 4 CPU-Kerne mit AVX2 und 8 GB RAM für ein 3B- bis 4B-Modell in Q4-Quantisierung, 16 GB für 7B- bis 8B-Modelle.
GPU-Betrieb (empfohlen für schnelles LLM-Serving und Bildgenerierung): NVIDIA-GPU mit ausreichend VRAM, passendes GPU-Image und nvidia-container-toolkit (Schritt 6).
Speicher: mindestens 30 GB frei. Das CPU-Image ist rund 0,3 GB groß, das CUDA-Image rund 3,7 GB; dazu kommen Backends (je 1 bis 3 GB) und Modelle (2 bis 8 GB pro GGUF-Modell).
Netzwerk/Domain: Der Container lauscht auf Port 8080. Für Zugriff von außen brauchen Sie eine Domain und einen Reverse-Proxy mit HTTPS (Schritt 7). Standardmäßig gibt es keine Authentifizierung.

Grundlagen zu Compose-Stacks: Docker Compose: Grundlagen und Stacks.

Hardware für diese Anleitung

Enthält Werbelinks

Grafikkarte mit viel VRAM	Der Grafikspeicher entscheidet, welche Modelle laufen. Faustregel bei 4-Bit-Quantisierung: 8 GB für 7–8B-Modelle, 16 GB für 14B, 24 GB für die 30B-Klasse.	Grafikkarten bei Amazon (Werbelink)
Arbeitsspeicher	32 GB RAM, damit Modelle, die nicht ganz in den Grafikspeicher passen, auf die CPU ausweichen können.	Bei Amazon ansehen (Werbelink)
Welche Karte passt?	Unsere Kaufberatung vergleicht die Karten nach VRAM und Budget.	Zur Kaufberatung

Vorhandene Hardware reicht oft. Die Liste zeigt, worauf es bei einem Neukauf ankommt. * Werbelink

Schritt 1: Image-Strategie verstehen (Standard vs. AIO, CPU vs. GPU)

LocalAI gibt es mit identischen Tags auf Docker Hub (localai/localai, hier verwendet) und Quay (quay.io/go-skynet/local-ai). Modelle und passende Backends lädt LocalAI bei Bedarf nach.

Image-Tags: localai/localai:latest (CPU), latest-gpu-nvidia-cuda-12, latest-gpu-nvidia-cuda-13 (NVIDIA), latest-gpu-hipblas (AMD ROCm), latest-gpu-intel (Intel), latest-gpu-vulkan sowie latest-nvidia-l4t-arm64 (Jetson).
Keine AIO-Images mehr: Die All-in-One-Images (latest-aio-cpu usw.) mit vorinstallierten Modellen unter OpenAI-Namen wie gpt-4 wurden mit v4.0.0 eingestellt; die Tags stammen von v3.12 (Februar 2026) ohne Updates. Auch latest-cpu ist veraltet (Stand Juni 2025), das CPU-Image heißt latest.

Stabilität: Pinnen Sie in Produktion einen festen Versions-Tag, z. B. localai/localai:v4.11.0 (CPU) bzw. v4.11.0-gpu-nvidia-cuda-12 (Stand Oktober 2026). Die master-Tags sind Entwicklungs-Builds.

Verifizieren: docker manifest inspect localai/localai:v4.11.0 >/dev/null && echo ok gibt ok aus; der gewählte Tag existiert.

Schritt 2: Schnelltest mit docker run

Ein Befehl prüft Image-Download, Container-Start und Web-UI:

# CPU-Schnellstart:
docker run -ti --name local-ai -p 8080:8080 localai/localai:latest

Haben Sie den Container mit Strg+C gestoppt, starten Sie ihn so wieder:

docker start -i local-ai

Ohne benanntes Volume gehen Modelle beim Löschen des Containers verloren. Entfernen Sie den Testcontainer vor Schritt 3 mit docker rm -f local-ai, sonst kollidiert der Containername.

Verifizieren: curl -s http://localhost:8080/readyz antwortet mit HTTP 200, und http://SERVER-IP:8080 zeigt die Web-UI.

Schritt 3: Verzeichnis und compose.yaml anlegen

Legen Sie auf dem Server ein Projektverzeichnis an:

mkdir -p $HOME/localai
cd $HOME/localai

Die compose.yaml nutzt das CPU-Image in fester Version, vier benannte Volumes (Modelle, Backends, Konfiguration, Daten) und schützt die API per LOCALAI_API_KEY. Die Pfade im Container müssen genau /models, /backends, /configuration und /data lauten.

services:
  local-ai:
    image: localai/localai:v4.11.0   # CPU-Image, feste Version
    container_name: local-ai
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"   # nur lokal, extern per Reverse-Proxy (Schritt 7)
    environment:
      - MODELS_PATH=/models
      - THREADS=4
      - CONTEXT_SIZE=4096
      - LOCALAI_API_KEY=BITTE-EIGENEN-KEY-SETZEN
      # - DEBUG=true
    volumes:
      - localai-models:/models
      - localai-data:/data
      - localai-backends:/backends
      - localai-config:/configuration
volumes:
  localai-models:
  localai-data:
  localai-backends:
  localai-config:

Was die wichtigsten Umgebungsvariablen bedeuten:

MODELS_PATH=/models – Modellverzeichnis im Container, dort ist das localai-models-Volume gemountet.
THREADS – CPU-Threads für die Inferenz, auf die Zahl der physischen Kerne setzen (nproc zeigt logische Kerne).
CONTEXT_SIZE – Kontextfenster der LLMs; zu große Werte erhöhen den RAM-/VRAM-Bedarf bis zu OOM-Abbrüchen.
LOCALAI_API_KEY – schützt die API per Bearer-Token und gewährt vollen Admin-Zugriff. Bei erreichbarem Server nie leer lassen.
DEBUG=true – optional für ausführliche Logs bei der Fehlersuche.

Weitere nützliche Variablen: GALLERIES (JSON-Array zusätzlicher Modell-Galleries, auch file:// im models-Verzeichnis) und PRELOAD_MODELS (JSON-Array, lädt Modelle beim Start).

Verifizieren: docker compose config gibt die Datei ohne Fehlermeldung aus.

Schritt 4: API-Key setzen und Stack starten

Erzeugen Sie einen zufälligen API-Key und tragen Sie ihn in die compose.yaml bei LOCALAI_API_KEY ein:

openssl rand -hex 32

Starten Sie den Stack im Hintergrund und prüfen Sie, dass der Container läuft:

docker compose up -d
docker compose ps
docker compose logs -f local-ai   # Logs live mitlesen, mit Strg+C beenden

Schicken Sie den API-Key bei jedem Aufruf als Bearer-Token mit. Ohne installiertes Modell ist die Liste leer:

curl -s http://localhost:8080/v1/models \
  -H "Authorization: Bearer BITTE-EIGENEN-KEY-SETZEN"

Verifizieren: docker compose ps zeigt den Container als running und nach dem Start (healthy). Der Aufruf ohne Key liefert HTTP 401, mit Key ein JSON-Objekt mit "data".

Schritt 5: Web-UI-Ersteinrichtung und Modelle laden

Der Port ist nur an 127.0.0.1 gebunden; vor Schritt 7 erreichen Sie die Web-UI per SSH-Tunnel ssh -L 8080:127.0.0.1:8080 BENUTZER@SERVER-IP unter http://localhost:8080 mit dem API-Key. Anfangs sind keine Modelle vorhanden:

Über die Model-Gallery: Im Bereich Models der Web-UI installieren Sie Modelle per Klick; angezeigt werden Download-Größe und VRAM-Bedarf. Das Backend lädt LocalAI automatisch.
Über die API: Gallery-Modelle installieren Sie per POST /models/apply. Beispiel für das Chat-Modell qwen3-4b:

curl http://localhost:8080/models/apply \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer BITTE-EIGENEN-KEY-SETZEN" \
  -d '{"id": "localai@qwen3-4b"}'

Alternativ laden Sie Modelle über die CLI im Container, auch per URI (huggingface://, ollama://, oci://), oder legen eine GGUF-Datei ins /models-Volume:

docker exec local-ai /local-ai models list
docker exec local-ai /local-ai models install qwen3-4b

Modelle im Volume überleben Neustarts und Updates. GET /v1/models listet installierte, GET /models/available verfügbare Modelle. Test der Chat-API:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer BITTE-EIGENEN-KEY-SETZEN" \
  -d '{"model": "qwen3-4b", "messages": [{"role": "user", "content": "Antworte mit einem Wort: Hauptstadt von Frankreich?"}]}'

Verifizieren: GET /v1/models listet qwen3-4b, und die Chat-Anfrage liefert ein JSON mit choices[0].message.content. Die erste Anfrage dauert länger, weil LocalAI das Modell lädt.

Schritt 6: GPU-Betrieb mit NVIDIA aktivieren

Auf dem Host brauchen Sie den NVIDIA-Treiber und das NVIDIA Container Toolkit. Wählen Sie gpu-nvidia-cuda-12 oder gpu-nvidia-cuda-13; nvidia-smi zeigt oben rechts die höchste vom Treiber unterstützte CUDA-Version. Bei älteren Treibern nehmen Sie CUDA 12.

Ein schneller Test per docker run mit GPU-Zugriff:

# NVIDIA-GPU (CUDA 12), Standard-Image, braucht nvidia-container-toolkit:
docker run -ti --name local-ai -p 8080:8080 --gpus all localai/localai:latest-gpu-nvidia-cuda-12

In der compose.yaml setzen Sie den Image-Tag auf eine GPU-Variante und reservieren die GPU über die deploy-Sektion:

services:
  local-ai:
    image: localai/localai:v4.11.0-gpu-nvidia-cuda-12
    container_name: local-ai
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:8080"
    environment:
      - MODELS_PATH=/models
      - LOCALAI_API_KEY=BITTE-EIGENEN-KEY-SETZEN
    volumes:
      - localai-models:/models
      - localai-data:/data
      - localai-backends:/backends
      - localai-config:/configuration
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia   # Toolkit ab 1.14 mit CDI: driver: nvidia.com/gpu
              count: all
              capabilities: [gpu]
volumes:
  localai-models:
  localai-data:
  localai-backends:
  localai-config:

AMD: latest-gpu-hipblas mit --device=/dev/kfd --device=/dev/dri --group-add=video. Intel: latest-gpu-intel mit --device=/dev/dri/card1 --device=/dev/dri/renderD128. Bei falschem Image-Tag oder fehlendem Toolkit läuft alles auf der CPU oder der Container findet die GPU nicht.

Verifizieren: docker exec local-ai nvidia-smi zeigt die GPU, und während einer Chat-Anfrage steigt dort die Speicherbelegung.

Schritt 7: Reverse-Proxy und HTTPS

Ohne LOCALAI_API_KEY und LOCALAI_AUTH ist die API offen. Veröffentlichen Sie Port 8080 nie ungeschützt, sondern stellen Sie einen Reverse-Proxy mit TLS davor, der auf 443 lauscht und an 127.0.0.1:8080 weiterleitet. Beispiel für nginx:

server {
    listen 443 ssl;
    server_name ki.example.de;

    ssl_certificate     /etc/letsencrypt/live/ki.example.de/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/ki.example.de/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_read_timeout 600s;   # LLM-Antworten koennen dauern
    }
}

Die compose.yaml bindet den Port bereits an 127.0.0.1. Für mehrere Benutzer mit Rollen aktivieren Sie zusätzlich LOCALAI_AUTH=true (Admin- und User-Rolle, optional OIDC).

Verifizieren: curl -I https://ki.example.de/readyz liefert HTTP 200, curl -I http://SERVER-IP:8080 von einem anderen Rechner scheitert mit Connection refused.

Schritt 8: LocalAI als Backend für Chat-UIs

In Chat-Oberflächen wie LibreChat oder AnythingLLM tragen Sie als OpenAI-Base-URL https://ki.example.de/v1 und als API-Key den LOCALAI_API_KEY ein. Der Modellname muss einem installierten Modell entsprechen (z. B. qwen3-4b).

Die wichtigsten OpenAI-kompatiblen Endpunkte im Überblick:

Funktion	Endpunkt
Chat	`/v1/chat/completions`
Completion	`/v1/completions`
Embeddings	`/v1/embeddings`
Bildgenerierung	`/v1/images/generations`
Transkription (STT/Whisper)	`/v1/audio/transcriptions`
Sprachausgabe (TTS)	`/v1/audio/speech`
Modell-Liste	`/v1/models`

Ein Beispiel für Bildgenerierung; installieren Sie vorher ein Bildmodell aus der Gallery (Filter „image generation“) und setzen Sie dessen Namen ein:

curl http://localhost:8080/v1/images/generations \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer BITTE-EIGENEN-KEY-SETZEN" \
  -d '{"model": "NAME-DES-BILDMODELLS", "prompt": "Ein Leuchtturm bei Sonnenuntergang", "size": "256x256"}'

Verifizieren: Die Oberfläche listet die LocalAI-Modelle, und eine Chat-Anfrage aus der UI erscheint in docker compose logs local-ai.

Schritt 9: Update-Workflow und Backup

Für ein Update tragen Sie den neuen Versions-Tag in die compose.yaml ein (Release-Notes auf GitHub prüfen) und führen aus:

docker compose pull && docker compose up -d

Beim Wechsel von v4.10 auf v4.11 nennen die Release-Notes keine Breaking Changes; Volumes, Umgebungsvariablen und API-Endpunkte bleiben gleich. Neu sind unter anderem Failover-Ketten für Modelle, Entscheidungsmodelle über /v1/systemone, signierte OCI-Modell-Galleries und eine Betriebsansicht für Ressourcen, Logs und geladene Modelle auf einem einzelnen Host.

Sichern Sie vor jedem Update die benannten Volumes. Compose stellt den Projektnamen voran (Verzeichnisname, hier localai_); docker volume ls zeigt die Namen. Ein Hilfscontainer packt das Volume in ein Tar-Archiv:

docker run --rm \
  -v localai_localai-models:/models \
  -v $(pwd):/backup \
  alpine tar czf /backup/localai-models.tar.gz -C /models .

Wiederholen Sie das für localai-data und localai-config; Backends lädt LocalAI bei Bedarf neu. Mit den Archiven stellen Sie die Instanz auf einem anderen Host ohne erneuten Modell-Download wieder her.

Verifizieren: tar tzf localai-models.tar.gz | head listet Modelldateien, und docker compose ps zeigt nach dem Update die neue Version im Image-Namen.

Troubleshooting

Modelle nach Update/down weg: Kein Volume auf /models (bzw. MODELS_PATH). Mounten Sie localai-models wie in der compose.yaml und laden Sie die Modelle einmalig neu.
GPU wird nicht genutzt: Falscher Image-Tag oder fehlendes Toolkit, siehe Schritt 6.
Erste Anfrage sehr langsam oder Fehler backend not found: LocalAI lädt beim ersten Einsatz eines Modells das Backend (1 bis 3 GB). Fortschritt in docker compose logs -f local-ai; ohne Internetzugang schlägt der Download fehl.
OOM / Container stürzt ab: RAM/VRAM oder Disk zu knapp. Kleinere Quantisierung, kleineres Modell oder geringere CONTEXT_SIZE wählen.
Veraltetes Image trotz pull: latest-cpu und latest-aio-* werden nicht mehr gepflegt. Nutzen Sie latest oder einen festen Tag wie v4.11.0; die docker-compose.yaml im Repository verweist auf den Entwicklungs-Tag master.
API antwortet mit 401/Unauthorized: Es ist ein LOCALAI_API_KEY gesetzt. Schicken Sie ihn als Authorization: Bearer ...-Header mit.

Häufige Fragen

Worin unterscheidet sich LocalAI von Ollama?

LocalAI deckt Text-LLMs, Embeddings, Bild und Audio (TTS/STT) über die OpenAI-API ab, Ollama nur Text- und Vision-LLMs. Für ein reines Chat-LLM eignet sich Ollama mit Open WebUI per Docker; als OpenAI-Ersatz über mehrere Modalitäten LocalAI.

Brauche ich zwingend eine GPU?

Nein. LocalAI läuft auf der CPU, nur langsamer. Für schnelle Antworten und Bildgenerierung empfiehlt sich eine GPU (Schritt 6).

Soll ich das AIO-Image oder das schlanke Image nehmen?

Sie wurden mit v4.0.0 eingestellt und erhalten keine Updates. Nehmen Sie das Standard-Image und installieren Sie Modelle über die Gallery.

Wie lade ich Modelle in LocalAI?

Über die Model-Gallery der Web-UI, POST /models/apply, local-ai models install, URIs wie huggingface:///ollama:///file:// oder eine GGUF-Datei im /models-Volume.

Kann ich bestehende OpenAI-Tools umlenken?

Ja, mit der LocalAI-Adresse samt /v1 als OpenAI-Base-URL und dem LOCALAI_API_KEY (Schritt 8).

Ist LocalAI nach dem Start abgesichert?

Nein. Ohne LOCALAI_API_KEY bzw. LOCALAI_AUTH=true ist die API offen. Nötig sind API-Key, Port-Bindung an 127.0.0.1 und Reverse-Proxy mit TLS (Schritt 7).

Fazit

Für den Dauerbetrieb von LocalAI mit Docker zählen drei Dinge: Volumes für /models, /configuration und /data, ein gesetzter LOCALAI_API_KEY und ein Reverse-Proxy mit TLS. OpenAI-Tools lenken Sie per Base-URL um, die Daten bleiben im eigenen Haus.

Weiterführende Anleitungen und Quellen

Passende Anleitungen aus unserem Wissensbereich:

Docker Compose: Grundlagen und Stacks – Basis für die hier verwendete compose.yaml.
Ollama mit Open WebUI per Docker – die schlankere Alternative für reines Text-Chat-LLM.
Offene LLMs mit vLLM selbst hosten – High-Throughput-Inferenz für große Modelle.
Alle Anleitungen der Kategorie Künstliche Intelligenz

Quellen (offizielle Doku/Repo, Stand 2026):