billion-context: nén ngữ cảnh để phiên AI chạy cả tháng — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về ranxianglei/billion-context — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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à một plugin kiêm 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, nhờ vậy phiên dài không bị tràn cửa sổ. Cài bằng một lệnh npm, rồi chọn một trong ba cách nối với client; người mới cần chút thời gian đọc bảng client.
billion-context là một plugin nén ngữ cảnh (context compression) cho các agent lập trình. Nó nằm giữa agent của bạn và API của mô hình, viết lại luồng Anthropic/OpenAI để những đoạn hội thoại cũ được gói thành bản tóm tắt chi tiết. Lệnh bạn gõ sau khi cài là bili.
Vấn đề nó giải quyết rất quen thuộc: làm việc với agent code lâu thì hội thoại phình ra, tốn token theo từng lượt, và khi vượt cửa sổ ngữ cảnh thì phiên bị chậm, lú lẫn hoặc chết hẳn. Ai hay để agent chạy cả buổi, cả tuần trên cùng một dự án, hoặc dùng mô hình có cửa sổ nhỏ, sẽ thấy đây là công cụ đáng thử.
Điểm đáng giá nhất: việc nén không phải cắt cụt cứng. Mô hình tự quyết định nén gì và khi nào, bản tóm tắt có thể giải nén lại khi cần chi tiết, và phần đầu của hội thoại được giữ nguyên để cache của nhà cung cấp vẫn trúng. Repo hiện có khoảng 7074 sao và 580 fork, viết bằng TypeScript, cần Node từ bản 20 trở lên.
ranxianglei/billion-context
Plugin nén ngữ cảnh đứng giữa agent code và API mô hình, để một phiên làm việc chạy nhiều ngày mà cửa sổ 100K vẫn đủ dùng.
I.billion-context làm được gì
A.Nén dần từng đoạn, không cắt cứng
Thay vì tóm tắt cả cuộc trò chuyện một lần như trình tóm tắt có sẵn của nhiều công cụ, plugin này nén theo từng khoảng nhỏ. Lợi ích thực tế: bạn mất ít chi tiết hơn, và những đoạn gần đây vẫn nguyên văn.
B.Bốn công cụ quản lý ngữ cảnh
Proxy tự thêm bốn công cụ vào cuộc hội thoại để mô hình gọi khi ngữ cảnh lớn dần:
compress: gói một khoảng tin nhắn thành bản tóm tắt chi tiết. Proxy chạy lệnh này ở phía máy chủ, nên đoạn đã nén vẫn ở dạng tóm tắt cho tới khi được khôi phục.decompress: khôi phục đoạn đã nén khi cần lại chi tiết chính xác (ví dụ một đoạn log hay một đoạn code đã đọc từ lâu).search_context: tìm theo từ khoá trong các bản tóm tắt và các tin nhắn đang hiển thị.acp_status: xem mức dùng ngữ cảnh và đoạn nào còn nén được.
C.Giữ cache hiệu quả
Theo README, một phiên khoẻ mạnh giữ tỉ lệ trúng prefix-cache khoảng 95–97%, còn bản thân việc nén tốn không quá 2%. Nếu thấy tỉ lệ thấp kéo dài, bạn kiểm tra nguyên nhân bằng /acp hoặc /acp-cache. Những nguyên nhân thường gặp, theo thứ tự: cache phía nhà cung cấp hết hạn, đổi mô hình, lỗi của chính bili (nên báo cho tác giả), hoặc không rõ.
D.Chạy được với rất nhiều client
README liệt kê các client như pi, opencode, omp, dsh, kimi, hermes, zcode, claude, codex, jcode, gemini, iflow, qwen, antigravity, mcode, aider, copilot, amp, kiro, crush, zed, goose. Client nào không có móc ngữ cảnh riêng vẫn dùng được qua launcher hoặc tiền tố /bili/.
E.Số liệu từ tác giả
Tác giả công bố một bài nghiên cứu (nằm trong thư mục paper/, giấy phép MIT) theo dõi 4,5 tháng, ba máy chủ, 174.327 lượt gọi mô hình, không lần nào vượt cửa sổ trên mô hình 204.800 token. Họ cũng có bản so sánh 1.500 mục với full context và ba kiểu RAG: xếp số 1 trên ContextBench với chi phí thấp hơn khoảng 58,3% so với full, và 79,20% trên LongMemEval-S so với 62,60% của RAG tốt nhất. Đây là số do tác giả công bố, bạn nên coi là tham khảo.
II.Cần chuẩn bị gì
Theo tư liệu:
- Node.js từ bản 20 trở lên (package.json yêu cầu
>=20) và npm. - Một client agent đã dùng được sẵn (ví dụ Claude Code, pi, opencode…). billion-context không thay client, nó gắn vào client.
- API hoặc tài khoản mô hình mà client của bạn đang dùng. README phần đã có không nêu thêm khoá riêng nào cho bili.
- Hệ điều hành: README có hướng dẫn cho Linux, macOS và Windows. Chưa thấy yêu cầu GPU hay phần cứng riêng.
- Tuỳ chọn: Docker, vì repo có sẵn
Dockerfileở thư mục gốc (README trỏ tới mục Running in Docker, phần này nằm ngoài đoạn tư liệu mình có).
Vì bili đứng giữa client và API, mọi nội dung hội thoại (kể cả code, key nếu lỡ dán vào) đi qua proxy trên máy bạn. Hãy chỉ dùng bản cài từ npm đúng tên billion-context và đọc kỹ lệnh trước khi chạy.
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 PATHBảo đảm thư mục chứa lệnh bili đã nằm trong PATH
- Chọn cách nốiPlugin native, launcher hoặc đổi baseURL
- Nối với clientChạy bili plugin install hoặc bili tên-client
- Khởi động lại clientMở client như bình thường và thử /acp
A.Bước 1: Cài gói bằng npm
Mở terminal (Terminal trên macOS/Linux, PowerShell trên Windows). Trên Linux/macOS, README khuyên cài với tiền tố thư mục người dùng để khỏi cần sudo và để tính năng tự cập nhật của bili không bị lỗi quyền:
npm install -g billion-context --prefix=~/.localNếu bạn dùng Node qua nvm hoặc Homebrew, thư mục mặc định đã thuộc quyền người dùng, nên chạy lệnh thường là đủ:
npm install -g billion-contextTrên Windows, thư mục mặc định (%APPDATA%\npm) cũng ghi được, nên dùng lệnh thường ở trên trong PowerShell.
B.Bước 2: Kiểm tra lệnh bili có trong PATH
Lệnh bili được đặt ở ~/.local/bin. Phần lớn bản Linux đã có thư mục này trong PATH. Nếu terminal báo không tìm thấy bili, thêm dòng sau vào ~/.bashrc hoặc ~/.zshrc rồi mở terminal mới:
export PATH="$HOME/.local/bin:$PATH"Gói cài thêm bili-proxy làm tên gọi phụ. Nếu gặp lỗi EACCES do thư mục gốc từng thuộc root, hãy cài lại với --prefix=~/.local (lần cài lại sau này cũng phải gõ cờ này) và tránh dùng sudo.
C.Bước 3: Chọn một trong ba cách dùng
README đưa ra ba cách:
- Plugin native:
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>bật proxy và client cùng lúc, không đụng vào file cấu hình thật. - Đổi URL: thêm tiền tố địa chỉ proxy cộng
/bili/vào baseURL của client. Cách này phổ quát nhất.
Người mới nên bắt đầu bằng launcher, vì dễ gỡ nhất: tắt lệnh là xong. Plugin native hỗ trợ pi, omp, opencode, dsh, kimi, hermes, zcode.
D.Bước 4: Nối với client của bạn
Ví dụ dùng launcher với Claude Code:
bili claudeHoặc cài dạng native cho Claude Code. 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 cuối tự chạy bili plugin install claude giúp bạn và nhắc bạn khởi động lại client.
Các client khác, theo README:
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 zcodeMỗi lệnh ghi một mục vào file cấu hình của client tương ứng (ví dụ pi, omp, opencode) và lưu bản sao cấu hình gốc dưới dạng .bili-bak. Với opencode, lệnh còn tắt tính năng tự nén có sẵn của opencode để tránh nén đôi. Muốn gỡ:
bili plugin remove <client>Với codex: bili codex là cách đầy đủ, còn bili plugin install codex chỉ thêm bộ công cụ MCP và bạn phải bật bili trước.
E.Bước 5: Tránh nén đôi
Plugin native và các tiện ích độc lập billion-context-pi, opencode-acp loại trừ lẫn nhau: bật cả hai là nén hai lần. Trình cài đặt sẽ thay các mục cũ giúp bạn, nhưng bản cài cục bộ theo từng dự án thì không đụng tới, bạn phải gỡ bằng tay.
Phần README mình có bị cắt ở đây, nên chưa có các mục cấu hình nâng cao, Docker và FAQ. Bạn xem thêm trong CONFIGURATION.md, CLIENTS.md và docs/ của repo.
IV.Kiểm tra đã chạy được chưa
Phần README mình có chưa ghi một lệnh "kiểm tra thành công" riêng. Bạn có thể dựa vào các dấu hiệu sau, đều có trong tư liệu:
- Lệnh
bilichạy được trong terminal (không báo "command not found"). - Client mở bình thường sau khi cài native hoặc qua launcher.
- Trong client có lệnh
/acphoặc/acp-cacheđể xem tình trạng cache và nguồn gốc nếu tỉ lệ trúng thấp. - Mô hình có thêm bốn công cụ
compress,decompress,search_context,acp_status. Bạn có thể nhờ nó gọiacp_statusđể xem mức dùng ngữ cảnh. - Sau một thời gian dài, tỉ lệ trúng prefix-cache nên ở mức 95–97% theo mô tả của tác giả.
Nếu không thấy gì, quay lại bước nối client và đọc CLIENTS.md.
V.Dùng vào việc thật
A.Dev làm một dự án lớn trong nhiều ngày
Bối cảnh: bạn dùng Claude Code để refactor một codebase, phiên chạy hàng ngày liền và hay bị đầy ngữ cảnh. Bạn cài theo cách native hoặc chạy bili claude, rồi làm việc như thường. Khi hội thoại phình, mô hình tự gọi compress cho những đoạn đã xử lý xong. Khi cần xem lại một quyết định cũ, bạn nhắn: "Dùng search_context tìm lần mình bàn về cấu trúc thư mục, nếu cần chi tiết thì decompress đoạn đó." Kết quả: phiên không phải mở lại từ đầu và bớt tốn token.
Phiên dài không cần cửa sổ lớn hơn, chỉ cần biết nén đúng chỗ và giải nén đúng lúc.
Ông T
B.Người dùng mô hình có cửa sổ nhỏ
Bối cảnh: bạn dùng một mô hình rẻ hoặc chạy qua client như aider, cửa sổ chỉ cỡ 100K. Mô tả của tác giả nói 100K là đủ. Bạn chạy launcher:
bili aiderREADME ghi aider đi theo kiểu cert-MITM hoặc tiền tố /bili/. Kết quả: phiên làm việc với mô hình nhỏ vẫn kéo dài mà không chạm trần cửa sổ.
C.Chủ shop hoặc nhân viên văn phòng dùng agent làm việc nhiều bước
Bối cảnh: bạn nhờ agent xử lý nhiều file báo cáo, bảng giá, email trong một phiên dài. Bạn không cần biết kỹ thuật nén, chỉ cần cài một lần rồi mở client như cũ. Khi muốn kiểm tra, bạn nhắn: "Cho mình xem acp_status, ngữ cảnh đang dùng bao nhiêu và đoạn nào còn nén được." Kết quả: bạn nắm được mức dùng ngữ cảnh mà không phải đoán. Lưu ý: bili dành cho client agent, không phải ứng dụng chat thông thường trên web.
D.Theo dõi chi phí và cache
Bối cảnh: hoá đơn API tăng bất thường. Bạn mở client và gõ /acp-cache để xem tỉ lệ trúng cache. Nếu thấp kéo dài, đối chiếu với bốn nguyên nhân README liệt kê: cache hết hạn, đổi mô hình, lỗi của bili, hoặc không rõ. Kết quả: bạn biết nên chỉnh thói quen (ví dụ đừng đổi mô hình giữa chừng) hay báo lỗi cho tác giả.
VI.Lỗi hay gặp và cách xử lý
A.Báo EACCES khi cài
Thường do thư mục npm toàn cục thuộc root. Cài lại với npm install -g billion-context --prefix=~/.local và không dùng sudo, đúng như README khuyên.
B.Gõ bili báo không tìm thấy lệnh
Thư mục ~/.local/bin chưa nằm trong PATH. Thêm dòng export PATH="$HOME/.local/bin:$PATH" vào ~/.bashrc hoặc ~/.zshrc, rồi mở terminal mới.
C.Bị nén hai lần
Bạn đang bật cả plugin native lẫn tiện ích độc lập như billion-context-pi hay opencode-acp. Chạy lại bili plugin install <client> để trình cài đặt thay mục cũ. Nếu bạn có bản cài cục bộ theo dự án thì gỡ bằng tay. Bản gốc cấu hình được lưu dưới tên .bili-bak nên bạn có thể quay lại.
D.Tỉ lệ trúng cache thấp
Dùng /acp hoặc /acp-cache để xem nguyên nhân. Hay gặp nhất là cache của nhà cung cấp hết hạn sau một lúc không dùng, hoặc bạn vừa đổi mô hình. Nếu nghi là lỗi của bili thì báo cho tác giả.
E.Dùng sai cách với opencode 2.x
README cảnh báo: với OpenCode 2.x, ghi tên gói trần vào danh sách plugin không chạy được. Cách dễ nhất là bili plugin install opencode vì nó tự chọn dạng mục phù hợp với phiên bản. Nếu cài tay, bạn nhớ đặt compaction.auto thành false và sao lưu file cấu hình trước.
VII.Có nên dùng không
Điểm mạnh: giải quyết đúng nỗi đau của phiên dài; để mô hình tự quyết định nén gì; có thể giải nén lại; giữ cache tốt; hỗ trợ rất nhiều client; có bài nghiên cứu và số liệu đối chiếu công khai; repo vẫn được cập nhật trong vài tháng gần đây.
Giới hạn: cấu hình khá nhiều ngả (launcher, native, đổi URL) nên người mới dễ rối; mỗi client có điểm riêng, có client chỉ chạy kiểu launcher. Một số client là binary đóng nên chỉ qua cert-MITM hoặc tiền tố /bili/. Số liệu hiệu quả do chính tác giả công bố. Tư liệu mình có không ghi rõ giấy phép của mã nguồn (repo có file LICENSE, bạn nên đọc trước khi dùng thương mại).
Nên thử nếu bạn dùng agent lập trình hằng ngày và hay chạm trần ngữ cảnh. Nếu bạn chỉ chat ngắn, hoặc dùng ứng dụng chat trên web, thì không cần. Nếu bạn ngại một proxy đứng giữa client và API, hãy cân nhắc dùng tính năng nén có sẵn của client.
Câu hỏi thường gặp
billion-context có miễn phí không?
Gói cài bằng npm, bạn cài bằng một lệnh. Tư liệu mình có không nêu giá hay gói trả phí. Giấy phép của mã nguồn không được ghi trong tư liệu, nên bạn xem file LICENSE trong repo. Bạn vẫn phải trả tiền API cho mô hình mà client đang dùng.
Cần GPU không?
Tư liệu không yêu cầu GPU hay phần cứng riêng. Chỉ cần Node.js từ bản 20 trở lên.
Chạy được trên Windows không?
Có. README ghi rõ trên Windows thư mục npm mặc định ghi được, nên chạy npm install -g billion-context bình thường. Một số client có cách nối riêng, bạn xem CLIENTS.md.
Dữ liệu của mình có an toàn không?
Tư liệu mô tả billion-context là proxy đứng giữa client và API của mô hình, nên nội dung hội thoại đi qua nó. Phần chính sách dữ liệu chi tiết chưa có trong đoạn README mình đọc. Bạn nên xem mã nguồn và tài liệu trong repo trước khi dùng với dữ liệu nhạy cảm.
Khác gì bộ tóm tắt có sẵn của client?
Theo tác giả, bộ tóm tắt có sẵn thường làm một lần. billion-context nén theo từng đoạn nhỏ, có thể giải nén lại khi cần, để mô hình tự quyết định và giữ nguyên phần đầu hội thoại cho cache.
Hỗ trợ những client nào?
README liệt kê pi, opencode, omp, dsh, kimi, hermes, zcode, claude, codex, jcode, gemini, iflow, qwen, antigravity, mcode, aider, copilot, amp, kiro, crush, zed, goose. Client khác dùng được qua launcher hoặc tiền tố /bili/.
Gỡ ra thế nào nếu không ưng?
Với plugin native, chạy bili plugin remove <client>. Bản sao cấu hình gốc được lưu dưới tên .bili-bak. Với launcher, bạn chỉ cần không chạy lệnh bili nữa vì launcher không sửa file cấu hình thật.


