# kimi-k3-in-c: chạy mô hình 2,78 nghìn tỷ tham số trên CPU, 8 GB RAM — hướng dẫn cài đặt và dùng

> kimi-k3-in-c là một engine suy luận viết bằng C99 thuần, chạy mô hình Kimi K3 cỡ 2,78 nghìn tỷ tham số trên CPU với đỉnh RAM đo được khoảng 8,24 GB. Cài phần engine rất dễ (git clone, make, make test), nhưng muốn sinh chữ thật bạn phải tải checkpoint nặng 1,56 TB. Máy RAM nhỏ chạy rất chậm, RAM càng nhiều càng nhanh nhưng kết quả không đổi.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-08-07 · Cập nhật: 2026-11-13
- URL: https://ongt.vn/bai-viet/kimi-k3-in-c-chay-kimi-k3-tren-cpu-8gb-ram

kimi-k3-in-c là một engine suy luận (inference engine) viết bằng C99 thuần, dùng để chạy mô hình Kimi K3 với 2,78 nghìn tỷ tham số ngay trên CPU. Không GPU, không thư viện BLAS, không framework học sâu. Theo tác giả, cả engine chỉ nặng khoảng 176 KB và đỉnh RAM đo được là 8,24 GB.

Con số nghe vô lý vì checkpoint của mô hình nặng tới 1,56 TB. Mẹo nằm ở chỗ: phần “thân” dày đặc của mô hình được giữ trong RAM tới mức bạn cho phép, phần còn lại (các chuyên gia định tuyến, khoảng 1,45 TB) không bao giờ nằm hết trong bộ nhớ mà được đọc từ ổ đĩa và nhân thẳng ở dạng nén 4-bit. Hệ quả là cùng một mô hình chạy được trên máy 8 GB lẫn máy 224 GB, và kết quả giống nhau từng byte. RAM nhiều chỉ làm nhanh hơn.

Repo hợp với lập trình viên, người thích tìm hiểu cách một LLM khổng lồ chạy trên phần cứng bình thường, và ai muốn có một engine nhỏ, đọc được, tự build được. Điểm đáng giá nhất là bạn kiểm tra được engine trong khoảng một phút mà không cần tải model. Hiện repo có khoảng 11.922 sao và 1.838 fork.

```repo
- repo | FareedKhan-dev/kimi-k3-in-c
- kind | Ứng dụng
- desc | Engine C99 chạy suy luận Kimi K3 (2,78 nghìn tỷ tham số) trên CPU thường, chỉ cần khoảng 8 GB RAM, không GPU, không BLAS, không framework.
- stars | 12k
- lang | C
- license | Apache-2.0
```

## kimi-k3-in-c làm được gì

**Chạy mô hình khổng lồ trên máy thường.** Với preset nhỏ nhất, máy 8 GB RAM vẫn sinh được chữ. Theo bảng đo của tác giả, máy 8 GB mất khoảng 26,5 giây cho mỗi token, máy 32 GB khoảng 24,2 giây, máy 64 GB khoảng 19,8 giây, còn máy 128 GB trở lên khoảng 5,6 giây. Tác giả đo trên máy 124 lõi với ổ NVMe nhanh, nên máy của bạn có thể khác.

**Kết quả không đổi theo cấu hình.** Cùng một câu lệnh, máy nhỏ và máy lớn cho ra cùng một văn bản. Bạn không phải lo “máy yếu thì câu trả lời kém đi”, chỉ lo chờ lâu hơn.

**Có chế độ chat.** Cờ `--chat` dùng đúng định dạng XTML chính thức của Kimi K3. Bản hiện tại chỉ có văn bản: chưa có công cụ, ảnh, server hay nén ngữ cảnh.

**Có bộ kiểm thử không cần model.** Lệnh `make test` chạy toàn bộ bộ kiểm thử trên một mô hình nhỏ 13 lớp có cùng đồ thị tensor với bản thật, so với kết quả chuẩn từ PyTorch lưu sẵn trong repo. Đây là cách an toàn để biết engine đúng trước khi bạn tải 1,56 TB.

