Headroom: nén context cục bộ trước khi gửi dữ liệu cho LLM

Headroom là lớp nén context cho AI agent, xử lý log, JSON, mã nguồn, file, RAG và lịch sử hội thoại trước khi chúng tới LLM. Dự án hỗ trợ thư viện, proxy, agent wrap và MCP, đồng thời lưu bản gốc cục bộ để truy xuất khi cần.

Một agent SRE có thể kéo về hàng chục nghìn token log, JSON, kết quả tool và cấu hình trước khi kịp đặt câu hỏi cho LLM. Khi toàn bộ dữ liệu đó được gửi nguyên khối, context nhanh đầy và lượng token đầu vào tăng lên.

Headroom là một lớp nén context đặt giữa agent hoặc ứng dụng và LLM. Dự án cho biết nó nén tool output, log, file, mẩu RAG và lịch sử hội thoại trước khi chúng được gửi tới model. Headroom có thể dùng dưới dạng thư viện Python/TypeScript, proxy, lớp bọc cho một số coding agent, hoặc MCP server.

Headroom xử lý dữ liệu như thế nào?

Theo README, Headroom chạy việc nén trên máy cục bộ; prompt và nội dung file không được gửi tới nơi khác chỉ để phục vụ nén.

Luồng mà dự án mô tả:

text Agent hoặc ứng dụng ↓ Headroom chạy cục bộ ↓ Prompt đã nén + cơ chế truy xuất bản gốc ↓ LLM provider hoặc endpoint model

Các thành phần chính gồm:

ContentRouter nhận diện loại nội dung để chọn bộ nén. SmartCrusher xử lý JSON. CodeCompressor xử lý mã nguồn dựa trên AST. Kompress-v2-base xử lý văn bản. CacheAligner đánh dấu nội dung biến động có thể làm ảnh hưởng đến tiền tố KV-cache của nhà cung cấp; README nói thành phần này không tự viết lại prompt. CCR lưu bản gốc tại chỗ, để model có thể gọi headroomretrieve nếu cần nội dung đầy đủ.

Điểm cần phân biệt: sau bước nén, prompt vẫn được gửi đến LLM endpoint mà tổ chức đang dùng. Nếu endpoint đó là dịch vụ bên ngoài, chính sách lưu trữ và xử lý dữ liệu vẫn phụ thuộc vào nhà cung cấp endpoint đó.

Các số liệu nén mà dự án công bố

README đưa ra bốn kịch bản xây dựng từ định dạng output của MCP server. Các phép đo dùng tokenizer của nhà cung cấp và hàm compress() đi kèm dự án; tài liệu nói chúng được chạy offline với seed cố định.

| Kịch bản | Token trước | Token sau | Tiết kiệm | |---|---:|---:|---:| | Tìm kiếm mã nguồn, 100 kết quả | 17.199 | 13.597 | 21% | | Gỡ sự cố SRE | 55.957 | 24.340 | 57% | | Khám phá codebase | 58.801 | 33.895 | 42% | | Phân loại GitHub issue | 46.067 | 32.429 | 30% |

Dự án cũng cho biết mảng JSON lặp lại và các dòng log lặp có thể giảm hơn 90% trong benchmark độ trễ của họ. Ngược lại, văn bản đã cô đọng hoặc giàu thông tin có thể nén rất ít.

Về thời gian nén, README báo cáo:

0,21 ms p50 với kết quả JSON tìm kiếm khoảng 10K token; 1,4 ms với payload 100K token.

Đây là số liệu do dự án công bố, không phải kết quả đánh giá độc lập. Với đội vận hành, tỷ lệ phù hợp nhất vẫn là tỷ lệ đo trên log, JSON và tool output của chính môi trường triển khai.

Bốn cách tích hợp được README nêu

1. Nhúng thư viện vào ứng dụng

Headroom cung cấp hàm compress() cho Python. Ví dụ trong README:

python from headroom import compress from openai import OpenAI

messages = [{"role": "user", "content": "Analyze these results"}] result = compress(messages, model="gpt-4o")

client = OpenAI() response = client.chat.completions.create( model="gpt-4o", messages=result.messages )

print(f"Saved {result.tokenssaved} tokens ({result.compressionratio:.0%})")

Trong luồng này, ứng dụng gửi result.messages — phiên bản đã nén — tới client LLM.

2. Dùng proxy cục bộ

README nêu proxy như một phương án không cần thay đổi mã ứng dụng:

bash headroom proxy --port 8787

Dự án cũng có lệnh dashboard để theo dõi mức tiết kiệm; dashboard yêu cầu proxy đang chạy:

