TRiP: transformer engine viết từ đầu trong C — 18 tháng nightside hand-coding

Giới thiệu

TRiP — TRansformer in Progress — là một engine all-in-one viết bằng C cho model AI Transformer: inference, training, tạo tokenizer, chat, và vision.

Viết từ đầu trong 18 tháng (từ March 2024 đến August 2025) trong giờ lunch break và đêm cuối tuần, TRiP tồn tại đơn giản vì tác giả Carlo Valenti muốn thực sự hiểu nội tại transformer — từ matrix multiplication trở lên.

Mục đích của TRiP là thuần educational, cho tác giả và cho bất kỳ ai muốn học về transformer. Hỗ trợ Gemma 1, Llama 2, PaliGemma và GPT-2, với full inference và training. Không nhằm theo kịp release model mới nhất, và không cố cạnh tranh với llama.cpp.

LƯU Ý từ tác giả: phần AI-generated trong code:

• json parser (có một số fix)
• safetensors checkpoint save function
• toàn bộ jpeg-X11 management functions (tôi không có hứng thú develop chúng)
• final file split (ban đầu tôi viết tất cả thành main.c)
• một số bản chỉnh comment trước khi commit
• README này, phần lớn

Phần còn lại đều hand-coded. Và sẽ vô nghĩa nếu khác — vì mục đích cả dự án là đạt sự hiểu full-stack về transformer internals.

Tính năng chính

• Architecture: Llama2, Gemma 1.0/1.1, PaliGemma 1 (vision+language), GPT-2
• Checkpoint format: SafeTensors (HuggingFace), Karpathy’s llama2.c và gpt2 format
• Weight type: bf16, float16, float32
• Training: full backpropagation với AdamW, cosine annealing LR, gradient clipping
• Tokenizer: BPE (SentencePiece-compatible), với khả năng tạo vocabulary từ scratch
• Inference: greedy, top-k, và nucleus (top-p) sampling
• Chat: interactive chat với Llama, Gemma và TinyLlama chat template
• Vision: multimodal inference với PaliGemma (JPEG input, X11 display)
• Memory: RAM-optimized mode qua mmap cho model lớn trên hardware hạn chế

Build

Dependency

gcc (khuyến nghị: version 13 trở lên, để có support bfloat16; với OpenMP support)
libjpeg-dev (hoặc libjpeg62-turbo-dev)
libx11-dev

WARNING: ĐỪNG kỳ vọng performance cao hơn với bfloat16 hoặc float16 trên CPU; CPU hiện tại không được optimize cho floating point ở format đó, và float32 luôn perform tốt nhất. Điều đó cũng làm tác giả ngạc nhiên.

Trên Debian:

sudo apt install build-essential libomp-dev libjpeg62-turbo-dev libx11-dev

Trên Ubuntu:

sudo apt install build-essential libomp-dev libjpeg-dev libx11-dev

Cách sử dụng

Chat với model Gemma

Download model Gemma-2B-IT từ HuggingFace (safetensors format), sau đó:

./trip --chat \
    --checkpoint gemma-2b-it/model.safetensors \
    --tokenizer gemma-2b-it/tokenizer.json \
    --chat_scheme GEMMA

Chạy inference trên prompt

./trip --decode \
    --input_text "The capital of Italy is" \
    --checkpoint gemma-2b-it/model.safetensors \
    --tokenizer gemma-2b-it/tokenizer.json

Train model

./trip --train \
    --checkpoint my_model/model.safetensors \
    --tokenizer my_model/tokenizer.json \
    --train_data my_dataset.txt \
    --train_config training_args.json

Vision (PaliGemma)

./trip --vision photo.jpg \
    --checkpoint paligemma/model.safetensors \
    --tokenizer paligemma/tokenizer.json \
    --input_text "Describe this image"

Build tokenizer vocabulary từ scratch

./trip --build_vocab corpus.txt --vocab_size 32000 --tokenizer my_tokenizer.json

Cấu trúc file

TRiP tổ chức thành 7 file. Mở trip.h cho map đầy đủ.

Cách hoạt động (cho ai tò mò)

TRiP implement transformer từ first principles trong C. Không PyTorch, không TensorFlow, không ONNX — chỉ linear algebra trên array của float.

Residual stream là concept trung tâm: một vector chảy qua model như data trên bus. Mỗi layer đọc từ nó, xử lý qua attention và feed-forward network, và ghi lại vào nó. Forward pass đi qua các layer từ trên xuống dưới; backward pass đi từ dưới lên, tính gradient qua chain rule.

Mỗi math operation (math.c) được implement như một forward+backward pair: bạn có thể đọc rmsnorm() và ngay bên dưới là rmsnorm_backward(), và thấy chính xác gradient chảy qua cùng computation theo chiều ngược.

Tác giả đặt nhiều comment trong code, vừa làm reminder cho chính mình, vừa biến TRiP về cơ bản thành một quyển sách giáo khoa annotated về transformer.

Để hiểu sâu hơn về backpropagation, xem bài giảng của Andrej Karpathy; TRiP sẽ không bao giờ tồn tại nếu không có công trình của ông ấy.

License

CC BY-NC 4.0 — free to use, study, modify, share cho mục đích phi thương mại, có attribution. Cho commercial licensing, liên hệ tác giả.