Docker Model Runner: AI-modellen lokaal draaien met gemak

Nu generatieve AI softwareontwikkeling blijft veranderen, zie ik een hardnekkige uitdaging: AI-modellen lokaal draaien is nog altijd complexer dan zou moeten. 

Ontwikkelaars lopen aan tegen gefragmenteerde tooling, hardwarecompatibiliteit en workflows die losstaan van hun dagelijkse ontwikkelomgeving. Docker Model Runner is in april 2025 gelanceerd om deze uitdagingen aan te pakken en het makkelijker te maken AI-modellen lokaal te draaien en te testen binnen bestaande Docker-workflows.

Docker Model Runner markeert een verschuiving van cloudgebaseerde AI naar lokale, gecontaineriseerde workflows, met voordelen als gegevensprivacy, kostenreductie en snellere iteratie, en dat alles geïntegreerd in het Docker-ecosysteem. Uit mijn ervaring met AI-deployments zijn deze voordelen cruciaal voor teams die production-ready applicaties bouwen en tegelijk controle over gevoelige data behouden.

Ben je nieuw met Docker, dan raad ik deze introductiecursus Docker aan. 

Wat is Docker Model Runner?

Traditionele AI-modelserving kent verschillende uitdagingen die ik zelf ook heb ervaren. 

AI-modellen bevatten wiskundige gewichten die, in tegenstelling tot traditionele Docker-images, niet profiteren van compressie. Dit veroorzaakt opslaginefficiënties wanneer modellen met hun runtime worden verpakt. Bovendien zorgen het opzetten van inference-engines, het beheren van hardware-acceleratie en het onderhouden van aparte tooling voor modellen versus applicatiecontainers voor onnodige complexiteit.

Precies hier komt Docker Model Runner om de hoek kijken. In plaats van nóg een tool toe te voegen aan je stack, maakt het het eenvoudig om Large Language Models (LLM’s) rechtstreeks van Docker Hub te pullen, draaien en distribueren in een OCI-conform (Open Container Initiative) formaat of van Hugging Face als modellen beschikbaar zijn in GPT-Generated Unified Format (GGUF). Het platform pakt het fragmentatieprobleem aan door modelbeheer onder te brengen in dezelfde workflow die ontwikkelaars al voor containers gebruiken.

De historische context is belangrijk. Naarmate de adoptie van generatieve AI versnelde, zag de sector een groeiende trend richting veilige, local-first AI-workflows. Organisaties maakten zich steeds meer zorgen over dataprivacy, API-kosten en vendor lock-in bij cloudgebaseerde AI-services. 

Docker werkte samen met invloedrijke namen in AI en softwareontwikkeling, waaronder Google, Continue, Dagger, Qualcomm Technologies, Hugging Face, Spring AI en VMware Tanzu AI Solutions, vanuit de erkenning dat ontwikkelaars een betere manier nodig hadden om lokaal met AI-modellen te werken zonder de gemakken van moderne ontwikkelpraktijken op te geven.

Systeemvereisten voor Docker Model Runner

Voordat we in Docker Model Runner duiken, loop ik de systeemvereisten met je door. Het goede nieuws: gebruik je al Docker, dan ben je al halverwege. Docker Model Runner is nu algemeen beschikbaar en werkt in alle Docker-versies, met ondersteuning voor macOS, Windows en Linux.

Hoewel Docker Model Runner aanvankelijk exclusief op Docker Desktop werd uitgebracht, is het sinds december 2025 compatibel met elk platform dat Docker Engine ondersteunt.

Dit heb je nodig per platform:

Systeemvereisten voor Docker Model Runner

Vereisten voor GPU-acceleratie

Voor GPU-acceleratie ondersteunt Docker Model Runner nu meerdere backends:

• Apple Silicon (M1/M2/M3/M4): Gebruikt Metal API voor GPU-acceleratie, automatisch geconfigureerd.

• NVIDIA GPU’s: Vereist NVIDIA Container Runtime, ondersteunt CUDA-acceleratie.

• ARM/Qualcomm: Hardware-acceleratie beschikbaar op compatibele apparaten.

Daarnaast ondersteunt Docker Model Runner sinds Vulkan oktober 2025, waardoor hardware-acceleratie mogelijk is op een veel bredere reeks GPU’s, inclusief geïntegreerde GPU’s en die van AMD, Intel en andere leveranciers.

Je kunt modellen ook alleen op een CPU draaien, maar GPU-ondersteuning verbetert de inference-prestaties drastisch. We hebben het over het verschil tussen 10 seconden wachten en 3 seconden.

