# 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à bộ máy suy luận C99 cho Kimi K3, cho phép chạy mô hình 2,78 nghìn tỷ tham số trên CPU bằng cách đọc checkpoint theo luồng từ ổ đĩa. Repo không cần BLAS, framework hay GPU, nhưng cần khoảng 1,7 TB dung lượng trống và thời gian tải mô hình rất lớn. Phần kiểm thử không cần checkpoint nên người mới có thể kiểm tra trước khi tải dữ liệu.

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

kimi-k3-in-c là một bộ máy suy luận viết bằng C99 để chạy Kimi K3 2,78 nghìn tỷ tham số trên CPU. Repo không dùng BLAS, framework hay GPU. Điểm đặc biệt là mô hình được đọc từng phần từ ổ đĩa thay vì nạp toàn bộ vào RAM.

Repo phù hợp với lập trình viên muốn nghiên cứu cách một mô hình ngôn ngữ lớn hoạt động ở mức thấp, người có máy trạm nhiều RAM và người muốn thử một cách chạy LLM không phụ thuộc GPU. Nó cũng có các bài kiểm thử, mã nguồn kernel, tokenizer, trình đọc safetensors và tài liệu giải thích kiến trúc.

Đây không phải công cụ trò chuyện nhanh trên laptop thông thường. Checkpoint có kích thước khoảng 1,56 TB. Với máy 8 GB RAM, tốc độ đo được là khoảng 26,5 giây mỗi token. Giá trị lớn nhất của repo nằm ở tính minh bạch và khả năng chạy cùng một mô hình trên nhiều mức RAM, với đầu ra byte-identical; nhiều RAM hơn chỉ làm chương trình nhanh hơn.

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

Repo cung cấp chương trình `bin/k3` để nhận prompt, token ID hoặc tệp văn bản rồi sinh token tiếp theo. Mã nguồn dùng C99 và các kernel CPU chuyên dụng. Trên x86-64, máy cần AVX2 và FMA; trên arm64, repo có cổng NEON.

Bạn không cần GPU, CUDA, BLAS hay một framework machine learning lớn. Điều này hữu ích khi bạn muốn nghiên cứu inference, tối ưu bộ nhớ hoặc chạy thử trên phần cứng không có card đồ họa.

### Chạy mô hình lớn hơn dung lượng RAM

Checkpoint Kimi K3 có khoảng 1,56 TB nhưng chương trình có thể stream phần dense trunk từ ổ đĩa. Bộ trunk được đóng gói thành một tệp khoảng 109 GB, rồi các lớp được đọc theo offset đã biết.

Với preset laptop, desktop, workstation, server hoặc max, bạn chọn ngân sách bộ nhớ khác nhau. Mô hình và kết quả không đổi giữa các mức RAM. Máy có 8 GB vẫn có thể chạy theo đường ultra-low-memory, nhưng đây là chế độ chứng minh khả năng chứ không phù hợp để tương tác nhanh.

### Giữ cache và trạng thái giữa các token

Tùy chọn `--incremental` giữ KV cache và trạng thái KDA giữa các token. Nhờ vậy, chương trình không phải chạy lại toàn bộ prompt cho từng token mới. README cho biết đường chạy incremental và đường chạy tính lại đều được kiểm tra để cho cùng token; khác biệt chính là tốc độ.

### Hỗ trợ chat theo XTML chính thức

Tùy chọn `--chat` dùng các segment XTML và control token của Kimi K3. Repo có REPL nhận văn bản thông thường cùng các lệnh `/help`, `/reset` và `/exit`. Có thể lưu lịch sử bằng `--history`.

Phiên bản trong README chỉ hỗ trợ văn bản. Nó chưa có tools, hình ảnh, server hoặc context compaction. Khi chạy chat, chương trình in cả bản ghi canonical, gồm các phần `<think>...</think>` và `<response>...</response>`.

### Kiểm tra từ kernel đến toàn bộ engine

`make test` chạy các gate cho teacher forcing, greedy decode và incremental decode. Các fixture trong repo đối chiếu với một tham chiếu PyTorch trên mô hình 13 lớp có cùng tensor graph.

Repo cũng có công cụ mô phỏng cache chuyên gia và tài liệu đo lường. Bạn có thể kiểm tra engine trước khi tải checkpoint đầy đủ.

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

