LocalAI QuickStart: Voer OpenAI-compatibele LLM's lokaal uit

LocalAI is een self-hosted, local-first inference server die ontworpen is om te gedragen als een drop-in OpenAI API voor het uitvoeren van AI-werklasten op uw eigen hardware (laptop, workstation of on-premise server).

Het project richt zich op praktische compatibiliteit met het doel “de cloud API URL vervangen”, terwijl het ondersteuning biedt voor meerdere backends en modaliteiten (tekst, afbeeldingen, audio, embeddings, en meer).

Wat LocalAI is en waarom ingenieurs het gebruiken

LocalAI presenteert een HTTP REST API die belangrijke OpenAI-endpoints nabootst, waaronder chat-completies, embeddings, afbeeldingsgeneratie en audio-endpoints, zodat bestaande OpenAI-compatibele tooling kan worden hergebruikt voor uw eigen infrastructuur.

Basis tekstgeneratie daargelaten, beslaat LocalAI’s functionaliteitset gemeenschappelijke “productie-bouwstenen” zoals embeddings voor RAG, diffusie-gebaseerde afbeeldingsgeneratie, speech-to-text en text-to-speech, met optionele GPU-acceleratie en gedistribueerde patronen.

Als u self-hosted LLM-serving evalueert, is LocalAI interessant omdat het zich richt op API-compatibiliteit (voor eenvoudigere integratie) en tevens een ingebouwde Web UI en een model-galerij-workflow biedt om de wrijving bij het installeren en configureren van modellen te verminderen.

Voor een bredere vergelijking van opties voor self-hosted en cloud LLM-hosting — waaronder Ollama, vLLM, Docker Model Runner en beheerde cloudproviders — zie de LLM hosting gids voor 2026.

Als u een zij-aan-zij analyse wilt van LocalAI tegenover Ollama, vLLM, LM Studio en anderen, behandelt het vergelijken van de belangrijkste lokale LLM-tools in 2026 API-ondersteuning, hardwarecompatibiliteit en productieklare status. Voor de bredere case voor het behoud van modellen op uw eigen infrastructuur, behandelt LLM self-hosting en AI-soevereiniteit data-residentie en nalevingsmotivaties.

LocalAI-installatieopties die in de praktijk goed werken

LocalAI kan op verschillende manieren worden geïnstalleerd, maar voor de meeste teams is de snelste en risicovrijste startpunt containers (Docker of Podman). Als u een commandoverwijzing wilt terwijl u door de voorbeelden hieronder werkt, behandelt de Docker cheatsheet de meest frequente en nuttige Docker-commando’s.

Snelste start met Docker

Dit start de LocalAI-server en bindt de API en Web UI aan poort 8080:

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

De containerdocumentatie van LocalAI noemt dit het snelste pad om een werkende server op te zetten, met de API bereikbaar op http://localhost:8080.

De juiste LocalAI-containerafbeelding kiezen

LocalAI publiceert meerdere containervarianten zodat u uw hardware kunt afstemmen:

• Een CPU-afbeelding voor brede compatibiliteit.
• GPU-specifieke afbeeldingen voor NVIDIA CUDA, AMD ROCm, Intel oneAPI en Vulkan.
• All-in-One (AIO)-afbeeldingen die vooraf zijn geconfigureerd met modellen die gekoppeld zijn aan OpenAI-achtige modelnamen.

De upstream GitHub README bevat concrete docker run-voorbeelden voor CPU-only en diverse GPU-opties (NVIDIA CUDA-varianten, AMD ROCm, Intel, Vulkan), plus AIO-varianten.

Modellen behouden tussen herstarten

Als u geen opslag monteert, kunnen uw gedownloade modellen niet persistent blijven over containerlifecycle-wijzigingen heen. De containerhandleiding beveelt het monteren van een models-volume aan, bijvoorbeeld:

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

Dit maakt /models binnen de container persistent op uw host.

Een minimale Docker Compose QuickStart

LocalAI biedt ook een referentie docker-compose.yaml in het repository, die een veelvoorkomend patroon demonstreert: poort 8080 binden, een /models-volume monteren, MODELS_PATH=/models instellen, en optioneel een model vooraf laden door het op te geven in de commandolijst (het repo-voorbeeld toont phi-2). De Docker Compose cheatsheet is een handige verwijzing bij het aanpassen hiervan aan uw setup.

Een “goede standaard” Compose-setup (CPU) ziet er als volgt uit:

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

Het kernidee is hetzelfde als het upstream-voorbeeld: host modellenmap ↔ container /models.

Als u ook de native docker model-tooling van Docker naast LocalAI gebruikt, behandelt de Docker Model Runner cheatsheet pull, run, package en configuratiecommando’s.

