# 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 portable để chạy suy luận Kimi K3 trên CPU, với checkpoint 1,56 TB và mức RAM tối thiểu khoảng 8 GB. Repo không dùng BLAS, framework hay GPU; phần khó nhất là chuẩn bị đủ dung lượng lưu trữ và chờ tải model.

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

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

Repo phù hợp với người muốn nghiên cứu cách một LLM lớn được triển khai từ đầu, lập trình viên cần một engine C nhỏ và người có phần cứng phổ thông nhưng muốn thử chạy Kimi K3. Điểm đáng giá nhất là đầu ra được thiết kế byte-identical giữa 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.

Tuy vậy, đây không phải công cụ chat nhẹ để cài trong vài phút. Checkpoint chiếm khoảng 1,56 TB, cần thêm khoảng 109 GB cho trunk đã đóng gói và tốc độ sinh token khá chậm trên máy ít RAM. Bạn nên xem đây là một dự án nghiên cứu, kiểm chứng và khám phá kỹ thuật inference hơn là một chatbot dùng hằng ngày.

```repo
- repo | FareedKhan-dev/kimi-k3-in-c
- kind | CLI
- desc | Chạy suy luận Kimi K3 2,78 nghìn tỷ tham số bằng C99 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 chỉ bằng CPU

Engine chạy suy luận Kimi K3 trên CPU, không cần GPU, BLAS hoặc framework. Trên x86-64, repo dùng AVX2 và FMA; trên arm64 dùng NEON. AVX-512 không bắt buộc.

Điều này hữu ích nếu bạn không có card đồ họa đủ lớn hoặc muốn hiểu rõ một mô hình lớn được đọc, giải mã và tính toán như thế nào ở mức C99.

### Giảm yêu cầu RAM bằng cách streaming

Checkpoint đầy đủ có kích thước khoảng 1,56 TB, nhưng engine không cần nạp toàn bộ vào RAM. Phần trunk được đóng gói thành một file khoảng 109 GB. Khi chạy, engine giữ một phần trong bộ nhớ và đọc phần còn lại từ ổ đĩa.

Preset `laptop`, `desktop`, `workstation`, `server` và `max` giúp chọn ngân sách bộ nhớ. Có thêm preset `ultra` cho máy khoảng 8 GB RAM. Preset này thiên về chứng minh khả năng chạy, không phải tốc độ tương tác.

### Có cache cho routed experts

Các expert được lưu trong cache LRU theo ngân sách bạn chọn. Phần expert routed khoảng 1,45 TB không nằm thường trực trong RAM; engine đọc và nhân trực tiếp từ dạng packed 4-bit.

Bạn có thể điều chỉnh `--cache-gb` hoặc chọn preset. Tăng cache thường giúp giảm chờ đọc lại dữ liệu, nhưng không làm thay đổi kết quả sinh ra.

### Hỗ trợ prompt dạng văn bản, file hoặc token ID

Bạn có thể truyền prompt bằng `--prompt`, đọc nguyên byte từ file bằng `--prompt-file`, hoặc đưa thẳng danh sách token ID bằng `--ids`. Cách đọc từ file phù hợp hơn với tiếng Việt, ký tự có dấu, emoji và văn bản không phải ASCII.

### Có chế độ sinh tăng dần và chat

`--incremental` giữ KV cache và trạng thái recurrent giữa các token. Nếu không dùng tùy chọn này, engine phải chạy lại toàn bộ prefix ở mỗi bước, khiến quá trình sinh dài chậm hơn nhiều.

K3 cũng có chế độ `--chat` dùng các segment XTML chính thức của Kimi K3. REPL hỗ trợ văn bản thông thường cùng `/help`, `/reset` và `/exit`, và có thể lưu lịch sử phiên bằng `--history`.

Theo README, phiên bản chat này chỉ xử lý văn bản. Chưa có tools, hình ảnh, server hoặc context compaction.

### Có bộ kiểm thử và oracle để đối chiếu

Repo cung cấp test không cần checkpoint hay mạng. Bộ test kiểm tra kernel, streaming cache, safetensors reader, config reader, tokenizer và đường chạy end-to-end trên model 13 layer.

Kết quả mong đợi là các gate đều khớp chính xác với reference. Đây là điểm quan trọng nếu bạn muốn dùng repo để học hoặc sửa engine mà vẫn có cách kiểm chứng.

Hiện repo có khoảng 11.951 sao và 1.848 fork. Repo dùng giấy phép Apache-2.0, ngôn ngữ chính là C.

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

- Hệ điều hành tham chiếu là Linux x86-64. README cũng nói bản macOS/arm64 và Windows/x86-64 build và vượt qua các gate. Trên Windows, phần I/O được port qua MSYS2 MinGW-w64.
- CPU x86-64 cần AVX2 và FMA. CPU arm64 cần NEON. `make portable` nhắm tới AVX2 phổ thông trên x86-64.
- RAM tối thiểu khoảng 8 GB. Mọi preset đều có thể chạy, nhưng nhiều RAM hơn sẽ nhanh hơn.
- Khoảng 1,7 TB dung lượng trống. Trong đó checkpoint khoảng 1,56 TB và packed trunk khoảng 109 GB. Nên đặt dữ liệu trên ổ đĩa cục bộ nhanh.
- GCC từ 9 trở lên hoặc Clang từ 10 trở lên.
- GNU make hoặc CMake.
- Python 3.9 trở lên cho công cụ tải model, đóng gói và phân tích. `make test` không cần Python.
- Một token Hugging Face để tải checkpoint. README không nêu gói trả phí hay mức phí tải model.

Không cần GPU. Không cần BLAS hoặc framework deep learning. Nếu chưa có checkpoint, bạn vẫn có thể clone, build và chạy toàn bộ test không trọng số.

```note
Checkpoint rất lớn. Hãy kiểm tra dung lượng ổ đĩa, tốc độ đọc và quyền truy cập trước khi bắt đầu tải. Không đưa HF_TOKEN vào log hoặc chia sẻ token này cho người khác.
```

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

```steps
- Clone và build | Tải mã nguồn rồi biên dịch engine C
- Kiểm tra máy | Đo RAM, ổ đĩa và toolchain bằng k3-doctor
- Chạy test | Xác nhận engine khớp reference trước khi tải model
- Tải checkpoint | Lấy 1,56 TB model và kiểm tra từng shard
- Đóng gói trunk | Tạo trunk.bin khoảng 109 GB để bật streaming
- Chạy suy luận | Chọn preset, tokenizer và prompt để sinh text
```

### Clone và build

Mở terminal tại thư mục bạn muốn lưu dự án. Hai lệnh sau là đường đi cơ bản được README sử dụng:

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

Sau đó build bằng GNU make:

```bash
make -j
```

`make -j` biên dịch engine và các thành phần C cần thiết. README nói bước này thường chỉ mất vài giây. Nếu máy dùng CMake, có thể dùng chuỗi lệnh sau:

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

Người mới thường mở terminal ở nhầm thư mục. Hãy chắc chắn lệnh `cd` đưa bạn vào thư mục chứa `Makefile`, `CMakeLists.txt` và thư mục `src`.

### Kiểm tra máy

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

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

Công cụ kiểm tra toolchain, ước lượng preset phù hợp với RAM, đo dung lượng lưu trữ và in lệnh tiếp theo nên chạy. README nói nó có thể mất khoảng một phút vì đo ổ đĩa theo cách engine đọc dữ liệu.

Nếu máy không thể chạy model, script sẽ kết thúc với mã lỗi khác 0. Trên Windows, README mô tả việc build và chạy qua MSYS2 MinGW-w64; phần lệnh shell ở đây dùng cú pháp Unix nên bạn cần chạy trong môi trường tương ứng.

### Chạy test trước khi tải model

```bash
make test
```

Bước này không cần checkpoint, không cần mạng và không cần Python. Nó giúp bạn biết engine đã build đúng trước khi dành nhiều thời gian tải dữ liệu.

Kết quả thành công kết thúc bằng các dòng tương tự:

```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 muốn chạy kiểm tra cache có dùng Python và numpy, README đưa lệnh:

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