- Hệ điều hành tham chiếu là Linux x86-64. macOS/arm64 và Windows/x86-64 cũng được README ghi là build và vượt qua các gate. Windows dùng cổng MSYS2 MinGW-w64.
- CPU x86-64 cần AVX2 và FMA. AVX-512 không bắt buộc. Máy arm64 dùng NEON.
- RAM tối thiểu theo tài liệu là 8 GB. Mọi preset đều chạy được, nhưng nhiều RAM hơn sẽ nhanh hơn.
- Cần khoảng 1,7 TB dung lượng trống: 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.
- Cần 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 dùng cho công cụ tải, đóng gói và phân tích. `make test` không cần Python.
- Cần token Hugging Face để tải checkpoint. README chỉ rõ token cần quyền đọc.
- Không cần GPU, BLAS hoặc framework machine learning.

Tokenizer và config reader là C99 portable. Không có checkpoint, bạn vẫn có thể clone, build và chạy toàn bộ phần kiểm thử không trọng số.

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

```steps
- Clone repo | tải mã nguồn và đi vào thư mục dự án
- Kiểm tra máy | đo toolchain, RAM và tốc độ lưu trữ
- Build và test | biên dịch engine rồi xác minh các gate
- Tải checkpoint | lấy 1,56 TB shard từ Hugging Face
- Đóng gói trunk | tạo packed trunk khoảng 109 GB
- Chạy mô hình | chọn preset, tokenizer và prompt
```

### Clone repo

Mở Terminal trên Linux, hoặc terminal MSYS2 MinGW-w64 trên Windows. Chạy:

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

Lệnh đầu tiên tải mã nguồn. Lệnh thứ hai đưa terminal vào đúng thư mục repo. Người mới thường chạy `make` ở thư mục khác nên hệ thống không tìm thấy `Makefile`.

### Kiểm tra máy

Chạy script kiểm tra có sẵn:

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

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

### Build bằng Make hoặc CMake

Cách dùng Make:

```bash
make -j
```

Lệnh này biên dịch engine. README cho biết quá trình chỉ cần compiler C99, `libm` và OpenMP.

Nếu muốn dùng CMake:

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

Sau khi build, chạy test trước khi tải checkpoint:

```bash
make test
```

Bước này không cần mạng, checkpoint hay Python. Nó giúp phát hiện lỗi compiler hoặc môi trường trước khi bạn dành thời gian tải dữ liệu rất lớn.

### Đọc kết quả kiểm thử

Kết quả thành công kết thúc 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 chưa có đúng kết luận này, chưa nên tải checkpoint. Hãy đọc lỗi compiler hoặc test trước.

Một kiểm tra khác dùng Python và numpy:

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

Lệnh này phát lại một trace cache đã có trong repo và in bảng dung lượng cache. Đây không phải bước bắt buộc để chạy mô hình đầy đủ.

### Tải checkpoint

Trước hết, tạo token có quyền đọc trên Hugging Face rồi đặt token vào biến môi trường:

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

Không chèn token trực tiếp vào bài viết công khai, script chia sẻ hoặc log. Lệnh tải có thể chạy lại để tiếp tục phần bị gián đoạn.

Checkpoint khoảng 1,56 TB nên có thể mất nhiều giờ. Script kiểm tra số shard, tổng số byte và kích thước từng shard. 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
```

Nếu thấy `FAIL`, hãy dừng lại và kiểm tra shard hỏng. README cảnh báo tải chưa hoàn chỉnh 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, 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 packed trunk khoảng 109 GB, trong đó 93 lớp dense có offset đã biết để engine đọc trong một lần gọi. Nên đặt `~/k3trunk` trên ổ nhanh nhất.

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

Lệnh 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` bật cơ chế streaming. `--preset workstation` chọn ngân sách bộ nhớ. `--tok ~/k3model` trỏ tới tokenizer trong thư mục model. `--prompt` là văn bản đầu vào, `--gen 8` yêu cầu sinh 8 token và `--incremental` giữ trạng thái để tránh tính lại toàn bộ prompt.