Non-container LocalAI-installaties

LocalAI ondersteunt ook installaties via platform-specifieke methoden (bijvoorbeeld een macOS DMG en Linux-binaires), en bredere implementatieopties zoals Kubernetes.

Als u de voorkeur geeft aan gescripte installaties op Linux, beschrijft de DeepWiki quick start een install.sh-pad dat hardware automatisch detecteert en het systeem daarop configureert.

Een voorspelbare gebruiksvolgorde

Een betrouwbare LocalAI-werkstroom is:

LocalAI starten → model installeren of importeren → geladen modellen verifiëren → OpenAI-compatibele endpoints aanroepen.

Deze volgorde komt overeen met de officiële “Probeer het uit” en “Modellen instellen” richtlijnen, die het proces rondom het starten van de server, installeren van modellen via galerij of CLI, en vervolgens testen van endpoints met curl presenteren.

Server starten en controleren of deze gezond is

Zodra de server draait, is een veelvoorkomende gezondheidscontrole het readiness-endpoint:

curl http://localhost:8080/readyz

De troubleshooting-handleiding gebruikt /readyz als eerste diagnostiek om te bevestigen dat LocalAI responsief is.

Model installeren uit de galerij of URI importeren

LocalAI biedt twee mainstream model-onboardingstromen:

• Model Gallery installatie via Web UI, waarbij u de UI opent, naar het Models-tabblad gaat, modellen doorzoekt en op Installatie klikt.
• CLI-gedreven installatie en uitvoering, met gebruik van local-ai models list, local-ai models install, en local-ai run.

De documentatie ondersteunt ook het importeren van modellen via URI (Hugging Face-repositories, directe model-bestands-URIs en andere registers), en de Web UI bevat een speciaal Import Model-stroom met een YAML-editor voor geavanceerde configuratie.

Verifiëren wat LocalAI denkt dat het kan serveren

Om gedeployde modellen op te lijsten via de OpenAI-compatibele API:

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

Dit wordt expliciet aanbevolen zowel als “volgende stap” na container-installatie als als troubleshooting-diagnostiek.

Belangrijke commandoregelparameters om te leren

LocalAI’s CLI is gebouwd rond het local-ai run-commando, met een uitgebreid configuratieoppervlak. We moeten twee belangrijke operationele gedragingen benadrukken:

• Elke CLI-flag kan worden ingesteld via een omgevingsvariabele.
• Omgevingsvariabelen hebben voorrang boven CLI-flags.

Hieronder staan de parameters die gebruikers meestal vroeg gebruiken, gegroepeerd op intentie. Alle standaardwaarden en omgevingsvariabelenamen zijn afkomstig van de upstream CLI-verwijzing. Als u Ollama naast LocalAI evalueert, behandelt de Ollama CLI cheatsheet zijn serve, run, ps, en modelbeheercommando’s voor vergelijking.

Core server en opslagflags

De LocalAI FAQ documenteert ook standaard modelopslaglocaties en beveelt expliciet LOCALAI_MODELS_PATH of --models-path aan als u modellen buiten de standaarddirectory wilt (bijvoorbeeld om te voorkomen dat een home-directory vol raakt).

Prestatie- en capaciteitflags

Voor bredere compatibiliteit en acceleratiebeperkingen documenteert de modelcompatibiliteitstabel welke backends welke acceleratiemodi ondersteunen (CUDA, ROCm, SYCL, Vulkan, Metal, CPU), en merkt ook op dat modellen die niet expliciek zijn geconfigureerd mogelijk automatisch worden geladen, terwijl YAML-configuratie u gedrag kunt vastpinnen. Voor doorvoer-georiënteerde multi-GPU-implementaties met PagedAttention, doorloopt de vLLM quickstart gids een vergelijkbare OpenAI-compatibele server met productie-georiënteerde configuratie.

API-, beveiligings- en UI flags

Als u LocalAI extern blootstelt, moet u endpoints beschermen en toegang kunnen blokkeren met een API-sleutel, waarbij de API-sleutel effectief volledige toegang verleent.

Web UI-tour en hoe het mapt naar het systeem

Standaard serveert LocalAI een ingebouwde Web UI naast de API (tenzij u deze uitschakelt). De documentatie stelt dat de UI toegankelijk is op hetzelfde host en poort als de server, doorgaans http://localhost:8080.

Wat u kunt doen in de ingebouwde UI

Web UI is een browsergebaseerde interface die behandelt:

• Modelbeheer en de galerij-browservoorwaarde
• Chat-interacties
• Afbeeldingsgeneratie en text-to-speech interfaces
• Gedistribueerde en P2P-configuratie

De routestructuur geeft een duidelijk mentaal model van het UI-oppervlak:

