Ce post répond à cette question, et explique comment les modèles open-source circulent depuis les labos de recherche jusqu'à ton cluster.

Pourquoi la quantization existe : trois objectifs​

La quantization n'est pas une astuce technique pour "faire tenir un modèle". C'est une réponse à trois problèmes concrets.

1. Démocratiser l'accès​

Sans quantization, un modèle 7B en FP16 occupe 14 Go de VRAM. Il te faut une RTX 3080 (700€ minimum) ou une A100 (10 000€ en datacenter). Seuls les labos de recherche bien financés et les grandes entreprises peuvent faire de l'inférence locale.

Avec Q4_K_M, ce même modèle tient en 4.7 Go de RAM. Un ThinkPad d'occasion à 300€ peut le faire tourner. C'est ce changement qui a déclenché l'explosion de l'open-source LLM en 2023 : le jour où des modèles de qualité sont devenus accessibles sur du hardware grand public.

2. Accélérer l'inférence​

Moins de bits ne signifie pas seulement moins de mémoire — cela signifie aussi moins de données à lire depuis la RAM à chaque calcul.

Sur CPU, la vitesse de génération de tokens est souvent limitée par la bande passante mémoire : le processeur doit lire les poids du modèle à chaque étape de génération. Un modèle Q4 lit 8× moins de données qu'un modèle FP32. En pratique, un 7B Q4_K_M génère souvent 1.5 à 2× plus de tokens par seconde qu'un 7B Q8 — pas seulement parce qu'il est plus petit, mais parce que les lectures mémoire sont plus rapides.

3. Permettre le déploiement privé​

C'est l'objectif le plus stratégique pour les entreprises.

Si tu utilises l'API OpenAI ou Groq, chaque message de tes utilisateurs traverse les serveurs d'une entreprise tierce. Pour un usage personnel ou grand public, c'est acceptable. Pour des données médicales, financières, ou industrielles, c'est souvent impossible légalement et inacceptable en termes de confidentialité.

Un LLM quantisé qui tourne en local résout ce problème par l'architecture : les données ne quittent jamais l'infrastructure. Sur minicloud, les interactions avec Open WebUI ne quittent pas le cluster. C'est une propriété garantie par le design, pas par une promesse contractuelle.

Le cycle de vie d'un modèle open-source​

Il y a une question que peu de gens se posent quand ils font ollama pull : d'où vient ce fichier, et qui l'a préparé ?

Voici ce qui se passe entre la sortie d'un modèle et son exécution sur ton cluster.

Étape 1 — Entraînement par le labo​

Un laboratoire (Meta, Alibaba, Mistral, Microsoft...) entraîne le modèle sur des milliers de GPUs pendant des semaines ou des mois. Le résultat : des poids en FP32 ou BF16 — la représentation la plus précise possible des connaissances acquises.

Ces poids sont publiés sur HuggingFace. Le modèle original de Qwen 2.5 7B par Alibaba, par exemple, est disponible là-bas en BF16 (~14 Go).

Étape 2 — Quantization par la communauté​

Des membres de la communauté open-source prennent ces poids FP16/BF16 et créent des versions quantisées. Les noms les plus connus dans cet écosystème : bartowski, TheBloke, unsloth.

Leur travail :

1. Télécharger les poids originaux depuis HuggingFace
2. Appliquer llama.cpp ou d'autres outils pour créer les fichiers GGUF
3. Générer toutes les variantes : Q2_K, Q3_K_M, Q4_K_M, Q5_K_M, Q8_0
4. Publier ces fichiers dérivés sur HuggingFace

C'est un travail bénévole, non rémunéré, qui rend l'écosystème possible.

Étape 3 — Packaging par Ollama​

Ollama récupère les fichiers GGUF créés par la communauté et les rend disponibles via son registry (registry.ollama.ai). Il ajoute un Modelfile qui précise le template de prompt, le system message par défaut, et les paramètres d'inférence recommandés.

# Ce que tu fais :
ollama pull qwen2.5:7b-instruct-q4_k_m

# Ce qui se passe :
# → Ollama contacte registry.ollama.ai
# → Télécharge les blobs GGUF Q4_K_M (~4.7 Go)
# → Les stocke dans /root/.ollama/models/
# → Le modèle est prêt à l'inférence

Étape 4 — Inférence sur ton cluster​

Le modèle tourne dans un pod Ollama, pinné sur un nœud spécifique. LiteLLM route les requêtes vers l'instance la moins occupée. L'utilisateur voit une réponse en quelques secondes.

Utilisateur → Open WebUI → LiteLLM → Ollama (pod fast-heron)
                                           ↓
                                   qwen2.5:7b-instruct-q4_k_m
                                   (GGUF Q4_K_M, 4.7 Go en RAM)

Modèles non-quantisés vs quantisés — ce sont des artefacts différents​

Une confusion fréquente : on parle de "le modèle" comme s'il n'en existait qu'une version. En réalité :

Le modèle original et ses versions quantisées coexistent sur HuggingFace. Elles ne se remplacent pas — elles servent des usages différents.

Les 3 vraies façons de spécialiser un LLM​

Avant d'aller plus loin, une distinction essentielle que beaucoup de ressources mélangent.

Ces trois techniques sont complémentaires, pas substituables. On peut les combiner — et c'est exactement ce que fait le pipeline phi3-financial sur minicloud.

Le cas de phi3-financial — Modelfile, pas fine-tuning​

Il est tentant d'appeler phi3-financial un modèle fine-tuné parce qu'il a un nom distinct dans ollama list. Mais la preuve par les chiffres contredit cette interprétation :

