# kimi-k3-in-c: chạy Kimi K3 trên CPU — hướng dẫn cài đặt và dùng

> kimi-k3-in-c là engine C99 để chạy suy luận Kimi K3 trên CPU, không dùng GPU, BLAS hay framework. Repo hỗ trợ Linux, Windows và macOS, nhưng cần checkpoint khoảng 1,56 TB cùng nhiều dung lượng trống. Phần kiểm tra không cần tải model, còn chạy model đầy đủ cần chuẩn bị máy và thời gian tải đáng kể.

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

kimi-k3-in-c là một engine C99 chạy suy luận Kimi K3 2,78 nghìn tỷ tham số trên CPU. Repo không dùng GPU, BLAS hay framework học máy. Engine có thể chạy model trên máy chỉ có 8 GB RAM bằng cách đọc dữ liệu từ ổ đĩa theo từng phần.

Repo phù hợp với lập trình viên muốn nghiên cứu cách xây dựng inference engine từ đầu, người làm AI muốn thử chạy model cực lớn trên phần cứng phổ thông, và người muốn kiểm chứng cách giảm nhu cầu bộ nhớ. Điểm đáng chú ý nhất là kết quả sinh ra byte-identical ở các mức RAM khác nhau; nhiều RAM hơn chủ yếu giúp chạy nhanh hơn, không đổi câu trả lời.

```repo
- repo | FareedKhan-dev/kimi-k3-in-c
- kind | CLI
- desc | Engine C99 chạy suy luận Kimi K3 2,78 nghìn tỷ tham số trên CPU, không cần GPU hay framework.
- stars | 12k
- lang | C
- license | Apache-2.0
```

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

- Chạy Kimi K3 bằng CPU: engine hỗ trợ x86-64 với AVX2 và FMA, hoặc arm64 với NEON. AVX-512 không bắt buộc.

- Chạy model lớn trên máy ít RAM: phần trunk và routed experts được tổ chức để có thể đọc từ ổ đĩa theo nhu cầu. Preset laptop có thể chạy trong khoảng 8 GB RAM, dù tốc độ rất chậm.

- Không phụ thuộc framework lớn: phần engine chính là C99 portable, không cần BLAS hay GPU. Đây là lựa chọn phù hợp để đọc mã nguồn và hiểu từng thành phần của một hệ thống suy luận.

- Hỗ trợ nhiều mức bộ nhớ: các preset `laptop`, `desktop`, `workstation`, `server`, `max` đặt ngân sách cho trunk và expert cache. Bạn cũng có thể tự đặt ngân sách bằng `--trunk-gb` và `--cache-gb`.

- Hỗ trợ sinh văn bản theo token: có thể đưa prompt dạng chữ, đọc prompt từ file hoặc truyền trực tiếp danh sách token id. Cách đọc từ file phù hợp với tiếng Việt có dấu, CJK, emoji và dữ liệu không phải ASCII.

- Có chế độ sinh tăng dần: `--incremental` giữ KV cache và trạng thái KDA giữa các token. Với prompt dài, tùy chọn này tránh phải chạy lại toàn bộ tiền tố ở mỗi bước.

- Có chat nhiều lượt: `--chat` dùng định dạng XTML chính thức của Kimi K3, có lịch sử phiên qua file JSONL, cùng các lệnh `/help`, `/reset` và `/exit` trong REPL.

- Có bộ kiểm tra và oracle: `make test` kiểm tra kernel, cache streaming, safetensors reader, config reader, tokenizer và đường chạy end-to-end. Repo còn có bài kiểm tra cache từ trace đã ghi sẵn.

- Có công cụ kiểm tra máy: `k3-doctor.sh` kiểm tra toolchain, đo RAM, đo tốc độ lưu trữ và gợi ý lệnh tiếp theo. Điều này hữu ích vì tốc độ của repo phụ thuộc rất nhiều vào ổ đĩa.

- Có thể đóng gói trunk: `pack-trunk.sh` chuyển 93 dense layer thành một file 109 GB với offset đã biết. Nhờ vậy engine có thể stream trunk thay vì giữ toàn bộ khoảng 113,5 GB trong RAM.

Hiện repo có khoảng 11.951 sao và 1.848 fork. Giấy phép là Apache-2.0. Phần mã nguồn chính dùng C, đi kèm Makefile, CMakeLists.txt, thư mục `src/`, `include/`, `tests/`, `tools/` và các script hỗ trợ.

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

