Colibri

1. Colibri là gì?

Colibri là một chương trình (gọi là "engine suy luận") giúp chạy các mô hình AI ngôn ngữ cực lớn, cỡ hàng trăm tỷ tham số, ngay trên máy tính cá nhân. Bình thường những mô hình này cần cả dàn máy chủ có card đồ họa đắt tiền. Colibri khéo ở chỗ: phần cần dùng liên tục thì để trong RAM, còn phần còn lại (gọi là các "chuyên gia") nằm trên ổ cứng và được nạp vào khi cần. Đổi lại, tốc độ trả lời phụ thuộc rất nhiều vào ổ cứng của bạn.

Nó thay cho việc thuê một AI trả phí qua API: mô hình chạy hoàn toàn trên máy bạn, không cần tài khoản. Colibri miễn phí, mã nguồn mở (giấy phép Apache-2.0), viết bằng ngôn ngữ C.

Nói thẳng: đây là công cụ của người làm kỹ thuật và nghiên cứu, không phải ứng dụng "cài xong bấm là dùng". Nhóm phát triển tự mô tả nó là một nền tảng nghiên cứu, và nói rõ là không cam kết về tốc độ. Bạn phải gõ vài dòng lệnh và tải một mô hình nặng hàng chục đến hàng trăm GB. Hướng dẫn này đi theo con đường nhẹ nhất mà một người mới có thể làm: dùng mô hình Qwen3.6 bản 35B, nặng khoảng 20 GB.

Hợp với bạn nếu:

• Bạn tò mò muốn tự chạy một mô hình AI lớn trên máy mình, không phụ thuộc dịch vụ nào.
• Bạn có máy với ít nhất 24 GB RAM, ổ SSD còn trống vài chục GB, và không ngại gõ lệnh.
• Bạn thích thử nghiệm, chấp nhận trả lời chậm.

Chưa hợp nếu:

• Bạn muốn một trợ lý AI nhanh như ChatGPT. Trên máy thường, Colibri có thể chỉ ra vài token mỗi giây hoặc chậm hơn (token là từng mẩu chữ nhỏ mà AI viết ra từng chút một).
• Máy bạn có 8 GB RAM hoặc ổ cứng còn ít chỗ trống.
• Bạn chỉ có điện thoại. Colibri chạy trên Windows, macOS và Linux.

2. Cần chuẩn bị gì?

Máy tính: Windows 10/11, macOS hoặc Linux. Bản tải sẵn có cho Linux (x86-64), Windows (x86-64) và macOS chip Apple (arm64). Mac đời Intel hoặc Linux ARM phải tự biên dịch từ mã nguồn, việc này nằm ngoài phạm vi hướng dẫn cho người mới.

RAM và ổ cứng (theo bảng trong README của dự án, cho mô hình mà hướng dẫn này dùng):

Mô hình	Dung lượng ổ cứng	RAM	Card đồ họa
Qwen3.6-35B-A3B (khuyên dùng để thử)	khoảng 20 GB	24 GB	Không bắt buộc
GLM-5.2 (mô hình chính của dự án)	khoảng 372 GB	tối thiểu 16 GB	Không bắt buộc

Card đồ họa chỉ làm cho nhanh hơn, không bắt buộc. Ổ SSD NVMe nhanh là yếu tố quyết định tốc độ. Trang riêng của mô hình Qwen3.6 khuyên khoảng 30 GB RAM nếu muốn chạy thoải mái.

Phần mềm cần cài trước:

• Python 3 (ngôn ngữ lập trình; ở đây chỉ dùng để chạy bộ khởi động coli, còn engine thì viết bằng C và không cần gì thêm). Tải tại https://www.python.org/downloads/ . Trên Windows, nhớ tick ô "Add python.exe to PATH" khi cài.
• Công cụ hf của Hugging Face (để tải mô hình từ trang Hugging Face, nơi người ta chia sẻ mô hình AI). Cách cài ở Bước 2.

