# 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

> TensorFold là một engine chạy mô hình ngôn ngữ (LLM) ngay trên máy của bạn, dùng Metal trên Mac Apple Silicon hoặc CUDA trên card NVIDIA. Nó mở một máy chủ API cục bộ để các công cụ khác gọi vào, và phần chạy không cần cài Python hay MLX. Trên Mac, cài chỉ bằng Homebrew nên khá dễ; trên Linux cần tải bản phát hành và có driver NVIDIA đủ mới.

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

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. Nó là một chương trình viết bằng ngôn ngữ Zig, đọc file mô hình, xử lý câu hỏi rồi chạy thẳng trên Metal (Mac Apple Silicon) hoặc CUDA (card NVIDIA). Theo README, phần chạy mô hình không cần cài Python hay MLX.

Nếu bạn muốn có một "ChatGPT riêng" chạy trong máy, không gửi dữ liệu ra ngoài, thì đây là một lựa chọn đáng xem. Nó phù hợp với lập trình viên cần một API cục bộ để gắn vào ứng dụng của mình, hoặc người làm văn phòng có Mac đời mới muốn thử mô hình AI offline. Repo hiện có khoảng 2048 sao và 399 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 là cách cài rất gọn: trên Mac chỉ cần Homebrew, rồi hai lệnh là mô hình chạy và trả lời qua một địa chỉ API quen thuộc. Bài này đi theo đúng ví dụ nhỏ nhất trong README (mô hình Qwen3.5-2B) để bạn chạy được trước, rồi mới tính chuyện mô hình lớn hơn.