- Hệ điều hành: Linux x86-64 là môi trường tham chiếu. Repo cũng build và vượt các gate trên macOS/arm64 và Windows/x86-64. Windows dùng lớp tương thích MSYS2 với MinGW-w64 theo tài liệu repo.

- CPU: x86-64 cần AVX2 và FMA. Arm64 dùng NEON. AVX-512 không cần thiết.

- RAM: tối thiểu khoảng 8 GB cho các preset. Máy có nhiều RAM sẽ nhanh hơn. README nêu rằng 8 GB có thể chạy nhưng thường phải stream model từ ổ đĩa ở mỗi bước.

- Dung lượng lưu trữ: cần khoảng 1,7 TB trống. Checkpoint chiếm 1,56 TB và trunk đã đóng gói chiếm khoảng 109 GB. Nên đặt trunk trên ổ đĩa cục bộ nhanh.

- Trình biên dịch: GCC từ 9 trở lên hoặc Clang từ 10 trở lên. Bạn cần GNU make hoặc CMake.

- Python: README yêu cầu Python 3.9 trở lên cho các công cụ tải model, đóng gói và phân tích. Tuy nhiên `pyproject.toml` của repo khai báo Python từ 3.12 trở lên, nên cần kiểm tra đúng yêu cầu của công cụ bạn định chạy.

- Tài khoản và token: chỉ cần khi tải checkpoint từ Hugging Face. Bạn phải tạo một token có quyền đọc và đặt vào biến môi trường `HF_TOKEN`.

- Checkpoint: để chạy model đầy đủ, cần tải 96 shard với tổng kích thước chính xác 1.560.936.091.448 byte. Bước kiểm tra không cần checkpoint, không cần mạng và không cần Python.

- GPU: không cần GPU. Engine được thiết kế để chạy suy luận trên CPU.

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

```steps
- Clone mã nguồn | Tải repo và đi vào thư mục dự án
- Kiểm tra máy | Đo toolchain, RAM và ổ đĩa bằng k3-doctor
- Build và test | Biên dịch engine rồi chạy toàn bộ gate không cần model
- Tải checkpoint | Tải 96 shard Kimi K3 bằng token đọc
- Đóng gói trunk | Tạo trunk.bin để bật chế độ streaming
- Chạy thử | Gọi bin/k3 với preset, tokenizer và prompt
```

### Clone mã nguồn

Mở terminal tại thư mục bạn muốn lưu dự án. Có thể dùng lệnh phổ thông sau:

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

`git clone` tải mã nguồn về máy. `cd` chuyển terminal vào thư mục repo. Nếu dùng Windows, README cho biết port Windows dùng MSYS2 MinGW-w64; các lệnh bên dưới là cú pháp shell kiểu Unix.

Repo chiếm khoảng 45 MB, chủ yếu là mã nguồn, tài liệu, hình minh họa và test fixture. Bạn không cần tải checkpoint để build hoặc chạy test ban đầu.

### Kiểm tra máy

Chạy công cụ chẩn đoán trước khi tải model:

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

Script này mất khoảng một phút vì đo ổ đĩa theo cách engine sẽ đọc dữ liệu. Nó kiểm tra toolchain, đo RAM, đo bộ nhớ lưu trữ và chọn preset phù hợp. Nếu máy không thể chạy model, script sẽ kết thúc với mã lỗi khác 0.

Đây là bước nên làm sớm vì checkpoint rất lớn. Nếu ổ đĩa không đủ khoảng 1,7 TB hoặc tốc độ đọc không phù hợp, việc tải model trước sẽ làm mất nhiều thời gian mà chưa giải quyết được vấn đề.

### Build engine

Cách build bằng GNU make:

```bash
make -j
```

Lệnh này biên dịch engine trong vài giây. README nêu các phụ thuộc chính là trình biên dịch C99, `libm` và OpenMP.

Nếu muốn dùng CMake, chạy:

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

Lệnh CMake tạo thư mục build, biên dịch dự án rồi chạy test bằng CTest. Người mới nên chọn một cách build và dùng nhất quán để tránh nhầm vị trí file thực thi.

### Test trước khi tải model

Chạy toàn bộ test không cần checkpoint:

```bash
make test
```

README cho biết test thường hoàn tất trong chưa đầy một phút. Kết quả thành công có các dòng chính:

```text
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
```

Nếu chưa thấy kết luận này, chưa nên tải checkpoint. Test kiểm tra các kernel, streaming cache, safetensors reader, config reader, tokenizer và một mô hình oracle 13 layer có cùng tensor graph với model phát hành.

