LocalAI QuickStart: OpenAI-kompatible LLMs lokal ausführen

LocalAI ist ein selbstgehosteter, lokal-first Inferenzserver, der sich wie eine Drop-in OpenAI API verhält, um KI-Arbeitslasten auf Ihrer eigenen Hardware (Laptop, Workstation oder lokaler Server) auszuführen.

Das Projekt zielt auf eine praktische „Ersetzen der Cloud-API-URL"-Kompatibilität ab und unterstützt gleichzeitig mehrere Backends und Modalitäten (Text, Bilder, Audio, Embeddings und mehr).

Was LocalAI ist und warum Ingenieure es nutzen

LocalAI bietet eine HTTP REST API, die wichtige OpenAI-Endpunkte nachbildet, darunter Chat-Completion, Embeddings, Bildgenerierung und Audio-Endpunkte, sodass bestehende OpenAI-kompatible Tooling auf Ihre eigene Infrastruktur umgeleitet werden kann.

Über die reine Textgenerierung hinaus umfasst das Funktionspaket von LocalAI gängige „Produktions-Bausteine" wie Embeddings für RAG, diffusionsbasierte Bildgenerierung, Spracherkennung und Sprachsynthese, mit optionaler GPU-Beschleunigung und verteilten Mustern.

Wenn Sie selbstgehostete LLM-Serverung evaluieren, ist LocalAI interessant, weil es sich auf API-Kompatibilität (für eine einfachere Integration) konzentriert, während es gleichzeitig eine integrierte Web-Oberfläche und einen Modell-Galerie-Workflow bietet, um die Reibung bei der Installation und Konfiguration von Modellen zu reduzieren.

Für einen breiteren Vergleich von Optionen für selbstgehostete und Cloud-LLM-Hosting – einschließlich Ollama, vLLM, Docker Model Runner und verwalteter Cloud-Anbieter – sehen Sie sich den LLM Hosting Guide für 2026 an.

Wenn Sie eine detaillierte Gegenüberstellung von LocalAI gegenüber Ollama, vLLM, LM Studio und anderen wünschen, deckt der Vergleich der wichtigsten lokalen LLM-Tools im Jahr 2026 API-Unterstützung, Hardware-Kompatibilität und Produktionsreife ab. Für den breiteren Fall, Modelle auf Ihrer eigenen Infrastruktur zu halten, behandelt LLM Self-Hosting und AI Souveränität Datenresidenz und Compliance-Motivationen.

LocalAI-Installationsoptionen, die in der Praxis gut funktionieren

LocalAI kann auf verschiedene Arten installiert werden, aber für die meisten Teams ist der schnellste und risikofreiste Einstiegspunkt Container (Docker oder Podman). Wenn Sie während der Bearbeitung der folgenden Beispiele eine Befehlsreferenz benötigen, deckt das Docker Cheatsheet die häufigsten und nützlichsten Docker-Befehle ab.

Schnellster Start mit Docker

Dies startet den LocalAI-Server und bindet die API und die Web-Oberfläche an Port 8080:

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

Die Container-Dokumentation von LocalAI bezeichnet dies als den schnellsten Weg, einen funktionierenden Server hochzufahren, wobei die API unter http://localhost:8080 erreichbar ist.

Auswahl des richtigen LocalAI-Container-Images

LocalAI veröffentlicht mehrere Container-Varianten, damit Sie diese an Ihre Hardware anpassen können:

• Ein CPU-Image für breite Kompatibilität.
• GPU-spezifische Images für NVIDIA CUDA, AMD ROCm, Intel oneAPI und Vulkan.
• All-in-One (AIO)-Images, die vorkonfiguriert mit Modellen geliefert werden, die OpenAI-ähnlichen Modellnamen zugeordnet sind.

Die upstream GitHub README enthält konkrete docker run-Beispiele für CPU-only und verschiedene GPU-Optionen (NVIDIA CUDA-Varianten, AMD ROCm, Intel, Vulkan) sowie AIO-Varianten.