kubectl exec -n ai deployment/ollama -- ollama list

phi4-mini:latest       78fad5d182a7    2.5 GB
phi3-financial:latest  66e3380808ef    2.5 GB

Exactement la même taille. Un vrai fine-tuning modifie les valeurs des poids — la taille du fichier GGUF résultant varie légèrement. Ici les deux fichiers font 2.5 GB, ce qui indique que les poids sont identiques.

phi3-financial est un Ollama Modelfile : une configuration qui enveloppe phi4-mini avec un system prompt et des paramètres d'inférence, sans toucher aux poids.

FROM phi4-mini

SYSTEM """
Tu es un expert en analyse financière spécialisé dans le secteur des assurances.
Tu analyses uniquement des données financières et réponds de façon précise et factuelle.
"""

PARAMETER temperature 0.3

Quand tu fais ollama create phi3-financial -f Modelfile, Ollama crée une nouvelle entrée dans son registry avec ce nom et cette configuration. Les poids sont identiques à ceux de phi4-mini — aucun entraînement n'a eu lieu.

La spécialisation de phi3-financial vient en réalité de trois couches empilées :

Requête utilisateur
    │
    ▼
LangfusePromptHandler (LiteLLM CustomLogger)
    │ Injecte le system prompt financier depuis Langfuse
    │ (versioning des prompts, A/B testing possible)
    ▼
phi3-financial Modelfile
    │ Applique temperature=0.3, contraintes de persona
    ▼
phi4-mini GGUF Q4_K_M
    │ Poids identiques au modèle original Microsoft
    ▼
Réponse générée

C'est une spécialisation par prompt engineering en profondeur, pas du fine-tuning. C'est parfaitement valide et largement utilisé en production — plus rapide à itérer, plus facile à maintenir, aucun GPU requis.

Quand le fine-tuning devient nécessaire​

Le fine-tuning n'est justifié que dans des cas précis :

Nouvelles connaissances factuelles — si le modèle doit connaître des faits qui n'étaient pas dans ses données d'entraînement (documentation interne, terminologie propriétaire, données post-cutoff).

Comportement très contraignant — si le system prompt seul ne suffit pas à maintenir le persona sous des prompts adversariaux.

Efficacité à l'inférence — un modèle fine-tuné sur une tâche précise peut atteindre de meilleures performances avec un context plus court, ce qui réduit les coûts.

Pour phi3-financial, le RAG + LangfusePromptHandler couvre les deux premiers besoins sans les coûts d'un fine-tuning réel. Si le pipeline nécessitait un jour de connaître des règlements ACPR très spécifiques absents du pre-training, le fine-tuning deviendrait pertinent.

Ce que ça implique concrètement pour l'inférence​

Ces types de modèles ne s'utilisent pas de la même façon dans un stack de production.

Le modèle original (FP16) — uniquement pour le fine-tuning. Il faut au minimum un GPU avec 14 Go de VRAM et du temps de calcul. C'est l'entrée d'un pipeline ML, pas sa sortie.

Le modèle quantisé (GGUF Q4_K_M) — ce que tu déploies en production pour l'inférence. Tourne sur CPU, sur des GPUs grand public, sur du hardware embarqué. C'est la sortie du pipeline, celle qui crée de la valeur.

Le Modelfile — une couche de configuration au-dessus d'un modèle quantisé existant. Zéro coût de calcul supplémentaire, itération rapide sur le comportement. C'est l'état réel de phi3-financial sur minicloud.

Pourquoi c'est important pour le déploiement en entreprise​

Dans un contexte professionnel, ces quatre niveaux correspondent à des rôles distincts :

Sur minicloud, ces rôles sont joués par une seule personne. En entreprise, ce sont des équipes distinctes avec des compétences différentes. Comprendre quelle technique appartient à quel niveau — et pourquoi — est ce qui distingue un ingénieur qui "utilise des LLMs" d'un ingénieur qui "conçoit des systèmes AI".

La quantization a résolu ce problème. Pas en sacrifiant la qualité — en changeant la façon dont les poids sont stockés.

Ce qu'est un paramètre, concrètement​

Un LLM "7B" a 7 milliards de paramètres. Chaque paramètre est un nombre en virgule flottante — un poids appris pendant l'entraînement qui encode une fraction des patterns vus dans les données.

En FP32 (float 32 bits), chaque paramètre occupe 4 octets.

7 000 000 000 paramètres × 4 octets = 28 000 000 000 octets = 28 Go

28 Go juste pour charger le modèle en RAM. Sans compter le KV cache pendant l'inférence, les activations, l'overhead du runtime.

Sur un ThinkPad avec 16 Go de RAM système et 8 à 12 Go disponibles pour les workloads : impossible.

Le principe de la quantization​

La quantization réduit la précision de chaque paramètre — moins de bits par nombre, moins de mémoire, au prix d'une légère perte de précision.

L'analogie : imagine que tu mesures une distance. En FP32, tu utilises une règle au millimètre. En Q4, tu utilises une règle au centimètre. Pour construire une maison, la différence est négligeable. Pour de l'horlogerie de précision, ça change tout.

Pour les LLMs, la grande majorité des tâches — conversation, résumé, code, Q&A — tolèrent très bien la réduction de précision des poids. Le réseau neuronal est redondant par nature : des millions de paramètres collaborent pour chaque réponse, et une légère imprécision sur chacun ne change pas le résultat global de façon perceptible.

La hiérarchie des formats​

