Вы подключили Ollama, DeepSeek или Llama к фреймворку агента, попросили прочитать весь monorepo — и интерфейс завис на три–восемь минут: не сбой, а prefill, тонущий в JSON инструментов. На Mac mini M4 с 16–32 ГБ унифицированной памяти локальные модели упираются в потолок, когда один ход отправляет 40–80 тыс. токенов вывода npm test, SQL-дампов или результатов ripgrep. Облачные API тарифицируют по объёму; локальный GPU сжигает реальное время на attention за каждый байт.
Headroom сжимает выводы инструментов, логи и блоки RAG до попадания в модель — опубликованные нагрузки показывают сжатие на 92 % для SRE-трасс и 73–92 % для поиска по коду. Это руководство Type A ставит Headroom перед OpenAI-совместимым API Ollama: инструменты агента не меняются, но модель видит 5 тыс. токенов вместо 50 тыс. токенов сена. Контроль расходов через облачный шлюз: OpenClaw + прокси Headroom; локальный торговый стек без API: TradingAgents на Ollama.
Раскрытие: MacHTML предлагает опциональную аренду облачного Mac mini; это руководство применимо к любому локальному хосту macOS или Linux с установленным Ollama.
Почему локальные агенты «зависают» на больших выводах инструментов
На Apple Silicon задержка prefill локальных LLM примерно линейно зависит от длины контекста — нет магии «бесконечного контекста» при 30 tok/s, когда вы заливаете весь CI-лог. Симптомы, которые операторы путают с зависанием:
| Симптом | Вероятная причина | Рычаг Headroom |
|---|---|---|
Спиннер после read_file 2-МБ лога | 50 тыс.+ токенов в одном сообщении инструмента | SmartCrusher / LogCompressor |
| Первый ход быстрый, 5-й зависает | Накопление контекста через несколько ходов инструментов | CCR + IntelligentContext drops |
| Давление на RAM, swap на Mac mini 16 ГБ | KV-кэш + огромный prompt | Сокращение prefill-токенов на 60–95 % |
| «На GPT-4o работало» | Облачная модель шире / кремний быстрее | Локально нужны сжатие + меньший эффективный контекст |
Цитата: На железе класса Mac mini маршрутизация трафика агента через Headroom на 127.0.0.1:8787 к Ollama на 11434 может сократить prompt'ы с большим объёмом инструментов на 60–95 % и вернуть субминутные ходы инструментов, невозможные с сырыми логами.
Внешние ссылки: Headroom GitHub, документация прокси, API Ollama.
Архитектура слоя сжатия
┌──────────────┐ 工具 JSON/日志 ┌─────────────────────┐ 压缩后 ┌─────────────┐
│ Agent │ ────────────────► │ Headroom 代理 │ ───────────►│ Ollama │
│ (OpenClaw、 │ OPENAI_BASE_URL │ :8787 │ 聊天 API │ :11434/v1 │
│ LangGraph、 │ = localhost:8787 │ SmartCrusher + CCR │ │ llama3 等 │
│ Aider…) │ │ │ │ │
└──────────────┘ └─────────────────────┘ └─────────────┘Прокси Headroom предоставляет OpenAI-совместимый /v1/chat/completions — тот же интерфейс, что и у Ollama. Вы направляете клиент агента на Headroom; Headroom сжимает и пересылает на upstream URL Ollama.
Пошаговое руководство (Ollama + Headroom)
1. Базовый Ollama на хосте
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.toolВыберите модель по объёму RAM: 3B–8B на Mac mini 16 ГБ для циклов агента; 14B+ требует 32 ГБ+ для комфортного запаса KV.
2. Установка стека прокси Headroom
python3 --version # 3.10+
pip install "headroom-ai[proxy]"
headroom --version3. Запуск Headroom с указанием на 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.jsonlПроверка:
curl -s http://127.0.0.1:8787/health | python3 -m json.tool4. Направить SDK агента на Headroom, не напрямую на Ollama
export OPENAI_BASE_URL=http://127.0.0.1:8787/v1
export OPENAI_API_KEY=ollama-localЛокальная модель OpenClaw — настройте в ~/.openclaw/.env; режим входа можно сочетать с OpenClaw + Webhook Ollama.
5. Режим библиотеки для собственного Python-агента
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"])Если HTTP оркестрируете сами, режим библиотеки избегает конфликтов портов прокси.
6. Ограничить payload инструментов до сжатия (двойная страховка)
rg -n "ERROR" logs/ | head -n 200Лучше, чем cat logs/build.log. Headroom спасёт грубые Skill, но лимит 200 строк ограничивает худшую задержку на хосте 16 ГБ.
7. Измерить экономию и задержку
curl -s http://127.0.0.1:8787/stats | python3 -m json.toolЗаписывайте tokens_before, tokens_after и реальное время за ход. При первом аудите репозитория цель — сокращение ≥50 %; дампы JSON/поиска часто дают 60–90 %.
8. Опциональный MCP: Claude Code + локальный sidecar Ollama
headroom mcp installПолезно, когда локальная модель работает в другом терминале — MCP headroom_stats; удобно при смешении сжатия памяти Hermes в облаке и локального Headroom.
9. Персистентность прокси через launchd (постоянно включённый Mac mini)
Создайте ~/Library/LaunchAgents/ai.headroom.ollama.plist, задайте OPENAI_TARGET_API_URL=http://127.0.0.1:11434/v1, загрузите до шлюза агента. Ollama в отдельном LaunchAgent — порядок запуска: Ollama → Headroom → Agent.
10. Регрессионная проверка после смены модели
После ollama pull нового тега перезапустите фикстуру с раздутым инструментом. Выигрыш от квантизации не заменяет сжатие — длина контекста по-прежнему доминирует в prefill.
Шаблон бенчмарка Mac mini
| Фикстура | Исходные токены (типично) | После Headroom (типично) | Цель по времени |
|---|---|---|---|
stderr npm test упавшего набора | 25–45 тыс. | 3–8 тыс. | Prefill M4 16 ГБ <45 с |
Список find . -name '*.ts' | 15–30 тыс. | 2–5 тыс. | <30 с |
| Один JSON API-дамп 500 КБ | 40–70 тыс. | 4–10 тыс. | <60 с |
Для каждой фикстуры один раз обойдите прокси (заголовок x-headroom-bypass: true), зафиксируйте зависание, которое нужно устранить — цифры в wiki команды.
Устранение неполадок
Агент всё ещё подключается напрямую к 11434
Симптом: ноль запросов в Headroom /stats.
Исправление: проверьте окружение процесса (ps eww -p $(pgrep -f your-agent)). OPENAI_BASE_URL у процесса агента должен быть http://127.0.0.1:8787/v1, а не только в конфиге shell.
Ollama 404 модель не найдена через прокси
Симптом: upstream 404 в логах Headroom.
Исправление: имя модели в chat-запросе должно совпадать с ollama list; сначала pull локально — Headroom не управляет файлами моделей.
Сжатие удаляет нужные строки стека
Симптом: в аудите нет номеров строк.
Исправление: включите CCR-извлечение в Skill («вызвать headroom_retrieve, если стек неполный») или обойдите один ход. Не отключайте сжатие глобально.
Mac mini заблокирован swap'ом
Симптом: memory_pressure критический во время работы агента.
Исправление: меньшая квантизация (:q4_0), меньше параллельных инструментов, добавьте Headroom. На 16 ГБ избегайте 14B + 80 тыс. сырых токенов одновременно.
Частые вопросы
Headroom работает только с облачным OpenAI?
Нет. Прокси сжимает и пересылает на любой OpenAI-совместимый upstream — Ollama, локальный vLLM или облако. Укажите OPENAI_TARGET_API_URL на локальный сервис.
Реалистично ли сжатие 95 %?
Некоторые нагрузки агентов публично достигают 92 %; в смешанных репозиториях обычно 60–80 %. Измеряйте через /stats — не предполагайте маркетинговый потолок на каждом ходу.
Помогает ли от перегрева GPU?
По сравнению с гигантским сырым prompt'ом меньше работы prefill снижает нагрев — но непрерывные циклы инструментов всё равно нагружают CPU/GPU. На Mac mini следите за powermetrics.
Headroom vs Hermes trajectory_compressor?
Hermes сжимает долгую память диалога; Headroom сжимает payload инструментов и RAG на уровне HTTP/библиотеки. Оба можно использовать вместе в гибриде облако/локально.
Нужен ли Headroom с облачным Anthropic?
Опционально для контроля расходов; локальные модели часто зависят от него, чтобы оставаться пригодными. Для смешения провайдеров см. облачный OpenClaw Headroom.
Развернуть Ollama + Headroom на облачном Mac mini
Запускайте прокси и Ollama на Apple Silicon через SSH/VNC — проверьте порты, порядок LaunchAgent и бенчмарки с раздутыми инструментами перед выводом цикла агента в прод.