Belangrijke opmerking: Sommige llama.cpp-features worden mogelijk niet volledig ondersteund op 6xx-serie GPU’s, en ondersteuning voor extra engines zoals MLX of vLLM volgt in de toekomst. 

Technische architectuur van Docker Model Runner

Hier wordt het echt interessant. Het architectuurontwerp van Docker Model Runner wijkt af van traditionele containerization op manieren die je kunnen verrassen. Zo werkt het onder de motorkap.

Hybride architectuur

Docker Model Runner hanteert een hybride aanpak die Docker’s orkestratie combineert met native hostprestaties voor AI-inference. Wat maakt deze architectuur onderscheidend? Ze heroverweegt fundamenteel hoe we AI-workloads draaien.

In tegenstelling tot standaard Docker-containers draait de inference-engine niet in een container. De inference-server gebruikt in plaats daarvan llama.cpp als engine, draaiend als een native hostproces dat modellen on demand laadt en direct op je hardware inference uitvoert.

Waarom is dat belangrijk? Deze ontwerpkeuze maakt directe toegang tot Apple’s Metal API voor GPU-acceleratie mogelijk en vermijdt de performance-overhead van inference in virtuele machines. De scheiding tussen modelopslag en -uitvoering is bewust: modellen worden afzonderlijk opgeslagen en alleen geladen wanneer nodig, waarna ze na een periode van inactiviteit weer uit het geheugen worden gehaald. 

Modulaire componenten

Laten we uitzoomen en kijken hoe de onderdelen samenkomen. Op hoofdlijnen bestaat Docker Model Runner uit drie componenten: de model runner, de modeldistributietooling en de model-CLI-plugin. Deze modulaire architectuur maakt snellere iteratie mogelijk en zorgt voor heldere API-grenzen tussen verschillende verantwoordelijkheden. 

Architectuur van Docker Model Runner

Naast de kernarchitectuur anticipeert Docker Model Runner ook op operationele behoeften. De Model Runner stelt metric-endpoints bloot op /metrics, zodat je modelprestaties, verzoeksstatistieken en resourcegebruik kunt monitoren. Deze ingebouwde observability is cruciaal voor productieomgevingen waarin je inzicht nodig hebt in modelgedrag en resourceverbruik.

Kernfeatures van Docker Model Runner

Nu de architectuur duidelijk is, vraag je je waarschijnlijk af: wat kan ik hier concreet mee? Dit zijn de features die Docker Model Runner voor mijn AI-ontwikkelworkflows aantrekkelijk maken.

Een kort overzicht van de opvallende mogelijkheden:

Kernfeatures van Docker Model Runner

De command-line interface integreert soepel met bestaande Docker-workflows. Je gebruikt commando’s zoals docker model pull, docker model run en docker model list, volgens dezelfde patronen die je al kent van werken met containers.

De grafische interface in Docker Desktop biedt begeleide onboarding zodat zelfs beginnende AI-ontwikkelaars modellen soepel kunnen serven, met automatische afhandeling van beschikbare resources zoals RAM en GPU.

Docker Model Hub

Modelverpakking en applicatie-integratie

Laten we nu kijken hoe modellen worden verpakt en gedistribueerd. Docker Model Runner ondersteunt OCI-verpakte modellen, zodat je modellen kunt opslaan en distribueren via elke OCI-compatibele registry, waaronder Docker Hub. Deze gestandaardiseerde verpakking betekent dat je dezelfde versiebeheer-, toegangscontrole- en distributiepatronen kunt toepassen als bij containerimages.

Wat integratie met applicaties betreft: de REST API-mogelijkheden zijn bijzonder waardevol. Docker Model Runner bevat een inference-engine bovenop llama.cpp en is bereikbaar via de vertrouwde OpenAI API. 

Die OpenAI-compatibiliteit betekent dat bestaande code voor de OpenAI-API met minimale aanpassingen met lokale modellen kan werken—wijs je applicatie simpelweg naar de lokale endpoint in plaats van de cloud-API. Alleen al deze flexibiliteit kan weken aan refactoring schelen.

Docker Model Runner instellen

Ik help je stap voor stap om Docker Model Runner op je systeem te krijgen. Het installatieproces is rechttoe rechtaan, maar er zijn enkele platformspecifieke aandachtspunten die handig zijn om vooraf te weten.

Docker Model Runner installeren

Voor macOS- en Windows-gebruikers wordt Docker Model Runner meegeleverd met Docker Desktop 4.40 of hoger. Download simpelweg de nieuwste versie van de officiële Docker-website en installeer deze. Schakel daarna Docker Model Runner in de instellingen in. Ga naar Settings > AI en selecteer de optie Docker Model Runner en GPU-backend inference als je computer een NVIDIA-GPU ondersteunt.