Repo còn có một bài kiểm tra mô phỏng cache:

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

Lệnh này dùng Python và numpy để đọc trace có sẵn, sau đó in lại bảng dung lượng expert cache. Đây là kiểm tra bổ sung, không phải bước bắt buộc để build engine.

### Tải checkpoint

Trước hết, tạo token đọc trên Hugging Face rồi đặt token vào biến môi trường. Lệnh README cung cấp là:

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

`export` đặt token cho phiên terminal hiện tại. Không dán token vào mã nguồn, không gửi token trong ảnh chụp màn hình và không đưa token vào file công khai.

`download-model.sh` tải checkpoint vào thư mục `~/k3model`. Nếu bị gián đoạn, có thể chạy lại để tiếp tục. Bước này cần tải khoảng 1,56 TB nên có thể mất nhiều giờ, không phải vài phút.

Khi hoàn tất, script kiểm tra số shard, tổng số byte và kích thước từng shard. Kết quả mong đợi có dạng:

```text
verifying…
  shards : 96 (expect 96)
  bytes  : 1560936091448 (expect 1560936091448)
  shards : all 96 match their published sizes individually
  RESULT : byte-exact match
```

Nếu kết quả là `FAIL`, hãy dừng lại và xử lý trước khi chạy model. README cảnh báo bản tải thiếu hoặc sai có thể không báo lỗi rõ ràng nhưng tạo ra token sai.

### Đóng gói trunk

Sau khi checkpoint đã được xác minh, đóng gói 93 dense layer:

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

Lệnh này tạo thư mục `~/k3trunk`, gồm `trunk.bin` và `trunk.json`. Quá trình mất khoảng bốn phút và thực hiện một lần. File đầu ra khoảng 109 GB nên đặt trên ổ đĩa nhanh nhất.

Trunk đã đóng gói giúp engine biết vị trí từng layer và đọc layer bằng một lần gọi. Nếu bỏ qua `--trunk` khi chạy, engine sẽ nạp toàn bộ trunk khoảng 113,5 GB vào RAM, bất kể preset bạn chọn.

### Chạy prompt đầu tiên

Lệnh chạy mẫu:

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

`~/k3model` là thư mục chứa các shard `.safetensors`. `--trunk` trỏ đến trunk đã đóng gói. `--preset workstation` chọn ngân sách bộ nhớ. `--tok ~/k3model` trỏ đến tokenizer nằm cùng thư mục model. `--prompt` đưa văn bản vào, `--gen 8` yêu cầu sinh 8 token và `--incremental` bật trạng thái tăng dần.

Token đầu tiên có thể chậm hơn nhiều vì engine phải tải các layer được ghim. Sau đó tốc độ ổn định hơn. Với máy 8 GB, nên kỳ vọng chạy rất chậm; README ghi nhận mức khoảng 26,5 giây mỗi token cho một laptop thông thường với preset laptop.

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

Có ba mức kiểm tra rõ ràng:

- Sau `make -j`, phải có file thực thi `bin/k3` theo đường chạy trong README.
- Sau `make test`, phải thấy `VERDICT: ENGINE MATCHES THE REFERENCE EXACTLY` và `ALL WEIGHTLESS TESTS PASSED`.
- Sau khi tải model, script phải báo 96 shard, đúng tổng byte và `RESULT : byte-exact match`.

Bạn cũng có thể kiểm tra giao diện lệnh mà không cần chỉ định thư mục model:

```bash
./bin/k3 --help
./bin/k3 --version
./bin/k3 --list-presets
```

Khi chạy prompt thành công, chương trình in phần văn bản được sinh, số token, thời gian trung bình mỗi token và `PEAK RSS` của toàn bộ lần chạy. README có ví dụ sinh đúng câu trả lời cho prompt về thủ đô nước Pháp và ví dụ sinh mã Fibonacci.

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

### Chủ shop muốn thử trợ lý trả lời nhanh tại máy cá nhân

Chủ shop có thể dùng chế độ chat để hỏi nhiều câu liên tiếp, chẳng hạn yêu cầu soạn nội dung trả lời khách hoặc viết mô tả sản phẩm. Lệnh khởi động theo README:

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

Sau khi chạy, REPL nhận văn bản thông thường cùng `/help`, `/reset` và `/exit`. `--history` lưu phiên vào file JSONL để giữ lịch sử trong lần chạy đó. Đây là chạy cục bộ, nhưng tốc độ còn phụ thuộc mạnh vào RAM và ổ đĩa.