FP32    4 bytes/param   7B = 28.0 Go   référence
FP16    2 bytes/param   7B = 14.0 Go   
Q8_0    1 byte/param    7B =  7.0 Go   
Q4_K_M  ~0.5 byte       7B =  4.7 Go   ← le point d'équilibre
Q3_K_M  ~0.4 byte       7B =  3.9 Go   dégradation notable
Q2_K    ~0.25 byte      7B =  2.7 Go   à éviter

Chaque niveau vers le bas divise approximativement la mémoire par deux, mais la perte de qualité n'est pas linéaire. De FP32 à Q4_K_M, la dégradation est quasi imperceptible en pratique. De Q4 à Q2, elle devient audible — hallucinations plus fréquentes, raisonnement moins stable.

Ce que signifient les suffixes​

Si tu vas sur Ollama ou HuggingFace, tu verras des noms comme Q4_K_M, Q5_K_S, IQ3_XS. Voici comment les lire :

Le chiffre — le nombre de bits par paramètre.

• Q4 = 4 bits
• Q5 = 5 bits
• Q8 = 8 bits

La lettre après le chiffre — la méthode de quantization.

• _K = "K-quant" — une méthode qui quantize différemment selon l'importance relative de chaque couche du réseau. Plus intelligente que la quantization uniforme.
• _0 = quantization uniforme basique (plus ancienne).

La dernière lettre — la taille des "blocs" de calcul.

• _S (Small) = plus petit, légèrement plus rapide, légèrement moins précis.
• _M (Medium) = équilibre qualité/vitesse.
• _L (Large) = plus précis, un peu plus lent.

Résumé pratique :

• Q4_K_M = 4 bits, K-quant, taille medium → le choix par défaut.
• Q5_K_M = 5 bits, K-quant, medium → +20% de RAM, presque aucune perte vs Q4.
• Q8_0 = 8 bits, uniforme → pratiquement identique à FP16.
• IQ3_XS = une variante "importance-aware" à 3 bits → pour situations très contraintes.

Les quatre familles de formats​

Selon ton hardware, tu croiseras quatre formats principaux :

GGUF — le format CPU-first​

Développé par llama.cpp, utilisé par Ollama. Conçu pour tourner sur CPU avec possibilité d'offloader des couches vers un GPU si disponible.

C'est le format qu'on utilise sur minicloud. Tous les suffixes Q4_K_M, Q5_K_M, etc. font référence à GGUF.

Avantage : fonctionne sans GPU, très bien optimisé pour les architectures x86 modernes. Inconvénient : moins efficace qu'un format GPU-natif si tu as un GPU.

GPTQ — quantization post-training orientée GPU​

Quantize les poids après entraînement en minimisant l'erreur de reconstruction. Très bon si tu as assez de VRAM.

Avantage : bonne qualité sur GPU. Inconvénient : CPU-unfriendly, nécessite ExLlama ou AutoGPTQ pour l'inférence.

AWQ — Activation-aware Weight Quantization​

Plus récent que GPTQ. L'idée : certains paramètres sont plus importants que d'autres (ceux qui activent souvent). AWQ les protège en les quantizant moins agressivement.

Avantage : meilleure qualité que GPTQ à même taille, de plus en plus standard. Inconvénient : nécessite un runtime compatible (vLLM, AutoAWQ).

EXL2 — ExLlamaV2​

Format propriétaire à ExLlamaV2, très efficace pour l'inférence GPU en batch. Permet des taux de bits mixtes par couche.

Avantage : débit maximal sur GPU NVIDIA. Inconvénient : écosystème plus fermé, pas pour CPU.

La règle d'or​

Descends d'un niveau de quantization avant de descendre à un modèle plus petit.

Un 7B Q4 surpasse un 3B Q8 sur presque toutes les tâches — raisonnement, suivi d'instructions, cohérence longue. Les 7 milliards de paramètres, même légèrement imprécis, encodent plus de connaissance que 3 milliards de paramètres très précis.

Concrètement sur minicloud :

Pour 1.7 Go de RAM supplémentaire, on gagne un saut de qualité massif.

L'impact sur la qualité — les chiffres réels​

Le standard de mesure de la dégradation par quantization est la perplexité — une mesure de la "surprise" du modèle face à un texte de référence. Plus la perplexité est basse, mieux le modèle prédit le langage.

Sur Llama 3 8B (valeurs représentatives de la famille 7-8B) :

En pratique : entre FP16 et Q4_K_M, la différence de perplexité est de 1.6%. Dans une conversation réelle, c'est imperceptible. Entre Q4 et Q2, le saut de 16.8% correspond à des réponses notablement moins cohérentes sur les tâches complexes.

Ce que ça donne sur le cluster minicloud​

Le cluster tourne sur des ThinkPads CPU-only (pas de GPU). La contrainte est réelle.

Avant : phi4-mini (3.8B, format propriétaire Microsoft) — 2.5 Go en RAM, ~15 tokens/sec sur ThinkPad.

Après : qwen2.5:7b-instruct-q4_k_m (7B, GGUF Q4_K_M) — 4.7 Go en RAM, ~10 tokens/sec.

On perd 5 tokens/sec (vitesse), on gagne 15–20% de qualité sur les benchmarks. Pour du chat interactif où l'utilisateur lit à 4–5 mots/seconde, 10 tokens/sec est largement suffisant.

# Vérifier les modèles chargés sur les 3 instances Ollama
kubectl exec -n ai deployment/ollama -- ollama list
kubectl exec -n ai deployment/ollama-secondary -- ollama list
kubectl exec -n ai deployment/ollama-tertiary -- ollama list