Docker Model Runner activeren

Linux-gebruikers hebben een nog gestroomlijndere ervaring. Update je systeem en installeer de Docker Model Runner-plugin met de volgende commando’s.

sudo apt-get update
sudo apt-get install docker-model-pluginMogelijk gemaakt door

Controleer na installatie of alles werkt met docker model version. 

Docker Model Runner configureren

Op Apple Silicon wordt GPU-acceleratie via Metal automatisch geconfigureerd; extra setup is niet nodig. Voor NVIDIA-GPU’s moet je zorgen dat de NVIDIA Container Runtime is geïnstalleerd. 

Met Vulkan-ondersteuning kun je nu hardware-acceleratie benutten op AMD-, Intel- en andere GPU’s die de Vulkan API ondersteunen. Het systeem detecteert je hardware intelligent en past de juiste acceleratie toe.

Een model downloaden is daarna heel eenvoudig. Je hoeft het model alleen te pullen en vervolgens te runnen om ermee te interacteren:

docker model pull ai/smollm2
docker model run ai/smollm2Mogelijk gemaakt door

Als alles goed is ingesteld, zie je het model in de lijst:

docker model listMogelijk gemaakt door

MODEL NAME                               
ai/smollm2Mogelijk gemaakt door

Modeldistributie en registry-integratie

Als je Docker Model Runner hebt geïnstalleerd en weet hoe je modellen kunt pullen, is de logische vervolgvraag: waar komen deze modellen vandaan en hoe beheer ik ze op schaal? Hier blinkt de aanpak van Docker Model Runner echt uit.

Docker verpakt modellen als OCI-artifacts, een open standaard die distributie via dezelfde registries en workflows mogelijk maakt als voor containers. Teams die al private Docker-registries gebruiken, kunnen dezelfde infrastructuur inzetten voor AI-modellen. Docker Hub biedt enterprise-features zoals Registry Access Management voor beleidsgestuurde toegangscontroles.

Hugging Face-integratie

De integratie met Hugging Face verdient speciale vermelding. Ontwikkelaars kunnen Docker Model Runner gebruiken als lokale inference-engine voor het draaien van modellen op Hugging Face en filteren op ondersteunde modellen (GGUF-formaat vereist) rechtstreeks in de Hugging Face-interface. Dit maakt modelontdekking aanzienlijk eenvoudiger.

docker model pull hf.co/bartowski/Llama-3.2-1B-Instruct-GGUFMogelijk gemaakt door

Het slimme zit ’m in hoe deze integratie onder de motorkap werkt. Wanneer je een model in GGUF-formaat van Hugging Face pullt, pakt Docker Model Runner het automatisch on the fly als een OCI-artifact in. Deze naadloze conversie elimineert handmatige verpakkingsstappen en versnelt de weg van modelontdekking naar deployment.

Beschikbare modellen in Docker Model Runner

Begrijpen hoe distributie werkt is mooi, maar welke modellen kun je daadwerkelijk draaien? Dit is wat out-of-the-box beschikbaar is en hoe je meer vindt.

Docker Model Runner biedt een samengestelde selectie modellen die je direct kunt gebruiken. SmolLM2 is een populaire keuze, perfect voor chatassistenten, tekstanalyse, herschrijven en samenvatten, met 360 miljoen parameters. Ik vind dit model bijzonder handig voor development en testen vanwege de kleine omvang en snelle inference.

AI-modelcatalogus van Docker Hub

Voor het ontdekken van extra modellen raad ik aan te beginnen met de AI-modelcatalogus van Docker Hub. Bekijk beschikbare modellen, check hun documentatie voor ondersteunde taken en hardwarevereisten, en pull ze vervolgens met een simpele docker model pull. 

Modellen worden de eerste keer dat je ze gebruikt van Docker Hub gepulld en lokaal opgeslagen. Ze worden pas tijdens runtime in het geheugen geladen wanneer er een request binnenkomt en weer uitgeladen als ze niet worden gebruikt, om resources te optimaliseren. 

Deze aanpak houdt je systeem responsief, zelfs met meerdere gedownloade modellen. Je hoeft niet alles tegelijk in RAM te houden.

Modelkwantisatie-niveaus en versiebeheer

Bij elke modellisting staat informatie over kwantisatieniveaus (zoals Q4_0, Q8_0), die invloed hebben op modelgrootte en inference-kwaliteit.

Modelkwantisatie