Modelle zwischen Neustarts persistieren

Wenn Sie keinen Speicher einbinden, werden Ihre heruntergeladenen Modelle möglicherweise nicht über Container-Lebenszyklusänderungen hinweg persistiert. Die Container-Anleitung empfiehlt das Einbinden eines Models-Volumes, zum Beispiel:

docker run -ti --name local-ai -p 8080:8080 \
  -v "$PWD/models:/models" \
  localai/localai:latest-aio-cpu

Dies macht /models innerhalb des Containers persistent auf Ihrem Host.

Ein minimales Docker Compose QuickStart

LocalAI bietet auch eine Referenz docker-compose.yaml im Repository, die ein häufiges Muster demonstriert: Port 8080 binden, ein /models-Volume einbinden, MODELS_PATH=/models setzen und optional ein Modell vorladen, indem es in der Befehlsliste angegeben wird (das Repository-Beispiel zeigt phi-2). Das Docker Compose Cheatsheet ist eine praktische Referenz, während Sie dies an Ihr Setup anpassen.

Ein „guter Standard"-Compose-Setup (CPU) sieht so aus:

services:
  localai:
    image: localai/localai:latest
    container_name: local-ai
    ports:
      - "8080:8080"
    volumes:
      - ./models:/models
    environment:
      - MODELS_PATH=/models

Die Kernidee ist dieselbe wie im upstream-Beispiel: Host-Modellverzeichnis ↔ Container /models.

Wenn Sie neben LocalAI auch die native Docker docker model-Tooling verwenden, deckt das Docker Model Runner Cheatsheet Befehle zum Ziehen, Ausführen, Verpacken und Konfigurieren ab.

Nicht-Container-LocalAI-Installationen

LocalAI unterstützt auch Installationen über plattformspezifische Methoden (zum Beispiel ein macOS DMG und Linux-Binärdateien) und breitere Bereitstellungsoptionen wie Kubernetes.

Wenn Sie skriptbasierte Installationen unter Linux bevorzugen, beschreibt der DeepWiki-Quickstart einen install.sh-Pfad, der die Hardware automatisch erkennt und das System entsprechend konfiguriert.

Eine vorhersehbare Nutzungssequenz

Ein zuverlässiger LocalAI-Workflow ist:

LocalAI starten → Modell installieren oder importieren → geladene Modelle überprüfen → OpenAI-kompatible Endpoints aufrufen.

Diese Sequenz entspricht der offiziellen „Try it out"- und „Setting up models"-Anleitung, die den Prozess um das Starten des Servers, das Installieren von Modellen über Galerie oder CLI und das Testen von Endpoints mit curl herum beschreibt.

Server starten und Gesundheit bestätigen

Sobald der Server läuft, ist ein häufiger Sanity-Check der Readiness-Endpoint:

curl http://localhost:8080/readyz

Das Troubleshooting-Leitbild verwendet /readyz als erste Diagnose, um zu bestätigen, dass LocalAI ansprechbar ist.

Modell aus der Galerie installieren oder URI importieren

LocalAI bietet zwei gängige Modell-Onboarding-Flows:

• Model Gallery Install über die Web-Oberfläche, wobei Sie die UI öffnen, zum Register „Models" gehen, Modelle durchsuchen und „Install" klicken.
• CLI-getriebene Installation und Ausführung, unter Verwendung von local-ai models list, local-ai models install und local-ai run.

Die Dokumentation unterstützt auch den Import von Modellen per URI (Hugging Face Repositories, direkte Modell-Datei-URIs und andere Register) und die Web-Oberfläche enthält einen dedizierten Import-Modell-Flow mit einem YAML-Editor für erweiterte Konfiguration.

Überprüfen, was LocalAI bereitstellen kann

Um bereitgestellte Modelle über die OpenAI-kompatible API aufzulisten:

curl http://localhost:8080/v1/models

Dies wird ausdrücklich sowohl als „nächster Schritt" nach der Container-Installation als auch als Troubleshooting-Diagnose empfohlen.

