TensorFold: chạy mô hình AI cục bộ trên Mac và GPU NVIDIA — hướng dẫn cài đặt và dùng
Bài này là một góc nhìn khác về ashhart/TensorFold — repo từng đổi tên nên mình viết lại với cách tiếp cận khác. Bài hướng dẫn chính: 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à một engine chạy mô hình ngôn ngữ lớn (LLM) ngay trên máy của bạn, viết bằng Zig, hỗ trợ Mac Apple Silicon và GPU NVIDIA. Bạn tải mô hình về rồi bật một máy chủ cục bộ có API tương tự OpenAI để gọi từ code hoặc ứng dụng. Cài trên Mac khá nhẹ nhàng với Homebrew; trên Linux có sẵn bản đóng gói nhưng đòi hỏi 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ó viết bằng Zig, đọc trực tiếp file mô hình, tách từ cho câu hỏi và chạy các kernel Metal (Mac) hoặc CUDA (NVIDIA). Theo README, khi phục vụ mô hình bạn không cần cài Python hay MLX.
Repo này hợp với ba nhóm người. Thứ nhất là lập trình viên muốn có một "máy chủ AI" chạy cục bộ để gọi bằng API, khỏi gửi dữ liệu ra dịch vụ ngoài. Thứ hai là người dùng Mac chip Apple Silicon muốn thử mô hình mở mà không phải dựng môi trường Python rắc rối. Thứ ba là người có card NVIDIA trên Linux hoặc máy như GB10 (DGX Spark) và muốn một bộ chạy gọn.
Điểm đáng giá nhất: một binary duy nhất, vài lệnh là có máy chủ nghe ở địa chỉ cục bộ, trả lời qua API quen thuộc. Hiện repo có khoảng 2.048 sao và 399 fork, giấy phép Apache-2.0. Lưu ý trọng lượng của mô hình thì có giấy phép riêng, README nhắc rõ điều này.
ashhart/TensorFold
Engine suy luận LLM viết bằng Zig, chạy mô hình cục bộ trên Mac Apple Silicon và GPU NVIDIA, có API tương thích OpenAI, không cần Python.
I.TensorFold làm được gì
Chạy mô hình trực tiếp trên GPU của bạn. Engine đọc checkpoint, tách từ và chạy kernel Metal hoặc CUDA. Với bạn, nghĩa là ít thứ phải cài hơn và ít chỗ để hỏng hơn.
Có API sẵn để gọi. Máy chủ phục vụ chat completions, completions, Responses và Anthropic Messages. Đường dẫn /v1/models liệt kê tên mô hình đang phục vụ. Nếu code của bạn đã dùng kiểu API này, việc đổi sang mô hình chạy cục bộ thường chỉ là đổi địa chỉ và tên mô hình.
Tải mô hình bằng một lệnh. Lệnh tensorfold pull tải mô hình về, và bạn có thể ghim đúng một bản (revision) bằng cách thêm @ rồi mã bản. Ghim bản giúp mọi người cùng chạy một thứ giống nhau.
Xử lý 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ỏ cờ này, engine dùng --parallel auto và xin tối đa tám luồng tuỳ bộ nhớ.
Giao diện web và app Mac. Lệnh tensorfold web mở TensorFold Web, một ứng dụng web nhỏ chạy cục bộ để chọn, chạy và trò chuyện với mô hình. Ngoài ra có ứng dụng desktop cho Mac Apple Silicon (bản beta) gồm engine, tải mô hình, gợi ý theo phần cứng, số đo tốc độ và soạn tài liệu.
Living Weights (thử nghiệm). Tính năng dạy cho mô hình đang chạy những dữ kiện mới, được ghi thẳng vào file trọng số. Tác giả ghi rõ đây là thử nghiệm và có hạn chế, mình nói kỹ hơn ở các phần sau.
Bản doanh nghiệp tách riêng. TensorFold Starlight, nằm ở repo riêng, dành cho tổ chức muốn một cổng chung có đăng nhập, phân quyền và tính token cho cả đàn máy TensorFold. Bài này chỉ nói về engine.
II.Cần chuẩn bị gì
Theo README, bạn cần một trong các môi trường sau:
- Mac chip Apple Siliconcài bằng Homebrew. README không nêu mức RAM tối thiểu cho mô hình nhỏ dùng trong phần khởi động nhanh. Mô hình lớn hơn thì cần xem bằng
tensorfold info REPO, lệnh này báo mức bộ nhớ tối thiểu của mô hình. - Linux với GPU NVIDIAcó hai bản,
linux-aarch64cho GB10 vàlinux-x86_64cho máy x86_64. Cần glibc 2.28 trở lên và driver NVIDIA R580 trở lên (CUDA 13.0), cólibcuda.so.1. Dùngnvidia-smiđể xem driver hiện tại. - Windows với GPU NVIDIAREADME chỉ nói làm theo hướng dẫn build Windows gốc (native Windows build guide) trong repo. Bài này không đi sâu phần đó.
- Công cụtrên Linux cần
curl,sha256sumvàtar(các lệnh này trong README). Cần kết nối mạng để tải mô hình. - Tài khoản / API keyphần khởi động nhanh không yêu cầu. Riêng Living Weights yêu cầu một khóa để máy chủ chạy với
--slide, mình sẽ nói bên dưới.
Mô hình tải về có giấy phép riêng của nó, tách khỏi giấy phép Apache-2.0 của TensorFold. Nếu bạn dùng cho công việc kinh doanh, hãy đọc giấy phép của đúng mô hình bạn chọn.
III.Cài đặt từng bước
- Mở terminalDùng Terminal trên Mac hoặc shell trên Linux
- Cài TensorFoldMac dùng Homebrew; Linux tải bản nén, kiểm tra sha256 rồi giải nén
- Tải mô hìnhChạy tensorfold pull với mô hình Qwen3.5-2B 4-bit
- Bật máy chủChạy tensorfold serve và đặt tên local-model
- Gửi thử một yêu cầuDùng curl ở terminal thứ hai
A.Mở terminal
Trên Mac, mở ứng dụng Terminal. Trên Linux, mở cửa sổ shell. Bạn chạy các lệnh dưới đây trong cửa sổ này. Cửa sổ chạy máy chủ sẽ phải để mở, nên về sau bạn sẽ cần thêm một cửa sổ thứ hai.
B.Cài TensorFold trên Mac Apple Silicon
Cài bằng Homebrew:
brew install ashhart/tensorfold/tensorfoldLệnh này cài chương trình tensorfold. Nếu máy bạn chưa có Homebrew thì cần cài Homebrew trước (README không hướng dẫn phần này).
C.Cài TensorFold trên Linux có GPU NVIDIA
Trước hết xem driver bằng nvidia-smi, phải là R580 trở lên. Sau đó chạy khối lệnh sau. Nó tự chọn bản theo loại CPU, tải file nén và file kiểm tra, rồi kiểm tra tính toàn vẹn, giải nén và thêm vào PATH:
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 "$@"; }Chỗ người mới hay vấp: hai dòng export PATH=... và tensorfold() {...} chỉ có hiệu lực trong cửa sổ terminal hiện tại. Mở cửa sổ mới là phải chạy lại hai dòng này (trong thư mục có chứa thư mục đã giải nén). README cũng dặn giữ nguyên các thư mục bên trong bản nén, đừng tách riêng.
D.Tải mô hình
Phần khởi động nhanh dùng Qwen3.5-2B bản 4-bit, một mô hình nhỏ. README ghi là đã kiểm tra trên Metal và GB10. Lệnh dưới ghim đúng bản mô hình:
tensorfold pull mlx-community/Qwen3.5-2B-MLX-4bit@93760be4f1f69842a46bc13dbdc0f19e291392a3Lệnh sẽ tải file mô hình về máy, nên cần đợi tuỳ tốc độ mạng.
E.Bật máy chủ
tensorfold serve mlx-community/Qwen3.5-2B-MLX-4bit --name local-model --context 8192 --no-thinkingÝ nghĩa các cờ theo README: --name local-model đặt tên mô hình sẽ dùng khi gọi API; --context 8192 đặt độ dài ngữ cảnh; --no-thinking tắt chế độ "suy nghĩ". Ghi nhớ là sau khi đã pull, bạn gọi serve bằng tên repo, không kèm phần @mã-bản.
Để cửa sổ này chạy, đừng đóng.
F.Gửi thử một yêu cầu
Mở một cửa sổ terminal mới (trên Linux nhớ chạy lại hai dòng PATH nếu cần) rồi chạy:
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}'Địa chỉ 127.0.0.1 nghĩa là chỉ máy bạn gọi được. Chuỗi local-model phải khớp với tên bạn đặt ở bước serve.
IV.Kiểm tra đã chạy được chưa
Có ba dấu hiệu theo tư liệu:
- Lệnh
curlở bước cuối trả về JSON có câu trả lời của mô hình, thay vì báo lỗi kết nối. - Mở
http://127.0.0.1:8080/v1/modelssẽ thấy tênlocal-modeltrong danh sách. README ghi rằng đường dẫn này liệt kê tên mô hình đang phục vụ. - Khi máy chủ khởi động, nó in dòng báo sức chứa, ví dụ
8 streams at oncetrên CUDA. Đó là số luồng đồng thời mà engine đã chấp nhận.
Ngoài ra có thể xem nhanh bằng tensorfold --help, tensorfold capabilities --json và tensorfold serve REPO --help để biết bản của bạn hỗ trợ gì.
V.Dùng vào việc thật
A.Lập trình viên: dựng API AI cục bộ để thử ứng dụng
Bạn đang viết ứng dụng gọi AI và không muốn mỗi lần thử lại tốn tiền hay gửi dữ liệu ra ngoài. Bạn bật tensorfold serve như trên, rồi trỏ code của bạn tới http://127.0.0.1:8080/v1/chat/completions với tên mô hình local-model. Vì API cũng phục vụ completions, Responses và Anthropic Messages, bạn có thể chọn kiểu gọi gần nhất với code đang có.
Kết quả: một môi trường thử nghiệm chạy ngay trên máy, dữ liệu không rời khỏi máy bạn.
Cài một lần, bật một lệnh, và máy của bạn thành một máy chủ AI nhỏ.
Ông T
B.Người dùng Mac: trò chuyện với mô hình qua giao diện web
Bạn không thích gõ curl. Sau khi cài, chạy lệnh:
tensorfold webLệnh này mở TensorFold Web, một ứng dụng web nhỏ chạy cục bộ để chọn mô hình, chạy và chat. README nói nếu cần cài thêm, bản binary tương tác sẽ hỏi bạn và chỉ cài khi bạn đồng ý, bằng uv. Bạn cũng có thể tải app desktop cho Apple Silicon (bản beta) từ trang phát hành, nếu thích dùng ứng dụng có sẵn công cụ tải mô hình và gợi ý theo phần cứng.
Kết quả: có chỗ chat với mô hình cục bộ mà không phải viết dòng code nào.
C.Nhóm nhỏ: cho nhiều người cùng dùng một máy chủ
Một máy Mac hoặc máy Linux GPU mạnh đặt trong văn phòng, vài người cùng gọi. Bạn thêm cờ --parallel N vào lệnh serve để giới hạn số yêu cầu chạy cùng lúc. Yêu cầu dư sẽ xếp hàng, hoàn tất hoặc huỷ một yêu cầu đang chạy sẽ giải phóng chỗ. Nếu không đặt cờ này thì --parallel auto được dùng. Nếu bạn đặt số lớn hơn khả năng, engine từ chối. Khi chưa bật xác thực API, đường dẫn /health báo live.connections (đang chạy cộng đang chờ) và live.waiting (số đang chờ), giúp bạn biết máy đang bận cỡ nào.
Kết quả: biết máy có quá tải không, và hàng đợi hoạt động thế nào.
D.Người thích thử nghiệm: dạy mô hình một dữ kiện mới (Living Weights)
Đây là tính năng thử nghiệm, chỉ nên làm trên bản sao. README hướng dẫn tải mô hình Nemotron 3.5 Lightning, sao chép ra thư mục riêng, tạo khóa và chạy với --slide:
tensorfold pull TensorFold/NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit
hub="${HF_HUB_CACHE:-${HF_HOME:-$HOME/.cache/huggingface}/hub}/models--TensorFold--NVIDIA-Nemotron-3.5-Lightning-30B-A3B-MLX-4bit"
src="$hub/snapshots/$(cat "$hub/refs/main")"
mkdir -p ~/models && cp -RL "$src" ~/models/nemotron-living # always teach a copy
(umask 077; openssl rand -hex 24 > ~/models/slide-key) # --slide starts only with a key
tensorfold serve ~/models/nemotron-living --slide --api-key-file ~/models/slide-keySau đó, ở terminal khác, gửi một "bài học":
curl -N http://127.0.0.1:8080/v1/slide/learn -H "Authorization: Bearer $(cat ~/models/slide-key)" \
-H 'Content-Type: application/json' -d '{"text": "I like blue."}'Bạn cũng có thể gửi cả tài liệu, engine sẽ tự tìm các dữ kiện rồi học từng cái, và mở http://127.0.0.1:8080/slide để xem trực quan 3D. Muốn hoàn tác, dùng tensorfold slide rollback ~/models/nemotron-living, lệnh này trả lại các file gốc, huỷ mọi bài học.
Kết quả: mô hình nhớ được dữ kiện bạn dạy. Nhưng tác giả cảnh báo: các dữ kiện liên quan có thể làm nhiễu nhau, khả năng nhớ giảm khi vượt vài chục dữ kiện hoặc khi bật chế độ suy nghĩ, và trên Mac tốc độ giải mã bị giảm chút ít.
Living Weights ghi đè lên các file của thư mục mô hình, nên luôn dạy trên một bản sao, đừng dạy trên bản gốc. Giữ file khóa (slide-key) kín: README tạo nó với umask 077 để chỉ bạn đọc được.
VI.Lỗi hay gặp và cách xử lý
Máy chủ từ chối khởi động vì driver cũ (Linux). README nói kernel xây bằng CUDA 13 nên TensorFold từ chối driver cũ hơn khi khởi động. Chạy nvidia-smi để xem phiên bản, cần R580 trở lên. Nâng driver rồi chạy lại.
Kiểm tra sha256 báo lỗi. Nếu bước sha256sum -c không báo OK, file tải về có thể bị hỏng hoặc tải dở. Xoá hai file vừa tải và chạy lại các lệnh curl. Không giải nén và chạy file chưa qua kiểm tra.
Gõ tensorfold báo không tìm thấy lệnh (Linux). Thường do bạn mở cửa sổ terminal mới, trong khi dòng export PATH=... và hàm tensorfold() chỉ sống trong cửa sổ cũ. Chạy lại hai dòng đó, đúng thư mục nơi bạn đã giải nén.
curl báo không kết nối được. Có thể máy chủ chưa chạy xong, hoặc bạn đã đóng cửa sổ chạy serve. Kiểm tra cửa sổ serve còn mở và đã tải xong mô hình. Cũng kiểm tra tên mô hình trong yêu cầu có đúng local-model như bạn đặt với --name.
Mac 32 GB không nạp nổi mô hình lớn. README ghi với mô hình Qwen3.8-27B, Mac 32 GB cần nâng iogpu.wired_limit_mb, và thông báo từ chối lúc khởi động sẽ nêu giá trị cần đặt. Hãy đọc kỹ thông báo đó thay vì tự đoán số. Trước khi tải mô hình lớn, chạy tensorfold info REPO để xem mức bộ nhớ tối thiểu.
VII.Có nên dùng không
Điểm mạnh. Một binary, không cần Python hay MLX khi phục vụ. Hỗ trợ Mac Apple Silicon và NVIDIA. Có API tương thích kiểu OpenAI và Anthropic nên dễ ráp vào code sẵn có. Giấy phép Apache-2.0, repo vẫn được cập nhật trong vài tháng gần đây. Danh sách mô hình trong README ghi rõ phần cứng nào đã được kiểm tra, khá trung thực về chỗ chưa kiểm tra.
Giới hạn. Mô hình nhỏ trong phần khởi động nhanh chỉ xử lý văn bản. Nhiều mô hình lớn cần phần cứng đặc thù, ví dụ hai GB10 hoặc hai máy Mac M5 Ultra, và có mô hình README ghi rõ là chưa đủ điều kiện chạy trên một máy Mac. Driver NVIDIA phải đủ mới. Living Weights vẫn là thử nghiệm. App di động còn ở mức bản xem trước. Bảng mô hình trong README khá dày, người mới nên bắt đầu với mô hình nhỏ rồi mới đi lên.
Khi nào chọn cách khác. Nếu bạn chỉ cần chat thỉnh thoảng và không muốn dùng terminal, một app đóng gói sẵn có thể đủ, dù bản app Mac của TensorFold cũng khá gần mục đích đó. Nếu bạn cần mô hình rất lớn mà không có phần cứng phù hợp, dịch vụ đám mây có thể thực tế hơn. Nếu bạn cần quản lý cả tổ chức, hãy xem TensorFold Starlight, README nói rõ nó còn mới và vẫn có những hạng mục kiểm định chưa xong.
Tóm lại: nếu bạn có Mac Apple Silicon hoặc GPU NVIDIA đời mới và muốn chạy AI cục bộ gọn gàng, TensorFold đáng thử, bắt đầu với mô hình 2B trong hướng dẫn.
Câu hỏi thường gặp
TensorFold có miễn phí không?
Mã nguồn TensorFold dùng giấy phép Apache-2.0. Trọng số các mô hình tải về có giấy phép riêng, README nhắc rõ điều này nên bạn cần đọc giấy phép của từng mô hình. Tư liệu không nói gì về phí khác.
Có cần cài Python không?
Theo README, phần phục vụ mô hình không cần Python hay MLX. Riêng lệnh `tensorfold web` có thể đề nghị cài thêm bản web bằng `uv`, và chỉ cài sau khi bạn đồng ý.
Chạy được trên máy nào?
Mac chip Apple Silicon (Metal) và GPU NVIDIA (CUDA). Trên Linux cần glibc 2.28 trở lên và driver R580 trở lên. Với Windows có GPU NVIDIA, README chỉ trỏ tới hướng dẫn build Windows trong repo.
Cần GPU không, RAM bao nhiêu?
Cần Mac Apple Silicon hoặc GPU NVIDIA như README nêu. Mô hình nhỏ Qwen3.5-2B trong phần khởi động nhanh không có mức RAM tối thiểu được công bố. Với mô hình khác, dùng `tensorfold info REPO` để xem mức bộ nhớ tối thiểu.
Gọi bằng API nào?
API phục vụ chat completions, completions, Responses và Anthropic Messages. Mặc định ví dụ gọi tới `http://127.0.0.1:8080/v1/chat/completions`, và `/v1/models` liệt kê tên mô hình đang phục vụ.
Dữ liệu của tôi có an toàn không?
Ví dụ trong README chạy máy chủ ở địa chỉ cục bộ 127.0.0.1 và mô hình chạy trên máy bạn. Tư liệu chưa có phần đánh giá bảo mật chi tiết ở đoạn mình đọc; repo có file SECURITY.md để bạn xem thêm.
Living Weights có dùng được trong công việc thật không?
Tác giả ghi đây là tính năng thử nghiệm. Các dữ kiện liên quan có thể làm nhiễu nhau, khả năng nhớ giảm sau vài chục dữ kiện hoặc khi bật chế độ suy nghĩ. Bạn nên dạy trên bản sao và có thể hoàn tác bằng `tensorfold slide rollback`.


