Een lokaal taalmodel (LLM) in Docker draaien: De complete gids

Het lokaal draaien van een LLM (Large Language Model) geeft je ongekende controle over je privacy en data. Geen abonnementen, geen datalekken naar de cloud, maar pure rekenkracht op je eigen hardware. Terwijl je software als Ollama of LM Studio direct op je besturingssysteem kunt installeren, kiezen veel ontwikkelaars en hobbyisten ervoor om hun AI-infrastructuur in Docker te draaien.

Docker is een platform waarmee je applicaties in geïsoleerde containers verpakt. Alles wat het taalmodel nodig heeft om te functioneren (bibliotheken, afhankelijkheden en configuraties) zit in één pakketje. Maar het draaien van zware, hardware-intensieve AI-modellen in een container werkt fundamenteel anders dan het hosten van een simpele webserver. In deze gids bespreken we waarom je dit wel (of juist niet) zou willen, hoe je omgaat met hardwareversnelling, en geven we een praktische blauwdruk voor je eigen configuratie.

Waarom een LLM in Docker draaien?

De keuze voor Docker brengt een aantal aanzienlijke voordelen met zich mee, vooral als je complexe AI-applicaties bouwt of je systeem schoon wilt houden.

Volledige isolatie (geen 'Dependency Hell'): AI-applicaties vereisen vaak specifieke versies van Python, PyTorch, CUDA-libraries en andere afhankelijkheden. Door alles in Docker te draaien, voorkom je dat deze pakketten conflicteren met software die al op je computer staat.
Eenvoudig te verplaatsen (Portabiliteit): Heb je een werkende setup gebouwd op je laptop? Je kunt exact dezelfde Docker-container met één commando overzetten naar een krachtige server of een cloud-omgeving. De omgeving is overal identiek.
Reproduceerbaarheid: Via een docker-compose.yml bestand leg je je hele architectuur vast als code. Je weet altijd precies welke versie van het AI-model en welke poorten je gebruikt.
Microservices: In de praktijk draai je vaak niet alleen een model. Je wilt misschien een vector-database voor contextuele zoekopdrachten toevoegen, of een grafische interface zoals beschreven in onze gids over Open WebUI opzetten. Docker Compose koppelt deze verschillende containers moeiteloos aan elkaar via een intern netwerk.

Wil je deze opzet later uitbreiden en het model trainen op je eigen bedrijfsdocumenten? Dan verwijzen we je graag naar het leer-platform voor onze externe cursus RAG voor beginners.

De GPU-valkuil: Waarom Docker soms trager is

Hoewel Docker fantastisch is voor software-isolatie, introduceert het een uitdaging op het gebied van hardware. Taalmodellen hebben extreem veel rekenkracht nodig, bij voorkeur geleverd door een GPU (videokaart). En precies daar wringt de schoen: een Docker-container heeft standaard geen toegang tot de hardware van de host-machine.

Zonder expliciete configuratie draait een LLM in Docker uitsluitend op je processor (CPU). Omdat een CPU data sequentieel verwerkt in plaats van parallel, zal het genereren van tekst tergend langzaam gaan (vaak minder dan 2 tokens per seconde). Om de GPU te gebruiken, moet deze worden 'doorgegeven' (passthrough) aan de container. Hoe goed dit werkt, hangt volledig af van je besturingssysteem.

Verschillen per besturingssysteem

1. Linux met een NVIDIA GPU (De Ideale Situatie)

Docker is oorspronkelijk gebouwd voor Linux. Op een Linux-machine delen containers direct de kernel (het hart) van het besturingssysteem. Als je de NVIDIA Container Toolkit installeert, kun je de kracht van je videokaart vrijwel zonder prestatieverlies doorgeven aan de container. Voor serieuze lokale AI-servers is dit veruit de beste keuze. Lees ook onze gids over hardware voor lokale LLM's om te zien welke kaarten het meest geschikt zijn.

2. macOS (Apple Silicon: M1/M2/M3/M4)

Op een Mac draait Docker niet native. Docker Desktop voor Mac maakt op de achtergrond een verborgen Linux virtuele machine (VM) aan. Het probleem? macOS staat het momenteel niet of nauwelijks toe om de krachtige geïntegreerde GPU's van de Apple Silicon-chips efficiënt door te geven aan deze Linux VM. Hierdoor vallen LLM's in Docker op een Mac vaak terug op de CPU, wat leidt tot dramatisch slechte prestaties vergeleken met native applicaties. Advies: Gebruik op een Mac liever native software zoals Ollama of LM Studio buiten Docker, tenzij je een trage CPU-fallback accepteert voor testdoeleinden.

3. Network Attached Storage (NAS)

Een LLM draaien op een thuisserver is populair, maar een gemiddelde NAS heeft geen krachtige grafische kaart. Je bent hierdoor gebonden aan CPU-inferentie en beperkt RAM-geheugen. Dit maakt het genereren van antwoorden traag. Het kan nuttig zijn voor asynchrone achtergrondtaken, maar verwacht geen real-time chatervaring. Meer hierover lees je in het artikel over een LLM op een Synology NAS.