### Nhân viên văn phòng cần xử lý văn bản có tiếng Việt

Không nên nhét văn bản dài, emoji hoặc ký tự ngoài ASCII trực tiếp vào tham số shell. README khuyên ghi nội dung vào file rồi dùng `--prompt-file`:

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

`--prompt-file` đọc byte của file nguyên vẹn, tránh việc shell mã hóa lại `argv`. Cách này phù hợp khi prompt có dấu, CJK, emoji hoặc nhiều dòng. Kết quả là các token được model sinh ra theo nội dung file.

### Lập trình viên muốn sinh hoặc kiểm tra đoạn mã

Bạn có thể đưa prompt mã nguồn và yêu cầu số token cụ thể:

```bash
./bin/k3 ~/k3model --trunk ~/k3trunk --preset server \
  --tok ~/k3model --prompt "def fibonacci(n):" --gen 28 --incremental
```

Ví dụ trong README sinh tiếp phần điều kiện cơ sở và lời gọi đệ quy. `--incremental` đặc biệt quan trọng khi sinh nhiều token, vì không bật tùy chọn này engine sẽ chạy lại toàn bộ prefix ở mỗi bước, có chi phí O(T²).

### Kỹ sư muốn tái lập kết quả bằng token id

Khi cần kênh đầu vào có thể tái lập, dùng `--ids` thay vì tokenizer:

```bash
./bin/k3 ~/k3model --ids 1008,10484,318,15383,387 \
  --gen 8 --incremental
```

Cách này truyền trực tiếp danh sách token id và không tải tokenizer. Nó phù hợp cho test, benchmark hoặc so sánh kết quả giữa các máy. README gọi đây là kênh tái lập mà bộ test sử dụng.


> Công cụ này biến giới hạn RAM thành một nút điều chỉnh: máy nhỏ vẫn chạy được, còn máy lớn chỉ chạy nhanh hơn.
>
> — Ông T

### Người nghiên cứu muốn so sánh nhiều mức bộ nhớ

Có thể đổi preset giữa `laptop`, `desktop`, `workstation`, `server` và `max`. Bạn cũng có thể ghi đè ngân sách:

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

README nêu rằng cờ xuất hiện sau sẽ thắng cờ trước. Vì vậy lệnh này giữ ngân sách trunk của `server` nhưng đặt expert cache còn 40 GB. Kết quả sinh phải giữ nguyên giữa các mức ngân sách; khác biệt chính là thời gian chạy.

```note
Checkpoint có kích thước 1,56 TB và cần khoảng 1,7 TB dung lượng trống. Token Hugging Face cần được giữ kín. Hãy xác minh kết quả byte-exact trước khi dùng model; bản tải lỗi có thể sinh token sai mà không báo lỗi rõ ràng.
```

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

### Tải xong nhưng tổng byte hoặc shard không đúng

Nguyên nhân thường là tải bị gián đoạn hoặc một shard bị lỗi. Chạy lại `./scripts/download-model.sh ~/k3model` để tiếp tục tải, sau đó chờ phần xác minh báo đủ 96 shard, đúng tổng byte và tất cả kích thước riêng lẻ khớp. Không chạy suy luận khi kết quả là `FAIL`.

### Không đủ dung lượng ổ đĩa

Checkpoint 1,56 TB chưa phải toàn bộ nhu cầu; trunk đóng gói thêm khoảng 109 GB và README khuyên có khoảng 1,7 TB trống. Hãy dùng `./scripts/k3-doctor.sh` để đo dung lượng và tốc độ lưu trữ trước khi tải. Không tự ý đổi tên hoặc xóa shard vì script cần cấu trúc model đầy đủ.

### Có preset nhưng chương trình vẫn dùng nhiều RAM

Mọi preset đều giả định bạn truyền `--trunk`. Nếu bỏ `--trunk`, engine nạp toàn bộ trunk khoảng 113,5 GB vào RAM và ngân sách streaming không còn tác dụng. Kiểm tra lại đường dẫn `~/k3trunk` và bảo đảm thư mục có trunk đã tạo bởi `pack-trunk.sh`.

### Prompt có dấu hoặc emoji cho kết quả không như mong đợi

Shell có thể mã hóa lại nội dung `argv`. Hãy ghi prompt vào file rồi dùng `--prompt-file PATH`, vì README chỉ rõ cách này đọc byte nguyên vẹn. Nếu cần kiểm thử tái lập tuyệt đối, truyền token trực tiếp bằng `--ids`.