```repo
- repo | ashhart/TensorFold
- kind | Ứng dụng
- desc | TensorFold là engine viết bằng Zig, chạy mô hình ngôn ngữ 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 cục bộ trên Mac và card NVIDIA.** Engine đọc checkpoint, tách từ (tokenize) yêu cầu và chạy kernel Metal hoặc CUDA trực tiếp. Lợi ích thực tế: bạn không phải dựng môi trường Python phức tạp, thứ hay làm người mới nản.

**Máy chủ API dùng chung giao thức quen thuộc.** README cho biết API có phục vụ chat completions, completions, Responses và Anthropic Messages. Nghĩa là nhiều công cụ đã biết nói chuyện với OpenAI hoặc Anthropic có thể trỏ sang máy chủ cục bộ của bạn. Địa chỉ `/v1/models` liệt kê tên mô hình đang phục vụ.

**Tải mô hình bằng một lệnh.** Lệnh `tensorfold pull` tải mô hình về, có thể ghim đúng một phiên bản (revision) để lần nào tải cũng ra cùng một bản. Bạn cũng có thể phục vụ một thư mục checkpoint đầy đủ có sẵn trong máy hoặc dùng lại bộ nhớ đệm Hugging Face.

**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 mô hình, chạy và trò chuyện. Ngoài ra có ứng dụng desktop cho Mac gộp sẵn engine, tải mô hình, gợi ý theo phần cứng và số đo tốc độ khi sinh chữ.

**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 chế độ `auto` và xin tối đa tám luồng tuỳ bộ nhớ.

**Nhiều mô hình được ghi nhận.** README có bảng các mô hình đã kiểm tra: Qwen, Nemotron, GLM… với thông tin máy nào đã thử. Bảng cho thấy rất rõ chỗ nào đã kiểm chứng, chỗ nào chưa.

**Tính năng thử nghiệm.** Có "Living Weights" (dạy mô hình sự kiện mới, README ghi rõ là experimental) và TensorFold Starlight cho doanh nghiệp (repo riêng). Người mới có thể bỏ qua cả hai ở giai đoạn đầu.

## Cần chuẩn bị gì

Theo README, bạn cần một trong các cấu hình sau:

- **Mac Apple Silicon:** cài được Homebrew. README không nêu mức RAM tối thiểu cho mô hình nhỏ Qwen3.5-2B (ghi "no RAM minimum published"). Lệnh `tensorfold info REPO` sẽ báo mức bộ nhớ tối thiểu của từng mô hình.
- **Linux có card NVIDIA:** glibc 2.28 trở lên, driver NVIDIA R580 trở lên (CUDA 13.0) có `libcuda.so.1`. Kernel được build bằng CUDA 13 nên TensorFold từ chối chạy nếu driver cũ hơn. Gõ `nvidia-smi` để xem driver bạn đang có. Có hai bản: `linux-aarch64` (cho GB10) và `linux-x86_64`.
- **Windows có card NVIDIA:** README chỉ nói làm theo hướng dẫn build Windows riêng (native Windows build guide) trong repo; mình không có chi tiết hơn.
- **Kết nối mạng và dung lượng ổ đĩa** để tải mô hình. README không ghi dung lượng của mô hình 2B.
- **Terminal:** Terminal trên Mac hoặc shell trên Linux. Bạn cần một cửa sổ cho máy chủ và một cửa sổ khác để gửi thử câu hỏi.

Lưu ý: trọng số mô hình có giấy phép riêng, tách khỏi giấy phép Apache-2.0 của TensorFold. Muốn dùng cho kinh doanh, bạn nên đọc giấy phép của mô hình cụ thể.

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

```steps
- Cài TensorFold | Mac dùng Homebrew; Linux tải bản phát hành và kiểm tra checksum
- Tải mô hình | Dùng tensorfold pull để lấy mô hình Qwen3.5-2B 4-bit
- Chạy máy chủ | Dùng tensorfold serve, đặt tên mô hình là local-model
- Gửi thử câu hỏi | Dùng curl ở cửa sổ terminal thứ hai
```

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

Mở ứng dụng Terminal và chạy lệnh Homebrew dưới đây. Lệnh này cài chương trình `tensorfold` từ kho riêng của tác giả.

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

Nếu máy báo không có lệnh `brew`, nghĩa là bạn chưa cài Homebrew. README không hướng dẫn cài Homebrew, bạn cần cài nó từ trang chính thức của Homebrew trước.

### Cài trên Linux có card NVIDIA

Trên Linux, README dùng bản nén phát hành. Đoạn lệnh dưới đây tự chọn bản đúng với CPU, tải file kèm file checksum, kiểm tra toàn vẹn, giải nén rồi thêm thư mục `bin` vào PATH. Hãy chạy cả đoạn trong cùng một cửa sổ terminal, vì lệnh `export` và hàm `tensorfold` chỉ có hiệu lực trong cửa sổ đó.

```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 "$@"; }
```

Dòng `sha256sum -c` kiểm tra file tải về có đúng bản gốc không; nó phải in `OK`. Hãy giữ nguyên các thư mục trong bản nén, đừng tách riêng file chạy ra. Dòng cuối tạo hàm `tensorfold` gọi tới `tensorfold-native`, nên các lệnh phía sau dùng được y như trên Mac.

### Tải mô hình

Lệnh dưới tải mô hình Qwen3.5-2B 4-bit ở đúng phiên bản được ghim. Đây là mô hình nhỏ mà README dùng để thử trên Mac (Metal) và GB10.

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

Phần sau dấu `@` là mã phiên bản. Lần tải đầu mất thời gian tuỳ đường truyền.

### Chạy máy chủ

Sau khi tải xong, chạy máy chủ. Lúc này hãy dùng tên mô hình không kèm phần `@...`, như README dặn.

```bash
tensorfold serve mlx-community/Qwen3.5-2B-MLX-4bit --name local-model --context 8192 --no-thinking
```

Giải thích nhanh: `--name local-model` đặt tên để các ứng dụng gọi vào; `--context 8192` đặt độ dài ngữ cảnh; `--no-thinking` tắt chế độ "suy nghĩ" của mô hình. Cửa sổ này sẽ đứng chờ, đó là bình thường. Đừng đóng nó.

### Gửi thử một câu hỏi

Mở một cửa sổ terminal thứ hai và chạy lệnh sau. Địa chỉ mặc định theo README là cổng 8080 trên máy bạn.

```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}'
```

Chỗ người mới hay vấp: nếu bạn mở cửa sổ mới trên Linux, hàm `tensorfold` và PATH ở bước cài có thể chưa còn. Khi đó hãy làm lại hai dòng `export` và hàm trong cửa sổ đó.

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

Có ba cách kiểm tra, đều theo README:

1. Lệnh `curl` ở trên trả về một phản hồi JSON chứa câu chào của mô hình. Đó là dấu hiệu rõ nhất là cả chuỗi đã chạy được.
2. Mở danh sách mô hình đang phục vụ để thấy tên `local-model`:

```bash
curl -fsS http://127.0.0.1:8080/v1/models
```

3. Xem khả năng của bản cài bằng các lệnh trợ giúp:

```bash
tensorfold --help
tensorfold capabilities --json
```

Trên Linux, nếu driver NVIDIA quá cũ, TensorFold sẽ từ chối khởi động ngay và báo lỗi ở cửa sổ máy chủ. Trên card NVIDIA, dòng khởi động có thể in số luồng chạy cùng lúc, ví dụ `8 streams at once`, đó là số engine đã chấp nhận.

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

### Dev gắn mô hình cục bộ vào ứng dụng của mình

Bạn là lập trình viên đang viết một công cụ nội bộ cần gọi LLM nhưng không muốn trả tiền theo token trong lúc thử nghiệm. Bạn chạy `tensorfold serve` như trên, rồi cho ứng dụng gọi vào địa chỉ `http://127.0.0.1:8080/v1/chat/completions` với `"model":"local-model"`. Vì API có dạng quen thuộc, phần lớn mã gọi OpenAI chỉ cần đổi địa chỉ. Kết quả là bạn có môi trường thử miễn phí, chạy offline.