**Có công cụ hỗ trợ.** Script `k3-doctor.sh` kiểm tra máy, đo tốc độ đĩa và in ra lệnh nên chạy tiếp theo. Script tải và đóng gói model đi kèm, có thể tải tiếp khi bị ngắt.

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

Theo README, thứ khó nhất là ổ đĩa, còn lại khá bình thường:

- **Hệ điều hành:** Linux x86-64 là bản tham chiếu. macOS arm64 và Windows x86-64 cũng build được và qua các bài kiểm tra. Trên Windows, README nói cổng này dùng MSYS2 MinGW-w64.
- **CPU:** x86-64 cần AVX2 và FMA; arm64 dùng NEON. Không cần AVX-512.
- **RAM:** từ 8 GB trở lên, preset nào cũng chạy được.
- **Ổ đĩa:** khoảng 1,7 TB trống: 1,56 TB checkpoint cộng 109 GB “trunk” đã đóng gói. Nên đặt trên ổ local nhanh.
- **Trình biên dịch:** GCC từ 9 hoặc Clang từ 10, cùng GNU make hoặc CMake. Phụ thuộc duy nhất là libm và OpenMP.
- **Python:** README ghi 3.9 trở lên cho các công cụ tải, đóng gói và phân tích, không cần cho `make test`. Riêng file `pyproject.toml` khai báo `>=3.12` cho gói `kimi-k3-in-c`. Để chắc ăn, bạn dùng Python 3.12 trở lên.
- **Tài khoản:** cần một token Hugging Face để chạy script tải model.

```note
Chỉ phần “cài và kiểm thử engine” là nhẹ. Chạy thật cần tải 1,56 TB, mất hàng giờ và tốn băng thông. Hãy chạy make test và k3-doctor.sh trước khi quyết định tải.
```

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

```steps
- Tải mã nguồn | git clone repo rồi cd vào thư mục
- Kiểm tra máy | chạy k3-doctor.sh để biết máy hợp preset nào
- Build và kiểm thử | make -j rồi make test, chưa cần model
- Tải checkpoint | đặt HF_TOKEN và chạy download-model.sh (1,56 TB)
- Đóng gói trunk | chạy pack-trunk.sh một lần
- Chạy thử | gọi ./bin/k3 với prompt ngắn
```

### Tải mã nguồn

Mở terminal (Linux, macOS, hoặc MSYS2 trên Windows) ở thư mục bạn muốn đặt dự án, rồi chạy:

```bash
git clone https://github.com/FareedKhan-dev/kimi-k3-in-c.git
cd kimi-k3-in-c
```

Thư mục này chỉ khoảng 45 MB, phần lớn là sơ đồ và dữ liệu kiểm thử. Các lệnh sau đều chạy từ bên trong thư mục `kimi-k3-in-c`, nên đừng quên lệnh `cd`.

### Kiểm tra máy

```bash
./scripts/k3-doctor.sh
```

Script kiểm tra trình biên dịch, so RAM của bạn với các preset, đo ổ đĩa theo đúng cách engine sẽ đọc và in ra lệnh nên chạy tiếp. Nó mất khoảng một phút. Nếu máy không thể chạy model, script thoát với mã lỗi khác 0. README nói có thể chạy script này bất cứ lúc nào.

### Build và kiểm thử

```bash
make -j
make test
```

`make -j` biên dịch bảy file C, mất vài giây. `make test` chạy toàn bộ kiểm thử trong dưới một phút. Nếu bạn quen CMake, README cũng có cách này:

```bash
cmake -B build && cmake --build build -j && ctest --test-dir build
```

Bước này rất đáng làm trước khi tải 1,56 TB, vì nó chứng minh engine khớp với bản tham chiếu và chỉ cần repo.

### Tải checkpoint

Lấy token trên trang cài đặt token của Hugging Face, rồi:

```bash
export HF_TOKEN=hf_your_token_here          # read from the environment, never echoed
./scripts/download-model.sh ~/k3model       # resumable, re-run to continue
```

