Chạy Qwen3.8-27B với TensorFold: hướng dẫn Mac, NVIDIA và API

Muốn chạy Qwen3.8-27B trên máy cá nhân và kết nối nó với ứng dụng qua API? TensorFold cung cấp engine suy luận cho Apple Silicon và GPU NVIDIA, với endpoint tương thích OpenAI. Cùng một checkpoint Vontra/Qwen3.8-27B-MLX-4bit có thể được đọc bởi cả backend MLX lẫn CUDA của dự án.[1]

Đừng nhầm tên: bài này hướng dẫn TensorFold, dự án tại ashhart/TensorFold, không phải framework TensorFlow. Backend của TensorFold là MLX hoặc CUDA; hướng dẫn NVIDIA dùng container PyTorch của NVIDIA, không cài TensorFlow.[1][2]

Phạm vi kiểm chứng: AIDaLat đối chiếu README, runbook, recipe Qwen3.8-27B, API và khai báo phụ thuộc ngày 01/10/2026. Mã nguồn tham chiếu: c4646171139ee8a3c38103eaa1699dad226ec12b. Bài hướng dẫn chưa được kiểm thử suy luận trên Mac/GPU NVIDIA bởi AIDaLat, không cung cấp đầu ra server hay số đo tự dựng. Tài liệu nhánh main có thể mới hơn phần README mà trang GitHub hiển thị; kiểm tra revision khi tái lập.

1. Kiểm tra máy có phù hợp không

TensorFold yêu cầu Python 3.11 trở lên. Với Mac, sử dụng Apple Silicon và để pip cài MLX trong khoảng phiên bản mà package quy định. Với NVIDIA, README hiện yêu cầu compute capability 8.9 trở lên cho các kernel CUDA: Ada/RTX 40, Hopper và Blackwell, gồm DGX Spark GB10 và RTX 50. RTX 30 với compute capability 8.6 không được hỗ trợ; checkpoint NVFP4/FP8 yêu cầu mức 9.0 trở lên.[1][5]

Máy bạn đang dùng	Lộ trình trong bài
Mac Apple Silicon	Python venv → MLX → checkpoint MLX 4-bit
Linux có NVIDIA tương thích	Container NVIDIA PyTorch → CUDA → checkpoint MLX 4-bit
Windows/WSL	Chỉ xem xét lộ trình CUDA nếu GPU được nhận trong Linux/container; bài này không bảo đảm Windows native hoặc mọi cấu hình WSL
Không có Apple Silicon hoặc GPU NVIDIA phù hợp	Không tiếp tục theo hai lộ trình này; dùng máy/cloud có phần cứng phù hợp

Có đủ chỗ chứa model chưa có nghĩa là đủ bộ nhớ để chạy. Bộ nhớ còn dành cho drafter, KV cache, recurrent state, prompt và workspace. MLX mặc định đặt ngân sách tiến trình khoảng 70% RAM; README lưu ý Qwen3.8-27B trên Mac 32 GB cần vượt ngân sách mặc định 22,4 GiB, dù có hay không có DFlash2.[1]

Khuyến nghị thực hành: bắt đầu với context 8.192 token, trả lời tối đa 512–1.024 token, một request tại một thời điểm. Đây là cấu hình khởi đầu để thử, không phải lời hứa rằng mọi máy đều chạy được. Nếu startup từ chối vì thiếu bộ nhớ, giảm context hoặc dùng phần cứng nhiều bộ nhớ hơn; không ép tải bằng cách bỏ qua kiểm tra.

2. Hiểu model chính và DFlash2

Lộ trình chuẩn trong recipe dùng:[3]

Model chính: Vontra/Qwen3.8-27B-MLX-4bit.
Model đề xuất token: z-lab/Qwen3.8-27B-DFlash2.

DFlash2 dự đoán các token tiếp theo; model chính xác minh từng token. Theo thiết kế của TensorFold, token đề xuất chỉ được chấp nhận nếu trùng token mà cùng engine sinh theo đường tuần tự. “Exact” ở đây áp dụng với cùng engine, weights, runtime và thiết lập, không có nghĩa bản lượng tử này giống bản gốc, hay MLX cho đầu ra giống CUDA.[1][3]

