# FreeToken: chạy model MoE cỡ lớn trên PC gaming — hướng dẫn cài đặt và dùng

> FreeToken là engine phục vụ (serving) model MoE mã nguồn mở, viết bằng Python, để chạy các model rất lớn ngay trên PC gaming hoặc laptop có card NVIDIA RTX. Bạn có thể cài bằng app desktop cho Windows/Linux hoặc cài gói Python bằng uv/pip. Với người mới, cách dễ nhất là dùng app desktop vì nó tự dựng engine giúp bạn.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-23 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/freetoken-chay-model-moe-lon-tren-pc-gaming

FreeToken là một engine chạy model AI (inference engine) dành cho máy cá nhân. Nó chuyên chạy các model dạng Mixture-of-Experts (MoE) mã nguồn mở, kể cả loại rất lớn, ngay trên PC gaming hay laptop của bạn thay vì thuê máy chủ đắt tiền. Repo viết bằng Python, giấy phép Apache-2.0, hiện có khoảng 17098 sao và 1694 fork.

Vấn đề nó giải quyết khá rõ. Các model mở mạnh nhất hiện nay thường quá to so với một card đồ họa thông thường. Tác giả nói FreeToken coi GPU, CPU, RAM máy và đường truyền giữa chúng như một khối tài nguyên chung, rồi chia việc cho hợp lý. Nhờ vậy model lớn vẫn chạy được ở tốc độ đủ để trò chuyện. README nêu mục tiêu chạy model MoE cỡ 290B+ trên máy gaming.

Bạn nên đọc bài này nếu có máy với card NVIDIA RTX đời 30, 40 hoặc 50 và muốn tự chạy model ở máy mình. Điểm đáng giá nhất là FreeToken có API tương thích Anthropic và OpenAI, nên các công cụ code agent như Claude Code hay Codex có thể nối vào model chạy cục bộ. Với người mới, có sẵn app desktop để khỏi gõ lệnh.

```repo
- repo | FlashML-org/FreeToken
- kind | Framework
- desc | FreeToken là engine chạy các model MoE mã nguồn mở cỡ lớn ngay trên máy cá nhân có card NVIDIA RTX, có app desktop, CLI và API tương thích OpenAI/Anthropic.
- stars | 17k
- lang | Python
- license | Apache-2.0
```

## FreeToken làm được gì

Dưới đây là các tính năng chính, kèm lợi ích thực tế cho người dùng.

### Chạy model lớn bằng cách phối hợp CPU và GPU

README mô tả một runtime "edge-native" cho MoE. Nó chia việc giữa CPU và GPU tùy theo băng thông của máy, có cơ chế nạp trước (prefill) theo từng lớp và bộ nhớ đệm các "chuyên gia" (expert) dùng gần đây. Với bạn, ý nghĩa đơn giản là: máy không đủ VRAM chứa cả model vẫn có cơ hội chạy được. Tốc độ thực tế còn phụ thuộc máy của bạn, tư liệu không đưa con số cụ thể cho từng cấu hình.

### Cache thông minh cho agent

Khi dùng agent code, ngữ cảnh hay bị sửa giữa chừng, ví dụ thêm kết quả gọi công cụ hoặc khối suy nghĩ. FreeToken lưu các điểm neo (checkpoint) để không phải tính lại toàn bộ ngữ cảnh mỗi lần. Kết quả là phản hồi nhanh hơn khi làm việc dài với agent.

### Chia lại VRAM khi đang chạy

Engine có thể chuyển VRAM giữa bộ nhớ chuyên gia và bộ nhớ KV ngay lúc chạy, không cần khởi động lại hay nạp lại trọng số. Bạn đỡ phải chờ khi muốn điều chỉnh cho hợp công việc.

### Nhiều model, nhiều định dạng

README nhắc tới các model như DeepSeek-V4-Flash, Qwen3.6-35B-A3B, GLM-5.2. Các định dạng lượng tử hóa gồm MXFP4, NVFP4, FP8, BF16 và GGUF. Danh sách đầy đủ nằm ở trang Supported models trong thư mục docs của repo.

### API tương thích Anthropic và OpenAI

Đây là phần giúp bạn dùng được ngay với công cụ có sẵn. README liệt kê Codex, Claude Code, OpenCode, OpenClaw và DeepSeek Harness là các agent có thể nối vào.

### App desktop có giao diện

App cho Windows và Linux tự dựng engine, có giao diện để chạy model, trò chuyện và chỉnh engine. Người không quen dòng lệnh nên bắt đầu từ đây.

## Cần chuẩn bị gì

