LocalAI Local Stack (Windows + NVIDIA)

Deze repository bevat een lokale LocalAI setup met GPU-acceleratie en Caddy reverse proxy.

Primair doel:

• Een chat-compatibele LocalAI server lokaal draaien.
• NVIDIA GPU gebruiken via CDI.
• HTTPS endpoint aanbieden via Caddy op poort 8443.

Secundair:

• Referentiebestanden voor distributed mode behouden.

Huidige Scope Van Deze Repo

Werkbestanden voor lokale single-machine setup:

• docker-compose.yaml
• Caddyfile.local

Referentiebestanden (niet de standaard flow):

• docker-compose.dev.yaml
• docker-compose.distributed.yaml
• Caddyfile.example

Vereisten

• Windows host
• NVIDIA GPU
• Container engine met compose ondersteuning (Docker Compose of Podman Compose)
• CDI geconfigureerd voor NVIDIA in de container runtime

Voor Podman CUDA troubleshooting en CDI herstelstappen, zie:

• docs/podman-cuda.md
• docs/named-volumes.md

Aanbevolen Start (Lokale Flow)

Start de stack met het hoofd-composebestand:

podman compose up -d

Of met Docker:

docker compose -f docker-compose.yaml up -d

Endpoints:

• HTTP: http://localhost:8081
• HTTPS: https://localhost:8443

LLM Chat Setup (Gedocumenteerd)

Volgende componenten zijn als chat-compatibele setup gedocumenteerd:

• Gedownload model: qwen3.5-9b
• Gedownloade backend: cuda13-llama-cpp

Praktisch betekent dit:

• Runtime model- en backenddata leven in named volumes, niet meer in de Windows bind mounts.
• LocalAI draait met een CUDA 13 image en gebruikt llama.cpp-compatibele modellen/backends.

TTS Setup (Gedocumenteerd)

Voor Text-to-Speech is volgende setup gekozen:

• Backend: piper
• Stemmodel: voice-nl-rdh-medium

Referentie voor Dutch (Belgium) Piper modellen:

• https://docs.gladecore.com/files/piper-voice-models#dutch-belgium

Opmerking:

• rdh wordt gebruikt als gekozen stem (waarschijnlijk mannelijk profiel).
• nathalie wordt gezien als alternatief (waarschijnlijk vrouwelijk profiel).

Image Generation Setup (Gedocumenteerd)

Voor het genereren van afbeeldingen is volgende setup toegevoegd:

• Model: flux.2-klein-9b
• Backend: cuda13-stablediffusion-ggml

Text-to-Video Setup (Wan)

Voor text-to-video is de meest bruikbare kandidaat op deze machine:

• Model: Wan2.1-T2V-1.3B-Diffusers
• Backend: diffusers

Belangrijk:

• De LocalAI image latest-gpu-nvidia-cuda-13 in deze repo bevat geen vllm backend.
• De UI importflow kan voor Hugging Face modellen toch automatisch op vllm uitkomen.
• Als dat gebeurt krijg je een fout zoals: no backend found with name "vllm".

Gebruik voor Wan daarom geen automatische backenddetectie, maar forceer handmatig diffusers.

Werkende modelconfig:

name: Wan2.1-T2V-1.3B-Diffusers
backend: diffusers
description: Imported manually for LocalAI text-to-video
known_usecases:
  - text-to-video
parameters:
  model: Wan-AI/Wan2.1-T2V-1.3B-Diffusers
f16: true
step: 81  # Wan recommendations: 81 frames per output
gpu_layers: 200  # Force all GPU
diffusers:
  cuda: true
  pipeline_type: WanPipeline
  scheduler_type: FlowMatchEulerDiscreteScheduler
  enable_parameters: negative_prompt,num_inference_steps,guidance_scale,height,width
cfg_scale: 6.0  # Recommended for T2V-1.3B

Praktisch in de UI (Model Editor):

UI-veld	Waarde	Opmerking
Backend	diffusers	Forceer; laat niet auto-detect doen (anders kies het vllm)
Model Name	Wan2.1-T2V-1.3B-Diffusers	Custom naam voor de UI
Description	Imported manually for LocalAI text-to-video	Optioneel
Pipeline Type	WanPipeline	Essentieel voor Wan
Scheduler Type	FlowMatchEulerDiscreteScheduler	Vereist voor Wan (flow-matching)
Enable Parameters	negative_prompt,num_inference_steps,guidance_scale,height,width	Komma-gescheiden; geen spaties
CUDA	Aanvinken	GPU moet ingeschakeld zijn

Model URI (in de YAML of via import dialoog):