Praktische Gids: Docker instellen voor LLM's

Als je hebt besloten dat Docker voor jou de juiste route is (bijvoorbeeld op een Linux-machine of Windows met WSL2), zijn er vier cruciale concepten die je correct moet configureren: volumes, netwerken, geheugenlimieten en updates.

1. Docker Volumes (Voorkom dat je modellen kwijtraakt)

LLM's zijn grote bestanden. Een model zoals Llama 3 (8B) neemt al snel 4 tot 5 gigabyte in beslag. Wanneer een Docker-container stopt of wordt verwijderd, verdwijnt standaard ook alle data die erin was opgeslagen. Zonder zogenaamde volumes zou je de gigabytes aan modelbestanden bij elke herstart opnieuw moeten downloaden.

Met een volume koppel je een map op je eigen harde schijf (de host) aan een map in de container. Zelfs als je de container verwijdert om hem te updaten, blijven je gedownloade AI-modellen veilig bewaard op je schijf.

2. Poorten en Netwerk

AI-software in een container draait vaak een lokale API-server (bijvoorbeeld op poort 11434). Om deze API vanaf je eigen computer of vanuit een andere applicatie te benaderen, moet je de poort van de container 'mappen' naar een poort op je host-machine. Zonder deze mapping zit het model geïsoleerd opgesloten en kan het geen opdrachten ontvangen.

3. Geheugenlimieten instellen

Taalmodellen consumeren RAM-geheugen alsof het water is. Als een model tijdens het genereren meer geheugen probeert te gebruiken dan je systeem beschikbaar heeft, grijpt het besturingssysteem in en sluit het willekeurige processen af (de gevreesde OOM-killer, Out Of Memory). Binnen Docker kun je harde limieten instellen (mem_limit) zodat de container nooit je hele systeem kan laten vastlopen.

4. Updaten zonder dataverlies

Een van de mooiste aspecten van Docker is het onderhoud. Is er een nieuwe versie van de LLM-software? Omdat je je modelbestanden veilig in een volume hebt gezet, bestaat een update slechts uit drie simpele stappen in de terminal:

docker pull ollama/ollama:latest (Download de nieuwste software-versie)
docker stop [containernaam] && docker rm [containernaam] (Verwijder de oude container)
Start de container opnieuw met je bestaande volume-commando.

Je software is direct geüpdatet en je modellen staan er nog gewoon.

Stap-voor-stap voorbeeld: Ollama via Docker Compose

De makkelijkste manier om dit alles samen te brengen, is via Docker Compose. Met één configuratiebestand start je zowel de engine die het model draait (Ollama) als een grafische interface. Hier is een productie-klaar docker-compose.yml voorbeeld.

Let op: Dit voorbeeld gaat ervan uit dat je Linux gebruikt met de NVIDIA Container Toolkit geïnstalleerd. Zonder deze toolkit zal Docker de deploy-sectie voor de GPU negeren of een foutmelding geven.

version: '3.8'

services:
  # De AI Engine (Ollama)
  ollama:
    image: ollama/ollama:latest
    container_name: lokale-llm
    restart: unless-stopped
    ports:
      - "11434:11434"
    volumes:
      - ollama_data:/root/.ollama
    # Koppel de NVIDIA GPU aan de container
    deploy:
      resources:
        reservations:
          devices:
            - driver: nvidia
              count: 1
              capabilities: [gpu]

  # De Grafische Interface (Open WebUI)
  open-webui:
    image: ghcr.io/open-webui/open-webui:main
    container_name: llm-interface
    restart: unless-stopped
    ports:
      - "3000:8080"
    volumes:
      - open-webui_data:/app/backend/data
    environment:
      # Vertel de UI waar de AI Engine te vinden is in het Docker-netwerk
      - OLLAMA_BASE_URL=http://ollama:11434
    depends_on:
      - ollama

# Definieer de volumes voor persistente data
volumes:
  ollama_data:
  open-webui_data:

Met dit bestand hoef je in je terminal enkel naar de betreffende map te navigeren en het commando docker-compose up -d uit te voeren. Docker downloadt de benodigde software, koppelt de mappen, verbindt je GPU en start een intern netwerk. Vervolgens kun je je webbrowser openen op http://localhost:3000 om met je eigen lokale model te chatten.

Conclusie

Het draaien van een lokaal LLM in Docker biedt een schone, reproduceerbare en veilige manier om met kunstmatige intelligentie te experimenteren. Hoewel het voor Windows- en Linux-gebruikers met een NVIDIA videokaart de gouden standaard is dankzij uitstekende GPU-passthrough, moeten macOS-gebruikers voorzichtig zijn met prestatieverlies door virtualisatie. Zorg er altijd voor dat je met volumes werkt om je grote modelbestanden te behouden en wees je bewust van het geheugenverbruik van je applicaties.