Tư liệu nói rõ những điều sau:

- **Phần cứng:** hỗ trợ gốc cho card NVIDIA RTX 30, RTX 40 và RTX 50. README cũng nói chạy được trên laptop, PC gaming và card workstation.
- **Hệ điều hành:** app desktop có bản Windows và Linux.
- **Python:** nếu cài bản CLI thì cần Python từ 3.10 trở lên (theo pyproject.toml).
- **Công cụ cài:** README khuyên dùng uv, hoặc dùng pip.
- **Git:** cần nếu bạn muốn build từ mã nguồn.

Tư liệu không nói rõ cần bao nhiêu RAM hay VRAM tối thiểu cho từng model, cũng không nói có cần tài khoản hay API key nào. Muốn biết model nào hợp máy mình, hãy xem trang Supported models và Quick start trong thư mục docs của repo trước khi tải file model lớn.

```note
Model cỡ lớn có thể nặng hàng chục đến hàng trăm GB khi tải về. Hãy kiểm tra dung lượng ổ đĩa và RAM máy trước, và đọc docs/models.md để biết model nào hợp với máy của bạn.
```

## Cài đặt từng bước

```steps
- Chọn cách cài | App desktop (dễ nhất) hoặc CLI bằng uv/pip
- Cài bằng app | Tải app cho Windows hoặc Linux ở flashml.ai
- Cài gói bằng uv | Chạy lệnh uv pip install với freetoken[accel]
- Hoặc build từ mã nguồn | Clone repo, tạo môi trường ảo, cài bản chỉnh sửa được
- Đọc docs | Xem docs/install.md và docs/quickstart.md để chạy model đầu tiên
```

### Chọn cách cài phù hợp

README đưa ra hai đường. Đường thứ nhất là app desktop, hợp với người không quen terminal. Đường thứ hai là CLI, hợp với lập trình viên hoặc ai cần chạy trên máy chủ. Nếu bạn là dân văn phòng hay chủ shop, hãy chọn app.

### Cài bằng app desktop

Vào trang chủ dự án flashml.ai và tải bản FreeToken cho Windows hoặc Linux. README nói app sẽ tự thiết lập engine và có giao diện để chạy model, chat và chỉnh engine. README không ghi chi tiết từng thao tác trong app, nên bạn làm theo hướng dẫn trên màn hình cài đặt.

### Cài bản CLI bằng uv

Mở terminal (PowerShell hoặc Terminal tùy máy), rồi chạy lệnh sau. Lệnh này cài gói freetoken kèm phần tăng tốc (accel) vào môi trường Python hiện tại:

```bash
uv pip install "freetoken[accel]"
```

Chỗ người mới hay vấp: phải có sẵn uv và Python 3.10 trở lên. Nếu chưa có uv, xem hướng dẫn cài ở trang docs.astral.sh/uv. README cũng nói bạn có thể dùng pip thay cho uv, nhưng không đưa lệnh pip cụ thể, nên hãy xem docs/install.md.

### Hoặc build từ mã nguồn

Cách này hợp với lập trình viên muốn sửa code hoặc theo dõi bản mới nhất. Các lệnh dưới đây đúng như README:

```bash
git clone https://github.com/FlashML-org/FreeToken.git && cd FreeToken
uv venv && source .venv/bin/activate
uv pip install -e ".[accel]"
```

Lệnh đầu tải mã nguồn về và vào thư mục FreeToken. Lệnh thứ hai tạo môi trường ảo rồi kích hoạt nó. Lệnh thứ ba cài ở chế độ chỉnh sửa (editable), nghĩa là bạn sửa code là có hiệu lực ngay. Lưu ý dòng kích hoạt `source .venv/bin/activate` trong README là kiểu Linux. Nếu dùng Windows, cách dễ hơn là cài app desktop, hoặc xem docs/install.md để biết cách làm đúng.

### Đọc tài liệu cài đặt chi tiết

Repo có sẵn trang hướng dẫn cài đặt (docs/install.md), hướng dẫn bắt đầu nhanh (docs/quickstart.md) và tham chiếu lệnh CLI (docs/cli.md). Ngoài ra còn có file install.sh ở thư mục gốc, nhưng README không giải thích cách dùng nó, nên bạn đừng chạy khi chưa đọc docs. Cách chạy model đầu tiên và các lệnh CLI cụ thể nằm trong những trang này, mình không chép lại vì README chưa ghi.

## Kiểm tra đã chạy được chưa

README không nêu một lệnh kiểm tra cụ thể nào. Vì vậy mình chỉ gợi ý những cách an toàn:

- Với app desktop: mở app lên, nếu thấy giao diện chạy model và chat thì phần cài đặt đã ổn. Sau đó thử nạp một model nhỏ trong danh sách hỗ trợ và gõ một câu chào.
- Với CLI: làm theo docs/quickstart.md, chạy model đầu tiên và xem có nhận được câu trả lời không. Đó là cách kiểm tra đáng tin nhất.
- Nếu model không nạp được: repo có công cụ chẩn đoán checkpoint trong thư mục scripts/checkpoint_diagnose (có README riêng) và trang hướng dẫn sửa checkpoint FTW cũ (docs/ftw-hotfix.md).

## Dùng vào việc thật

Tư liệu không có kịch bản mẫu, nên các tình huống dưới đây bám đúng khả năng README mô tả. Lệnh cụ thể bạn sẽ lấy từ docs/cli.md và docs/quickstart.md.

### Chủ shop muốn chatbot nội bộ không gửi dữ liệu ra ngoài

Bạn có file bảng giá, chính sách đổi trả, mẫu trả lời khách và không muốn đưa lên dịch vụ đám mây. Cài app desktop trên chiếc PC gaming ở cửa hàng, chọn một model trong danh sách hỗ trợ và chat trực tiếp trong app. Dữ liệu chạy trên máy của bạn. Kết quả là có trợ lý soạn tin nhắn trả lời khách, tóm tắt chính sách, viết mô tả sản phẩm. Về mặt an toàn dữ liệu, tài liệu chỉ cho biết model chạy cục bộ trên máy, bạn vẫn nên tự kiểm tra cấu hình mạng.

### Nhân viên văn phòng soạn và tóm tắt văn bản

Bạn thường phải tóm tắt biên bản họp hay soạn email dài. Mở app, nạp model, dán nội dung vào và đưa yêu cầu rõ ràng, ví dụ: "Tóm tắt đoạn văn bản sau thành 5 gạch đầu dòng, nêu rõ việc cần làm và người phụ trách". Bạn nhận được bản tóm tắt ngay trong khung chat mà không phải trả phí theo lượt dùng cho nhà cung cấp.

> Model lớn không còn là đặc quyền của máy chủ: một chiếc PC gaming đủ để bắt đầu.
>
> — Ông T

### Lập trình viên nối Claude Code hoặc Codex vào model chạy cục bộ

Bạn muốn dùng agent code nhưng không muốn mọi dòng mã đi qua dịch vụ ngoài. FreeToken có API tương thích Anthropic và OpenAI, nên bạn chạy engine, rồi trỏ công cụ agent tới địa chỉ cục bộ của nó. Cách khai báo địa chỉ và cổng cụ thể nằm trong docs/cli.md và docs/quickstart.md, mình không đoán để tránh sai. Điểm lợi là cơ chế cache neo giúp agent sửa ngữ cảnh giữa chừng mà không phải tính lại hết từ đầu.

### Nhóm nghiên cứu thử nghiệm model MoE mới

Nếu bạn làm kỹ thuật hoặc nghiên cứu, README liệt kê các model như DeepSeek-V4-Flash, Qwen3.6-35B-A3B, GLM-5.2 và nhiều định dạng lượng tử hóa. Bạn có thể tải các model đó, so sánh chất lượng và tốc độ trên cùng một máy. Repo còn có thư mục benchmarks để tham khảo cách đo. Nếu dùng cho nghiên cứu, README đề nghị trích dẫn bài báo của nhóm tác giả.

## Lỗi hay gặp và cách xử lý

Tư liệu không có mục xử lý lỗi, nên dưới đây là các lỗi rất dễ gặp với loại công cụ này, cùng cách xử lý an toàn.

### Không tìm thấy lệnh uv

Lệnh uv pip báo "command not found" hoặc tương tự nghĩa là máy chưa cài uv. Cài uv theo trang hướng dẫn chính thức rồi mở lại terminal. Nếu vẫn ngại, README nói bạn có thể dùng pip, xem docs/install.md.

### Phiên bản Python quá cũ

Gói yêu cầu Python từ 3.10 trở lên. Nếu máy đang dùng bản cũ hơn, việc cài sẽ báo lỗi về phiên bản. Hãy cài Python mới hơn rồi tạo lại môi trường ảo.

### Dòng source .venv/bin/activate không chạy trên Windows

Dòng này theo kiểu Linux. Trên Windows nó có thể báo lỗi. Cách gọn nhất là cài app desktop cho Windows. Nếu cần dùng CLI, hãy theo hướng dẫn cài đặt trong docs/install.md.