Wichtige Befehlszeilenparameter zum Lernen

LocalAIs CLI ist um den Befehl local-ai run aufgebaut, mit einer umfassenden Konfigurationsoberfläche. Wir müssen zwei wichtige Betriebsverhalten hervorheben:

• Jeder CLI-Flag kann über eine Umgebungsvariable gesetzt werden.
• Umgebungsvariablen haben Vorrang vor CLI-Flags.

Unten sind die Parameter, die Praktiker am Anfang am häufigsten verwenden, gruppiert nach Absicht. Alle Standardwerte und Namen von Umgebungsvariablen stammen aus der upstream CLI-Referenz. Wenn Sie Ollama neben LocalAI evaluieren, deckt das Ollama CLI Cheatsheet dessen serve, run, ps und Modellverwaltungsbefehle zum Vergleich ab.

Kern-Server- und Speicher-Flags

LocalAIs FAQ dokumentiert auch Standardspeicherorte für Modelle und empfiehlt ausdrücklich LOCALAI_MODELS_PATH oder --models-path, wenn Sie Modelle außerhalb des Standardverzeichnisses speichern möchten (zum Beispiel, um zu verhindern, dass ein Home-Verzeichnis voll wird).

Leistungs- und Kapazitäts-Flags

Für breitere Kompatibilität und Beschleunigungseinschränkungen dokumentiert die Modell-Kompatibilitätstabelle, welche Backends welche Beschleunigungsmodi unterstützen (CUDA, ROCm, SYCL, Vulkan, Metal, CPU), und merkt auch an, dass nicht explizit konfigurierte Modelle automatisch geladen werden können, während YAML-Konfiguration das Verhalten festlegen kann. Für hochdurchsatzfähige Multi-GPU-Bereitstellungen mit PagedAttention führt die vLLM Quickstart-Anleitung durch einen vergleichbaren OpenAI-kompatiblen Server mit produktionsorientierter Konfiguration.

API-, Sicherheits- und UI-Flags

Wenn Sie LocalAI remote exponieren, sollten Sie Endpoints schützen und den Zugriff mit einem API-Schlüssel sperren; der API-Schlüssel erteilt effektiv vollen Zugriff.

Web-Oberfläche Tour und wie sie zum System passt

Standardmäßig dient LocalAI eine integrierte Web-Oberfläche neben der API (es sei denn, Sie deaktivieren sie). Die Dokumentation besagt, dass die UI auf demselben Host und Port wie der Server zugänglich ist, typischerweise http://localhost:8080.

Was Sie in der integrierten UI tun können

Die Web-Oberfläche ist eine browserbasierte Schnittstelle, die Folgendes abdeckt:

• Modellverwaltung und das Galerie-Browsing-Erlebnis
• Chat-Interaktionen
• Bildgenerierung und Text-zu-Sprache-Schnittstellen
• Verteilte und P2P-Konfiguration

Die Routenstruktur bietet ein klares mentales Modell der UI-Oberfläche:

• / für das Dashboard
• /browse für den Modell-Galerie-Browser
• /chat/ für Chat
• /text2image/ für Bildgenerierung
• /tts/ für Text-zu-Sprache
• /talk/ für Sprachinteraktion
• /p2p für P2P-Einstellungen und Überwachung

Modell-Galerie und „Import Model"-Workflow

Für Ingenieure ist das wichtigste UI-Feature das Modell-Onboarding. Die offizielle „Setting Up Models"-Anleitung beschreibt:

• Installieren von Modellen über das Register „Models" mit einem Klick-Install.
• Importieren von Modellen über eine Import-Modell-UI, die einen einfachen Modus (URI + Präferenzen) und einen erweiterten Modus mit einem YAML-Editor und Validierungstools unterstützt.

Dies ist wichtig, weil LocalAI Modelle letztendlich auf Basis von YAML-Konfiguration ausführt: Sie können einzelne YAML-Dateien im Modellverzeichnis verwalten, eine einzelne Datei mit mehreren Modelldefinitionen über --models-config-file verwenden oder Remote-YAML-URLs beim Start referenzieren.