### Sinh quá chậm

Đây là đặc điểm của việc chạy model cực lớn trên CPU và đọc dữ liệu từ ổ đĩa. Dùng `--incremental` cho mọi lần sinh có độ dài, đặt trunk trên ổ nhanh và chọn preset phù hợp với RAM. Máy 8 GB có thể chạy nhưng preset thấp là đường proof-of-life, không phải trải nghiệm chat tương tác nhanh.

### Đưa nhiều hơn một kiểu prompt hoặc không đưa kiểu nào

Ngoài `--chat`, phải chọn đúng một trong `--prompt`, `--prompt-file` hoặc `--ids`. Truyền thiếu hoặc truyền nhiều hơn một tùy chọn là lỗi sử dụng với exit code 2. Kiểm tra lại `./bin/k3 --help` để xem cú pháp.

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

Nên dùng nếu bạn muốn nghiên cứu inference engine C99, tìm hiểu cách chạy model rất lớn trên CPU hoặc kiểm chứng các kỹ thuật streaming, cache và giảm bộ nhớ. Repo có test rõ ràng, có công cụ chẩn đoán, có đường chạy không cần checkpoint và hỗ trợ nhiều hệ điều hành.

Điểm mạnh lớn nhất là engine không yêu cầu GPU hay framework lớn, đồng thời giữ kết quả giống nhau giữa nhiều mức RAM. Mã nguồn có đủ các phần từ tokenizer, config reader, safetensors reader đến kernel và cache, nên phù hợp cho người muốn học cách một inference engine hoạt động từ bên trong.

Giới hạn cũng rất rõ. Checkpoint chiếm 1,56 TB, cần khoảng 1,7 TB dung lượng trống và thời gian tải có thể tính bằng giờ. Chạy trên 8 GB RAM có thể rất chậm; ngay cả máy mạnh cũng cần ổ đĩa nhanh và nhiều thời gian cho token đầu tiên. README chỉ mô tả phiên bản chat dạng văn bản, không có tools, ảnh, server hay context compaction.

Nếu bạn cần chatbot phản hồi nhanh, triển khai dịch vụ nhiều người dùng, xử lý ảnh hoặc dùng tool, repo này chưa phải lựa chọn phù hợp theo phạm vi được README mô tả. Nếu mục tiêu là học, nghiên cứu và chạy đúng Kimi K3 trên phần cứng CPU có sẵn, đây là một dự án đáng thử.

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

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

README cung cấp mã nguồn theo giấy phép Apache-2.0. Tư liệu không nêu chi phí tải checkpoint, chi phí lưu trữ hoặc chi phí sử dụng token Hugging Face, nên chưa thể khẳng định toàn bộ quá trình là miễn phí.

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

Không. Repo được thiết kế để chạy suy luận trên CPU, không dùng GPU, BLAS hay framework. CPU x86-64 cần AVX2 và FMA; máy arm64 dùng NEON.

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

Có. README nói bản Windows/x86-64 build và vượt mọi gate, thông qua MSYS2 với MinGW-w64. Các lệnh mẫu trong tài liệu dùng cú pháp shell kiểu Unix.

### Có cần tải model ngay để kiểm tra repo không?

Không. `make -j` và `make test` chạy không cần checkpoint, không cần mạng và không cần Python. Chỉ khi muốn sinh văn bản bằng Kimi K3 đầy đủ mới cần checkpoint 1,56 TB.

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

Có thể chạy theo các preset dành cho máy ít RAM, vì engine stream model từ ổ đĩa. Tuy nhiên tốc độ rất chậm; README ghi nhận khoảng 26,5 giây mỗi token trên một laptop 8 GB trong phép đo mẫu.

### Dữ liệu và prompt có an toàn không?

README mô tả engine chạy suy luận cục bộ và không yêu cầu GPU hay server. Tuy vậy, tư liệu không cung cấp chính sách bảo mật dữ liệu đầy đủ. Bạn vẫn phải giữ kín token Hugging Face và kiểm soát quyền truy cập vào checkpoint, file lịch sử và prompt.

### Repo này có hỗ trợ chat, ảnh hoặc tools không?

Repo có chế độ chat văn bản dùng XTML chính thức của Kimi K3, có lịch sử nhiều lượt. README ghi rõ phiên bản này không có tools, ảnh, server hoặc context compaction.
