billion-context: nén ngữ cảnh cho phiên agent chạy hàng tuần — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
billion-context là plugin/proxy nén ngữ cảnh cho các agent lập trình như Claude Code, pi, opencode, codex, aider… Nó để chính mô hình quyết định khi nào và nén đoạn nào thành bản tóm tắt chi tiết, nhờ vậy phiên dài không bị tràn cửa sổ ngữ cảnh. Cài bằng một lệnh npm (cần Node 20 trở lên), sau đó chạy lệnh bili cho client bạn dùng.
billion-context là một plugin kiêm proxy nén ngữ cảnh: nó đứng giữa agent lập trình của bạn (Claude Code, pi, opencode, codex, aider…) và API của mô hình, rồi nén phần hội thoại đã dùng xong thành các bản tóm tắt nhiều lớp. Nhờ đó bạn chạy được một phiên làm việc rất dài mà không bị tràn cửa sổ ngữ cảnh. Tác giả nói cửa sổ 100K token là đủ.
Vấn đề nó giải quyết thì ai dùng agent lập trình lâu đều gặp. Phiên càng dài, ngữ cảnh càng phình. Nhà cung cấp tính tiền theo token. Qua giới hạn cửa sổ thì phiên chạy kém đi hoặc chết hẳn. Repo này nhắm tới người chạy một phiên liên tục nhiều ngày, thậm chí cả tháng, và người dùng mô hình có cửa sổ nhỏ.
Điểm đáng giá nhất là mô hình tự quyết định nén gì, nén lúc nào, chứ không bị cắt cứng ở một mức giới hạn. Phần nén cũng đảo ngược được: cần chi tiết cũ thì mô hình giải nén lại. Repo hiện có khoảng 7.000 sao và 580 fork, vẫn được cập nhật trong 3 tháng gần đây.
ranxianglei/billion-context
Plugin nén ngữ cảnh đứng giữa agent lập trình và API mô hình, giúp một phiên chạy hàng ngày, hàng tuần mà không tràn cửa sổ ngữ cảnh.
I.billion-context làm được gì
Bốn công cụ quản lý ngữ cảnh được proxy chèn vào cuộc hội thoại. Mô hình tự gọi chúng khi ngữ cảnh lớn dần:
compressgộp một dải tin nhắn thành một bản tóm tắt chi tiết. Proxy chạy lệnh này phía máy chủ, nên các đoạn đã gộp vẫn ở dạng tóm tắt trong lịch sử cho tới khi được khôi phục.decompresskhôi phục đoạn đã nén khi cần lại chi tiết chính xác. Ví dụ bạn cần đúng dòng lỗi từ hôm kia.search_contexttìm theo từ khoá trong các bản tóm tắt và tin nhắn đang hiển thị. Phiên dài thì khỏi phải cuộn tìm.acp_statusxem mức dùng ngữ cảnh và những đoạn nào còn nén được.
So với bộ tóm tắt có sẵn trong từng công cụ, README nêu ba điểm khác biệt:
- Nén từng bước (incremental): bản tóm tắt được viết theo từng dải nhỏ, không tóm cả phiên một lần.
- Đảo ngược được (reversible): có thể giải nén khi cần.
- Thân thiện với prefix cache: phần đầu của prompt giữ nguyên, nên mô hình vẫn tận dụng được cache. README nói một phiên khoẻ mạnh giữ tỉ lệ trúng cache khoảng 95–97%, và bản thân việc nén tốn không quá 2%.
Về độ tin cậy, README dẫn một bài báo (nằm trong thư mục paper/) và một bộ đánh giá bên thứ ba. Bài báo nói về nghiên cứu thực tế 4,5 tháng trên ba máy, hơn 174 nghìn lượt gọi mô hình, không lần nào vượt cửa sổ trên các mô hình 204.800 token. Bộ đánh giá so sánh với việc giữ nguyên toàn bộ ngữ cảnh và ba kiểu RAG. README báo kết quả đứng đầu ở ContextBench và chi phí thấp hơn khoảng 58% so với giữ toàn bộ. Đây là số liệu do tác giả công bố, bạn nên xem như tham khảo và tự thử trên việc của mình.
Repo còn hỗ trợ rất nhiều client, từ pi, opencode, omp, dsh, kimi, hermes, zcode, claude, codex đến gemini, qwen, aider, copilot, amp, kiro, crush, zed, goose… Mỗi client có một cách gắn khác nhau (chi tiết ở phần cài đặt).
II.Cần chuẩn bị gì
Theo tư liệu, bạn cần:
- Node.js từ phiên bản 20 trở lên.
package.jsonghi>=20. - npm để cài gói toàn cục.
- Một client agent đã dùng được. Ví dụ Claude Code, opencode, pi, codex. billion-context không thay thế client, nó đứng giữa client và mô hình.
- Tài khoản/API key của chính client đó. billion-context chuyển tiếp luồng Anthropic/OpenAI, nên bạn vẫn dùng key bạn đang dùng. README không yêu cầu key riêng cho billion-context.
Về hệ điều hành, README có hướng dẫn riêng cho Linux/macOS và cho Windows. Tư liệu không nói gì về GPU hay cấu hình phần cứng. Repo có Dockerfile nếu bạn thích chạy trong container.
proxy này nhìn thấy toàn bộ nội dung hội thoại giữa client và mô hình, gồm cả mã nguồn và thông tin bạn dán vào. Nó cũng có thể sửa cấu hình của client (README nói bản cài sẽ sao lưu cấu hình gốc thành file .bili-bak). Trước khi cài, hãy tự sao lưu file cấu hình client và đừng thử đầu tiên trên dự án chứa dữ liệu nhạy cảm.
III.Cài đặt từng bước
- Cài góiChạy npm install -g billion-context để có lệnh bili
- Kiểm tra PATHĐảm bảo thư mục chứa bili nằm trong PATH
- Chọn cách dùngPlugin gốc, launcher hoặc đổi URL
- Gắn vào clientChạy bili plugin install hoặc bili <client>
- Khởi động lại clientMở client như bình thường rồi dùng
A.Cài gói billion-context
Mở terminal (Linux/macOS) hoặc PowerShell/Command Prompt (Windows). Chạy lệnh ở đâu cũng được, không cần vào thư mục dự án. README khuyên Linux/macOS cài với tiền tố thư mục người dùng, để không cần sudo, không đổi cấu hình npm, và tính năng tự cập nhật của bili không gặp lỗi quyền:
npm install -g billion-context --prefix=~/.localLệnh bili sẽ nằm trong ~/.local/bin. Gói cũng giữ bili-proxy làm tên gọi khác của cùng lệnh. Nếu bạn dùng nvm hoặc Homebrew Node, thư mục mặc định đã thuộc quyền người dùng, nên chạy lệnh thường là được:
npm install -g billion-contextTrên Windows, README nói thư mục mặc định (%APPDATA%\npm) đã ghi được, nên dùng đúng lệnh thường ở trên trong PowerShell:
npm install -g billion-contextB.Đảm bảo lệnh bili chạy được
Nếu gõ bili mà báo không tìm thấy lệnh, nhiều khả năng ~/.local/bin chưa có trong PATH. README hướng dẫn thêm dòng sau vào ~/.bashrc hoặc ~/.zshrc, rồi mở lại terminal:
export PATH="$HOME/.local/bin:$PATH"Nếu từng cài bằng thư mục thuộc quyền root và gặp lỗi EACCES, README bảo cài lại với --prefix=~/.local và tránh dùng sudo. Lần sau cài lại bằng npm cũng phải thêm cờ này.
C.Chọn cách dùng
README đưa ra ba cách, chọn một:
- Plugin gốc:
bili plugin install <client>. bili trở thành plugin bên trong client, bạn mở client như thường. - Launcher: một lệnh
bili <client>dựng proxy và mở client cùng lúc. README nói không đụng tới file cấu hình thật của client. - Đổi URL: thêm tiền tố địa chỉ proxy và
/bili/vào baseURL của client. Đây là cách phổ thông nhất.
Nếu bạn mới, cách launcher là dễ nhất vì không sửa cấu hình gì.
D.Gắn vào client của bạn
Với chế độ plugin gốc, README liệt kê các lệnh cho pi, omp, opencode, dsh, kimi, hermes, zcode:
bili plugin install pi
bili plugin install omp
bili plugin install opencode
bili plugin install dsh
bili plugin install kimi
bili plugin install hermes
bili plugin install zcode
bili plugin remove <client>Lệnh cuối dùng để gỡ. Bản cài sẽ lưu cấu hình gốc thành file .bili-bak.
Với Claude Code, README có hai đường. Cách một là chạy launcher:
bili claudeCách hai là dùng plugin gốc. Repo này đồng thời là một marketplace plugin của Claude Code. Trong Claude Code, gõ lần lượt:
/plugin marketplace add ranxianglei/billion-context
/plugin install billion-context@billion-context
/billion-context:bili-setupLệnh thứ ba chạy bili plugin install claude giúp bạn và nhắc bạn khởi động lại Claude Code.
Với codex, launcher là bili codex. Các client khác dùng cùng mẫu bili <client>, ví dụ bili opencode, bili pi, bili aider, bili gemini. Bảng đầy đủ nằm trong README và docs/clients.md.
Với opencode, nếu cài tay không qua bili thì bản 1.x thêm tên gói vào danh sách plugin của cấu hình:
"plugin": ["billion-context"]README dặn thêm cả "compaction": { "auto": false } trong cùng file cấu hình, nếu không opencode sẽ tự nén thêm lần nữa và thành nén đôi. Bản 2.x cần thêm một file chuyển tiếp nhỏ, bạn xem đúng đoạn đó trong README vì cách làm khác bản 1.x. Cách dễ nhất vẫn là bili plugin install opencode.
E.Tránh nén đôi
Plugin gốc và các tiện ích độc lập cũ (billion-context-pi, opencode-acp) loại trừ nhau. Bật cả hai thì nội dung bị nén hai lần. Bản cài sẽ thay các mục cũ cho bạn. Riêng bản cài cục bộ trong từng dự án thì không được động tới, bạn phải tự xoá bằng tay.
F.Về cổng mạng
Nếu bạn chạy proxy thủ công bằng bili start, nó dùng cổng 8787. Những gì launcher hoặc plugin tự bật sẽ dùng vùng cổng riêng bắt đầu từ 18787, trùng cổng thì tự nhảy sang cổng kế. Bình thường bạn không cần chỉnh gì.
README còn nhắc tới chạy bằng Docker (có Dockerfile ở thư mục gốc) nhưng phần hướng dẫn nằm ở đoạn bị cắt. README bản này chưa cho mình đủ lệnh Docker, bạn xem mục «Running in Docker» trong README gốc.
IV.Kiểm tra đã chạy được chưa
Tư liệu mình có không ghi một lệnh kiểm tra cài đặt riêng, chẳng hạn một lệnh in phiên bản. Bạn có thể kiểm tra theo các dấu hiệu sau:
- Gõ
bilitrong terminal mà không báo «không tìm thấy lệnh» là gói đã cài và PATH đúng. - Chạy
bili <client>hoặc mở client sau khibili plugin installthì client khởi động bình thường, không báo lỗi kết nối mô hình. - Khi phiên đã dài, README nói mô hình sẽ tự gọi
compress. Bạn có thể nhờ mô hình dùngacp_statusđể xem mức dùng ngữ cảnh. - README nhắc hai lệnh
/acpvà/acp-cacheđể xem nguyên nhân khi tỉ lệ trúng cache thấp kéo dài. Một phiên khoẻ mạnh nên giữ khoảng 95–97%. - Với Claude Code, sau
/billion-context:bili-setupbạn sẽ được nhắc khởi động lại. Làm đúng như vậy rồi mới đánh giá.
Nếu cần chắc hơn, xem docs/clients.md cho từng client trong repo.
V.Dùng vào việc thật
Sau khi cài, bạn gần như không phải làm gì thêm. Việc nén do mô hình tự gọi. Ba tình huống dưới đây dựa trên những gì README mô tả.
A.Lập trình viên chạy một phiên Claude Code kéo dài nhiều ngày
Bạn đang làm một tính năng lớn và không muốn mở phiên mới, vì mất hết bối cảnh. Chạy bili claude (hoặc cài plugin rồi mở Claude Code như thường) và cứ làm việc. Khi ngữ cảnh đầy dần, mô hình tự gọi compress để gộp phần cũ thành tóm tắt.
Khi cần lại chi tiết, bạn nói thẳng với agent. Ví dụ: «Dùng search_context tìm lại chỗ mình đã quyết định đặt tên bảng, rồi giải nén đoạn đó nếu cần». Kết quả là phiên tiếp tục mà vẫn nhớ quyết định cũ, thay vì quên sạch sau lần tóm tắt cứng.
Phiên dài không còn là phiên bị cắt cụt: cái cũ được gấp lại gọn, và mở ra được khi bạn cần.
Ông T
B.Người dùng mô hình có cửa sổ nhỏ
Bạn dùng mô hình hoặc gói dịch vụ có cửa sổ ngữ cảnh khoảng 100K và hay bị đầy giữa chừng. Dùng launcher bili <client> cho client bạn đang dùng, ví dụ bili opencode hoặc bili aider. README nói cửa sổ 100K là đủ, và nghiên cứu của tác giả không có lần nào vượt cửa sổ trên mô hình 204.800 token. Kết quả mong đợi là ít lần phải mở phiên mới hơn.
C.Muốn giảm hoá đơn token
Bạn trả tiền theo token và để agent chạy nhiều giờ. Vì mỗi lượt gọi gửi lại toàn bộ lịch sử, việc nén phần cũ làm lượng token gửi đi giảm. README nêu con số «ít hơn khoảng 5 lần token» và chi phí thấp hơn đáng kể so với giữ toàn bộ ngữ cảnh trong bộ đánh giá của tác giả. Bạn tự đối chiếu bằng cách so hoá đơn hoặc bảng thống kê token trước và sau khi bật. Nếu tỉ lệ trúng cache tụt thấp kéo dài, dùng /acp hoặc /acp-cache để xem nguyên nhân.
D.Dùng với client chưa có chế độ plugin
Bạn dùng một client như aider, gemini, copilot hay zed, mà README ghi là không có chế độ plugin gốc. Hãy chạy launcher bili <client>, hoặc thêm tiền tố /bili/ vào baseURL của client. Cách này vẫn nén được, chỉ là client không có công cụ tích hợp sâu như bản plugin. Chi tiết từng client nằm trong docs/clients.md.
VI.Lỗi hay gặp và cách xử lý
A.Gõ bili báo không tìm thấy lệnh
Thường là thư mục chứa bili chưa có trong PATH. Thêm dòng export PATH="$HOME/.local/bin:$PATH" vào ~/.bashrc hoặc ~/.zshrc rồi mở lại terminal. Trên Windows, đóng và mở lại cửa sổ PowerShell sau khi cài.
B.Báo lỗi quyền EACCES khi cài
Đây là lỗi do thư mục npm toàn cục thuộc quyền root. README nói cách sửa lâu dài là cài lại với --prefix=~/.local và tránh sudo. Nhớ thêm cờ này cho cả những lần cài lại sau.
C.Bị nén đôi, phiên có vẻ quên nhiều
Nếu cùng lúc bật plugin gốc và tiện ích độc lập cũ (billion-context-pi, opencode-acp), nội dung bị nén hai lần. Với opencode, cũng cần tắt nén tự động có sẵn bằng "compaction": { "auto": false }. Bản cài của bili thường tự xử lý, nhưng bản cài cục bộ trong dự án thì bạn phải gỡ tay. Với pi, README nói cần billion-context-pi từ 0.1.72 trở lên để nhận được dấu hiệu nhường chỗ.
D.Tỉ lệ trúng cache thấp, chi phí không giảm
README liệt kê nguyên nhân thường gặp theo thứ tự: hết hạn TTL của cache phía nhà cung cấp, đổi mô hình giữa chừng, lỗi của bili (nên báo lên repo), hoặc nguyên nhân khác. Dùng /acp hoặc /acp-cache để xem nguyên nhân thuộc nhóm nào trước khi kết luận.
E.Dùng cổng mạng bị trùng
Nếu có chương trình khác đang chiếm cổng, bili tự nhảy sang cổng kế tiếp. Nếu bạn cố ý chạy bili start (cổng 8787), các plugin sẽ ưu tiên gắn vào tiến trình của chính nó trước. Khi thấy hành vi lạ, hãy tắt các tiến trình bili cũ rồi bật lại.
VII.Có nên dùng không
Điểm mạnh. Cách nén do mô hình quyết định, đảo ngược được và giữ prefix cache là hướng tiếp cận hợp lý cho phiên dài. Số client hỗ trợ rất rộng. Cài đặt chỉ cần một lệnh npm. Tác giả công khai cả bài báo lẫn bộ đánh giá, và repo vẫn được cập nhật.
Giới hạn.
- Một số client không có chế độ plugin gốc. Với các client đó bạn phải đi qua launcher hoặc đổi URL, trong đó có cách dùng chứng chỉ man-in-the-middle (cert-MITM) mà README nhắc tới. Bạn cần hiểu bản chất proxy trước khi dùng cho dữ liệu nhạy cảm.
- Tài liệu rất dày và nhiều chi tiết kỹ thuật theo từng client, người mới dễ rối. Hãy chọn đúng một client của bạn và chỉ đọc phần đó.
- README bản mình có chưa ghi lệnh kiểm tra cài đặt riêng, và giấy phép không được ghi rõ trong tư liệu. Nếu dùng trong công ty, bạn nên mở file
LICENSEtrong repo để xem trước. - Các con số hiệu quả do tác giả công bố. Kết quả thực tế phụ thuộc vào mô hình, client và kiểu công việc của bạn.
Khi nên chọn cách khác. Nếu phiên của bạn ngắn, hiếm khi chạm giới hạn ngữ cảnh, thì bộ tóm tắt có sẵn trong client là đủ và không cần thêm một lớp proxy. Nếu bạn cần kiểm soát từng chữ trong lịch sử hội thoại, việc để mô hình tự tóm tắt có thể làm bạn khó chịu. Còn nếu bạn chạy agent liên tục nhiều giờ đến nhiều ngày và thấy hoá đơn token hoặc giới hạn cửa sổ là điểm nghẽn, billion-context đáng để thử, bắt đầu bằng launcher cho an toàn.
Câu hỏi thường gặp
billion-context có miễn phí không?
Gói cài qua npm bằng lệnh npm install -g billion-context. Tư liệu không nói về phí dùng riêng cho billion-context. Bạn vẫn trả tiền token cho nhà cung cấp mô hình như bình thường. Giấy phép không được ghi rõ trong tư liệu, bạn nên xem file LICENSE trong repo.
Cần Node.js phiên bản nào?
package.json yêu cầu Node từ phiên bản 20 trở lên. Nếu máy bạn dùng Node cũ hơn, hãy nâng cấp trước khi cài.
Chạy được trên Windows không?
README có hướng dẫn riêng cho Windows: dùng lệnh npm install -g billion-context bình thường vì thư mục mặc định đã ghi được. Với từng client cụ thể trên Windows, bạn xem thêm docs/clients.md vì tư liệu mình có chưa nêu đủ.
Có cần GPU hay cấu hình mạnh không?
Tư liệu không nhắc tới yêu cầu GPU hay phần cứng. Đây là plugin/proxy viết bằng TypeScript chạy trên Node, nên phần nén do mô hình mà bạn đang dùng thực hiện qua API.
Dữ liệu của tôi có an toàn không?
billion-context đứng giữa client và API mô hình nên nó đi qua toàn bộ nội dung hội thoại. Tư liệu chưa nói chi tiết về lưu trữ hay gửi dữ liệu đi đâu. Bạn nên đọc tài liệu trong repo và cẩn trọng với dự án có dữ liệu nhạy cảm.
Khác gì bộ tóm tắt có sẵn của Claude Code hay opencode?
README nói bộ tóm tắt sẵn có của client thì khác: ở billion-context việc nén diễn ra từng bước, có thể giải nén khi cần, và giữ nguyên prefix cache. Mô hình tự quyết định nén khi nào và đoạn nào, thay vì bị cắt cứng ở một giới hạn. Với opencode, bạn cần tắt nén tự động có sẵn để tránh nén đôi.
Tôi nên chọn cách nào trong ba cách dùng?
Nếu mới bắt đầu, README gợi ý launcher là cách không cần chỉnh cấu hình, chỉ cần chạy bili <client>. Plugin gốc (bili plugin install <client>) thì tiện hơn về lâu dài nhưng sẽ sửa cấu hình client. Đổi URL với tiền tố /bili/ là cách chung nhất cho client chưa có hỗ trợ.