Een belangrijk aandachtspunt is modelversiebeheer. Je kunt exacte versies specificeren met tags (zoals Q4_0 of latest), vergelijkbaar met Docker-images. Dit waarborgt reproduceerbare deployments en voorkomt onverwachte wijzigingen bij modelupdates. 

API-integratie met Docker Model Runner

Als je modellen lokaal hebt draaien, is de vraag: hoe koppel ik m’n applicaties? Wanneer host-side TCP-ondersteuning is ingeschakeld (bijv. via de TCP-instellingen van Docker Desktop), draait de standaard API-endpoint op localhost:12434, met OpenAI-compatibele endpoints.

API-integratie van Docker Model Runner

Hier is een eenvoudig voorbeeld om een request te maken:

curl http://localhost:12434/engines/llama.cpp/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "ai/smollm2",
    "messages": [{"role": "user", "content": "Explain containerization"}],
    "stream": false
  }'Mogelijk gemaakt door

Voor microservice-architecturen kunnen je applicatiecontainers met de modelservice communiceren via standaard HTTP-protocollen—er zijn geen speciale SDK’s nodig. Response-streaming wordt ondersteund voor realtime-applicaties door "stream": true in te stellen.

De REST API-documentatie biedt complete endpointspecificaties, parameteropties en response-schema’s. Raadpleeg de officiële Docker-documentatie voor de meest actuele API-details, aangezien het platform zich snel ontwikkelt.

Prestaties optimaliseren met Docker Model Runner

Optimale prestaties uit Docker Model Runner halen vraagt om een paar belangrijke strategieën. Dit zijn mijn lessen uit werken met lokale modeldeployments.

Doordat Model Runner als host-level proces met directe GPU-toegang draait, behaalt het betere performance-optimalisatie dan gecontaineriseerde oplossingen. Deze architecturale keuze betaalt zich terug in throughput en latency, maar je moet nog steeds goed tunen om het maximale eruit te halen.

Hardware-acceleratie is je eerste optimalisatiehefboom. GPU-ondersteuning levert doorgaans 2-3x verbetering op ten opzichte van alleen CPU-inference. Daarnaast is modelkwantisatie je tweede grote draaiknop. Ik begin meestal met Q8_0 voor beste kwaliteit en ga dan naar Q5_0 of Q4_0 als ik meer performance nodig heb.

Het ingebouwde metrics-endpoint op /metrics maakt monitoring met Prometheus of je bestaande monitoringstack mogelijk. Voor schalen: configureer de contextlengte op basis van daadwerkelijke behoefte en niet op maximumwaarden. Als je applicatie slechts 2048 tokens context nodig heeft, configureer dan niet op 8192.

Integratie met het Docker-ecosysteem

Een van de sterkste voordelen van Docker Model Runner is de integratie met het bredere Docker-ecosysteem. 

Docker Model Runner ondersteunt Docker Compose. Dit betekent dat je multi-service-applicaties kunt definiëren waarbij één service een AI-model is, en de hele stack beheren met vertrouwde Docker Compose-bestanden. Zo ziet dat eruit:

services:
  app:
    image: my-app:latest
    models:
      - llm
      - embedding

models:
  llm:
    model: ai/smollm2
  embedding:
    model: ai/embeddinggemmaMogelijk gemaakt door

Je kunt ook CI/CD-workflows automatiseren: modellen opstarten in je testomgeving, integratietests ertegen draaien en alles weer afbouwen—allemaal binnen je bestaande pipeline-infrastructuur. Dit haalt het “het werkt op mijn machine”-probleem bij AI-features weg.

Een andere interessante integratie is Docker Offload, waarmee je je lokale workflow indien nodig uitbreidt naar de cloud.  Hoewel het nog een bètaversie is, kun je lokaal ontwikkelen met Docker Model Runner en resource-intensieve inference naar cloudinfrastructuur offloaden wanneer de eisen de lokale capaciteit overstijgen.

Docker Offload

Ondersteuning voor draaien in Kubernetes is ook beschikbaar als een Helm-chart en een statisch YAML-bestand. Dit opent mogelijkheden voor deployments op productieschaal met horizontaal schalen, load balancing en hoge beschikbaarheid. 

Hoewel nog experimenteel, markeert Kubernetes-integratie de evolutie van Docker Model Runner richting enterprise-grade deployments, waarbij je duizenden requests per seconde over meerdere replicas serveert.

Gegevensbescherming met Docker Model Runner