• Wan-AI/Wan2.1-T2V-1.3B-Diffusers (geen huggingface:// prefix)

Waarom geen huggingface://? LocalAI's huggingface:// schema werkt niet met de Diffusers backend. De backend ziet het als letterlijk bestandspad en kan het niet vinden. Met alleen de repo ID (Wan-AI/Wan2.1-T2V-1.3B-Diffusers) downlaadt Diffusers' from_pretrained() het correct van HuggingFace.

Bij API-calls:

• Resolutie: 480×832 aangeraden (niet 720P). Vorstuur height: 480, width: 832.
• Frames: Minimal 81 (num_frames: 81 in de pipeline call).
• Guidance scale: 5.0–6.0 (Wan recommends 6.0 for T2V-1.3B).
• FPS: 15 is standaard.
• VAE torch_dtype: float32 (pipeline stelt automatisch bfloat16 in).

⚠️ Bekende beperking: LocalAI API-parameters worden niet altijd correct aan de Diffusers backend doorgegeven. Je kunt de YAML stap-waarde (step: 81) als fallback gebruiken en experimenteren met grootte/fps in directe Diffusers-calls.

Troubleshooting: Wan tensor device mismatch (CPU vs CUDA)

Als je in de logs dit ziet:

• Expected all tensors to be on the same device
• stacktrace in diffusers/schedulers/scheduling_unipc_multistep.py

Dan draait er meestal een scheduler- of modelconfig die niet volledig op GPU blijft.

Typische oorzaken in deze setup:

• De actieve model YAML in de named volume wijkt af van wat je verwacht.
• Een oude/backup YAML is ook geladen en overschrijft de bedoelde modelconfig.
• De scheduler komt toch op UniPCMultistep uit in plaats van een Wan-compatibele flow-matching scheduler.

Aanpak:

1. Controleer eerst welke modelbestanden LocalAI effectief ziet (in de container /models, niet in je Windows map):

docker compose -f docker-compose.yaml exec localai sh -lc "ls -la /models"

2. Zoek dubbele of oude Wan YAMLs en laat slechts 1 actieve versie over met exact dezelfde name als in je API-call.

3. Gebruik voor Wan een flow-matching scheduler in de actieve YAML:

• backend: diffusers
• diffusers.pipeline_type: WanPipeline
• diffusers.scheduler_type: FlowMatchEulerDiscreteScheduler
• diffusers.cuda: true

4. Herstart LocalAI en controleer de startup logs zodat je ziet welke modelconfig geladen werd:

docker compose -f docker-compose.yaml up -d localai docker compose -f docker-compose.yaml logs --tail=200 localai

5. Beperk de eerste test-run om VRAM-druk te verlagen:

• height: 480, width: 832
• num_frames: 81
• num_inference_steps: 20-30

Opmerking: in deze repository leeft de runtime modelstore in named volumes. volumes/models/ in de repo is een referentiepad en hoeft niet identiek te zijn aan wat LocalAI op runtime geladen heeft.

Runtime Settings (Watchdog)

In de LocalAI settings is de watchdog geactiveerd, specifiek met:

• Enable Idle Check: ingeschakeld
• Enable Busy Check: ingeschakeld

Reden: deze checks zijn handig op beperkte hardware om resources beter te beheren.

Belangrijke Bestanden

Bestand	Doel
docker-compose.yaml	Lokale LocalAI + Caddy stack
Caddyfile.local	HTTPS en reverse proxy routing
docs/podman-cuda.md	Podman + CUDA + CDI troubleshooting
docs/named-volumes.md	Waarom LocalAI hier named volumes gebruikt
volumes/models/	Referentiemap in de repo, niet de actieve runtime store
volumes/backends/	Referentiemap in de repo, niet de actieve runtime store
volumes/configuration/	Referentieconfiguratie

Basischecks Na Opstart

Controleer containers:

podman compose ps

Controleer LocalAI health:

Invoke-WebRequest -UseBasicParsing http://localhost:8081/readyz

Controleer Caddy logs:

podman compose logs --tail=80 caddy

Controleer LocalAI logs:

podman compose logs --tail=80 localai

Notes

• Als https://localhost:8443 een 502 geeft, draait meestal de localai service niet; start die opnieuw met podman compose up -d localai.
• Als GPU mount errors naar /usr/lib/wsl/drivers/.../libcuda.so.1.1 verschijnen, regenereer CDI volgens docs/podman-cuda.md.
• Voor LAN-toegang op Windows met Podman/WSL (bijv. https://192.168.x.x:8443) kan een portproxy nodig zijn. Voer in een Administrator PowerShell uit:

netsh interface portproxy add v4tov4 listenport=8443 listenaddress=0.0.0.0 connectport=8443 connectaddress=127.0.0.1

Controle:

netsh interface portproxy show all

• Rootless Podman op Windows bindt vaak enkel op localhost voor gepubliceerde poorten.
• Rootful Podman helpt, maar garandeert in WSL-setup niet automatisch LAN-bereikbaarheid.
• In deze setup is de beslissende stap voor LAN-toegang de Windows netsh interface portproxy regel.