headroom 實測：同一份工具輸出，模型收到的 token 從 18,050 降到 11,340

headroomlabs-ai/headroom 是 GitHub 上的開源專案，本站記錄時 77,985 星；一天內新增約 555 顆星。我們在一台 RTX A6000 48 GB 工作站 上，從安裝到跑出結果整段錄下終端機；測的是 2026-10-26 的版本（commit 17d38e5699b7）。實測影片公開後會嵌在本文最下方。

背景

AI Agent 在執行複雜任務時，往往需要將大量的工具輸出（如程式碼搜尋結果、日誌、RAG 檢索片段）餵給大型語言模型。這些原始資料通常冗長且包含大量重複或無關資訊，導致 Token 成本高昂，甚至超出模型的上下文視窗限制。

Headroom 是一個本地執行的上下文壓縮層，旨在解決這個問題。它在資料送達 LLM 之前進行壓縮，透過智能路由選擇不同的壓縮演算法（如針對 JSON 的 SmartCrusher、針對程式碼的 CodeCompressor、針對一般文字的 Kompress-v2-base），在保留關鍵資訊（如錯誤訊息、核心邏輯）的前提下，大幅減少 Token 數量。

運作方式與使用方式

Headroom 提供多種整合方式，包括 Python/TypeScript 函式庫、MCP 伺服器，以及最無需修改程式碼的「代理伺服器（Proxy）」模式。在本次實測中，我們採用代理模式，將 Headroom 作為中間層，攔截並壓縮送往本機 Ollama 模型的請求。

首先，我們透過 uv pip install 'headroom-ai[all]' 安裝套件，並使用 headroom proxy --port 8787 --openai-api-url http://127.0.0.1:11435/v1 啟動代理伺服器，將其上游指向本機運行的 Ollama 服務。接著，我們產生了一份約 6 萬字元的工具輸出（對專案原始碼進行 grep 搜尋），並透過自製腳本分別發送「直連模型」與「經 Headroom 代理」的請求，比較兩者進入模型的 Token 數量與最終回答。

與未使用時的差異

同一個請求（6 萬字元的程式碼搜尋結果當工具輸出，問模型壓縮相關的類別在哪些檔案），本站量到的差異：

安裝與執行過程

結果驗證

在實際測試中，Headroom 展現了顯著的壓縮能力。面對我們產生的 6 萬字元程式碼 grep 結果，直連 Ollama 時模型收到 18,050 個輸入 token；而經過 Headroom 代理後，輸入 token 降至 11,340 個。根據代理日誌顯示，實際進入壓縮管線的 token 從 15,071 降至 8,576，壓縮率達 43.1%，節省了 6,495 個 token。以模型自己回報的數字看，輸入少了 37%；這與 README 中聲稱的「程式碼代理節省 20%、JSON 節省 60-95%」的大致範圍相符。專案自帶的基準測試在本機也跑出和 README 相同的 41%，但那用的是專案自己準備的語料，本站把它當作安裝正確的驗證，不當作實測數據。

然而，壓縮並非毫無代價。日誌顯示壓縮過程耗時約 9,148 毫秒（inference_ms=8897），這使得整體請求延遲從直連的 28.3 秒增加到 31.2 秒：在一張 RTX A6000 上，27B 模型少處理 6,700 個 token 省下的時間，不夠抵掉壓縮本身的 9 秒。代理日誌顯示這次請求的壓縮主要由程式碼感知的路由完成（15,025 → 8,530），Kompress 文字壓縮只省了 363 個 token。另外要說明：兩次回覆都是空的，因為 Qwen3.8 的思考模式把 400 個輸出 token 的額度用在推理上，本站這次沒有驗證壓縮後的答案是否仍然正確，這是這篇實測的限制。

遇到的問題

1. 步驟 5 與步驟 9 執行 headroom doctor 時結束碼為 1，但輸出顯示「0 failure(s)」，僅有警告。原因未確認，可能是 CLI 將警告視為非零結束碼，但不影響代理實際運行。

2. 代理預設上游是 OpenAI 官方網址，不看 OPENAI_BASE_URL；第一次測試因此拿到 401，改用 --openai-api-url 指到本機 Ollama 才通。

3. 啟動時 kompress 文字壓縮模型還沒載入（健康檢查顯示 degraded），約 20 秒後才 ready；正式使用前要先預熱。

4. 壓縮本身耗時約 9.1 秒（ONNX 後端），在本機模型上省下的提示詞處理時間抵不過這段延遲；上游是雲端 API、按 token 計費時才划算。

5. 回答品質沒有比到：模型的思考模式吃掉輸出額度，兩次回覆都是空的。下次要關閉思考或放大輸出額度。

結論

Headroom 適合把 Agent 接在雲端、按 token 計費的 API 上的團隊：本站的語料經它一過，模型收到的輸入少了 37%，而且不用改程式碼，只改端點。接在本機模型上就不一定划算，這次省下的處理時間抵不過壓縮本身的 9 秒。它壓縮後的答案是否仍然正確，本站這次沒有驗證，要採用的人應該用自己的任務比一次。