Lệnh `export` đặt token vào biến môi trường của phiên terminal hiện tại, và bạn thay `hf_your_token_here` bằng token của mình. Script tải được, bị ngắt thì chạy lại để tiếp tục. Cuối cùng nó kiểm tra số shard, tổng số byte và kích thước từng shard. Kết quả đúng sẽ có dòng `RESULT : byte-exact match`.

Nếu thấy `FAIL`, hãy dừng lại. README cảnh báo tải thiếu không báo lỗi to mà chỉ cho ra token sai.

### Đóng gói trunk

```bash
./scripts/pack-trunk.sh ~/k3model ~/k3trunk
```

Bước này mất khoảng bốn phút, làm một lần. Nó gom 93 lớp dày đặc vào một file 109 GB, để mỗi lớp đọc được bằng một lần gọi. README nói chính bước này biến yêu cầu bộ nhớ thành một “núm vặn”. Nên đặt đầu ra ở ổ nhanh nhất bạn có.

### Chạy thử

```bash
./bin/k3 ~/k3model --trunk ~/k3trunk --preset workstation \
         --tok ~/k3model --prompt "The capital of France is" --gen 8 --incremental
```

Giải thích nhanh: `~/k3model` là thư mục chứa các shard; `--trunk` trỏ tới trunk đã đóng gói; `--preset` chọn mức dùng RAM; `--tok` trỏ tới thư mục có tokenizer (nó nằm sẵn trong thư mục model); `--gen 8` sinh 8 token; `--incremental` giữ bộ nhớ đệm giữa các token để nhanh hơn. Các preset có sẵn là `laptop`, `desktop`, `workstation`, `server`, `max`, và `ultra` cho máy cỡ 8 GB.

Lần chạy đầu sẽ chậm hơn hẳn, vì token đầu tiên phải nạp mọi lớp được ghim từ ổ đĩa (khoảng 108 GB ở preset `server`). Chi phí này chỉ trả một lần mỗi lần chạy.

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

Có hai mức kiểm tra.

Mức một, không cần model: sau `make test`, màn hình phải kết thúc bằng các dòng sau, nếu không là đã lỗi:

```
GATE 1  teacher forcing : 32/32 positions match tf_pred
        generated span  : 20/20  <- must be exact
GATE 2  greedy decode   : 20/20 generated tokens match full_ids
GATE 3  incremental    : 20/20 generated tokens match full_ids  <- KV cache + carried KDA state

VERDICT: ENGINE MATCHES THE REFERENCE EXACTLY

ALL WEIGHTLESS TESTS PASSED
```

Bạn cũng có thể phát lại một phép đo đã công bố bằng Python (cần numpy):

```bash
python3 tools/sim_cache.py tests/fixtures/expert_trace.bin
```

Mức hai, chạy model thật: lệnh chạy thử in ra phần chữ sinh ra, số token, thời gian trung bình mỗi token và dòng `PEAK RSS for the whole run`. Ví dụ trong README với preset `laptop` ra “Paris” rồi đoạn tiếp theo, đỉnh RAM 8,24 GB. Chữ chính xác trên máy bạn có thể khác về hình thức, nhưng lệnh `--prompt "The capital of France is"` là mô hình tiếp tục câu, nên nhận được nội dung kiểu “Paris” là đúng hướng.

Ngoài ra `./bin/k3 --help`, `./bin/k3 --version` và `./bin/k3 --list-presets` chạy được mà không cần model, tiện để biết file thực thi đã build xong.

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

### Lập trình viên kiểm tra engine trước khi tải model

Bạn là dev mới, tò mò nhưng không muốn mất cả ngày tải 1,56 TB để rồi phát hiện máy không hợp. Bạn clone repo, chạy `./scripts/k3-doctor.sh`, rồi `make -j` và `make test`. Trong khoảng vài phút bạn biết trình biên dịch ổn, đĩa đủ nhanh và engine khớp bản tham chiếu. Kết quả là một quyết định có cơ sở: tải tiếp hay dừng ở đây. Nếu muốn đọc code, bạn có thêm thư mục `src/`, `docs/` và `tests/`.