Các preset gồm `laptop`, `desktop`, `workstation`, `server` và `max`. Nếu dùng preset mà không có `--trunk`, engine vẫn nạp khoảng 113,5 GB trunk vào RAM; README nói preset khi đó không có tác dụng như mong đợi.

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

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

Mức đầu tiên là `make test` với dòng `VERDICT: ENGINE MATCHES THE REFERENCE EXACTLY`. Mức này chứng minh engine, kernel, cache streaming, safetensors reader, config reader và tokenizer hoạt động trên bộ fixture, nhưng chưa chứng minh máy đã có checkpoint đầy đủ.

Mức thứ hai là kết quả xác minh tải model với `96` shard, tổng `1560936091448` byte và dòng `RESULT : byte-exact match`. Nếu không đạt, không nên chạy suy luận.

Mức thứ ba là chạy prompt. Với prompt thủ công, chương trình in văn bản sinh ra, số token, thời gian trung bình mỗi token và `PEAK RSS`. Một phép đo trong README chạy 8 token trên máy 8 GB với kết quả `8.24 GB`; máy nhiều RAM cho thời gian thấp hơn nhưng cùng đầu ra.

Bạn cũng có thể kiểm tra các lệnh không cần model:

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

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

### Lập trình viên nghiên cứu inference trên CPU

Một dev muốn xem một LLM lớn được triển khai ở mức C có thể bắt đầu bằng test không trọng số, sau đó chạy prompt ngắn:

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

README cho thấy đầu ra có thể tiếp tục thành hàm Fibonacci Python. Kết quả phù hợp để quan sát token sinh ra và thời gian mỗi token, không phù hợp để dùng như IDE tương tác nhanh.

### Nhân viên văn phòng cần thử câu hỏi văn bản

Một người dùng có workstation đủ dung lượng có thể mở chat mode:

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

Sau đó nhập câu hỏi tự nhiên trong REPL. `/help` hiển thị trợ giúp, `/reset` xóa phiên hiện tại và `/exit` thoát. `--history` ghi lịch sử vào tệp để giữ lại bản ghi phiên.

### Chủ shop hoặc người dùng tiếng Việt cần giữ nguyên ký tự