Không cần tài khoản, không cần khóa API, không mất tiền. Chi phí thực tế duy nhất là dung lượng ổ cứng và đường truyền để tải khoảng 20 GB.

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

Bước 1: Tải bản Colibri dựng sẵn

1. Mở https://github.com/JustVugg/colibri/releases/latest . Bản mới nhất lúc viết hướng dẫn là v1.12.1 (24/9/2026).
2. Kéo xuống phần "Assets" và tải file đúng với máy của bạn:
   • Windows: colibri-v1.12.1-windows-x86_64.zip
   • macOS chip Apple (M1 trở lên): colibri-v1.12.1-macos-arm64.tar.gz
   • Linux: colibri-v1.12.1-linux-x86_64.tar.gz
3. Giải nén vào một thư mục riêng, ví dụ colibri.

Trên Windows, bấm chuột phải vào file zip và chọn giải nén. Trên macOS và Linux, dùng lệnh sau trong thư mục chứa file vừa tải:

mkdir colibri && tar xzf colibri-v1.12.1-linux-x86_64.tar.gz -C colibri && cd colibri

(Với macOS, thay tên file bằng colibri-v1.12.1-macos-arm64.tar.gz.)

Bên trong bạn thấy file colibri (hoặc colibri.exe), cùng các engine anh em và file coli. Trên Windows có thêm coli.cmd.

Lưu ý: trên Windows, đừng bấm đúp vào các file .exe. Đó là engine, không có mô hình thì nó chớp cửa sổ rồi tắt. File dùng để chạy là coli.cmd.

Bước 2: Cài Python và công cụ tải mô hình

Cài Python 3 theo link ở mục 2. Sau đó mở Terminal (macOS/Linux) hoặc PowerShell (Windows) và cài công cụ hf:

pip install -U "huggingface_hub"

Kiểm tra:

hf --help

Thấy gì là đúng: hiện danh sách các lệnh như download, auth. Nếu báo không tìm thấy lệnh hf, xem mục 5.

Nếu bạn dùng Windows, có cách cài khác theo tài liệu của Hugging Face:

powershell -ExecutionPolicy ByPass -c "irm https://hf.co/cli/install.ps1 | iex"

Lưu ý: bộ cài kiểu này còn cài thêm một "skill" cho các trợ lý AI lập trình. Nếu không muốn, hãy dùng lệnh pip ở trên.

Bước 3: Tải mô hình (khoảng 20 GB)

Chọn một thư mục trên ổ cứng còn trống, tốt nhất là ổ SSD nhanh. Dùng mô hình đã được chuyển sẵn cho Colibri, bản "gs64" mà dự án khuyên dùng:

Linux hoặc macOS:

hf download Kreuzzelg/qwen36-35b-a3b-colibri-i4-gs64 --local-dir ~/Models/qwen36_i4_gs64

Windows (ví dụ lưu ở ổ D):

hf download Kreuzzelg/qwen36-35b-a3b-colibri-i4-gs64 --local-dir D:\Models\qwen36_i4_gs64

Thấy gì là đúng: một thanh tiến trình chạy, tải xong thì thư mục chứa các file của mô hình. Việc này mất từ vài chục phút đến vài giờ tùy mạng. Nếu bị ngắt, chạy lại đúng lệnh đó.

Trang của mô hình: https://huggingface.co/Kreuzzelg/qwen36-35b-a3b-colibri-i4-gs64

Bước 4: Kiểm tra máy đã sẵn sàng

Mở Terminal hoặc PowerShell, đi tới thư mục colibri đã giải nén ở Bước 1.

Windows:

coli.cmd doctor --model D:\Models\qwen36_i4_gs64

macOS / Linux:

python3 coli doctor --model ~/Models/qwen36_i4_gs64