Trên MLX, DFlash2 là tùy chọn và được dùng tự động khi đã tải. Trên CUDA, Qwen3.8-27B cần DFlash2 nếu bật drafting; muốn chạy tuần tự thì phải chọn rõ --no-drafts. --drafter none tắt drafter tùy chọn trên MLX, còn --no-drafts tắt toàn bộ drafting trên cả hai backend.[3]

3. Cài trên Mac Apple Silicon

Bước 1: Tạo môi trường riêng

Mở Terminal và chạy:

mkdir -p ~/qwen-tensorfold
cd ~/qwen-tensorfold
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install "git+https://github.com/ashhart/TensorFold.git@c4646171139ee8a3c38103eaa1699dad226ec12b"
tensorfold --version
tensorfold models

Runbook dùng cài trực tiếp từ GitHub. Bài viết thêm revision cố định để tránh lệnh cài thay đổi theo nhánh main; khi muốn phiên bản mới, đọc release và yêu cầu phụ thuộc trước. Không nâng MLX riêng ra ngoài khoảng phiên bản trong pyproject.toml.[2][5]

Bước 2: Kiểm tra cấu hình rồi tải weights

tensorfold info Vontra/Qwen3.8-27B-MLX-4bit
tensorfold pull Vontra/Qwen3.8-27B-MLX-4bit z-lab/Qwen3.8-27B-DFlash2

info chỉ đọc cấu hình, không tải toàn bộ weights. pull tải trước; serve cũng có thể hoàn tất phần tải còn thiếu. Kiểm tra dung lượng ổ đĩa trước bước này.[1][2]

Bước 3: Khởi động server

tensorfold serve Vontra/Qwen3.8-27B-MLX-4bit \
  --backend mlx \
  --name qwen38-27b \
  --host 127.0.0.1 \
  --port 8080 \
  --context 8192 \
  --max-tokens 1024 \
  --parallel 1

Giữ terminal này mở. Đọc log về checkpoint, drafter và context thực sự được chấp nhận trước khi gọi client. Các cờ --name, --context, --max-tokens và --parallel thuộc giao diện phục vụ model của dự án.[1]

Để bỏ drafter tùy chọn trên Mac, thêm --drafter none vào lệnh trên. Để kiểm thử đường tuần tự hoàn toàn, dùng --no-drafts.[3]

4. Cài trên Linux với NVIDIA CUDA

Bước 1: Xác minh GPU và container runtime

nvidia-smi

Máy cần Docker cùng cấu hình NVIDIA Container Toolkit để container nhận GPU. Nếu nvidia-smi không nhận card hoặc compute capability không đạt yêu cầu, giải quyết phần môi trường trước; cài thêm package Python không khắc phục được phần cứng không hỗ trợ.

README khuyên dùng container nvcr.io/nvidia/pytorch:26.07-py3 để có CUDA, PyTorch, Triton và trình biên dịch extension phù hợp. Không có extra tensorfold[cuda]; cài TensorFold trong container mà không thay toolchain của container.[1][2]

Bước 2: Chạy container và lưu cache ra máy chủ

Lệnh dưới đây điều chỉnh mẫu Linux của dự án: dùng ánh xạ cổng localhost và volume để giữ cache tải model.

mkdir -p "$HOME/.cache/huggingface-tensorfold"
docker run -it --gpus all --ipc=host \
  --name tensorfold-qwen27b \
  -p 127.0.0.1:8080:8080 \
  -v "$HOME/.cache/huggingface-tensorfold:/root/.cache/huggingface" \
  nvcr.io/nvidia/pytorch:26.07-py3

Đây là lệnh Linux shell, không phải lệnh PowerShell. Container có tên được giữ lại sau khi thoát; tránh xóa container nếu muốn giữ cả package đã cài. Runbook lưu ý cache và cài đặt không persist sẽ mất khi container bị xóa.[2]

Bước 3: Cài và khởi động bên trong container

python -m pip install "git+https://github.com/ashhart/TensorFold.git@c4646171139ee8a3c38103eaa1699dad226ec12b"
tensorfold --version
tensorfold info Vontra/Qwen3.8-27B-MLX-4bit
tensorfold pull Vontra/Qwen3.8-27B-MLX-4bit z-lab/Qwen3.8-27B-DFlash2