> Cùng một mô hình, cùng một câu trả lời, chỉ khác đồng hồ.
>
> — Ông T

### Viết prompt tiếng Việt từ file

Bạn muốn thử câu có dấu tiếng Việt. README khuyên dùng `--prompt-file` cho mọi thứ không phải ASCII (tiếng Trung, emoji, chữ có dấu), vì shell có thể mã hóa lại tham số dòng lệnh, còn file được đọc nguyên văn. Ví dụ README đưa dùng tiếng Pháp:

```bash
printf 'La capitale de la France est' > /tmp/p.txt
./bin/k3 ~/k3model --tok ~/k3model --prompt-file /tmp/p.txt ...
```

Bạn làm tương tự: ghi câu của mình vào một file văn bản, rồi trỏ `--prompt-file` tới nó và giữ nguyên các cờ `--trunk`, `--preset`, `--incremental` như trên. Kết quả là văn bản được token hóa đúng byte, không bị shell làm hỏng.

### Hỏi đáp nhiều lượt bằng chế độ chat

Bạn muốn câu trả lời chứ không phải đoạn văn tiếp nối. Dùng chế độ chat chính thức:

```bash
./bin/k3 ~/k3model --trunk ~/k3trunk --preset desktop --tok ~/k3model \
  --chat --system "You are a helpful assistant." \
  --history my-session.jsonl --incremental
```

Vòng lặp chấp nhận chữ thường và các lệnh `/help`, `/reset`, `/exit`. Nó in cả bản ghi chuẩn, gồm các thẻ `<think>…</think>` và `<response>…</response>`. Khi có `--history`, phiên được lưu vào file để bạn xem lại. Hãy nhớ máy RAM nhỏ trả lời rất chậm, nên đây hợp để thử hơn là làm việc gấp.

### Làm nóng trước phần mở đầu dài

Bạn có một đoạn mở đầu dài dùng đi dùng lại. README nói `--gen 0 --incremental --save-state PATH` chỉ chạy bước nạp prompt rồi lưu trạng thái chính xác, để làm nóng một lần và dùng lại nhiều lần. Cách nạp lại trạng thái đã lưu nằm ở phần README mà mình chưa có trong tư liệu, nên bạn xem tiếp phần Usage trong README của repo để biết cờ tương ứng.

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

**Chạy với `--preset` mà không có `--trunk`.** README nói rõ như vậy là vô ích: engine nạp toàn bộ khoảng 113,5 GB vào RAM bất kể ngân sách bạn đặt. Cách xử lý: luôn thêm `--trunk ~/k3trunk` sau khi đã chạy bước đóng gói.

**Tải model bị thiếu hoặc sai.** Tải dở không báo lỗi to mà cho ra token sai. Hãy đọc kỹ phần `verifying…` ở cuối script tải. Thấy `FAIL` thì chạy lại `./scripts/download-model.sh ~/k3model`, vì script tải tiếp được và kiểm tra từng shard, nên bạn chỉ tải lại shard hỏng.

**Sinh chữ chậm bất thường.** Quên `--incremental` khiến mỗi bước chạy lại toàn bộ prompt từ đầu, chi phí tăng theo bình phương độ dài. Thêm cờ này cho mọi lần sinh chữ dài. Ngoài ra tốc độ phụ thuộc mạnh vào ổ đĩa: ở máy ít RAM, mô hình được đọc từ đĩa ở mỗi bước, nên ổ chậm sẽ chậm theo.

**Build không ra file hoặc báo thiếu OpenMP, trình biên dịch cũ.** README yêu cầu GCC từ 9 hoặc Clang từ 10 và OpenMP. Chạy `./scripts/k3-doctor.sh` để nó chỉ ra thiếu gì. README không liệt kê lệnh cài riêng cho từng hệ điều hành, nên bạn cài trình biên dịch theo cách của hệ điều hành mình.