Thấy gì là đúng: công cụ báo các mục đã sẵn sàng và chỉ rõ chỗ nào còn thiếu (thiếu file mô hình, thiếu quyền...). Lệnh này chỉ đọc, không thay đổi gì trên máy.

Bước 5 (tùy chọn): Tự biên dịch từ mã nguồn

Chỉ cần nếu bạn dùng Mac đời Intel, Linux ARM, hoặc muốn bản tối ưu cho đúng chip của mình. Cần gcc (hoặc clang) có OpenMP, git, make. Trên Ubuntu/Debian:

sudo apt update
sudo apt install -y build-essential git python3

Rồi lấy mã và dựng engine Qwen3.6:

git clone https://github.com/JustVugg/colibri
cd colibri
make -C c qwen36

Tài liệu chính thức cho từng hệ điều hành ở https://github.com/JustVugg/colibri/blob/main/docs/quickstart.md

4. Dùng lần đầu

Trong thư mục colibri, chạy chat với mô hình vừa tải.

Windows:

coli.cmd chat --model D:\Models\qwen36_i4_gs64

macOS / Linux:

python3 coli chat --model ~/Models/qwen36_i4_gs64

Thấy gì là đúng: chương trình nạp phần dữ liệu thường trú vào RAM (lần đầu mất một lúc), rồi hiện dấu nhắc để bạn gõ. Hãy thử gõ một câu ngắn như "Xin chào, bạn là ai?" rồi Enter. Chữ hiện ra từng mẩu một. Trên ổ cứng thường, chữ ra chậm là bình thường, vì các "chuyên gia" của mô hình đang được nạp từ ổ cứng. Chạy lâu hơn thì Colibri tự ghi nhớ những phần bạn hay dùng và nhanh dần lên.

Giao diện web. Nếu thích khung chat trong trình duyệt:

Windows:

coli.cmd web --model D:\Models\qwen36_i4_gs64

macOS / Linux:

python3 coli web --model ~/Models/qwen36_i4_gs64

Lệnh này mở bảng điều khiển ở trình duyệt, có khung chat và các số đo tốc độ. Địa chỉ mặc định là http://127.0.0.1:8000 , chỉ truy cập được từ chính máy bạn.

Một vài lệnh hữu ích khác, đều chạy cùng cách như trên:

Bạn muốn	Lệnh
Xem mô hình sẽ được đặt ở đâu (RAM, ổ cứng, card đồ họa)	coli plan --model <thư mục mô hình>
Chạy máy chủ API tương thích OpenAI, không mở trình duyệt	coli serve --model <thư mục mô hình>
Đo và lưu cấu hình nhanh nhất cho máy này	coli tune --model <thư mục mô hình>

Trên Windows viết coli.cmd thay cho coli; trên macOS/Linux viết python3 coli. Khi dùng <thư mục mô hình> ngoài khối lệnh, nhớ thay bằng đường dẫn thật của bạn.

5. Lỗi thường gặp và cách sửa