tensorfold serve Vontra/Qwen3.8-27B-MLX-4bit \
  --backend cuda \
  --name qwen38-27b \
  --host 0.0.0.0 \
  --port 8080 \
  --context 8192 \
  --max-tokens 1024 \
  --parallel 1

0.0.0.0 ở đây nằm trong container, để cổng được publish; phía host chỉ bind 127.0.0.1 theo lệnh Docker trên. Lần khởi động đầu biên dịch kernel, nên có thể lâu hơn các lần sau.[2]

Muốn mở lại container đã dừng:

docker start -ai tensorfold-qwen27b

Sau đó chạy lại lệnh tensorfold serve bên trong. Muốn chạy CUDA không dùng DFlash2, bỏ bước tải drafter và thêm --no-drafts vào lệnh serve.[3]

Không chọn NVFP4 chỉ vì tên nghe tối ưu hơn. Recipe còn có NVFP4 và EXL3, nhưng mỗi định dạng có giới hạn khác nhau; NVFP4 trong recipe là đường một GPU, còn EXL3 được ghi rõ thử nghiệm. Bắt đầu với checkpoint MLX 4-bit được tài liệu dùng cho cả Mac và CUDA.[1][3]

5. Kiểm tra API trước khi kết nối ứng dụng

Mở terminal thứ hai trên máy host:

curl -fsS http://127.0.0.1:8080/health
curl -fsS http://127.0.0.1:8080/v1/models

Đây là các endpoint kiểm tra trong runbook. Vì bài khởi động với --name qwen38-27b, dùng tên này ở request; nếu không đặt --name, lấy ID thật từ /v1/models.[2]

Gửi câu hỏi đầu tiên:

curl -fsS http://127.0.0.1:8080/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{"model":"qwen38-27b","messages":[{"role":"user","content":"Giải thích speculative decoding bằng tiếng Việt trong 5 câu."}],"max_tokens":512,"temperature":0}'

Lệnh là ví dụ request, không phải đầu ra đã đo. Model có thể tách reasoning khỏi câu trả lời; xem cả reasoning_content và content khi chẩn đoán, thay vì kết luận model không trả lời chỉ vì trường content trống.[2][4]

Nếu kiểm tra từ Windows PowerShell, dùng curl.exe cho hai request GET để tránh nhầm alias:

curl.exe http://127.0.0.1:8080/health
curl.exe http://127.0.0.1:8080/v1/models

Khả năng truy cập localhost từ Windows vào WSL/container phụ thuộc thiết lập mạng của máy. Hãy xác minh endpoint ngay trong Linux host trước.

6. Gọi từ Python với OpenAI SDK

Tạo môi trường client riêng trên máy host, không cần thay môi trường server:

python3 -m venv client-env
source client-env/bin/activate
python -m pip install openai

Lưu thành test_tensorfold.py:

from openai import OpenAI

client = OpenAI(
    base_url="http://127.0.0.1:8080/v1",
    api_key="local-placeholder",
)

response = client.chat.completions.create(
    model="qwen38-27b",
    messages=[{
        "role": "user",
        "content": "Viết một hàm Python loại bỏ phần tử trùng nhưng giữ thứ tự.",
    }],
    temperature=0,
    max_tokens=1024,
)
message = response.choices[0].message
print(message.content or "(Không có content; kiểm tra reasoning và giới hạn token.)")

Chạy python test_tensorfold.py. local-placeholder là chuỗi để khởi tạo SDK, không phải cơ chế bảo vệ server. Ví dụ điều chỉnh theo API tương thích OpenAI của dự án và chưa được AIDaLat kiểm thử với server suy luận thật.[1][4]

Với ứng dụng hỗ trợ OpenAI-compatible, nhập:

Base URL: http://127.0.0.1:8080/v1.
Model: qwen38-27b hoặc ID thật từ /v1/models.
API key: theo yêu cầu client/proxy đang dùng; không mặc định chuỗi giả tạo ra xác thực.

7. Tối ưu mà không đánh đồng tốc độ với chất lượng