NAME                          ID              SIZE
qwen2.5:7b-instruct-q4_k_m    845dbda0ea48    4.7 GB
phi4-mini:latest               78fad5d182a7    2.5 GB
deepseek-r1:7b                 755ced02ce7b    4.7 GB
...

Trois instances Ollama, chacune sur un nœud différent. LiteLLM route les requêtes vers l'instance la moins occupée. La quantization Q4_K_M est ce qui rend ce setup possible sur du hardware grand public.

Comment choisir​

Tu as un GPU avec assez de VRAM ?
├── Oui → AWQ ou GPTQ (meilleure qualité à même taille que GGUF)
└── Non → GGUF, et le format :

    RAM disponible pour le modèle ?
    ├── < 5 Go    → Q4_K_M  (défaut)
    ├── 5–7 Go    → Q5_K_M  (si tu peux)
    ├── 7–15 Go   → Q8_0    (quasi-FP16)
    └── > 15 Go   → FP16    (référence)

    Q2 ou Q3 ?
    └── Éviter sauf contrainte extrême (edge, IoT, <3 Go impératif)

Ce qu'on retient​

La quantization n'est pas un compromis entre "bon modèle" et "modèle qui tient en RAM". C'est une technique mature, mesurée, avec des pertes de qualité documentées et prévisibles.

Q4_K_M est devenu le standard de facto de l'écosystème open-source pour une raison : c'est le point où la perte de précision devient théorique plutôt que pratique pour la grande majorité des tâches.

Sur minicloud, c'est ce qui permet de faire tourner un LLM 7B de qualité production sur du matériel qu'on aurait jeté il y a trois ans.

There are more ways to install Kubernetes than there are Kubernetes certification paths. I ended up with k3s. Here is why — and exactly what the installation looked like.

The Constraint That Made the Decision​

Choosing a Kubernetes distribution for this cluster was not a philosophical debate. The hardware made the decision for me.

The cluster includes a MacBook Pro 13" (late 2012) — an Intel Core i5-3210M (dual-core, 2012 vintage), 8 GB DDR3 RAM. That machine became swift-mac, running Ubuntu 22.04 as a Longhorn storage worker. The MacBook cannot be provisioned via PXE (Apple's EFI firmware does not support network boot), so Ubuntu was installed manually from a USB drive. After that, it joins the cluster exactly like any other node.

If the MacBook can run a k3s agent without being starved of RAM, any node in this cluster can. That is the selection criterion.

The Options and Why They Fell Short​

Why k3s​

k3s wins on four criteria that actually matter for this hardware:

1. Single binary, everything included.
containerd, CoreDNS, flannel (CNI), kube-proxy, and a local path provisioner are all bundled into one ~70 MB binary. There is nothing to install separately, nothing to version-pin across multiple packages, nothing to break in a gap between component versions.

2. Minimal memory footprint.
The k3s control plane starts at around 300 MB of RAM on a quiet cluster. The MacBook Pro's 8 GB is not a ceiling — it is headroom. Under load, the same node runs Longhorn replicas, system daemonsets, and a k3s agent without being starved.

3. CNCF-certified Kubernetes.
This is the argument that matters for a portfolio. k3s exposes exactly the same APIs as GKE, EKS, and AKS. Every concept learned here — Deployments, Services, PersistentVolumes, RBAC, Admission Webhooks — transfers directly to managed cloud Kubernetes. This is not a homelab toy; it is Kubernetes, stripped of the components that are irrelevant at this scale.

4. Rolling upgrades with zero manual steps.
Once system-upgrade-controller is deployed, upgrading the entire cluster is a single YAML change: update the version: field in the Plan manifest and commit. The controller handles cordon → drain → upgrade → uncordon on each node, server before agents. The cluster was upgraded from v1.33 to v1.36.2+k3s1 this way with zero downtime across five nodes.

The Installation​

The four ThinkPad cluster nodes (set-hog, fast-skunk, fast-heron, star-kitten) were already running Ubuntu 22.04 LTS, provisioned by MAAS. swift-mac had Ubuntu installed manually. From there, the install is three steps.

Step 1 — Control plane on set-hog (10.0.0.2):

ssh ubuntu@10.0.0.2
curl -sfL https://get.k3s.io | sh -

The script detects the architecture, downloads the single binary, registers a systemd unit, and starts the k3s server. The full API server, scheduler, controller-manager, and embedded etcd are up within 30 seconds.

Step 2 — Retrieve the join token:

sudo cat /var/lib/rancher/k3s/server/node-token

Step 3 — Join each worker (fast-skunk, fast-heron, star-kitten, swift-mac):

curl -sfL https://get.k3s.io | \
  K3S_URL=https://10.0.0.2:6443 \
  K3S_TOKEN=<token> \
  sh -

Four SSH sessions. Four curl commands. The cluster appears in kubectl get nodes within seconds of each join.

NAME          STATUS   ROLES                  AGE   VERSION
set-hog       Ready    control-plane,master   5m    v1.36.2+k3s1
fast-skunk    Ready    <none>                 4m    v1.36.2+k3s1
fast-heron    Ready    <none>                 3m    v1.36.2+k3s1
star-kitten   Ready    <none>                 2m    v1.36.2+k3s1
swift-mac     Ready    <none>                 1m    v1.36.2+k3s1

The swift-mac node joined over the Tailscale mesh (the MAAS controller acts as NAT). Apple's SMC does not support Wake-on-AC, so swift-mac does not auto-start after a power failure — every other node does. That is the only infrastructure asymmetry introduced by the hardware.