**Hết chỗ trên ổ đĩa.** Bạn cần khoảng 1,7 TB trống (1,56 TB model cộng 109 GB trunk). Kiểm tra dung lượng trước khi tải. Đặt model và trunk trên ổ local nhanh thay vì ổ mạng.

**Prompt không phải ASCII bị lỗi chữ.** Dùng `--prompt-file` thay vì `--prompt`, như trong tình huống ở trên.

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

**Điểm mạnh.** Engine nhỏ, thuần C99, build trong vài giây, có bộ kiểm thử tự chứa so với PyTorch. Cách tiếp cận “RAM nhiều hơn chỉ nhanh hơn, không khác đi” rất rõ ràng và có số đo kèm. Giấy phép Apache-2.0, repo còn được cập nhật trong ba tháng gần đây, và có cổng macOS, Windows cùng NEON do cộng đồng đóng góp.

**Giới hạn.** Đừng kỳ vọng dùng như một trợ lý hằng ngày. Ở máy 8 GB, mỗi token mất khoảng nửa phút, và README gọi preset `ultra` là “proof-of-life” chứ không phải tốc độ tương tác. Bạn phải có khoảng 1,7 TB ổ đĩa trống và tải mất hàng giờ. Chế độ chat mới chỉ có văn bản, chưa có công cụ hay ảnh.

**Khi nên chọn cách khác.** Nếu bạn cần câu trả lời nhanh cho công việc, hãy dùng một dịch vụ API hoặc một mô hình nhỏ hơn chạy nội bộ. Repo này hợp nhất khi bạn muốn học cách chạy mô hình cỡ nghìn tỷ tham số trên phần cứng thường, tự kiểm chứng hoặc nghiên cứu. Nếu chỉ tò mò, dừng ở `make test` đã cho bạn khá nhiều thứ để xem mà không tốn terabyte nào.

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

### kimi-k3-in-c có miễn phí không?

Repo dùng giấy phép Apache-2.0 nên mã nguồn dùng tự do. Bạn cần token Hugging Face để chạy script tải model. Tư liệu không nói gì về chi phí hay điều khoản riêng của checkpoint, nên bạn tự xem trang model.

### Có cần GPU không?

Không. Repo ghi rõ không GPU, không BLAS, không framework. Chỉ cần CPU x86-64 có AVX2 và FMA, hoặc arm64 có NEON, cùng trình biên dịch C99 và OpenMP.

### Máy 8 GB RAM chạy được thật không?

Được, README đo đỉnh RAM 8,24 GB, nhưng rất chậm: khoảng 26,5 giây mỗi token ở bảng đo của tác giả. RAM nhiều hơn chỉ làm nhanh hơn, kết quả không đổi. Bạn vẫn cần khoảng 1,7 TB ổ đĩa trống.

### Chạy được trên Windows và macOS không?

Có. Linux x86-64 là bản tham chiếu, còn macOS arm64 và Windows x86-64 cũng build và qua các bài kiểm tra. Trên Windows, README nói cổng dùng MSYS2 MinGW-w64.

### Có thể thử mà không tải model 1,56 TB không?

Có. Chỉ cần git clone, make -j và make test là chạy được bộ kiểm thử trên mô hình nhỏ 13 lớp, không cần checkpoint, mạng hay Python. Các bài kiểm thử đó chạy trong khoảng một phút.

### Cần phiên bản Python nào?

README ghi Python 3.9 trở lên cho các công cụ tải, đóng gói và phân tích, không cần cho make test. Riêng pyproject.toml yêu cầu Python 3.12 trở lên, nên dùng 3.12 cho chắc.

### Dữ liệu của tôi có được gửi đi đâu không?

Tư liệu mô tả engine chạy cục bộ trên CPU của bạn. Mạng chỉ cần khi tải model qua script. Tư liệu chưa có thông tin chi tiết hơn về quyền riêng tư, nên bạn đọc SECURITY.md và mã nguồn nếu cần chắc chắn.