### Tải checkpoint

Bạn cần lấy token từ Hugging Face rồi đặt token trong biến môi trường. README đưa ví dụ sau:

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

Script có thể tiếp tục khi bị gián đoạn. Checkpoint gồm 96 shard và có tổng kích thước chính xác được kiểm tra sau khi tải. Kết quả thành công 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
```

Không nên bỏ qua dòng `RESULT`. README cảnh báo tải thiếu hoặc shard sai có thể không báo lỗi rõ ràng nhưng sinh token sai. Kiểm tra từng shard giúp chỉ phải tải lại file lỗi thay vì tải lại toàn bộ checkpoint.

### Đóng gói trunk

Sau khi checkpoint đã được xác minh, chạy:

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

Bước này mất khoảng bốn phút theo README. Script tạo `trunk.bin` và `trunk.json`, tổng khoảng 109 GB, trong đó 93 dense layer được sắp xếp để engine biết vị trí từng layer và đọc bằng một lần gọi.

Nên đặt `~/k3trunk` trên ổ đĩa nhanh nhất. Đây là bước biến yêu cầu bộ nhớ thành một ngân sách có thể điều chỉnh. Nếu bỏ qua trunk, engine phải nạp toàn bộ trunk khoảng 113,5 GB vào RAM và các preset streaming không còn phát huy tác dụng.

### Chạy suy luận đầu tiên

Lệnh mẫu trong README:

```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 và tokenizer. `--trunk` trỏ tới thư mục đã đóng gói. `--preset workstation` chọn ngân sách. `--tok ~/k3model` cho engine biết nơi có `tiktoken.model` và `tokenizer_config.json`. `--prompt` là văn bản đầu vào, `--gen 8` yêu cầu sinh 8 token, còn `--incremental` bật trạng thái sinh tăng dần.