Met al deze integratie-opties vraag je je misschien af: maar is het veilig? Docker Model Runner draait in een geïsoleerde, gecontroleerde omgeving en biedt sandboxing voor security. Deze isolatie voorkomt dat modellen toegang krijgen tot gevoelige systeemresources buiten wat expliciet is toegestaan.

Het primaire beveiligingsvoordeel is dataprivacy. Je inference-requests verlaten je infrastructuur niet, waardoor het risico op data-exfiltratie verdwijnt. Voor organisaties die met gevoelige data werken is deze lokale uitvoeringsmodus essentieel voor compliance met GDPR, HIPAA en andere privacyregelgeving.

Beheerders kunnen host-side TCP-ondersteuning en CORS configureren voor fijne-grained beveiligingscontrole. Modellenselicentiemetadata in registries maakt compliance-tracking en auditeerbare sporen mogelijk voor enterprise governance.

Docker Model Runner vs. Ollama vs. NVIDIA NIM

Je vraagt je nu wellicht af: hoe verhoudt dit zich tot tools die ik al gebruik? Zo vergelijkt Docker Model Runner met Ollama en NVIDIA NIM:

Het belangrijkste onderscheid voor Docker Model Runner is ecosysteemintegratie. Het behandelt AI-modellen als first-class citizens naast containers, waardoor toolsprawl afneemt voor Docker-centrische teams. 

Ollama biedt meer modelaanpassing en een volwassen community met uitgebreide SDK’s. NVIDIA NIM levert de hoogste prestaties voor NVIDIA GPU’s, maar mist de flexibiliteit en cross-platform ondersteuning van de andere opties.

Probleemoplossing met Docker Model Runner

Tot slot: wat als iets niet werkt?

Fout: “docker: 'model' is not a docker command”

Deze fout betekent meestal dat de Docker CLI het plugin-uitvoerbare bestand niet kan vinden.

• Oorzaak: Docker kan de plugin niet vinden in de verwachte CLI-plugindirectory.

• Oplossing: Waarschijnlijk moet je een symbolische link (symlink) aanmaken naar het uitvoerbare bestand. Raadpleeg de installatiesectie voor de specifieke commando’s.

Problemen met model-digests

Het kan momenteel mislukken om specifieke digests te gebruiken om modellen te pullen of te refereren.

• Workaround: Verwijs naar modellen via hun tagnamen (bijv. model:v1) in plaats van via hun digest.

• Status: Het engineeringteam werkt actief aan volledige digest-ondersteuning voor een toekomstige release.

GPU-acceleratie werkt niet

Als je modellen traag draaien of de GPU niet gebruiken, doe dan deze checks:

• Controleer drivers: Zorg dat de GPU-drivers van je host up-to-date zijn.

• Check permissies: Bevestig dat Docker permissies heeft om GPU-resources te benaderen.

• Linux (NVIDIA): Zorg dat de NVIDIA Container Runtime is geïnstalleerd en geconfigureerd.

• Verificatie: Voer het volgende commando uit om te bevestigen dat de GPU zichtbaar is voor het systeem: nvidia-smi

Hulp krijgen

Kom je een issue tegen dat hier niet staat?

• Dien een issue in: Meld bugs of vraag features aan in de officiële GitHub-repository.

• Community: Er is een actieve community die vaak snel workarounds biedt voor edge-cases.

Conclusie

Docker Model Runner is een belangrijke stap om AI-ontwikkeling toegankelijker te maken. Door modelbeheer naar het Docker-ecosysteem te brengen, neemt het de frictie weg die AI-adoptie historisch heeft vertraagd.

Het strategische belang gaat verder dan gemak. In een tijd waarin dataprivacy, kostenbeheersing en ontwikkelsnelheid belangrijker zijn dan ooit, wordt lokale AI-executie steeds crucialer. Docker Model Runner maakt het makkelijker om te experimenteren en AI-applicaties te bouwen met dezelfde Docker-commando’s en workflows die ontwikkelaars dagelijks gebruiken.

Vooruitkijkend evolueert het platform door ondersteuning voor extra inference-bibliotheken, geavanceerde configuratieopties en gedistribueerde deployment-mogelijkheden. De convergentie van containerization en AI is waar de industrie naartoe beweegt, en Docker Model Runner staat op dit kruispunt—waardoor privacygerichte, kosteneffectieve AI-ontwikkeling werkelijkheid wordt voor miljoenen ontwikkelaars die al Docker gebruiken.

Nu je modellen in je lokale Docker-omgeving draaien, is de volgende stap om er een betrouwbare pipeline omheen te bouwen. Beheers de principes van modelversiebeheer, deployment en lifecyclemanagement met de MLOps Fundamentals Skill Track op DataCamp.