Khi prompt có tiếng Việt, emoji, chữ Hán hoặc ký tự có dấu, nên đặt nội dung vào tệp 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
```

README giải thích rằng cách này đọc byte của tệp nguyên vẹn, tránh việc shell mã hóa lại `argv`. Bạn có thể thay nội dung tệp bằng yêu cầu thực tế trước khi chạy.

### Dev cần tái lập chính xác bằng token ID

Khi không muốn phụ thuộc tokenizer, truyền thẳng danh sách ID:

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

Cách này không tải tokenizer. Nó phù hợp khi tái hiện một test hoặc so sánh output giữa các máy. README gọi đây là kênh tái lập mà các test sử dụng.

> Khi phần cứng không có GPU, bạn vẫn có thể nghiên cứu một mô hình cực lớn nếu chấp nhận đánh đổi tốc độ lấy dung lượng lưu trữ.
>
> — Ông T

```note
Checkpoint có kích thước khoảng 1,56 TB và cần khoảng 1,7 TB dung lượng trống cùng packed trunk khoảng 109 GB. Hãy kiểm tra quyền truy cập token Hugging Face, dung lượng ổ đĩa và kết quả xác minh từng shard trước khi chạy model.
```

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

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

Checkpoint và packed trunk cần nhiều dung lượng hơn mã nguồn rất nhiều. Kiểm tra lại ổ đĩa trước khi chạy `k3-doctor.sh`. Không đặt model vào ổ tạm hoặc ổ mạng chậm nếu mục tiêu là đo tốc độ.

### Tải thiếu hoặc shard bị hỏng

Một bản tải dở có thể không báo lỗi ngay nhưng sinh token sai. Chạy lại script tải để tiếp tục, rồi chờ phần xác minh báo đủ 96 shard, đúng tổng byte và từng shard khớp. Nếu có `FAIL`, không dùng checkpoint đó cho benchmark.

### Dùng preset nhưng quên `--trunk`

Preset chỉ có ý nghĩa khi packed trunk được bật. Hãy kiểm tra lệnh có cả `--trunk ~/k3trunk`. Nếu bỏ tùy chọn này, engine có thể nạp toàn bộ khoảng 113,5 GB trunk vào RAM.

### Prompt không chạy vì thiếu tokenizer

`--prompt` và `--prompt-file` cần `--tok`. Hãy trỏ `--tok` tới thư mục chứa `tiktoken.model` và `tokenizer_config.json`, thường là `~/k3model`. Nếu không muốn dùng tokenizer, truyền `--ids`.

### Chạy quá chậm hoặc dùng lại toàn bộ prompt

Luôn thêm `--incremental` cho generation dài. Không có tùy chọn này, mỗi bước sẽ tính lại toàn bộ prefix và có chi phí O(T²). Với máy ít RAM, có thể chọn preset thấp hơn hoặc `ultra`, nhưng README nói `ultra` chủ yếu là đường proof-of-life và không dành cho tốc độ tương tác.

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

Bạn nên dùng repo này nếu muốn nghiên cứu inference C99, tìm hiểu cách stream checkpoint cực lớn, kiểm thử kernel hoặc chạy thử Kimi K3 trên CPU mà không dùng GPU. Bộ test không cần checkpoint giúp bạn kiểm tra mã nguồn trước. Apache-2.0 cũng là giấy phép rõ ràng cho việc nghiên cứu và phát triển tiếp theo theo điều kiện của giấy phép.

Điểm mạnh là mã nguồn portable, không phụ thuộc BLAS hay framework, có kiểm thử nhiều tầng và cho cùng output ở nhiều mức RAM. README cũng công bố cách đo bộ nhớ, thời gian và cấu trúc dữ liệu, nên repo phù hợp với người muốn hiểu sâu thay vì chỉ gọi một API.

Giới hạn rất lớn là dung lượng checkpoint 1,56 TB, yêu cầu ổ đĩa khoảng 1,7 TB và tốc độ chậm trên máy ít RAM. Đây không phải lựa chọn thực tế cho laptop văn phòng nếu bạn cần trả lời tức thời. Chế độ chat chỉ hỗ trợ văn bản, chưa có tools, hình ảnh, server hoặc context compaction theo tài liệu được cung cấp.

Nếu mục tiêu của bạn là chatbot nhanh, triển khai dịch vụ cho nhiều người hoặc làm việc với GPU, nên cân nhắc một runtime và mô hình được thiết kế cho các yêu cầu đó. Nếu mục tiêu là hiểu cách một mô hình rất lớn có thể chạy trên phần cứng phổ thông bằng streaming, cache và C99, kimi-k3-in-c là một repo đáng thử.

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

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

Không. README ghi rõ repo chạy inference bằng CPU, không dùng GPU, BLAS hay framework. CPU x86-64 cần AVX2 và FMA; arm64 dùng NEON.

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

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

### Cần bao nhiêu dung lượng và RAM?

Checkpoint cần khoảng 1,56 TB và tổng dung lượng trống nên khoảng 1,7 TB, chưa kể dữ liệu cần thiết khác. RAM tối thiểu được ghi là 8 GB; nhiều RAM hơn giúp chạy nhanh hơn nhưng không đổi output.

### Có thể kiểm tra repo mà chưa tải checkpoint không?

Có. `make -j` và `make test` chạy được không cần checkpoint, mạng hoặc Python. Test kiểm tra kernel, cache, tokenizer, config reader và đường suy luận trên fixture trong repo.

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

Không cần Python cho `make test`. README yêu cầu Python 3.9 trở lên cho các công cụ tải, đóng gói và phân tích; một công cụ mô phỏng cache cũng cần numpy.

### Repo có chạy chat nhiều lượt không?

Có. Tùy chọn `--chat` mở REPL dùng format XTML chính thức, hỗ trợ `/help`, `/reset`, `/exit` và có thể ghi lịch sử bằng `--history`. Tài liệu được cung cấp nói phiên bản này chỉ có văn bản, chưa có tools, hình ảnh, server hoặc context compaction.

### Dữ liệu có an toàn và miễn phí không?

Tài liệu được cung cấp không nêu chính sách dữ liệu, chi phí tải checkpoint hoặc điều khoản dịch vụ của nơi lưu model. README chỉ hướng dẫn dùng token Hugging Face để tải và nhắc token phải được đọc từ biến môi trường, không echo ra màn hình.