Dấu hiệu	Nguyên nhân	Cách sửa
Trên Windows, bấm đúp file .exe thì cửa sổ chớp rồi tắt	File .exe chỉ là engine, cần có mô hình do bộ khởi động chỉ định	Chạy coli.cmd từ PowerShell hoặc bấm đúp coli.cmd; xem mục 4
python hoặc python3 báo không tìm thấy	Chưa cài Python, hoặc lúc cài chưa tick "Add python.exe to PATH"	Cài lại Python từ https://www.python.org/downloads/ và tick ô đó; mở cửa sổ lệnh mới rồi thử lại
hf báo không tìm thấy lệnh	Thư mục chứa lệnh chưa có trong PATH, hoặc cửa sổ lệnh mở trước khi cài	Đóng và mở lại Terminal; nếu vẫn lỗi, thử python -m pip install -U "huggingface_hub" rồi mở cửa sổ mới, hoặc xem hướng dẫn cài của Hugging Face
Báo "engine is not built" khi chạy coli	Chạy coli ở ngoài thư mục đã giải nén, nên không thấy engine nằm cạnh	Đi vào thư mục colibri đã giải nén rồi chạy lại. Nếu bạn clone mã nguồn thì chạy make -C c qwen36 trước
Máy đơ, treo, hoặc chương trình tự tắt khi nạp mô hình	Thiếu RAM: mô hình Qwen3.6 cần khoảng 24 GB	Đóng các ứng dụng khác; nếu máy dưới 24 GB RAM thì mô hình này chưa phù hợp
Tải mô hình báo hết chỗ trống	Ổ đĩa không đủ khoảng 20 GB	Giải phóng ổ đĩa, hoặc đổi --local-dir sang ổ khác còn trống
Chữ ra rất chậm	Ổ cứng chậm: mô hình đọc dữ liệu từ ổ cứng mỗi khi sinh chữ	Chép mô hình sang ổ SSD NVMe. Tài liệu của dự án nói thẳng rằng tốc độ do ổ cứng quyết định
coli doctor báo thiếu thứ gì đó	Thư mục mô hình sai hoặc tải chưa xong	Kiểm tra đường dẫn sau --model, chạy lại lệnh hf download để tải nốt

Cổng 8000 bị chiếm khi chạy coli web: bạn có thể đang mở một bản Colibri khác. Đóng nó đi, hoặc thêm --port 8001 vào lệnh để dùng cổng khác.

Nếu vẫn chưa được, dự án có trang hỏi đáp tại https://github.com/JustVugg/colibri/issues và cộng đồng Discord được liệt kê trong README.

6. Gỡ cài đặt / cập nhật

Cập nhật

• Bản dựng sẵn: tải bản mới ở https://github.com/JustVugg/colibri/releases/latest , giải nén vào thư mục mới và dùng như cũ. Mô hình đã tải giữ nguyên, không cần tải lại.
• Bản biên dịch từ mã nguồn: vào thư mục đã git clone và chạy git pull, rồi dựng lại bằng make -C c qwen36.
• Công cụ hf: chạy hf update.

Gỡ cài đặt

• Xóa thư mục colibri đã giải nén. Colibri không cài thứ gì vào hệ thống.
• Muốn lấy lại ổ đĩa: xóa thư mục mô hình (ví dụ ~/Models/qwen36_i4_gs64 hoặc D:\Models\qwen36_i4_gs64).
• Nếu muốn gỡ công cụ tải mô hình: pip uninstall huggingface_hub.

7. Câu hỏi hay gặp

Colibri có mất tiền không? Không. Colibri là phần mềm miễn phí, mã nguồn mở (Apache-2.0). Mô hình Qwen3.6 được dự án ghi là giấy phép Apache 2.0. Bạn chỉ tốn dung lượng ổ cứng, điện và đường truyền để tải.

Có cần mạng không? Chỉ khi tải chương trình và mô hình. Sau khi đã tải xong, chat chạy trên máy bạn.

Câu chat của tôi có bị gửi đi đâu không? Engine chạy ngay trên máy bạn và máy chủ web mặc định chỉ lắng nghe ở địa chỉ 127.0.0.1 (chỉ máy bạn truy cập được). Muốn biết chi tiết hơn, hãy xem mã nguồn hoặc tài liệu chính thức của dự án.

Máy yếu có chạy được không? Mô hình Qwen3.6 bản này cần khoảng 24 GB RAM. Với máy ít RAM hơn, dự án có mô hình OLMoE nhỏ hơn (cần 8 GB RAM, khoảng 7 GB ổ cứng), nhưng bạn phải tự chuyển đổi mô hình bằng một công cụ Python đi kèm, việc này dành cho người đã quen lập trình. Chi tiết xem README của dự án.

Có cần card đồ họa không? Không. README nói rõ không mô hình nào bắt buộc phải có card đồ họa; nếu có thì chạy nhanh hơn.