The Analogy​

The relationship between kubeadm and k3s is the same as the relationship between manually installing a Linux server package by package versus using MAAS to provision it. The outcome is identical. The path is radically different. Kubeadm gives you maximum control over every component. k3s gives you a working cluster you can build on immediately.

For a project where the goal is to demonstrate platform engineering skills — not to demonstrate ability to configure etcd from scratch — k3s is the correct choice. The cluster is now in its 75th operational phase. The distribution has never been the bottleneck.

Automating It with Ansible​

Four SSH sessions is fine for a one-time bootstrap. But after the cluster was up and minicloud-ansible was established as the automation layer, the natural next step was to write a playbook that can reproduce the full install from scratch — so the next cluster rebuild takes one command, not four.

The playbook lives at playbooks/install-k3s.yml in minicloud-ansible. It has three plays:

Play 1 — Control plane (set-hog):
Installs the k3s server, waits for port 6443 to be ready, waits for the node to reach Ready state, then reads the join token into an Ansible variable.

Play 2 — Workers (fast-skunk, fast-heron, star-kitten, swift-mac):
Joins one worker at a time (serial: 1) using the token fetched from hostvars. Each worker must be Ready before the next one starts.

Play 3 — Kubeconfig:
Fetches /etc/rancher/k3s/k3s.yaml from the control plane, patches the server address from 127.0.0.1 to the real IP, and renames the context to minicloud. Saves the result to /tmp/minicloud.yaml on the Ansible controller.

# Dry run
ansible-playbook playbooks/install-k3s.yml --check

# Full install (pins to current cluster version)
ansible-playbook playbooks/install-k3s.yml

# Pin a different version
ansible-playbook playbooks/install-k3s.yml -e k3s_version=v1.37.0+k3s1

# Workers only (control plane already running)
ansible-playbook playbooks/install-k3s.yml --tags workers

# After the playbook — copy kubeconfig to the controller
scp /tmp/minicloud.yaml controller:~/.kube/minicloud.yaml

The playbook is idempotent — it checks for /usr/local/bin/k3s before installing. Re-running on an existing cluster skips the install tasks and only re-validates the Ready state.

Why the install wasn't automated from day one​

Two reasons. First, the k3s install is a Day-0 operation — it runs once per cluster lifetime. The effort of writing and testing a playbook outweighed the cost of four SSH commands. Second, swift-mac cannot be PXE-booted, so Ubuntu was installed manually via USB regardless. As long as one step is manual, the whole bootstrap sequence is effectively manual for that node.

What was automated from day one was the part that actually repeats: system-upgrade-controller handles every future k3s version bump as a single YAML commit. The Ansible playbook covers the edge case — rebuild from scratch — which is worth automating even if it only happens once or twice in the cluster's lifetime.

What Comes Next​

With five nodes running k3s, the next layer is networking and load balancing: MetalLB for bare-metal LoadBalancer services, a wildcard ingress controller, and a private CA so every internal service gets real TLS. That is covered in the next post.

The full runbooks for every phase, including the exact cloud-init templates used for MAAS provisioning, live in the Documentation section.

What "7B" Actually Means​

The "7B" in a model name is the number of parameters — floating-point weights stored in the neural network. Each parameter holds learned knowledge from training. More parameters generally means better reasoning, broader knowledge, and fewer hallucinations on complex tasks.

The catch: more parameters means more RAM.

Our cluster has no dedicated GPU — swift-mac has 8 GB RAM, ThinkPad workers have 16–32 GB. At FP32, even a 7B model is out of reach. This is where quantization becomes essential.

Quantization — Why It Changes Everything​

One FP32 parameter = 4 bytes. Quantization represents the same weight with fewer bits, accepting a small precision loss in exchange for dramatically lower memory usage.

FP32   → 4 bytes/param  → 7B model = 28 GB   (baseline)
FP16   → 2 bytes/param  → 7B model = 14 GB
Q8_0   → 1 byte/param   → 7B model =  7 GB
Q4_K_M → ~0.5 bytes/param → 7B model = 4.1 GB  ← most popular
Q2_K   → ~0.25 bytes/param → 7B model = 2.7 GB  (notable quality loss)

The quality loss from Q4_K_M vs FP16 is measurable on benchmarks but imperceptible in practical use for chat and RAG. Q2 and Q3 are a different story — avoid them for anything that requires accurate reasoning.

Rule of thumb: step down one quantization level before stepping down to a smaller model. A 7B Q4 beats a 3B Q8 on almost every task.

The Format Zoo​

You'll encounter four main formats depending on your runtime:

• GGUF (llama.cpp / Ollama) — CPU-first format with optional GPU offloading. Suffixes like Q4_K_M, Q5_K_M, Q8_0 tell you the quantization level. This is what Ollama uses.
• GPTQ — GPU-oriented post-training quantization. Better than GGUF if you have sufficient VRAM.
• AWQ — Activation-aware Weight Quantization. Better quality than GPTQ at the same size, increasingly standard.
• EXL2 — ExLlamaV2 format, very efficient for GPU batch inference.

For a CPU-only or CPU-primary cluster: GGUF Q4_K_M is your format.

SLM Candidates — The Real Options Under 8B​

Small Language Models (≤7B) have caught up dramatically since 2024. These are the relevant ones for a constrained inference cluster:

Why We Replaced phi4-mini​

phi4-mini isn't a bad model — Microsoft did good work on reasoning at 3.8B. But it has two structural limits:

3.8B is the quality ceiling. At 3.8B parameters, the model has less "memory" of training patterns. It hallucinates more on precise facts, multi-step reasoning degrades faster, and complex instruction following is less reliable than a 7B.

The market moved. In 2024–2025, 7B models became what 13B models were in 2023. Qwen 2.5 7B in particular outperforms phi4-mini on nearly every benchmark while fitting in the same RAM constraint once quantized.

The comparison that made the decision clear:

Qwen 2.5 is natively trained on 29 languages including French. For French-speaking end users interacting with Open WebUI, that's a direct advantage over Llama.

What Metrics Actually Matter for Inference Serving​

Three metrics to optimize, depending on the use case:

Time To First Token (TTFT) — latency before the user sees the first word. Critical for interactive chat. Smaller models win here. Groq's LPU hardware achieves TTFT < 200ms even on 8B models.

Tokens per second (throughput) — generation speed. GPU >> CPU. On CPU, phi4-mini Q4 generates ~15 tok/s on a ThinkPad, Llama 3.1 8B ~6 tok/s.

Concurrency — how many simultaneous users. Ollama handles one request at a time per instance by default. For multi-user, you need multiple instances (we have three) or a batching server like vLLM.

Decision Matrix​

User expects response in < 2s?
├── Yes → Groq (cloud LPU) or phi4-mini local Q4
└── No  → Llama 3.1 8B Q4 or Qwen 2.5 7B Q4

Task requires reasoning (math, analysis)?
├── Yes → deepseek-r1 distill or phi4-mini (strong on reasoning)
└── No  → Mistral 7B or Llama 3.2 3B (faster, cheaper)

French-speaking users?
├── Yes → Mistral 7B (native FR) or Llama 3.1 8B (solid multilingual)
└── No  → Qwen 2.5 7B or Gemma 3 4B

Tuning Ollama for CPU Inference​

Beyond the model choice, there are several environment variables that have immediate impact.

Keep the Model Loaded​

The most impactful single change: set OLLAMA_KEEP_ALIVE=-1 so the model is never unloaded from RAM. Without this, Ollama evicts the model after 5 minutes of inactivity — the next request pays a 3–5 second cold start penalty while the model reloads.

env:
  - name: OLLAMA_KEEP_ALIVE
    value: "-1"

Flash Attention​

Reduces KV cache memory usage and speeds up the attention computation:

  - name: OLLAMA_FLASH_ATTENTION
    value: "1"

Gain: ~15–20% less RAM, ~10% faster on longer contexts.

Context Window — the Most Underrated Lever​

Ollama defaults to loading the model's maximum context window (128k for Qwen 2.5). The KV cache grows linearly with context length. For standard chat, you don't need 128k tokens.

Forcing num_ctx=4096 in the LiteLLM params:

litellm_params:
  model: ollama/qwen2.5:7b-instruct-q4_k_m
  api_base: http://ollama.ai.svc.cluster.local:11434
  num_ctx: 4096

Impact: going from num_ctx=32768 to num_ctx=4096 can double throughput on CPU by reducing the amount of memory the model reads per token generation step.

CPU Threads — Align With Physical Cores​

Ollama uses all available cores by default, but hyperthreading can hurt inference (two logical threads on the same physical core compete for the same ALU). Set threads to physical core count:

  - name: OLLAMA_NUM_THREADS
    value: "6"   # physical cores, not logical — avoids hyperthreading overhead

Parallelism and Loaded Models​

  - name: OLLAMA_NUM_PARALLEL
    value: "4"   # max concurrent requests per instance
  - name: OLLAMA_MAX_LOADED_MODELS
    value: "2"   # keep at most 2 models in RAM simultaneously
  - name: OLLAMA_KV_CACHE_TYPE
    value: "q8_0"  # quantize the KV cache itself — saves RAM during long conversations

Summary: What Each Tuning Gains​

What We Actually Did on minicloud​

All three Ollama instances (ollama, ollama-secondary, ollama-tertiary in the ai namespace) already had all the environment variables set from a previous tuning session. The only missing piece was the model itself.

The model pull from inside a pod was blocked: the default-deny-egress NetworkPolicy and a routing difference between pod-level and node-level IPv4 traffic to Cloudflare R2 caused connection refused on 172.64.66.x:443. The node itself could reach the registry fine, but the CNI (flannel) traffic path from pod IPs didn't work the same way.

Workaround used: temporarily patched hostNetwork: true on all three deployments. This makes the pod use the node's network namespace directly, bypassing CNI. The node can reach registry.ollama.ai — so the pull works.

# Add hostNetwork temporarily
kubectl patch deployment/ollama deployment/ollama-secondary deployment/ollama-tertiary \
  -n ai --type=json \
  -p '[{"op":"add","path":"/spec/template/spec/hostNetwork","value":true}]'

# Pull the model (4.7 GB per instance)
kubectl exec -n ai deployment/ollama -- ollama pull qwen2.5:7b-instruct-q4_k_m
kubectl exec -n ai deployment/ollama-secondary -- ollama pull qwen2.5:7b-instruct-q4_k_m
kubectl exec -n ai deployment/ollama-tertiary -- ollama pull qwen2.5:7b-instruct-q4_k_m

# Remove hostNetwork — pods restart with normal CNI networking
kubectl patch deployment/ollama deployment/ollama-secondary deployment/ollama-tertiary \
  -n ai --type=json \
  -p '[{"op":"remove","path":"/spec/template/spec/hostNetwork"}]'

