# 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

> 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.

- Tác giả: Ông T (https://ongt.vn/gioi-thieu)
- Chủ đề: Repo & Skill
- Đăng: 2026-07-31 · Cập nhật: 2026-11-14
- URL: https://ongt.vn/bai-viet/tensorfold-chay-mo-hinh-ai-cuc-bo-mac-nvidia

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.

```repo
- repo | ashhart/TensorFold
- kind | Ứng dụng
- desc | 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.
- stars | 2k
- lang | Zig
- license | Apache-2.0
```

## 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.

## 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 Silicon**: cà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 NVIDIA**: có hai bản, `linux-aarch64` cho GB10 và `linux-x86_64` cho 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ùng `nvidia-smi` để xem driver hiện tại.
- **Windows với GPU NVIDIA**: README 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`, `sha256sum` và `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 key**: phầ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.

```note
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.
```

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

```steps
- Mở terminal | Dùng Terminal trên Mac hoặc shell trên Linux
- Cài TensorFold | Mac dùng Homebrew; Linux tải bản nén, kiểm tra sha256 rồi giải nén
- Tải mô hình | Chạ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ầu | Dùng curl ở terminal thứ hai
```

### 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.

### Cài TensorFold trên Mac Apple Silicon

Cài bằng Homebrew:

```bash
brew install ashhart/tensorfold/tensorfold
```

Lệ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à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:

```bash
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.

### 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:

```bash
tensorfold pull mlx-community/Qwen3.5-2B-MLX-4bit@93760be4f1f69842a46bc13dbdc0f19e291392a3
```

Lệnh sẽ tải file mô hình về máy, nên cần đợi tuỳ tốc độ mạng.

### Bật máy chủ

```bash
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.

### 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:

```bash
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.

## Kiểm tra đã chạy được chưa

Có ba dấu hiệu theo tư liệu:

1. 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.
2. Mở `http://127.0.0.1:8080/v1/models` sẽ thấy tên `local-model` trong danh sách. README ghi rằng đường dẫn này liệt kê tên mô hình đang phục vụ.
3. Khi máy chủ khởi động, nó in dòng báo sức chứa, ví dụ `8 streams at once` trê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ì.

## Dùng vào việc thật

### 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

### 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:

```bash
tensorfold web
```

Lệ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.

### 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.

### 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`:

```bash
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-key
```

Sau đó, ở terminal khác, gửi một "bài học":

```bash
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.

```note
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.
```

## 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.

## 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`.
