Vous avez branché Ollama, DeepSeek ou Llama sur un framework d'agent, lui avez demandé de lire tout un monorepo, et l'interface s'est figée pendant trois à huit minutes — pas un crash, mais le préremplissage noyé dans le JSON des outils. Sur un Mac mini M4 avec 16 à 32 Go de mémoire unifiée, les modèles locaux atteignent leurs limites lorsqu'un seul tour envoie 40 000 à 80 000 tokens de sortie npm test, de dumps SQL ou de résultats ripgrep. Les API cloud facturent à l'usage ; le GPU local brûle du temps réel en attention sur chaque octet.
Headroom compresse les sorties d'outils, les journaux et les blocs RAG avant qu'ils n'entrent dans le modèle — des charges publiées montrent une réduction de 92 % sur les traces SRE et de 73 à 92 % sur la recherche de code. Ce tutoriel Type A place Headroom devant l'API compatible OpenAI d'Ollama : les outils de l'agent restent inchangés, mais le modèle ne voit que 5 000 tokens au lieu d'une montagne de 50 000 tokens. Pour le contrôle des coûts via une passerelle cloud, voir OpenClaw + proxy Headroom ; pour une stack de trading locale sans API, voir TradingAgents sur Ollama.
Divulgation : MacHTML propose une location optionnelle de Mac mini cloud ; ce guide s'applique à tout hôte macOS ou Linux local avec Ollama installé.
Pourquoi les agents locaux « se figent » sur de gros retours d'outils
Sur Apple Silicon, la latence de préremplissage des LLM locaux est à peu près linéaire par rapport à la longueur du contexte — il n'existe pas de magie de « contexte illimité » à 30 tok/s quand on injecte tout un journal CI. Symptômes que les opérateurs confondent souvent avec un gel :
| Symptôme | Cause probable | Levier Headroom |
|---|---|---|
Spinner après read_file sur un journal de 2 Mo | Plus de 50 000 tokens dans un seul message d'outil | SmartCrusher / LogCompressor |
| Premier tour rapide, blocage au 5ᵉ tour | Contexte qui s'accumule sur plusieurs tours d'outils | CCR + IntelligentContext drops |
| Pression mémoire, swap sur Mac mini 16 Go | Cache KV + prompt géant | Réduction de 60 à 95 % des tokens de préremplissage |
| « Ça marchait avec GPT-4o » | Modèle cloud plus large / silicium plus rapide | Le local exige compression + contexte effectif réduit |
Citation : Sur du matériel de classe Mac mini, router le trafic agent via Headroom sur 127.0.0.1:8787 vers Ollama sur 11434 peut réduire les prompts riches en outils de 60 à 95 % et rétablir des tours d'outils sous la minute, impossibles avec les journaux bruts.
Références externes : Headroom GitHub, documentation du proxy, API Ollama.
Architecture de la couche de compression
┌──────────────┐ 工具 JSON/日志 ┌─────────────────────┐ 压缩后 ┌─────────────┐
│ Agent │ ────────────────► │ Headroom 代理 │ ───────────►│ Ollama │
│ (OpenClaw、 │ OPENAI_BASE_URL │ :8787 │ 聊天 API │ :11434/v1 │
│ LangGraph、 │ = localhost:8787 │ SmartCrusher + CCR │ │ llama3 等 │
│ Aider…) │ │ │ │ │
└──────────────┘ └─────────────────────┘ └─────────────┘Le proxy Headroom expose l'API compatible OpenAI /v1/chat/completions — la même interface que Ollama. Vous dirigez le client agent vers Headroom ; Headroom compresse puis transmet vers l'URL amont d'Ollama.
Guide pas à pas (Ollama + Headroom)
1. Ollama de référence sur l'hôte
ollama --version
ollama pull llama3.2:3b # 或 deepseek-r1:7b、qwen2.5-coder 等
curl -s http://127.0.0.1:11434/api/tags | python3 -m json.toolChoisissez un modèle adapté à la RAM : 3B–8B sur Mac mini 16 Go pour les boucles agent ; 14B+ nécessite 32 Go ou plus pour une marge KV confortable.
2. Installer la stack proxy Headroom
python3 --version # 3.10+
pip install "headroom-ai[proxy]"
headroom --version3. Démarrer Headroom et le pointer vers Ollama
export OPENAI_API_KEY=ollama-local
export OPENAI_TARGET_API_URL=http://127.0.0.1:11434/v1
headroom proxy --host 127.0.0.1 --port 8787 \
--log-file ~/.headroom/ollama-agent.jsonlVérification :
curl -s http://127.0.0.1:8787/health | python3 -m json.tool4. Orienter le SDK agent vers Headroom, pas directement vers Ollama
export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
export OPENAI_API_KEY=ollama-localModèle local OpenClaw — configurez dans ~/.openclaw/.env ; le mode d'entrée peut s'associer à OpenClaw + Webhook Ollama.
5. Mode bibliothèque pour un agent Python personnalisé
from headroom import compress
import ollama
messages = [...] # 含臃肿 tool 角色
result = compress(messages, model="llama3.2")
response = ollama.chat(model="llama3.2", messages=result.messages)
print(response["message"]["content"])Si vous orchestrez déjà le HTTP vous-même, le mode bibliothèque évite les conflits de port proxy.
6. Limiter les charges utiles des outils avant compression (double sécurité)
rg -n "ERROR" logs/ | head -n 200Préférez cela à cat logs/build.log. Headroom peut sauver des Skills grossiers, mais une limite de 200 lignes borne la latence maximale sur un hôte 16 Go.
7. Mesurer les économies et la latence
curl -s http://127.0.0.1:8787/stats | python3 -m json.toolEnregistrez tokens_before, tokens_after et le temps réel par tour. Visez ≥50 % de réduction lors du premier audit de dépôt ; les dumps JSON/recherche atteignent souvent 60–90 %.
8. MCP optionnel : Claude Code + sidecar Ollama local
headroom mcp installUtile quand le modèle local tourne dans un autre terminal — MCP headroom_stats ; pratique en mélangeant compression mémoire Hermes cloud et Headroom local.
9. Persistance du proxy via launchd (Mac mini toujours allumé)
Créez ~/Library/LaunchAgents/ai.headroom.ollama.plist, définissez OPENAI_TARGET_API_URL=http://127.0.0.1:11434/v1, chargez-le avant la passerelle agent. Ollama dans un LaunchAgent séparé — ordre de démarrage : Ollama → Headroom → Agent.
10. Vérification de régression après changement de modèle
Après ollama pull d'un nouveau tag, relancez un scénario avec un outil volumineux. Les gains de quantification ne remplacent pas la compression — la longueur du contexte domine toujours le préremplissage.
Modèle de benchmark Mac mini
| Scénario | Tokens bruts (typique) | Après Headroom (typique) | Objectif temps réel |
|---|---|---|---|
stderr npm test suite en échec | 25 000–45 000 | 3 000–8 000 | Préremplissage M4 16 Go <45 s |
Liste find . -name '*.ts' | 15 000–30 000 | 2 000–5 000 | <30 s |
| Dump JSON API unique de 500 Ko | 40 000–70 000 | 4 000–10 000 | <60 s |
Exécutez chaque scénario une fois en contournant le proxy (en-tête x-headroom-bypass: true), notez le gel à éliminer — consignez les chiffres dans le wiki d'équipe.
Dépannage
L'agent se connecte encore directement à 11434
Symptôme : zéro requête dans Headroom /stats.
Correction : vérifiez l'environnement du processus (ps eww -p $(pgrep -f your-agent)). OPENAI_BASE_URL du processus agent doit être http://127.0.0.1:8787/v1, pas seulement dans la config shell.
Ollama 404 modèle introuvable via le proxy
Symptôme : 404 amont dans les journaux Headroom.
Correction : le nom du modèle dans la requête chat doit correspondre à ollama list ; faites un pull local d'abord — Headroom ne gère pas les fichiers de modèle.
La compression supprime des lignes de pile nécessaires
Symptôme : numéros de ligne manquants dans l'audit.
Correction : activez la récupération CCR dans le Skill (« appeler headroom_retrieve si la pile est incomplète ») ou contournez un seul tour. Ne désactivez pas la compression globalement.
Mac mini bloqué par le swap
Symptôme : memory_pressure critique pendant l'exécution de l'agent.
Correction : quantification plus légère (:q4_0), moins d'outils parallèles, et ajoutez Headroom. Sur 16 Go, évitez 14B + 80 000 tokens bruts en parallèle.
Questions fréquentes
Headroom ne fonctionne qu'avec OpenAI cloud ?
Non. Le proxy compresse puis transmet vers tout amont compatible OpenAI — Ollama, vLLM local ou cloud. Pointez OPENAI_TARGET_API_URL vers votre service local.
Une compression à 95 % est-elle réaliste ?
Certaines charges agent atteignent publiquement 92 % ; sur des dépôts mixtes, comptez 60–80 %. Mesurez avec /stats — ne supposez pas le plafond marketing à chaque tour.
Peut-on réduire la surchauffe GPU ?
Par rapport à un prompt brut géant, moins de travail de préremplissage réduit la chaleur — mais les boucles d'outils continues consomment toujours CPU/GPU. Surveillez powermetrics sur Mac mini.
Headroom vs Hermes trajectory_compressor ?
Hermes compresse la mémoire de conversation longue ; Headroom compresse les charges d'outils et RAG au niveau HTTP/bibliothèque. Les deux peuvent coexister en hybride cloud/local.
Faut-il Headroom avec Anthropic cloud ?
Optionnel pour le contrôle des coûts ; les modèles locaux en dépendent souvent pour rester utilisables. Pour un mélange de fournisseurs, voir OpenClaw Headroom cloud.
Déployer Ollama + Headroom sur un Mac mini cloud
Exécutez le proxy et Ollama sur Apple Silicon via SSH/VNC — vérifiez ports, ordre LaunchAgent et benchmarks d'outils volumineux avant de mettre en production la boucle agent.