• / voor het dashboard
• /browse voor de modelgalerijbrowser
• /chat/ voor chat
• /text2image/ voor afbeeldingsgeneratie
• /tts/ voor text-to-speech
• /talk/ voor steminteractie
• /p2p voor P2P-instellingen en monitoring

Model Gallery en “Import Model” workflow

Voor ingenieurs is de belangrijkste UI-functie model-onboarding. De officiële “Setting Up Models” handleiding beschrijft:

• Modellen installeren via het Models-tabblad met één-klik installatie.
• Modellen importeren via een Import Model UI die een eenvoudige modus ondersteunt (URI + voorkeuren) en een geavanceerde modus met een YAML-editor en validatietools.

Dit is belangrijk omdat LocalAI uiteindelijk modellen draait op basis van YAML-configuratie: u kunt individuele YAML-bestanden beheren in de modellenmap, een enkel bestand gebruiken met meerdere modeldefinities via --models-config-file, of opstarten verwijzen naar externe YAML-URL’s.

Voorbeelden die u in een terminal kunt plakken

LocalAI’s OpenAI-compatibele endpoints zijn ontworpen om bekende aanvraagformaten te accepteren en JSON-antwoorden terug te geven (met audio-endpoints die audio-payloads teruggeven).

Voorbeeld chat-completies met curl

De LocalAI “Probeer het uit” pagina toont het aanroepen van het chat-completies endpoint direct:

curl http://localhost:8080/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4",
    "messages": [
      { "role": "user", "content": "Schrijf een uitleg van één alinea over wat LocalAI is." }
    ],
    "temperature": 0.2
  }'

AIO-afbeeldingen worden geleverd met vooraf geconfigureerde modellen die gekoppeld zijn aan OpenAI-achtige namen zoals gpt-4, en de containerdocumentatie verklaart dat deze worden ondersteund door open-source-modellen.

Als u geen AIO-afbeelding gebruikt, vervang dan "model" met de naam van het model dat u heeft geïnstalleerd (controleer met /v1/models).

Voorbeeld embeddings voor RAG-pipelines

LocalAI ondersteunt embeddings en documenten dat het embeddings endpoint compatibel is met diverse backends, waaronder llama.cpp, bert.cpp en sentence-transformers.

Een minimaal “embed deze tekst” verzoek tegen het OpenAI-compatibele endpoint ziet er als volgt uit:

curl http://localhost:8080/v1/embeddings \
  -H "Content-Type: application/json" \
  -d '{
    "model": "text-embedding-ada-002",
    "input": "LocalAI embeddings zijn handig voor semantisch zoeken en RAG."
  }'

LocalAI’s embeddings-documentatie toont ook hoe embeddings worden ingeschakeld via YAML-configuratie door embeddings: true in te stellen.

Voorbeeld gebruik van een OpenAI-compatibele client

LocalAI is ontworpen zodat u standaard OpenAI-clientbibliotheken kunt gebruiken door ze te wijzen naar de LocalAI-basis-URL (en optioneel een API-sleutel in te stellen als u authenticatie hebt ingeschakeld). Dit “drop-in vervanging” doel wordt beschreven zowel in de upstream README als in de OpenAI-compatibiliteitsdocumentatie.

Een typische configuratie is:

• Basis URL: http://localhost:8080/v1
• API-sleutel: ofwel niet vereist (standaard) of vereist als u --api-keys hebt geconfigureerd

Beveiliging en troubleshooting essenties

Een LocalAI-server beveiligen voordat u deze blootstelt

LocalAI kan standaard volledig open draaien op localhost. Als u bindt aan een publieke interface of het blootstelt via een ingress, voegt u ten minste een van deze controles toe:

• Inschakelen van API-sleutelauthenticatie met gebruik van --api-keys / API_KEY.
• Een reverse proxy en netwerkcontroles ervoor plaatsen (firewall, allowlisting, VPN).
• De Web UI uitschakelen als u alleen de API nodig heeft (--disable-webui).
• CORS uitgeschakeld houden tenzij een browsergebaseerde client dit echt nodig heeft.

Wanneer API-sleutels zijn ingeschakeld, accepteren de OpenAI-compatibele eindpunten inloggegevens op veelvoorkomende plaatsen zoals een Authorization Bearer header of x-api-key header.

Snelle diagnostiek wanneer iets niet werkt

LocalAI’s troubleshooting handleiding stelt een kleine set controles voor die de meeste “draait het” incidenten oplossen:

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

# modellen lijst
curl http://localhost:8080/v1/models

# versie
local-ai --version

Het documenteert ook het inschakelen van debug-loggen via DEBUG=true of --log-level=debug, en voor Docker-implementaties, het controleren van containerlogs met docker logs local-ai.