The model files are stored on a PVC, so they persist across pod restarts. After removing hostNetwork, all three instances came back up with qwen2.5:7b-instruct-q4_k_m cached locally — and LiteLLM started routing to it immediately.

The underlying networking issue (pod-to-Cloudflare IPv4 path via flannel) is a known limitation. Phase 76 will replace flannel with Cilium, which adds FQDN-based egress policies and Hubble observability — making this kind of debugging trivial next time.

What's Next​

With Qwen 2.5 7B running on all three instances and LiteLLM routing traffic via least-busy, the AI stack is:

• phi3-financial pipeline: Groq llama-3.1-8b-instant as primary (LPU-fast), Qwen 2.5 7B ×3 as local fallback
• Open WebUI chat: Qwen 2.5 7B for general use, deepseek-r1 7B for reasoning tasks
• RAG ingest: nomic-embed-text for embeddings (unchanged)

The speculative decoding optimization (a small draft model pre-generates tokens that the main model verifies) is available in Ollama v0.5+ and could push throughput 2–3× further on predictable outputs. That's the next tuning frontier once this setup is stable.

That is an operational smell. If git is the only write path, the restart should be automatic too.

Why Kubernetes Doesn't Auto-Reload ConfigMaps​

Kubernetes does update ConfigMap data in-place — but only for volume mounts that use the full directory. When you mount a ConfigMap with subPath (mounting a single file rather than the whole directory), Kubernetes intentionally skips the automatic update.

Homer mounts its config with subPath:

volumeMounts:
  - mountPath: /www/assets/config.yml
    name: config
    subPath: config.yml   # ← this disables automatic propagation

This is by design. subPath gives you fine-grained control over where a file lands inside a container, but it breaks the inotify watch that Kubernetes would otherwise use to propagate ConfigMap updates. The file the pod sees is frozen at mount time.

The common workaround — which I had in place — is a manual annotation bump on the pod template:

template:
  metadata:
    annotations:
      config-checksum: "v17-star-kitten-polaris"  # bump this manually after every config change

Changing the annotation forces a new pod-template-hash, which triggers a rolling restart. But this is noise: it clutters the git history, it's easy to forget, and it has nothing to do with the actual change being made.

The Broader Pattern​

It wasn't just Homer. Every ConfigMap-backed deployment in the cluster had the same problem:

The CLAUDE.md even had a note reminding me to run the restart after every Backstage config push. That note existing is the problem — if a human has to remember to do something after a git push, it will eventually be forgotten.

The Fix: Stakater Reloader​

Stakater Reloader is a Kubernetes controller that watches ConfigMaps and Secrets, and triggers rolling restarts on any Deployment (or StatefulSet, DaemonSet) that opts in via a single annotation.

The deployment is a single Helm chart in its own namespace:

# apps/reloader.yaml
sources:
  - repoURL: https://stakater.github.io/stakater-charts
    chart: reloader
    targetRevision: "2.2.14"   # app v1.4.19

And opting in is one line on any Deployment metadata:

metadata:
  annotations:
    reloader.stakater.com/auto: "true"

Reloader detects all ConfigMaps and Secrets referenced by the Deployment (via volumes, envFrom, and env.valueFrom) and watches them. When ArgoCD syncs a ConfigMap change, Reloader sees the update within seconds and triggers a rolling restart automatically.

The flow is now fully automated:

git push → ArgoCD syncs ConfigMap → Reloader detects change → pod rolling restart

No human step. No annotation bump. No runbook entry reminding you to remember.

Removing the Manual Workaround​

With Reloader installed, the config-checksum annotation in Homer's deployment was noise:

# before — manual workaround
template:
  metadata:
    annotations:
      config-checksum: "v17-star-kitten-polaris"

# after — clean
template:
  metadata:
    labels:
      app: homer
      backstage.io/kubernetes-id: homer

The deployment metadata gets the Reloader annotation instead:

metadata:
  name: homer
  namespace: homer
  annotations:
    reloader.stakater.com/auto: "true"

A Bonus Investigation: ArgoCD OOMKills​

While implementing Reloader, I noticed the ArgoCD application controller was in CrashLoopBackOff — 183 restarts over 44 hours:

argo-cd-argocd-application-controller-0   0/1   CrashLoopBackOff   183 (4m ago)   44h

This explained why syncs were taking forever and why Reloader itself couldn't complete its initial sync. The exit code was 137 — SIGKILL from the OOM killer:

Last State: Terminated
  Reason:    OOMKilled
  Exit Code: 137

The controller had a 1Gi memory limit, set when the cluster managed about 10 applications. It now manages ~40, including multi-source Helm applications with large manifests (Harbor, Authentik, kube-prometheus-stack). The reconciliation loop for 40 apps simply exceeded 1Gi.

The fix is in helm-values/argocd-values.yaml:

controller:
  resources:
    requests: { cpu: 100m, memory: 512Mi }
    limits:   { cpu: 1000m, memory: 2Gi }   # was 1Gi