### Model không nạp được hoặc báo lỗi checkpoint

Có thể file model hỏng, tải chưa đủ hoặc là checkpoint FTW cũ. Repo có tài liệu sửa checkpoint FTW cũ và công cụ chẩn đoán checkpoint. Hãy đọc chúng thay vì tự xóa hay sửa file.

### Hết bộ nhớ hoặc chạy rất chậm

Nếu model quá lớn so với VRAM và RAM của máy, bạn sẽ gặp lỗi hết bộ nhớ hoặc tốc độ thấp. Hãy thử model nhỏ hơn trong danh sách hỗ trợ hoặc định dạng lượng tử hóa nhẹ hơn, và đóng bớt ứng dụng nặng khác. Xem docs/models.md để chọn model hợp với máy.

## Có nên dùng không

**Điểm mạnh.** FreeToken nhắm đúng nhu cầu chạy model mở cỡ lớn trên phần cứng tiêu dùng. Có app desktop cho người không rành kỹ thuật và cũng có CLI cho dân lập trình. API tương thích Anthropic và OpenAI giúp nối thẳng vào công cụ agent quen thuộc. Giấy phép Apache-2.0 khá thoải mái, và repo vẫn được cập nhật trong 3 tháng gần đây.

**Giới hạn.** Hỗ trợ gốc tập trung vào card NVIDIA RTX 30, 40 và 50. README không nói về card AMD hay máy Mac. App desktop chỉ có bản Windows và Linux. Tư liệu cũng không công bố mức RAM và VRAM tối thiểu, nên bạn cần tự thử với model nhỏ trước. README chưa có hướng dẫn chi tiết từng lệnh ngay trong trang chính, phần lớn nằm trong thư mục docs.

**Khi nào chọn cách khác.** Nếu máy bạn không có card NVIDIA RTX, hoặc chỉ cần chat đơn giản với model nhỏ, một công cụ gọn hơn có thể hợp hơn. Nếu cần dịch vụ ổn định cho nhiều người dùng cùng lúc, các giải pháp trên máy chủ chuyên dụng sẽ phù hợp hơn. Còn nếu bạn có sẵn PC gaming đời mới và tò mò chạy model lớn ở nhà, FreeToken rất đáng thử, hãy bắt đầu bằng app desktop.

## Câu hỏi thường gặp

### FreeToken có miễn phí không?

Mã nguồn công khai theo giấy phép Apache-2.0, nên bạn dùng và tải về được. Tư liệu không nói gì về phí của app desktop hay dịch vụ đi kèm, nên phần này chưa có thông tin. Bạn nên xem trang flashml.ai để biết chắc.

### Chạy FreeToken có cần card đồ họa không?

README nói hỗ trợ gốc cho card NVIDIA RTX 30, RTX 40 và RTX 50, từ laptop đến máy gaming và workstation. Tư liệu không nói rõ có chạy được khi không có GPU hay không. Mức VRAM tối thiểu cũng chưa được nêu.

### FreeToken chạy được trên Windows không?

Được, README nói có app desktop cho Windows hoặc Linux. Với bản CLI, lệnh kích hoạt môi trường ảo trong README viết theo kiểu Linux. Người dùng Windows nên ưu tiên app desktop hoặc xem docs/install.md.

### Dữ liệu của tôi có an toàn không?

Mục đích của FreeToken là chạy model ngay trên máy cá nhân, nên bạn có thể giữ dữ liệu trong máy. Tuy nhiên tư liệu không có phần nào bàn riêng về bảo mật dữ liệu. Repo có file SECURITY.md để bạn xem chính sách báo lỗi bảo mật.

### FreeToken chạy được những model nào?

README nêu các model MoE mã nguồn mở như DeepSeek-V4-Flash, Qwen3.6-35B-A3B và GLM-5.2. Các định dạng gồm MXFP4, NVFP4, FP8, BF16 và GGUF. Danh sách đầy đủ nằm ở docs/models.md trong repo.

### Có dùng được với Claude Code hay Codex không?

Có thể. README nói FreeToken cung cấp API tương thích Anthropic và OpenAI, và liệt kê Codex, Claude Code, OpenCode, OpenClaw, DeepSeek Harness là các agent tích hợp được. Cách cấu hình cụ thể bạn xem trong docs/quickstart.md và docs/cli.md.

### Cài bằng cách nào là dễ nhất?

Dễ nhất là tải app desktop ở flashml.ai, vì app tự thiết lập engine và có giao diện. Nếu quen lập trình, bạn dùng lệnh uv pip install "freetoken[accel]" với Python từ 3.10 trở lên.
