TensorFold: chạy mô hình AI ngay trên máy Mac hoặc card NVIDIA — hướng dẫn cài đặt và dùng

Tóm tắt nhanh
TensorFold là engine suy luận (inference) mô hình ngôn ngữ lớn, viết bằng Zig, chạy trực tiếp trên Mac chip Apple và card NVIDIA. Bạn dùng nó để tự chạy mô hình AI trên máy mình rồi gọi qua API cục bộ. Trên Mac, cài bằng Homebrew chỉ vài lệnh; trên Linux cần tải bản phát hành và có driver NVIDIA đủ mới.
TensorFold là một engine để chạy mô hình ngôn ngữ (LLM) ngay trên máy của bạn. Nó là một file chạy viết bằng Zig, đọc trực tiếp file mô hình, tự xử lý phần chia chữ (tokenize) và chạy các kernel Metal (Mac chip Apple) hoặc CUDA (card NVIDIA). Theo README, khi phục vụ mô hình bạn không cần cài Python hay MLX.
Bạn nên đọc bài này nếu muốn có một "ChatGPT riêng" chạy trên máy mình: dữ liệu không phải gửi ra dịch vụ bên ngoài, và các công cụ khác có thể gọi vào qua một địa chỉ API cục bộ. Repo hiện có khoảng 1938 sao và 391 fork, giấy phép Apache-2.0, và vẫn được cập nhật trong 3 tháng gần đây.
Điểm đáng giá nhất: cài trên Mac chỉ cần Homebrew, rồi hai lệnh là có server chạy mô hình nhỏ. API còn hỗ trợ nhiều kiểu gọi (chat completions, completions, Responses và Anthropic Messages), nên nhiều ứng dụng có sẵn dùng được ngay.
ashhart/TensorFold
TensorFold là engine chạy mô hình ngôn ngữ cục bộ viết bằng Zig, dùng Metal hoặc CUDA, không cần Python hay MLX, mở sẵn API tương thích OpenAI.
I.TensorFold làm được gì
A.Chạy mô hình trực tiếp, không qua Python
Engine tự đọc checkpoint, tự tokenize và chạy kernel GPU. Với bạn, điều này có nghĩa là bớt một lớp cài đặt phức tạp (môi trường Python, thư viện) so với nhiều công cụ khác.
B.Mở sẵn API tương thích
Sau khi chạy tensorfold serve, bạn gọi vào địa chỉ cục bộ. API phục vụ chat completions, completions, Responses và Anthropic Messages. Đường dẫn /v1/models cho biết tên mô hình đang phục vụ. Nhờ vậy bạn có thể trỏ các công cụ hỗ trợ API kiểu này sang máy mình.
C.Chạy nhiều yêu cầu cùng lúc
Cờ --parallel N giới hạn số yêu cầu chạy đồng thời; yêu cầu thừa sẽ xếp hàng chờ. Nếu bạn không đặt cờ này, engine dùng --parallel auto và xin tối đa tám luồng tuỳ bộ nhớ. Nếu bạn đặt số mà máy không đủ chỗ, engine từ chối chứ không chạy bừa.
D.Nhiều lựa chọn mô hình
README có bảng mô hình đã được kiểm chứng: từ Qwen3.5-2B bản 4-bit (nhỏ, dùng để thử), tới các mô hình lớn hơn như Qwen3.8-27B, Nemotron 3.5 Lightning 30B-A3B, và các mô hình GLM chạy nhiều máy. Lệnh tensorfold info REPO cho bạn biết mức bộ nhớ tối thiểu của một checkpoint.
E.Giao diện web và app Mac
Lệnh tensorfold web mở TensorFold Web, một ứng dụng web cục bộ nhỏ để chọn mô hình, chạy và chat. Ngoài ra có app desktop cho Mac chip Apple (đang ở dạng beta) gộp engine, tải mô hình, gợi ý theo phần cứng, số đo tốc độ sinh chữ, và soạn tài liệu.
F.Tính năng thử nghiệm: Living Weights
Tính năng này dạy mô hình chạy cục bộ những sự kiện mới và ghi thẳng vào file trọng số. README ghi rõ đây là thử nghiệm: các sự kiện liên quan có thể làm nhiễu nhau, và khả năng nhớ giảm khi vượt vài chục sự kiện. Bài này không đi sâu vào phần đó.
II.Cần chuẩn bị gì
Theo README:
- Mac chip Apple (Apple Silicon) có Homebrew. Đây là đường cài nhanh nhất.
- Linux với card NVIDIA: cần glibc 2.28 trở lên và driver NVIDIA R580 trở lên (CUDA 13.0), có
libcuda.so.1. Kernel được build bằng CUDA 13 nên driver cũ hơn bị từ chối ngay khi khởi động. Gõnvidia-smiđể xem driver bạn đang có. - CPU của máy Linux: bản phát hành có hai loại là
linux-aarch64(dùng cho GB10) vàlinux-x86_64. - Windows với card NVIDIA: README chỉ nói làm theo "native Windows build guide" (hướng dẫn build bản Windows). Chi tiết không nằm trong đoạn README mình có, bạn xem trong thư mục
docs/của repo. - Đủ bộ nhớ cho mô hình. README nói rõ phần cứng ghi trong bảng là phạm vi đã được ghi nhận, không phải mức tối thiểu đã đo. Ngữ cảnh, số yêu cầu song song và bộ nhớ đệm đều cần thêm bộ nhớ ngoài trọng số.
- Đường mạng để tải mô hình. Trọng số mô hình có giấy phép riêng, bạn nên xem trước khi dùng.
Mô hình nhỏ Qwen3.5-2B 4-bit trong phần Quick start là lựa chọn an toàn để thử lần đầu. Với mô hình lớn, hãy chạy `tensorfold info REPO` để xem mức bộ nhớ tối thiểu trước khi tải hàng chục GB.
III.Cài đặt từng bước
- Mở terminalTerminal trên Mac, hoặc shell trên Linux
- Cài TensorFoldMac: brew install; Linux: tải và giải nén bản phát hành
- Tải mô hìnhDùng tensorfold pull với mô hình Qwen3.5-2B 4-bit
- Chạy serverDùng tensorfold serve, đặt tên mô hình là local-model
- Gửi thử một yêu cầuDùng curl ở terminal thứ hai
A.Mac chip Apple: cài bằng Homebrew
Mở ứng dụng Terminal, rồi chạy lệnh sau. Lệnh này cài TensorFold từ kho Homebrew của tác giả.
brew install ashhart/tensorfold/tensorfoldSau đó tải mô hình. Phần sau dấu @ là mã phiên bản được ghim cố định, nên bạn tải đúng bản đã được kiểm chứng.
tensorfold pull mlx-community/Qwen3.5-2B-MLX-4bit@93760be4f1f69842a46bc13dbdc0f19e291392a3Cuối cùng khởi động server. Chú ý: khi chạy serve bạn dùng tên repo mô hình, không kèm phần @revision.
tensorfold serve mlx-community/Qwen3.5-2B-MLX-4bit --name local-model --context 8192 --no-thinkingCờ --name local-model đặt tên mô hình để bạn gọi sau này. Cờ --context 8192 đặt độ dài ngữ cảnh. Cờ --no-thinking tắt chế độ "suy nghĩ" của mô hình. Cứ để cửa sổ này mở, server đang chạy trong đó.
B.Linux với NVIDIA: dùng bản phát hành
Bạn cần driver đủ mới như ở phần chuẩn bị. Đoạn lệnh dưới đây chọn đúng bản theo CPU, tải file và file kiểm tra, kiểm tra tính toàn vẹn, giải nén rồi thêm vào PATH. Hãy chạy cả khối trong cùng một terminal, vì các biến như V và PLATFORM chỉ có trong phiên terminal đó.
V=1.2.7
case "$(uname -m)" in
aarch64|arm64) PLATFORM=linux-aarch64 ;;
x86_64) PLATFORM=linux-x86_64 ;;
*) echo 'No release archive for this CPU' >&2; exit 1 ;;
esac
curl -fLO "https://github.com/ashhart/TensorFold/releases/download/v$V/tensorfold-$V-$PLATFORM.tar.gz"
curl -fLO "https://github.com/ashhart/TensorFold/releases/download/v$V/tensorfold-$V-$PLATFORM.tar.gz.sha256"
sha256sum -c "tensorfold-$V-$PLATFORM.tar.gz.sha256"
tar -xzf "tensorfold-$V-$PLATFORM.tar.gz"
export PATH="$PWD/tensorfold-$V-$PLATFORM/bin:$PATH"
tensorfold() { command tensorfold-native "$@"; }Dòng sha256sum -c phải báo OK; nếu không, đừng chạy tiếp vì file tải có thể hỏng. Hai dòng cuối thêm thư mục bin vào PATH và tạo hàm tensorfold gọi file tensorfold-native. Hãy giữ nguyên các thư mục bên trong bản giải nén, đừng di chuyển rời từng file.
Sau đó tải mô hình và chạy server, y như trên Mac:
tensorfold pull mlx-community/Qwen3.5-2B-MLX-4bit@93760be4f1f69842a46bc13dbdc0f19e291392a3
tensorfold serve mlx-community/Qwen3.5-2B-MLX-4bit --name local-model --context 8192 --no-thinkingC.Windows với NVIDIA
README chỉ ghi rằng bạn làm theo hướng dẫn build bản Windows gốc. Nội dung hướng dẫn đó không có trong phần README mình có, nên bạn hãy mở thư mục docs/ của repo để tìm.
IV.Kiểm tra đã chạy được chưa
Để server chạy ở terminal đầu. Mở một terminal thứ hai (trên cả Mac lẫn Linux) và gửi thử một yêu cầu:
curl -fsS http://127.0.0.1:8080/v1/chat/completions \
-H 'Content-Type: application/json' \
-d '{"model":"local-model","messages":[{"role":"user","content":"Say hello in one sentence."}],"max_tokens":128,"temperature":0}'Nếu nhận được một đoạn JSON có câu chào do mô hình trả lời thì bạn đã cài thành công. Bạn cũng có thể gọi /v1/models để xem tên mô hình đang phục vụ. Ngoài ra, các lệnh sau giúp bạn xem file chạy của mình có những gì:
tensorfold --help
tensorfold capabilities --json
tensorfold serve REPO --helpV.Dùng vào việc thật
A.Thử mô hình nhỏ trước khi đầu tư
Bạn là chủ một cửa hàng nhỏ, tò mò xem AI cục bộ chạy ra sao. Chạy đúng các lệnh trong phần cài đặt với mô hình Qwen3.5-2B 4-bit, rồi dùng lệnh curl ở trên, đổi nội dung content thành câu hỏi của bạn (ví dụ viết lại một đoạn mô tả sản phẩm). Kết quả là bạn thấy tận mắt tốc độ và chất lượng của mô hình nhỏ trên máy mình, không mất phí gọi dịch vụ ngoài. Lưu ý README ghi mô hình này chỉ xử lý văn bản.
Cài một lần, mô hình chạy ngay trên máy bạn, dữ liệu không phải đi đâu cả.
Ông T
B.Chat bằng giao diện web
Nhân viên văn phòng không thích gõ lệnh curl có thể chạy:
tensorfold webLệnh này mở TensorFold Web để chọn mô hình, chạy và chat. README nói nếu chưa có sẵn, bản release tương tác sẽ hỏi bạn có muốn cài đúng phiên bản bằng uv hay không, và chỉ cài sau khi bạn đồng ý. Kết quả là một cửa sổ chat cục bộ, không cần lập trình.
C.Dev dựng ứng dụng gọi API cục bộ
Lập trình viên mới đang viết một công cụ nội bộ (tóm tắt email, phân loại phản hồi khách). Bạn để tensorfold serve chạy, rồi gọi vào http://127.0.0.1:8080/v1/chat/completions với tên mô hình local-model, giống lệnh kiểm tra ở trên. Vì API cũng hỗ trợ kiểu Anthropic Messages và Responses, bạn có thể chọn kiểu gọi hợp với thư viện đang dùng. Kết quả là ứng dụng của bạn có "bộ não" chạy nội bộ, bạn chỉ cần đổi địa chỉ và tên mô hình.
D.Mô hình lớn hơn khi máy đủ mạnh
Nếu bạn có Mac cấu hình cao hoặc máy NVIDIA phù hợp, hãy xem bảng "Pick a model" trong README. Ví dụ mô hình Qwen3.8-27B có thể thêm drafter để giải mã nhanh hơn, bằng cờ --drafter z-lab/Qwen3.8-27B-DFlash2 (README ghi: không thêm thì giải mã ở chế độ thường). Với Mac 32 GB, README cảnh báo cần nâng iogpu.wired_limit_mb, và thông báo từ chối khi khởi động sẽ nêu giá trị cần đặt. Nếu máy không đủ, hãy ở lại với mô hình nhỏ.
VI.Lỗi hay gặp và cách xử lý
A.Driver NVIDIA quá cũ
TensorFold từ chối chạy ngay khi khởi động nếu driver thấp hơn R580 (CUDA 13.0). Gõ nvidia-smi để xem phiên bản đang cài, cập nhật driver rồi chạy lại.
B.Kiểm tra sha256 không khớp
Nếu sha256sum -c báo lỗi, file tải về có thể bị hỏng hoặc dở dang. Xoá file .tar.gz và file .sha256, rồi chạy lại các lệnh curl. Đừng giải nén hay chạy file chưa qua kiểm tra.
C.Gõ tensorfold báo không tìm thấy lệnh (Linux)
PATH và hàm tensorfold chỉ có hiệu lực trong phiên terminal bạn vừa chạy khối lệnh. Nếu mở terminal mới, bạn cần chạy lại hai dòng export PATH=... và tensorfold() {...}.
D.Máy không đủ bộ nhớ
Engine có thể từ chối khởi động, và nếu bạn đặt --parallel quá lớn mà máy không đủ chỗ, nó cũng từ chối. Chạy tensorfold info REPO để xem mức bộ nhớ tối thiểu, giảm --context, bỏ cờ --parallel để để engine tự chọn, hoặc chuyển sang mô hình nhỏ hơn.
E.Gọi curl bị từ chối kết nối
Thường là server chưa chạy hoặc đã bị tắt. Hãy kiểm tra terminal đầu tiên vẫn đang mở và đang chạy tensorfold serve. Cũng xem lại cổng 8080 trong lệnh có đúng với dòng khởi động của server không.
VII.Có nên dùng không
Điểm mạnh: chạy cục bộ nên dữ liệu ở trên máy bạn; cài Mac gọn; không cần Python khi phục vụ; API đa dạng; giấy phép Apache-2.0; dự án còn được cập nhật. Bảng mô hình ghi rõ máy nào đã được kiểm chứng.
Giới hạn: phần cứng bị giới hạn ở Mac chip Apple và card NVIDIA (README cũng nhắc tới một mô hình chạy trên card AMD, nhưng đó là trường hợp riêng). Nhiều mô hình lớn chỉ được kiểm chứng trên cấu hình khá nặng, thậm chí nhiều máy, nên không phải máy nào cũng chạy được. Các tính năng như Living Weights, app mobile là thử nghiệm hoặc bản xem trước. Mô hình nhỏ như 2B chỉ xử lý văn bản và chất lượng có giới hạn.
Khi nào chọn cách khác: nếu bạn chỉ cần chat thỉnh thoảng và máy yếu, một dịch vụ AI trực tuyến sẽ đơn giản hơn. Nếu bạn là doanh nghiệp cần cổng quản lý chung cho nhiều máy và người dùng, README nhắc tới sản phẩm riêng là TensorFold Starlight (ở repo khác, còn mới), bạn nên đọc kỹ ghi chú đánh giá của nó trước khi dùng.
Câu hỏi thường gặp
TensorFold có miễn phí không?
Repo dùng giấy phép Apache-2.0. Tuy nhiên README lưu ý trọng số mô hình có giấy phép riêng, nên bạn cần xem điều khoản của từng mô hình trước khi dùng.
Có cần cài Python không?
Theo README, khi phục vụ mô hình bạn không cần Python hay MLX. Riêng lệnh `tensorfold web` có thể đề nghị cài giao diện web bằng `uv` nếu máy chưa có, và chỉ làm sau khi bạn đồng ý.
Máy tôi cần gì để chạy?
Mac chip Apple hoặc máy Linux có card NVIDIA với driver R580 trở lên (CUDA 13.0) và glibc 2.28 trở lên. Mức RAM cần thiết tuỳ mô hình; dùng `tensorfold info REPO` để xem mức tối thiểu. Với Windows, README chỉ dẫn tới hướng dẫn build bản Windows cho card NVIDIA.
Chạy được trên Windows không?
README nói bạn dùng card NVIDIA trên Windows thì làm theo hướng dẫn build bản Windows gốc. Các bước cụ thể không có trong phần README mình có, nên bạn xem trong thư mục docs của repo.
Dữ liệu của tôi có an toàn không?
TensorFold chạy mô hình ngay trên máy bạn và phục vụ qua địa chỉ cục bộ 127.0.0.1, nên yêu cầu không phải đi qua dịch vụ ngoài. Tuy nhiên tư liệu không có phần đánh giá bảo mật chi tiết; repo có file SECURITY.md để bạn tham khảo.
Nó dùng như thế nào với ứng dụng khác?
Sau khi chạy `tensorfold serve`, API cục bộ hỗ trợ chat completions, completions, Responses và Anthropic Messages. Bạn trỏ ứng dụng hỗ trợ các kiểu gọi này tới địa chỉ cục bộ và dùng tên mô hình bạn đã đặt bằng `--name`.
Có app cho người không quen dòng lệnh không?
Có app desktop cho Mac chip Apple (đang ở dạng beta) gộp engine, tải mô hình, gợi ý theo phần cứng và soạn tài liệu. Ngoài ra lệnh `tensorfold web` mở giao diện web cục bộ để chọn mô hình và chat.