> Mô hình chạy trong máy bạn, câu hỏi cũng ở lại trong máy bạn.
>
> — Ông T

### Nhân viên văn phòng thử AI trên Mac, không gửi dữ liệu ra ngoài

Bạn làm kế toán hoặc hành chính, có chút văn bản nội bộ không muốn dán lên dịch vụ trực tuyến. Bạn cài TensorFold bằng Homebrew rồi chạy:

```bash
tensorfold web
```

README mô tả đây là ứng dụng web nhỏ chạy cục bộ để chọn mô hình, chạy và trò chuyện. Nếu cần cài thêm, bản release tương tác sẽ hỏi trước khi cài bản phù hợp bằng `uv`. Bạn nhớ rằng mô hình 2B khá nhỏ, nên hợp với việc đơn giản như viết lại câu, soạn nháp ngắn hơn là phân tích tài liệu phức tạp.

### Chủ shop muốn chạy nhiều yêu cầu cùng lúc

Bạn dựng chatbot nội bộ cho vài nhân viên cùng hỏi. Máy chủ mặc định dùng `--parallel auto` và xin tối đa tám luồng tuỳ bộ nhớ. Nếu muốn giới hạn để máy không quá tải, bạn đặt số cụ thể:

```bash
tensorfold serve mlx-community/Qwen3.5-2B-MLX-4bit --name local-model --context 8192 --no-thinking --parallel 4
```

Yêu cầu thứ năm sẽ chờ đến khi có chỗ trống. README cũng nói nếu bạn đặt số mà engine không đủ bộ nhớ để chạy, nó sẽ từ chối thay vì chạy chập chờn.

### Chọn mô hình lớn hơn theo máy của bạn

Khi đã quen, bạn xem bảng "Pick a model" trong README và chọn mô hình hợp máy. Trước khi tải mô hình lớn, hãy hỏi mức bộ nhớ tối thiểu:

```bash
tensorfold info REPO
```

Thay `REPO` bằng tên mô hình. Lệnh này báo mức bộ nhớ tối thiểu của checkpoint, giúp bạn tránh tải cả chục GB rồi mới biết máy không đủ.

```note
Chỉ nên mở máy chủ trên địa chỉ 127.0.0.1 (chỉ máy bạn truy cập được). Nếu sau này đưa ra mạng nội bộ, hãy xem tài liệu về xác thực API của TensorFold trước. Tính năng thử nghiệm Living Weights ghi thẳng vào file mô hình, nên README dặn luôn dạy trên một bản sao.
```

## Lỗi hay gặp và cách xử lý

**Báo không tìm thấy lệnh `tensorfold` trên Linux.** Thường do bạn đã mở cửa sổ terminal mới, nên PATH và hàm `tensorfold` ở bước cài không còn. Chạy lại hai dòng `export PATH=...` và `tensorfold() {...}` trong cửa sổ đó.

**TensorFold từ chối khởi động vì driver.** Bản Linux dùng kernel CUDA 13, yêu cầu driver R580 trở lên. Gõ `nvidia-smi` xem driver hiện tại, nếu cũ hơn thì cập nhật driver rồi chạy lại. Đừng cố chạy bản không khớp.

