yzma: Binding Go cho LLM Local qua llama.cpp
yzma là thư viện Go gọi thẳng llama.cpp trong cùng tiến trình để chạy suy luận LLM và VLM cục bộ, dùng purego và ffi thay vì CGo. Nên chọn yzma nếu bạn muốn đóng gói một binary Go độc lập, chạy suy luận on-device với tăng tốc GPU mà không cần toolchain C. Nên bỏ qua nếu bạn muốn chạy model server riêng qua HTTP, hoặc cần cộng đồng lớn hơn 533 star GitHub mà yzma đang có.
Binding Go cho llama.cpp
yzma là thư viện Go liên kết trực tiếp với llama.cpp để chạy suy luận cục bộ, cho phép chương trình Go nạp một model GGUF rồi sinh văn bản hoặc xử lý ảnh mà không cần khởi chạy server riêng. Nó nạp shared library của llama.cpp lúc runtime qua purego và ffi, nên không cần CGo và không cần bước biên dịch C trong `go build`. Đánh đổi: yzma cần một bản llama.cpp đi kèm khớp phiên bản, chứ không phải một dependency độc lập duy nhất.
Năng lực cốt lõi
- ✓Gọi llama.cpp ngay trong cùng tiến trình thay vì giao tiếp với một model server, bỏ qua bước round-trip qua HTTP của kiến trúc client-server.
- ✓Dùng purego và gói ffi để gọi thư viện dùng chung của llama.cpp, nhờ vậy `go build` và `go run` chạy bình thường mà không cần trình biên dịch C.
- ✓Nạp model ở định dạng GGUF — đúng định dạng llama.cpp dùng — nên bất kỳ model nào chuyển được sang GGUF từ Hugging Face đều dùng được.
- ✓Dùng được bất kỳ phần cứng tăng tốc nào có sẵn trên máy: CUDA, Metal, hoặc Vulkan, theo đúng danh sách trong README.
- ✓Bám theo các bản phát hành mới của llama.cpp, nên tính năng và bản vá phía thượng nguồn đến với yzma mà không cần chờ viết lại riêng.
- ✓Đi kèm CLI `yzma` để tải model GGUF trực tiếp từ URL Hugging Face, ví dụ `yzma model get -u <url>`.
- ✓Xử lý được cả model ngôn ngữ thuần văn bản lẫn vision-language model (VLM) nhận đầu vào là ảnh kèm prompt.
Ứng dụng thực tế
- •Nhúng chatbot cục bộ vào một CLI tool hoặc ứng dụng desktop viết bằng Go mà không cần gọi ra một inference server riêng.
- •Chạy suy luận vision-language — ví dụ chính trong README đưa một ảnh JPEG và một prompt cho model Qwen2.5-VL rồi nhận lại mô tả bằng văn bản.
- •Build cho phần cứng đặc thù hoặc giới hạn tài nguyên: repo có hướng dẫn cài đặt riêng cho Raspberry Pi, NVIDIA Jetson Orin, và Arduino UNO Q.
- •Cross-compile một binary Go duy nhất cho nhiều OS/GPU khác nhau bằng GOOS/GOARCH thông thường, không cần duy trì cấu hình build C riêng cho từng nền tảng.
Bắt đầu với yzma
Hướng dẫn cài đặt nằm trong INSTALL.md của repo, có phần riêng cho macOS, Linux, và Windows, cộng thêm ghi chú riêng cho Raspberry Pi, NVIDIA Jetson Orin, và Arduino UNO Q. README mô tả hai cách: chạy CLI `yzma` để tải các thư viện llama.cpp dựng sẵn cho nền tảng của bạn, hoặc để ứng dụng tự tải chúng lúc cài đặt — cách tự tải này có thể tự nhận diện CUDA và ROCm. Ngoài việc trỏ tới INSTALL.md, README không nêu rõ lệnh `go get`/module cụ thể, nên đường dẫn import package chính xác vẫn chưa được ghi rõ ràng ở đây.
Viết chương trình AI bằng Go
Một chương trình tối giản gọi `llama.Load(libPath)` để nạp thư viện dùng chung, `llama.Init()`, rồi `llama.ModelLoadFromFile()` và `llama.InitFromModel()` để lấy model và context. Từ đó bạn tokenize prompt bằng `llama.Tokenize()`, dựng batch bằng `llama.BatchGetOne()`, rồi lấy từng token một trong vòng lặp với một sampler chain, chuyển mỗi token về text bằng `llama.TokenToPiece()`. Thư mục examples/ của repo có ba chương trình chạy được ngay: một ví dụ hello world thuần văn bản, một vòng lặp chat tương tác, và một ví dụ VLM nhận đường dẫn ảnh cùng flag prompt. Chạy bất kỳ ví dụ nào bằng `go run ./examples/<name>/` sau khi đã tải model — phía Go không cần bước build riêng nào.
Điểm mạnh
- ✓Không cần CGo, không cần trình biên dịch C — `go build` và `go run` hoạt động bình thường, rất có ích trong CI hoặc khi cross-compile.
- ✓Chạy llama.cpp ngay trong tiến trình, nên không cần triển khai, giám sát, hay giữ sống một model server riêng bên cạnh ứng dụng Go.
- ✓Hỗ trợ cả LLM văn bản lẫn vision-language model qua cùng một API, theo đúng các ví dụ VLM và chat trong README.
- ✓Được cập nhật liên tục theo các bản phát hành mới của llama.cpp, với test chạy tự động trên từng bản theo README.
- ✓Có sẵn CLI `yzma` để tải model GGUF trực tiếp từ URL, khỏi phải tự viết script tải riêng.
Giới hạn hiện tại
- △License không được liệt kê trong metadata cung cấp ở đây, nên hãy kiểm tra trực tiếp trên repo trước khi dùng cho dự án thương mại.
- △Binary Go của bạn và thư viện dùng chung llama.cpp là hai artifact tách biệt, phải khớp phiên bản với nhau — bảng tương thích trong README liệt kê các khoảng build khá hẹp (ví dụ chỉ b9541–b9548 tương thích với yzma v1.16.0), nên nâng cấp một bên mà không để ý có thể gây lỗi.
- △README ghi yzma hỗ trợ 'hơn 96%' chức năng của llama.cpp, tức là vẫn còn một phần chức năng chưa hỗ trợ — phần 4% còn lại đó là gì thì không được nêu rõ.
- △Với 533 star và 21 fork, cộng đồng quanh dự án còn nhỏ, nên khả năng cao là bạn phải đọc source hoặc mở issue thay vì tìm được câu trả lời có sẵn trên mạng.
- △Tăng tốc GPU phụ thuộc vào việc bạn đã cài đúng driver stack (CUDA, ROCm, Vulkan, hoặc Metal) trên máy đích — phần này yzma không lo hộ bạn.
Các thư viện Go AI tương tự
yzma phù hợp với ai?
yzma phù hợp với lập trình viên Go muốn chạy suy luận LLM hoặc VLM cục bộ ngay trong ứng dụng của mình, thay vì gọi ra một API hosted hay dựng một model server riêng. Nó hợp nếu bạn đã quen cross-compile binary Go và không ngại tự khớp phiên bản thư viện llama.cpp với phiên bản yzma bằng tay. Nó sẽ không hợp nếu bạn muốn cài đặt turnkey mà không phải quản lý phiên bản, hoặc nếu team của bạn chưa có ai quen debug ở ranh giới FFI/shared-library khi có sự cố.
Câu hỏi thường gặp
yzma nạp model ở định dạng GGUF, đúng định dạng mà llama.cpp dùng, nên bất kỳ model nào đã convert sang GGUF — kể cả model tải từ Hugging Face — đều dùng được với yzma.
yzma không cần CGo. Nó gọi thư viện dùng chung của llama.cpp qua gói purego và ffi thay thế, nên `go build` và `go run` chạy được mà không cần trình biên dịch C trong toolchain.
yzma có thể dùng CUDA, Vulkan, HIP, ROCm, hoặc SYCL trên Linux, Metal trên macOS, và CUDA, Vulkan, HIP, SYCL, hoặc OpenCL trên Windows — tùy vào phần cứng tăng tốc có sẵn trên máy, theo bảng hỗ trợ trong README.
yzma chạy trên Linux, macOS, và Windows, hỗ trợ CPU amd64 và arm64 trên Linux, arm64 trên macOS. Repo cũng có hướng dẫn cài đặt riêng cho Raspberry Pi, NVIDIA Jetson Orin, và Arduino UNO Q.
Test của yzma chạy tự động trên mỗi bản phát hành mới của llama.cpp, và README duy trì một bảng tương thích ánh xạ các khoảng build của llama.cpp với phiên bản yzma — ví dụ, build b9541 đến b9548 của llama.cpp cần yzma v1.16.0.
yzma hỗ trợ suy luận đa phương thức qua vision-language model (VLM): ví dụ trong repo đưa một model Qwen2.5-VL cả ảnh lẫn prompt văn bản, rồi trả về mô tả của bức ảnh, dùng package mtmd của yzma.
Vấn đề mà yzma giải quyết
Phần lớn cách chạy LLM cục bộ trong ứng dụng Go hiện nay là gọi ra một server chạy riêng (binary server của chính llama.cpp, Ollama, LocalAI) rồi giao tiếp qua HTTP, nghĩa là thêm một tiến trình phải triển khai và thêm một round-trip mạng cho mỗi request. yzma giải quyết đúng phần ranh giới tiến trình đó: nó liên kết llama.cpp vào cùng không gian địa chỉ với chương trình Go của bạn qua purego, nên không cần khởi động, giám sát, hay restart server nào, và không cần bước CGo ép buộc toolchain C vào pipeline build.