bash headroom dashboard

Tài liệu nguồn không nêu chi tiết về cơ chế xác thực, TLS, địa chỉ bind mặc định hoặc chính sách logging của proxy. Nếu đánh giá mô hình này trong môi trường doanh nghiệp, đây là các điểm cần được kiểm tra trong tài liệu kỹ thuật và môi trường thử nghiệm trước khi mở rộng phạm vi sử dụng.

3. Bọc một số coding agent

Headroom hỗ trợ lệnh bọc nhiều agent, gồm Claude, Codex, Grok, Copilot, Cursor, Aider, OpenCode, Cline, Continue, Goose, OpenHands, OpenClaw, Vibe, OMP và Zcode.

Ví dụ:

bash headroom wrap claude headroom doctor headroom perf

Theo README, headroom wrap khởi động proxy cục bộ, cài Serena để điều hướng code theo ngữ nghĩa, rồi khởi chạy agent với cấu hình đi qua Headroom.

Với Claude Code, Serena được đăng ký cho dự án đang bọc dưới dạng MCP server phạm vi local trong ~/.claude.json. Tài liệu cũng nêu hai tùy chọn:

--code-memory-scope user: dùng cho mọi dự án; --code-memory none: không cài Serena.

Có thể gỡ cấu hình bằng:

bash headroom unwrap <tool>

4. Dùng MCP server

README liệt kê ba công cụ MCP:

headroomcompress headroomretrieve headroomstats

Cách này phù hợp để MCP client gọi nén, truy xuất bản gốc hoặc xem thống kê thông qua các tool được Headroom cung cấp.

Cài đặt: phân biệt CLI Python và SDK TypeScript

README cung cấp các lệnh cài đặt sau:

bash uv tool install --python 3.13 "headroom-ai[all]" pip install "headroom-ai[all]"

Cả hai cách trên cung cấp CLI headroom.

Với TypeScript:

bash npm install headroom-ai

Theo dự án, gói npm là SDK TypeScript để import, chẳng hạn import { compress } from 'headroom-ai', và không cung cấp lệnh CLI headroom.

Không nên lấy benchmark làm cam kết vận hành

README có nêu các đánh giá GSM8K, TruthfulQA, SQuAD v2 và BFCL, với cỡ mẫu 100 trong bảng được cung cấp. Kết quả dự án công bố gồm:

| Benchmark | Nhóm tác vụ | N | Baseline | Headroom | |---|---|---:|---:|---:| | GSM8K | Toán | 100 | 0,870 | 0,870 | | TruthfulQA | Tính xác thực | 100 | 0,530 | 0,560 | | SQuAD v2 | Hỏi đáp | 100 | — | 97% ở mức nén 19% | | BFCL | Tool calling | 100 | — | 97% ở mức nén 32% |

README lưu ý chênh lệch ±0,03 trên TruthfulQA ở cỡ mẫu 100 nằm trong khoảng tin cậy. Vì vậy, tuyên bố “same answers” nên được hiểu là mục tiêu và kết quả mà dự án báo cáo trong các phép thử của họ, không phải bảo đảm cho mọi workload.

Đặc biệt với log sự cố, cấu hình hay runbook nội bộ, đội triển khai nên kiểm thử trực tiếp các chi tiết quan trọng có nguy cơ bị bỏ sót sau nén.

Checklist thử nghiệm cho đội hạ tầng

[ ] Chọn một luồng có nhiều JSON, log hoặc tool output lặp lại. [ ] Cài bản thử nghiệm và chạy headroom doctor để kiểm tra routing. [ ] Dùng headroom savings trên workload đại diện để có số liệu của riêng tổ chức. [ ] Đo chất lượng trên các tác vụ thực tế như phân tích incident, đọc cấu hình và tra cứu runbook. [ ] Kiểm tra cách CCR lưu và bảo vệ bản gốc cục bộ, vì đây là dữ liệu có thể được truy xuất lại. [ ] Xác minh cấu hình proxy, dashboard và agent wrap trước khi đưa vào môi trường dùng chung. [ ] Chuẩn bị phương án gỡ cấu hình agent bằng headroom unwrap <tool> khi cần.

Headroom đáng để thử ở các luồng agent thường xuyên phải đọc payload lớn và lặp lại. Giá trị của dự án không nằm ở một tỷ lệ nén cố định, mà ở khả năng đo xem log, JSON, kết quả tool và context thực tế của tổ chức có thể được rút gọn đến đâu trước khi gửi cho LLM.