Kết quả đầu tiên có thể chậm vì engine phải đọc các layer cần thiết từ ổ đĩa. README ghi rõ token đầu tiên của mỗi lần chạy tốn nhiều thời gian hơn; chi phí này trả một lần mỗi run, không phải mỗi token.

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

Có ba mức kiểm tra. Mức đầu tiên là `make test` và phải hiện `VERDICT: ENGINE MATCHES THE REFERENCE EXACTLY`. Mức thứ hai là script tải model phải báo 96 shard, tổng byte đúng và `RESULT : byte-exact match`.

Mức cuối là chạy lệnh suy luận. Với prompt `The capital of France is`, README đưa một kết quả sinh có chứa `Paris`. Kết quả chính xác về thời gian sẽ phụ thuộc máy, RAM và ổ đĩa. README ghi nhận cùng một prompt có thể cho output byte-identical giữa máy 8 GB và máy 128 GB+, nhưng tốc độ mỗi token khác nhau.

Bạn cũng có thể kiểm tra các tùy chọn không cần model:

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

Ba lệnh này giúp xác nhận binary chạy được và xem các preset mà binary hiện có.

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

### Chủ shop muốn thử câu trả lời sản phẩm trên máy không có GPU

Một chủ shop có máy Linux 8 GB RAM có thể dùng preset `ultra` để kiểm tra khả năng chạy Kimi K3. Đây là đường chạy chứng minh khả năng, không phù hợp để trả lời khách theo thời gian thực.

```bash
./bin/k3 ~/k3model --trunk ~/k3trunk --preset ultra \
  --tok ~/k3model --prompt "Write a short product description for a reusable water bottle" \
  --gen 32 --incremental
```

Kết quả là phần text được sinh từ model. Với máy ít RAM, cần chấp nhận thời gian chờ dài và phụ thuộc mạnh vào tốc độ ổ đĩa.

### Nhân viên văn phòng cần xử lý văn bản có dấu

Nếu prompt có tiếng Việt, emoji hoặc ký tự ngoài ASCII, nên ghi prompt vào file rồi dùng `--prompt-file`. README nói cách này đọc byte của file nguyên vẹn, tránh shell mã hóa lại `argv`.

```bash
printf 'Viết ba ý chính của văn bản này' > /tmp/p.txt
./bin/k3 ~/k3model --tok ~/k3model --prompt-file /tmp/p.txt \
  --gen 24 --incremental
```

Kết quả là các token được sinh tiếp từ nội dung trong file. README không mô tả một workflow riêng để nạp tài liệu dài hoặc tự động lưu câu trả lời, nên bạn chỉ nên xem đây là cách thử prompt trực tiếp.

### Lập trình viên muốn sinh code dạng tiếp nối

Với một prompt code, engine có thể chạy raw continuation bằng `--prompt`. README đưa ví dụ:

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

Kết quả mẫu tiếp tục hàm Fibonacci bằng các dòng Python. Đây là sinh tiếp văn bản, không phải một trình biên dịch hay công cụ kiểm thử code; phần code nhận được vẫn cần được bạn đọc và kiểm tra.

### Người nghiên cứu muốn chạy chat nhiều lượt

K3 có thể dùng chế độ chat XTML chính thức và lưu lịch sử phiên:

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

Trong REPL, bạn nhập văn bản thông thường. `/help` xem trợ giúp, `/reset` đặt lại phiên và `/exit` thoát. Khi có `--history`, engine ghi lịch sử vào file được chỉ định.

README nói REPL in bản ghi canonical, gồm cả `<think>…</think>` và `<response>…</response>`. Chế độ này chỉ dành cho text; không nên kỳ vọng gọi tool, xử lý ảnh hoặc chạy như server.

> Điều đáng giá nhất là cùng một model có thể chạy trên nhiều mức RAM và vẫn cho output byte-identical; khác biệt lớn nhất nằm ở thời gian chờ.
>
> — Ông T

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