Beispiele, die Sie in ein Terminal einfügen können

LocalAIs OpenAI-kompatible Endpoints sind so konzipiert, dass sie vertraute Request-Formate akzeptieren und JSON-Antworten zurückgeben (mit Audio-Endpoints, die Audio-Payloads zurückgeben).

Beispiel-Chat-Completions mit curl

Die LocalAI „Try it out"-Seite zeigt den Aufruf des Chat-Completions-Endpoints direkt:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Write a one paragraph explanation of what LocalAI is." }
    ],
    "temperature": 0.2
  }'

AIO-Images liefern vorkonfigurierte Modelle, die OpenAI-ähnlichen Namen wie gpt-4 zugeordnet sind, und die Container-Dokumentation erklärt, dass diese von Open-Source-Modellen unterstützt werden.

Wenn Sie kein AIO-Image verwenden, ersetzen Sie "model" mit dem Namen des Modells, das Sie installiert haben (prüfen mit /v1/models).

Beispiel-Embeddings für RAG-Pipelines

LocalAI unterstützt Embeddings und Dokumente, wobei der Embedding-Endpoint mit mehreren Backends kompatibel ist, darunter llama.cpp, bert.cpp und sentence-transformers.

Eine minimale „embed this text"-Anfrage gegen den OpenAI-kompatiblen Endpoint sieht so aus:

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "LocalAI embeddings are handy for semantic search and RAG."
  }'

LocalAIs Embedding-Dokumentation zeigt auch, wie Embeddings durch YAML-Konfiguration aktiviert werden, indem embeddings: true gesetzt wird.

Beispiel mit einem OpenAI-kompatiblen Client

LocalAI ist so konzipiert, dass Sie Standard-OpenAI-Client-Bibliotheken verwenden können, indem Sie sie auf die LocalAI-Base-URL zeigen (und optional einen API-Schlüssel setzen, wenn Sie Authentifizierung aktiviert haben). Dieses „Drop-in Replacement"-Ziel wird sowohl in der upstream README als auch in der OpenAI-Kompatibilitätsdokumentation beschrieben.

Eine typische Konfiguration ist:

• Base URL: http://localhost:8080/v1
• API-Key: entweder nicht erforderlich (Standard) oder erforderlich, wenn Sie --api-keys konfiguriert haben

Sicherheits- und Troubleshooting-Essentials

Einen LocalAI-Server sichern, bevor Sie ihn exponieren

LocalAI kann standardmäßig vollständig offen auf localhost laufen. Wenn Sie an eine öffentliche Schnittstelle binden oder ihn durch einen Ingress exponieren, fügen Sie mindestens eine dieser Kontrollen hinzu:

• API-Schlüssel-Authentifizierung mit --api-keys / API_KEY aktivieren.
• Einen Reverse-Proxy und Netzwerkkontrollen davor platzieren (Firewall, Whitelisting, VPN).
• Die Web-Oberfläche deaktivieren, wenn Sie nur die API benötigen (--disable-webui).
• CORS deaktiviert lassen, es sei denn, ein browserbasierter Client benötigt es tatsächlich.

Wenn API-Schlüssel aktiviert sind, akzeptieren die OpenAI-kompatible Endpoints Credentials an gängigen Orten wie einem Authorization Bearer Header oder x-api-key Header.

Schnelle Diagnose, wenn etwas nicht funktioniert

LocalAIs Troubleshooting-Leitfaden schlägt eine kleine Menge von Checks vor, die die meisten „läuft es"-Vorfälle lösen:

# readiness
curl http://localhost:8080/readyz

# list models
curl http://localhost:8080/v1/models

# version
local-ai --version

Es dokumentiert auch die Aktivierung von Debug-Logging via DEBUG=true oder --log-level=debug, und für Docker-Bereitstellungen das Überprüfen von Container-Logs mit docker logs local-ai.