Context: prompt cộng reply phải nằm trong dung lượng được chấp nhận. Nếu thiếu bộ nhớ, giảm context và giới hạn reply trước.[1][2]
Concurrency: CUDA --parallel auto là một request; đặt N lớn hơn một mới bật shared rounds ở họ model được hỗ trợ. Tăng N làm tăng áp lực bộ nhớ, nên chưa dùng ngay ở lần khởi động đầu.[1]
Drafting: so cùng request với "draft": false để kiểm tra drafted và serial output trong cùng môi trường. Không dùng kết quả này để tuyên bố model lượng tử giống mọi runtime khác.[1][4]
Prefill precision: --prefill-fp8 đổi prompt matmul sang activation FP8 ở đường hỗ trợ; đây là thay đổi độ chính xác tính toán, không phải tăng tốc miễn phí. Mặc định CUDA dùng bf16 activation theo README.[1][3]
RAM Mac: TENSORFOLD_MEMORY_LIMIT_GB thay ngân sách tiến trình theo GiB, vẫn bị giới hạn bởi RAM thật và GPU working set. Không sao chép mức ngân sách của Mac 128 GB sang Mac 32 GB.[1][2]

Recipe công bố benchmark theo phần cứng, checkpoint và điều kiện đo cụ thể. Bài này không lấy một con số token/s làm lời hứa cho mọi Mac hoặc RTX: nên đo riêng thời gian xử lý prompt, thời gian token đầu tiên và tốc độ sinh reply trên máy của bạn.[3]

8. Xử lý lỗi thường gặp

Hiện tượng	Việc cần kiểm tra
`tensorfold: command not found`	Kích hoạt đúng venv; NVIDIA phải chạy trong container đã cài package
`info` chạy được nhưng `serve` vẫn tải	`info` chỉ kiểm tra cấu hình, chưa tải weights
CUDA báo thiếu drafter	Tải DFlash2 hoặc chọn `--no-drafts`
Startup từ chối checkpoint	Kiểm tra kiến trúc GPU, định dạng quantization và checkpoint ID
Thiếu bộ nhớ/context không fit	Giảm context, reply và parallel; đọc hướng dẫn fitting trong log
Client không kết nối	Kiểm tra tiến trình, `/health`, cổng Docker và base URL
Không thấy answer trong content	Kiểm tra reasoning và token budget của request

Những kiểm tra này dựa trên runbook và API, không thay thế log thực tế.[2][4]

Nếu CUDA dừng sau dòng loading trong khi GPU idle, runbook có cách in Python stack: kill -USR1 <pid>. Nếu stack chỉ ra chờ khóa biên dịch extension, chỉ xử lý khóa khi chắc chắn không có tiến trình build khác đang chạy, sau khi dừng lần startup bị kẹt. Không xóa tùy tiện cache hoặc lock của tiến trình đang hoạt động.[2]

9. Giữ endpoint riêng tư và cập nhật có kiểm soát

Giữ 127.0.0.1 cho dùng cá nhân. Nếu cần truy cập từ xa, dùng tunnel riêng hoặc reverse proxy có TLS, xác thực và giới hạn truy cập. Không mở trực tiếp cổng API ra Internet chỉ vì đã nhập một API key giả trong SDK.

Để kiểm tra cập nhật, dự án có tensorfold update --check; tensorfold update cài bản mới và cần khởi động lại server. Với CUDA, cập nhật bên trong container. Lưu revision/phiên bản trước khi cập nhật để biết bạn còn tái lập được cấu hình nào.[1][2]

Tóm lại: chọn backend đúng phần cứng, bắt đầu với Vontra/Qwen3.8-27B-MLX-4bit, tải DFlash2 nếu dùng CUDA drafting, xác minh /health và /v1/models, rồi mới kết nối ứng dụng. TensorFold không phải TensorFlow và không biến một máy thiếu GPU/RAM thành máy chạy 27B chỉ bằng vài lệnh cài đặt.

Xem thêm: Chạy Qwen3.8-Flash-Next trên PC với Strata — một engine và mô hình khác, không nên trộn yêu cầu phần cứng hay lệnh cài với hướng dẫn TensorFold này.

Sources

[1] https://github.com/ashhart/TensorFold/blob/main/README.md [2] https://github.com/ashhart/TensorFold/blob/main/RUNBOOK.md [3] https://github.com/ashhart/TensorFold/blob/main/docs/recipes/qwen3.8-27b.md [4] https://github.com/ashhart/TensorFold/blob/main/docs/api.md [5] https://github.com/ashhart/TensorFold/blob/main/pyproject.toml