### Hết dung lượng khi tải hoặc đóng gói

Checkpoint cần khoảng 1,56 TB và trunk thêm khoảng 109 GB. Hãy chạy `./scripts/k3-doctor.sh` trước, kiểm tra ổ đĩa cục bộ và chừa thêm khoảng trống cho quá trình tải. Không xóa shard đang có nếu chưa xác định rõ file nào lỗi.

### Checkpoint tải xong nhưng sinh token sai

Tổng dung lượng đúng chưa chắc mọi shard đều đúng. Hãy đọc phần xác minh của `download-model.sh`; kết quả cần có 96 shard khớp riêng lẻ và `RESULT : byte-exact match`. Nếu có `FAIL`, dừng chạy model và chạy lại script để tiếp tục tải phần hỏng.

### Máy chạy quá chậm

Máy 8 GB sẽ phải đọc nhiều dữ liệu từ ổ đĩa ở mỗi bước. Hãy đặt trunk trên ổ nhanh, chọn preset phù hợp và luôn dùng `--incremental` cho generation dài. Nhiều RAM hơn giúp tăng tốc, nhưng README không hứa hẹn tốc độ tương tác trên máy ít RAM.

### Dùng preset nhưng RAM vẫn tăng cao

`--preset` chỉ hữu ích khi có `--trunk`. Nếu bỏ `--trunk`, engine nạp toàn bộ trunk khoảng 113,5 GB resident bất kể ngân sách đã chọn. Kiểm tra lại đường dẫn `--trunk` và thư mục `~/k3trunk` sau bước đóng gói.

### Prompt tiếng Việt hoặc emoji bị sai

Không nên truyền văn bản phức tạp trực tiếp qua `argv`. Ghi nội dung vào file rồi dùng `--prompt-file`, vì README khuyến nghị file cho CJK, emoji và accent. Nếu dùng `--prompt`, cần đảm bảo terminal truyền đúng encoding.

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

Nên dùng nếu bạn muốn học sâu về inference engine, C99, tokenizer, safetensors, cache, attention và streaming model. Repo có test chi tiết, kết quả reference rõ ràng, không phụ thuộc GPU và cho thấy một model cực lớn có thể chạy với ngân sách RAM thấp hơn rất nhiều so với kích thước checkpoint.

Giới hạn lớn nhất là dung lượng lưu trữ, thời gian tải và tốc độ. Checkpoint 1,56 TB không phù hợp với laptop thông thường nếu ổ đĩa nhỏ. Máy 8 GB có thể chạy nhưng không phải trải nghiệm chat nhanh. Repo cũng không phải ứng dụng server, không có tools hay hình ảnh trong chế độ chat theo thông tin được cung cấp.

Nếu mục tiêu của bạn là dùng chatbot hằng ngày, cần phản hồi nhanh hoặc cần một model có thể chạy gọn trên máy cá nhân, nên cân nhắc công cụ inference nhỏ hơn. Nếu mục tiêu là hiểu cách triển khai Kimi K3 từ đầu và chấp nhận chi phí phần cứng, kimi-k3-in-c là một dự án rất đáng thử. Apache-2.0 cũng là một điểm thuận lợi cho việc nghiên cứu và tích hợp theo điều kiện của giấy phép.

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

### kimi-k3-in-c có cần GPU không?

Không. README mô tả engine chạy trên CPU, không dùng GPU, BLAS hoặc framework. x86-64 cần AVX2 và FMA; arm64 cần NEON.

### Có thể chạy trên Windows không?

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

### Cần bao nhiêu dung lượng ổ đĩa?

Khoảng 1,7 TB trống. Checkpoint chiếm khoảng 1,56 TB và packed trunk khoảng 109 GB, nên đặt trunk trên ổ đĩa nhanh.

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

Có, README nói RAM từ 8 GB và mọi preset đều chạy được. Preset `ultra` dành cho máy 8 GB-class nhưng là proof-of-life path, không phải preset tương tác nhanh.

### Có cần Python để cài và chạy không?

Không cần Python cho `make test`. Python 3.9 trở lên được dùng cho công cụ tải, đóng gói và phân tích; README cũng nêu một bài kiểm tra cache cần Python và numpy.

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

README yêu cầu đặt token trong biến môi trường và ghi rõ không echo token. Repo không cung cấp thêm thông tin về chính sách dữ liệu hoặc bảo mật ngoài hướng dẫn này.

### Có miễn phí không?

README được cung cấp theo giấy phép Apache-2.0 và không nêu phí sử dụng. Tuy nhiên, việc tải checkpoint 1,56 TB và lưu trữ, vận hành trên phần cứng của bạn vẫn có thể phát sinh chi phí.