**Kiểm tra checksum không báo OK.** File tải về có thể hỏng hoặc không trọn vẹn. Hãy xoá file và chạy lại hai lệnh `curl`, đừng giải nén file không qua được bước kiểm tra này.

**Mô hình lớn không nạp được trên Mac 32 GB.** Với một số mô hình lớn, README ghi rằng Mac 32 GB cần tăng giá trị `iogpu.wired_limit_mb`, và thông báo từ chối lúc khởi động sẽ nêu rõ giá trị cần đặt. Hãy đọc kỹ thông báo đó trước khi chỉnh. Với người mới, nên bắt đầu bằng mô hình nhỏ.

**`curl` báo không kết nối được.** Kiểm tra cửa sổ máy chủ còn chạy không, và tên trong phần `"model"` có đúng là `local-model` (hoặc tên bạn đặt bằng `--name`) không. Có thể mô hình còn đang nạp, hãy chờ dòng báo sẵn sàng rồi thử lại.

## Có nên dùng không

**Điểm mạnh.** Cài đặt gọn (Homebrew trên Mac), không cần Python để chạy, API cục bộ dùng được với nhiều công cụ, giấy phép Apache-2.0 và README ghi rất rõ máy nào đã được kiểm tra. Dữ liệu chạy trong máy bạn nên hợp với nhu cầu riêng tư.

**Giới hạn.** Phạm vi hỗ trợ là Mac Apple Silicon và card NVIDIA; Windows phải theo hướng dẫn build riêng, còn người chỉ có máy không có GPU phù hợp thì README không nói cách dùng. Mô hình lớn cần nhiều bộ nhớ và README còn ghi nhiều mục "chưa qualified" cho một số phần cứng. Các tính năng như Living Weights là thử nghiệm. Mô hình nhỏ như 2B chỉ xử lý văn bản và chất lượng không bằng các dịch vụ lớn.

**Khi nên chọn cách khác.** Nếu bạn chỉ cần hỏi đáp thỉnh thoảng và không quan tâm riêng tư, dịch vụ AI trực tuyến sẽ nhanh gọn hơn. Nếu máy bạn không phải Mac Apple Silicon hay card NVIDIA, hãy tìm công cụ khác phù hợp phần cứng. Còn nếu bạn có Mac đời mới hoặc card NVIDIA đủ mạnh và muốn một máy chủ AI cục bộ gọn nhẹ, TensorFold rất đáng thử.

## 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 trọng số mô hình có giấy phép riêng, README nhắc rõ điều này. Bạn nên đọc giấy phép của từng mô hình trước khi dùng cho mục đích kinh doanh.

### TensorFold có cần cài Python không?

Theo README, phần chạy mô hình không cần Python hay MLX. Riêng ứng dụng TensorFold Web, nếu cần cài thì bản release tương tác sẽ hỏi bạn rồi cài bằng `uv`.

### Có cần card đồ hoạ (GPU) không?

TensorFold chạy trên GPU của Mac Apple Silicon (Metal) hoặc card NVIDIA (CUDA). README không nói về chế độ chạy chỉ bằng CPU thông thường, nên chưa có thông tin về trường hợp đó.

### Chạy được trên Windows không?

Với Windows có card NVIDIA, README bảo làm theo hướng dẫn build Windows (native Windows build guide) có trong repo. Phần Quick start chỉ có hướng dẫn chi tiết cho Mac và Linux.

### Dữ liệu của tôi có an toàn không?

Engine chạy mô hình ngay trên máy bạn, và máy chủ mặc định nghe ở địa chỉ 127.0.0.1 trong ví dụ của README. README không nói chi tiết về chính sách dữ liệu khác, nên nếu cần mở ra mạng, bạn nên đọc tài liệu bảo mật của repo (có file SECURITY.md).

### Cần máy mạnh cỡ nào?

Với mô hình Qwen3.5-2B dùng trong bài, README không công bố mức RAM tối thiểu. Với mô hình lớn hơn, hãy dùng lệnh `tensorfold info REPO` để xem mức bộ nhớ tối thiểu trước khi tải.

### Tôi dùng được các ứng dụng đã có với TensorFold không?

README cho biết API phục vụ chat completions, completions, Responses và Anthropic Messages. Vì vậy các công cụ nói được giao thức đó có thể trỏ vào địa chỉ cục bộ. Danh sách công cụ cụ thể đã được thử thì chưa có trong phần README mình đọc.
