FreeToken
Mã nguồn mở bởi FlashML-org
FreeToken là engine suy luận (serving engine) để chạy các mô hình AI mã nguồn mở dạng Mixture-of-Experts (MoE) cỡ lớn trên máy có GPU NVIDIA dòng tiêu dùng. Nó mở một máy chủ API tương thích OpenAI và Anthropic trên máy của bạn, để Claude Code, Codex, OpenCode… gọi mô hình chạy tại chỗ. Chữ "Free" trong tên nói về việc tự chạy mô hình trên phần cứng của mình, không phải lấy token của dịch vụ trả phí.
FreeToken dùng để làm gì?
- Chạy mô hình MoE mã nguồn mở như Qwen3.6-35B-A3B, DeepSeek-V4-Flash, GLM-5.2 trên máy cá nhân có GPU NVIDIA
- Mở API tương thích OpenAI (/v1/chat/completions) và Anthropic (/v1/messages) ngay trên máy
- Cho Claude Code, Codex, OpenCode dùng mô hình chạy tại chỗ bằng lệnh ft launch
- Chat thử với mô hình trong terminal bằng lệnh ft shell
- Chia phần expert của mô hình giữa VRAM, RAM và CPU khi GPU không đủ bộ nhớ
Giao diện
Ảnh và video lấy từ README của dự án trên GitHub, bản quyền thuộc nhóm phát triển.
Cần biết trước khi dùng
- Lưu ýKhông tìm thấy docker-compose hay Dockerfile ở thư mục gốc: chưa thể gắn nút Deploy tự động.
- Lưu ýTino chưa kiểm thử dự án này.
Kiểm tra tự động ngày 04/11/2026 từ dữ liệu GitHub, OSV.dev và docker-compose. Đây không phải chứng nhận bảo mật; Tino không phát triển hay bảo trì repo này.
FreeToken là gì?
Các mô hình MoE mới có tổng số tham số rất lớn, thường cần GPU máy chủ mới chứa hết. FreeToken là engine phục vụ mô hình được viết cho phần cứng cá nhân: nó coi GPU, CPU, RAM của máy và đường truyền giữa chúng là một khối tài nguyên chung. Theo README, nhóm phát triển lấy cảm hứng từ mini-sglang và dùng lại mã từ SGLang, vLLM, FlashInfer, llama.cpp.
Điểm chính là cách xử lý phần expert của MoE. Expert có thể nằm hết trên GPU (fused), nằm trong RAM và chỉ một phần được cache trên GPU (offload), được tính bằng CPU (cpu), hoặc kết hợp cả hai (hybrid). Bộ nhớ VRAM chia giữa cache expert và KV cache có thể đổi khi đang chạy mà không phải khởi động lại engine. README còn nêu cơ chế lưu mốc ngữ cảnh để khi agent sửa ngữ cảnh (gọi công cụ, khối suy nghĩ) thì không phải tính lại từ đầu.
Sau khi chạy ft serve, máy mở API ở 127.0.0.1:1919, tương thích cả OpenAI và Anthropic, nên các thư viện client hiện có chỉ cần đổi base URL. Lệnh ft launch ghi cấu hình cho agent lập trình (claude, codex, opencode, openclaw, hermes, dsh) để agent gọi vào máy chủ này.
Ngoài bản dòng lệnh, nhóm phát triển phát hành ứng dụng desktop cho Windows và Linux tại flashml.ai, có giao diện để chạy mô hình, chat và chỉnh engine. README không nêu ứng dụng desktop có mở mã nguồn hay không. Dự án đi kèm một bài báo trên arXiv; README nói engine chạy mô hình 290B+ với tốc độ tương tác, nhưng đây là mô tả của tác giả.
Nên dùng khi
- Bạn có máy Linux với GPU NVIDIA RTX 30, 40 hoặc 50 và muốn chạy mô hình MoE mã nguồn mở tại chỗ
- Bạn muốn Claude Code, Codex hay OpenCode dùng mô hình chạy trên máy mình thay vì gửi mã ra ngoài
- Mô hình bạn cần lớn hơn VRAM của GPU và bạn chấp nhận dùng thêm RAM, CPU để bù
Không nên dùng khi
- Máy hoặc VPS không có GPU NVIDIA: tài liệu cài đặt yêu cầu GPU NVIDIA, driver r580+ (CUDA 13)
- Bạn cần một dịch vụ ổn định cho nhiều người dùng: dự án mới ra từ tháng 7/2026, bản nightly đổi hằng ngày
- Bạn định mở máy chủ ra Internet mà chưa đặt --api-key: mặc định không có xác thực
- Bạn dùng GPU AMD và cần cài đặt ổn định: hướng dẫn ROCm vẫn ghi là đang làm (WIP)
Tính năng chính
- API tương thích OpenAI (/v1/chat/completions, /v1/responses, /v1/models) và Anthropic (/v1/messages, /v1/messages/count_tokens)
- Bốn chiến lược đặt expert: fused, offload, cpu, hybrid, cùng chế độ auto
- Cache expert theo LRU trên GPU, chia lại VRAM giữa cache expert và KV cache khi đang chạy
- Hỗ trợ các định dạng MXFP4, NVFP4, FP8, BF16 và file GGUF
- Nhận ảnh đầu vào với một số họ mô hình như Qwen3.6, Gemma-4, GLM-5.3-Flash
- Lệnh ft launch ghi cấu hình cho claude, codex, opencode, openclaw, hermes, dsh
- Giao diện chat trong terminal (ft shell), lệnh ft ctl xem thống kê máy chủ
- Ứng dụng desktop cho Windows và Linux, phát hành riêng tại flashml.ai
Cách cài đặt FreeToken
-
Cài từ PyPI
Yêu cầu theo tài liệu: Linux x86_64, GPU NVIDIA với driver r580+ (CUDA 13), Python 3.10 trở lên, khuyên dùng uv. Lần đầu dùng, kernel CUDA được biên dịch JIT nên máy cần CUDA 13 toolkit có nvcc trong PATH.
uv venv && source .venv/bin/activate uv pip install "freetoken[accel]" -
Hoặc cài từ mã nguồn
Dùng khi muốn theo nhánh main. Tài liệu còn có bản wheel nightly trên trang Releases, tên file đổi mỗi đêm.
git clone https://github.com/FlashML-org/FreeToken.git && cd FreeToken uv venv && source .venv/bin/activate uv pip install -e ".[accel]" -
Chạy máy chủ và kiểm tra
--model nhận đường dẫn thư mục mô hình hoặc ID repo trên Hugging Face. Máy chủ sẵn sàng khi log in dòng API server is ready to serve on 127.0.0.1:1919.
source .venv/bin/activate ft --version ft serve --model ~/path/to/Qwen3.6-35B-A3B curl http://127.0.0.1:1919/v1/chat/completions -H 'Content-Type: application/json' \ -d '{"model":"Qwen3.6-35B-A3B","messages":[{"role":"user","content":"hi"}]}'
Lệnh chép từ README của dự án. Đọc kỹ trước khi chạy và đối chiếu với README mới nhất, vì lệnh có thể đổi theo phiên bản.
Cấu hình quan trọng
| Mục | Ý nghĩa |
|---|---|
FREETOKEN_API_KEY | Khoá API mặc định cho --api-key; khi bật, mọi route trừ /health yêu cầu Authorization: Bearer hoặc x-api-key |
FREETOKEN_HOME | Thư mục cài của script install.sh, mặc định ~/.freetoken; ứng dụng desktop đọc biến này để tìm engine |
FREETOKEN_PIN_PROBE_MARGIN_GB | Trên WSL và Windows: lượng bộ nhớ nhả thêm (khoảng 3 GiB) sau khi CUDA từ chối ghim bộ nhớ |
FREETOKEN_PIN_BUDGET_GB | Ngân sách bộ nhớ ghim khi dùng --moe-cpu-layers auto trên máy giới hạn pinned memory |
Cách tích hợp và sử dụng
- Xem mô hình đang chạycurl http://127.0.0.1:1919/v1/models trả về ID mô hình, dùng ID đó cho trường model trong yêu cầu.
- Gọi từ ứng dụng sẵn cóThư viện client của OpenAI hoặc Anthropic dùng được ngay khi đổi base URL về http://127.0.0.1:1919.
- Nối agent lập trìnhft launch claude (hoặc codex, opencode, openclaw, hermes, dsh) ghi cấu hình nhà cung cấp cho agent, cài CLI của agent nếu thiếu rồi mở agent trỏ vào máy chủ. Thêm --dry-run để xem trước thay đổi.
- Chat trong terminalft shell gắn vào máy chủ đang chạy; ft shell --model vừa mở engine vừa chat trong một tiến trình. Gõ /help để xem lệnh.
- Mở cho máy khác dùngMáy chủ mặc định chỉ nghe ở 127.0.0.1. Đổi bằng --host và --port, và đặt --api-key trước khi mở ra mạng.
- Tinh chỉnh khi thiếu VRAMChọn --moe-strategy offload, cpu hoặc hybrid. Với hybrid, chạy ft bench bw --model một lần cho mỗi máy và mô hình để đo băng thông.
Cập nhật và sao lưu
Cài bằng PyPI thì cập nhật như một gói Python trong virtualenv. Bản nightly là cặp wheel đổi tên mỗi đêm; tài liệu khuyên ghim URL wheel cụ thể, không ghim theo tag nightly.
README không nêu lệnh nâng cấp riêng. Dữ liệu cần giữ chủ yếu là thư mục mô hình bạn đã tải; checkpoint FTW cũ có hướng dẫn sửa riêng trong docs/ftw-hotfix.md.
Câu hỏi thường gặp
FreeToken có phải công cụ lấy token API miễn phí của OpenAI, Anthropic không?
Không. FreeToken chạy mô hình mã nguồn mở ngay trên GPU của bạn và mở API cùng định dạng với OpenAI, Anthropic. Nó không kết nối hay dùng tài khoản của các dịch vụ đó.
Thuê VPS thường không có GPU thì chạy được không?
Tài liệu cài đặt yêu cầu GPU NVIDIA với driver r580+ (CUDA 13). README không nêu cách chạy chỉ bằng CPU; chế độ cpu chỉ tính phần expert trên CPU, các phần còn lại vẫn cần GPU.
Dùng được với Claude Code không?
Được. FreeToken có API tương thích Anthropic. Lệnh ft launch claude ghi cấu hình và mở Claude Code trỏ vào máy chủ FreeToken trên máy.
Có hỗ trợ card AMD hay Windows không?
Có hướng dẫn ROCm cho AMD nhưng đang ghi là WIP. Bản dòng lệnh trong tài liệu dành cho Linux x86_64; ứng dụng desktop có bản Windows, còn tài liệu có ghi chú riêng cho WSL.
Ứng dụng liên quan
Miễn trừ trách nhiệm
Tino không phát triển, không sở hữu và không liên kết với FreeToken hay nhóm phát triển FlashML-org. Tên, logo và nhãn hiệu thuộc về chủ sở hữu tương ứng; việc nhắc tới chỉ để mô tả, không có nghĩa là dự án xác nhận hay hợp tác với Tino.
FreeToken được phân phối theo giấy phép Apache-2.0 của nhóm phát triển. Tino không bảo đảm về tính năng, bảo mật hay mức độ phù hợp của phần mềm; bạn tự chịu trách nhiệm khi cài đặt, cấu hình và sử dụng.
Lệnh cài và thông tin trên trang lấy từ tài liệu công khai của dự án tại thời điểm cập nhật và có thể đã thay đổi. Đọc tài liệu chính thức và sao lưu dữ liệu trước khi chạy trên máy chủ thật.
