LLM locaux plus rapides : Headroom réduit le contexte agent de 95 % (2026)

Vous faites tourner Ollama, DeepSeek-R1 ou Llama 3 sur un Mac mini ou un VPS léger, puis branchez un agent qui lit votre dépôt, suit des logs ou interroge une base. Le premier appel d'outil renvoie 50 000 tokens de JSON. Votre modèle local 7B reste figé 90+ secondes. Activity Monitor affiche un CPU bas ; l'UI semble morte. Ce n'est pas « le modèle est nul » — c'est la gonflement du contexte qui écrase les tokens-per-second sur petit matériel.

Les agents cloud masquent la douleur avec des fenêtres 200k et des GPU datacenter. Sur 8–16 Go Apple Silicon ou une boîte 2 vCPU, chaque ligne de log redondante coûte une seconde de prefill. Les guides Linux ignorent souvent la compression réversible des sorties d'outils — lacune comblée par Headroom, couche open source Apache-2.0 d'optimisation de contexte.

Ce guide s'adresse aux constructeurs homelab qui font déjà de l'inférence locale. Vous verrez pourquoi la latence outils explose, l'architecture Compress-Cache-Retrieve (CCR) de Headroom, et un runbook en 8 étapes pour placer le proxy devant Ollama — avec liens vers quantification DeepSeek-R1, routage OpenClaw, mémoire Mac mini, cartographie de codebase. ZecCloud propose des Mac mini 24/7 ; cet article se concentre sur la doc Headroom, pas les tarifs.

Introduction

Modèle de latence, architecture Headroom, matrice, runbook 8 étapes, dépannage et 6 FAQ.

Pourquoi les agents locaux « bloquent » sur de grosses sorties d'outils

User → LLM plans tool → Tool returns huge payload → LLM reads ALL bytes → Next token

Sur Mac mini M4 avec Llama 3.2 3B Q4 via Ollama, la génération atteint souvent 40–80 tok/s, mais un dump outil 32k tokens peut prendre des dizaines de secondes de prefill avant le premier token. Le modèle n'« réfléchit » pas — il avale des lignes de tests, clés JSON dupliquées, forêts de grep.

Apple documente la mémoire unifiée — moins de contexte, moins de pression sur le même pool (guide mémoire Mac mini OpenClaw).

Architecture Headroom : proxy, routeurs et CCR

Headroom se place entre l'agent et le fournisseur LLM — bibliothèque, proxy local, serveur MCP ou headroom wrap pour Claude Code / Cursor / Aider.

Agent (OpenClaw, Aider, custom)
    │  tool outputs, logs, file reads, RAG chunks
    ▼
Headroom proxy :8787  ── ContentRouter ──┬─ SmartCrusher (JSON arrays)
    │                                      ├─ CodeCompressor (AST, tree-sitter)
    │                                      ├─ LogCompressor (failures kept)
    │                                      └─ Kompress-base (prose)
    ▼
CCR store (originals cached locally, hash-addressable)
    ▼
Ollama / OpenAI-compatible API

CCR signifie compression réversible : originaux en cache local ; le modèle appelle headroom_retrieve si besoin. Exemples publics : 60–95 % de tokens en moins sur logs et JSON outils (Headroom GitHub).

Premier lancement : téléchargement possible de ~500 Mo de modèles de routage. Prévoyez de l'espace disque sur Mac mini 256 Go avec les poids Ollama.

Matrice de latence : quand la compression gagne

• Agent lit codebases/logs >~4k tokens/tour → Headroom en mode optimize.
• Calculatrice API seule → ignorer.
• OpenClaw 24/7 sur 16 Go → proxy local ; ne pas envoyer les sorties brutes à Ollama.

Runbook étape par étape

Étape 1 — Installer Headroom (Python 3.10+)

python3 -m venv ~/.headroom-venv
source ~/.headroom-venv/bin/activate
pip install "headroom-ai[proxy]"
headroom --version

Utilisez un venv sur macOS. Réservez ~1 Go pour venv + modèles cache.

Étape 2 — Mode audit (voir les gains sans risque)

headroom proxy --port 8787 --mode audit

Une requête test via le proxy (étape 4). Logs « would compress X → Y tokens ». Audit ne modifie pas les payloads.

Étape 3 — Démarrer le proxy optimize

headroom proxy --port 8787 --mode optimize

Terminal ouvert ou launchd sur Mac mini headless. Port 8787 vs Ollama 11434.

Étape 4 — Pointer le client Ollama vers Headroom

export OPENAI_API_BASE="http://127.0.0.1:8787/v1"
export OPENAI_API_KEY="ollama"   # placeholder; Ollama ignores

Ollama reste sur http://127.0.0.1:11434. Voir Headroom docs.

curl -s http://127.0.0.1:8787/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{"model":"llama3.2:3b","messages":[{"role":"user","content":"ping"}]}'

Étape 5 — Envelopper les agents de code (optionnel)

headroom wrap aider --model ollama/llama3.2:3b
# or: headroom wrap claude | codex | cursor | copilot

Étape 6 — Serveur MCP pour agents custom

headroom mcp

Utile pour pipelines OpenClaw (multi-agents OpenClaw).

Étape 7 — Mesurer avant/après

# Ollama-side: watch context size in logs
OLLAMA_DEBUG=1 ollama serve 2>&1 | tee /tmp/ollama-debug.log

# Headroom stats (when available in your version)
headroom stats

Time-to-first-token sur un gros read_file. 15k → 1,5k tokens → souvent 2–10× plus rapide.

Étape 8 — Durcir pour Mac mini 24/7

• Proxy sous launchd KeepAlive (guide SSH)
• OLLAMA_NUM_PARALLEL=1 sur 8–16 Go
• Quants Q4 du guide DeepSeek-R1
• Cartographier avec Understand Anything avant ingestion aveugle

Dépannage

Proxy actif mais agent toujours lent

Schéma : client contourne le proxy, frappe Ollama :11434. Fix : vérifier OPENAI_API_BASE=http://127.0.0.1:8787/v1 dans l'environnement agent (launchctl getenv sur macOS).

Boucle headroom_retrieve / détail manquant

Schéma : le modèle récupère des hash en boucle. Fix : mode simulate une fois ; prompts outils plus stricts ; relancer l'outil si TTL CCR expiré.

Téléchargement initial bloqué

Schéma : activité disque seule après install. Fix : autoriser ~500 Mo ; ≥5 Go APFS libres ; Ethernet filaire.

Ligne d'erreur supprimée par compression

Schéma : stack trace manquée. Fix : LogCompressor garde FATAL/ERROR — mettre à jour Headroom ; audit avant optimize en CI.

FAQ

Conclusion

La latence outils LLM local sur Mac mini est souvent un problème de volume de tokens. Headroom compresse sorties, logs et lectures avant Ollama — 60–95 % de contexte en moins avec CCR pour récupérer l'original.

Installez headroom-ai[proxy], lancez headroom proxy --port 8787 --mode optimize, pointez vers http://127.0.0.1:8787/v1. Associez DeepSeek et mémoire OpenClaw.

Officiel : Headroom GitHub · Headroom docs.