Applied immediately via kubectl patch statefulset without waiting for ArgoCD to self-sync (it couldn't, since the controller was the one crashing). After the patch, the controller came up clean: 1/1 Running 0.

The lesson: ArgoCD controller memory scales with the number of applications and the complexity of their manifests. If you're adding many Helm apps, keep an eye on it. A CrashLoopBackOff on the application controller means nothing syncs — it's the most critical pod in the cluster after the API server.

What's Deployed​

Namespace:  reloader
App:        reloader (ArgoCD)
Chart:      stakater/reloader 2.2.14 (app v1.4.19)
Security:   runAsNonRoot, runAsUser 65534, seccompProfile RuntimeDefault,
            capabilities.drop ALL, no privilege escalation
Resources:  10m/32Mi request — 100m/128Mi limit

Deployments that now auto-reload on ConfigMap change:

• homer — dashboard layout
• litellm — AI Gateway model routing, prompt handler, financial guardrails
• searxng — search engine settings
• backstage — catalog locations, proxy endpoints, auth config

Any future deployment that mounts a ConfigMap gets the same behaviour with one annotation line. The pattern scales for free.

One Gotcha: Chart Versioning​

The Stakater Reloader chart version does not match the application version. When I first pinned targetRevision: "1.4.3" (matching the app version format), ArgoCD failed:

error fetching chart: failed to fetch chart: helm pull --version 1.4.3 --repo https://stakater.github.io/stakater-charts

The correct version to use is the chart version, found via:

helm repo add stakater https://stakater.github.io/stakater-charts
helm search repo stakater/reloader
# NAME                  CHART VERSION   APP VERSION
# stakater/reloader     2.2.14          v1.4.19

Chart 2.2.14 = app v1.4.19. Always search before pinning.

This project started from a simple question: what does it actually take to build a production-grade Kubernetes platform from scratch?

The Setup​

The hardware is five laptops: four Lenovo ThinkPad X390s acting as cluster nodes and a MacBook Pro 2012 running as a storage worker. A fifth ThinkPad X390 runs as the MAAS controller — handling PXE boot, DHCP, DNS, and Tailscale NAT for the entire rack. Total cost: well under a cloud provider's monthly invoice for equivalent compute.

Controller (MAAS):    ktayl-ThinkPad-X390  — Tailscale endpoint, NAT, kubectl
Control plane:        set-hog              — k3s master, 10.0.0.2
Workers:              fast-skunk           — 10.0.0.4
                      fast-heron           — 10.0.0.7
                      star-kitten          — 10.0.0.8
                      swift-mac            — 10.0.0.10 (MacBook Pro 2012, Longhorn storage)

Every node is provisioned by MAAS via PXE: the controller broadcasts a boot offer, nodes pick it up, and Ubuntu 22.04 is deployed with a pre-seeded cloud-init. That means any node can be wiped and re-provisioned in under 10 minutes — the same discipline you'd apply in a real cloud provider's bare-metal service.

What "Production-Grade" Actually Means Here​

Running a home lab is easy. Running it like a platform team would run production is a different discipline entirely. The constraints I imposed on myself:

• No manual kubectl apply — all workloads live in Git and sync via ArgoCD (app-of-apps pattern, Kustomize base+overlays, 3-branch CI promotion flow)
• Zero-trust networking — OPA Gatekeeper admission policies in deny mode across all 23 namespaces, NetworkPolicy enforced everywhere, Vault auto-unseal via AWS KMS
• Observability from day one — Prometheus + Grafana + Loki + Tempo deployed before any application workload; node_exporter on the controller itself so disk alerts fire before MinIO crashes
• OIDC SSO on every service — Authentik as the identity provider, OIDC/PKCE protecting ArgoCD, Grafana, Harbor, Backstage, Open WebUI, and Vaultwarden
• Automated regression testing — 62 checks across infra, GitOps, security, storage, AI, and observability that I run after every significant change

The Things That Surprised Me​

Storage is the hardest part of bare metal. Longhorn on the MacBook Pro 2012 (swift-mac) required hand-tuning mount propagation, replica counts, and scheduling tolerations. When the node goes down unexpectedly — and it does, because Apple's SMC doesn't support Wake-on-AC — Longhorn's replica recovery needs headroom that you only understand by watching it fail twice.

Certificate chains break in non-obvious ways. I run a private CA (minicloud-ca.crt) for all internal HTTPS endpoints. The macOS System Keychain trusts it, but /opt/anaconda3/bin/curl uses OpenSSL and ignores it silently. Two hours of debugging a Harbor push failure taught me to always check which curl binary is in $PATH.

GitOps and ArgoCD StatefulSet sync have edge cases. When a StatefulSet's VolumeClaimTemplate is defined without explicit apiVersion, kind, and volumeMode, ArgoCD v3.4.1 perpetually shows a diff — even after sync. The fix is to write the full spec in the manifest; ignoreDifferences doesn't work for these fields.

Velero backup timeouts need tuning per workload. The default 4-hour itemOperationTimeout on Velero's kopia plugin wasn't enough for a 4.5 GB ClickHouse PV (Langfuse LLM trace data). Kopia transferred ~2.5 GB and then the backup was cancelled. Bumping to 8 hours fixed it — but the lesson is that backup SLOs depend on data size, not just infrastructure configuration.

What's Running Today​

After 35+ phases of incremental build-out, the current platform runs:

All publicly reachable at *.devandre.sbs via Cloudflare Tunnel, protected by Authentik SSO.

Why This Matters for Engineering​

The goal was never to run Kubernetes at home for its own sake. The goal was to develop the kind of platform instinct that only comes from operating infrastructure through failure: disk fills up and MinIO hangs in memory with no alert; a node's SMC doesn't respond to WoL and a cron job has to compensate; a Velero CRD upgrade job never sets status.succeeded because of a k3s Job controller bug.

Those incidents — and the fixes — are what platform engineering actually looks like beneath the abstractions. The next posts in this series will go deeper into specific components: the RAG pipeline architecture, the GitOps promotion workflow, and the OPA Gatekeeper policy set.

The full runbooks for every phase live in the Documentation section of this site.