Hướng dẫn AI

Chạy Qwen3.8 Flash Next trên một DGX Spark duy nhất với TensorFold

Tìm hiểu cách cài đặt, khởi chạy, kiểm thử và tinh chỉnh Qwen3.8 Flash Next trên một NVIDIA DGX Spark duy nhất. Hướng dẫn này đề cập đến các tập lệnh triển khai TensorFold, yêu cầu trò chuyện tương thích với OpenAI, đầu vào hình ảnh và video, các tùy chọn điều khiển suy luận, cấu hình bộ nhớ, giám sát và kiểm tra hiệu năng.

29 tháng 9, 2026Thời gian đọc khoảng 27 phút

Chạy Qwen3.8 Flash Next trên một DGX Spark với TensorFold

Tổng quan

Dự án này cung cấp Qwen3.8 Flash Next từ một NVIDIA DGX Spark thông qua API tương thích với OpenAI. Dự án sử dụng TensorFold v0.3.6.3, một checkpoint MLX 4-bit với đầu head dự đoán MTP, cùng một bộ bản vá được thiết kế để tăng tốc xử lý prompt mà không thay đổi văn bản được tạo ra.

Cấu hình mặc định hỗ trợ năm yêu cầu đồng thời, mỗi yêu cầu có toàn bộ cửa sổ ngữ cảnh 262.144 token của mô hình. Cấu hình này cũng tải vision tower của mô hình trên CUDA, cho phép tin nhắn trò chuyện chứa hình ảnh và video.

ID mô hình API: Qwen3.8-Flash-Next
Endpoint mặc định: http://<spark-address>:8888/v1
Luồng song song: 5
Ngữ cảnh mỗi luồng: 262.144 token
Tổng pool KV: 1.310.720 token
Bộ nhớ đệm KV: mặc định là int8
Chế độ đầu vào: văn bản, hình ảnh và video

Tính năng chính

Suy luận đồng thời với ngữ cảnh dài

TensorFold cấp cho mỗi luồng một bộ nhớ đệm ngữ cảnh đầy đủ riêng. Với các thiết lập mặc định, năm luồng, mỗi luồng nhận một cửa sổ prompt và phản hồi 262.144 token. Pool KV int8 kết quả tiêu thụ khoảng 23,4 GiB.

Cung cấp dịch vụ tương thích với OpenAI

Máy chủ cung cấp các endpoint như /v1/models và /v1/chat/completions. Các client tương thích với OpenAI có thể kết nối bằng cách thay đổi base URL và chọn ID mô hình Qwen3.8-Flash-Next.

Prompt đa phương thức

Tin nhắn người dùng có thể chứa các phần nội dung image_url và video_url theo kiểu OpenAI. Các định dạng hình ảnh được hỗ trợ gồm JPEG, PNG và WebP. Video có thể sử dụng MP4, WebM, MOV, MKV hoặc định dạng khác mà FFmpeg có thể giải mã.

Xử lý prompt đã được vá

Các bản vá TensorFold đi kèm bổ sung tính năng đọc trước từ SSD, đọc đa luồng gốc, cải thiện việc chọn block sparse attention, các chunk prompt có thể cấu hình, bản nháp sao chép, bộ đếm token trực tiếp và hỗ trợ vision cho Flash Next. Theo các phép đo của repository, xử lý prompt nhanh hơn khoảng 1,7 lần so với phiên bản chưa vá được dùng để so sánh, trong khi các phản hồi văn bản đã kiểm thử vẫn giống hệt nhau theo từng byte.

Yêu cầu hệ thống

Chuẩn bị máy chủ trước khi clone repository:

NVIDIA DGX Spark hoặc hệ thống GB10 khác có 128 GB bộ nhớ hợp nhất.
Khoảng 115 GiB bộ nhớ trống khi khởi động cấu hình mặc định.
Docker với runtime container NVIDIA.
Tài khoản người dùng thuộc nhóm docker.
Khoảng 160 GB dung lượng đĩa trống trên hệ thống mới.
Tùy chọn: CLI hf của Hugging Face để tải xuống tiếp tục nhanh hơn.
Tùy chọn: token Hugging Face trong ~/.cache/huggingface/token hoặc biến môi trường HF_TOKEN.

Triển khai mặc định dành cho DGX Spark đang không chạy tác vụ khác. Trên các hệ thống sử dụng bộ nhớ hợp nhất, việc cạn kiệt bộ nhớ có thể làm máy bị treo thay vì tạo ra lỗi cấp phát thông thường.

Cài đặt và khởi chạy lần đầu

1. Clone repository

git clone https://github.com/MiaAI-Lab/Qwen3.8-Flash-Next-Single-DGX-Spark-TensorFold.git
cd Qwen3.8-Flash-Next-Single-DGX-Spark-TensorFold

2. Khởi động máy chủ

./start.sh

Lần khởi chạy đầu tiên sẽ thực hiện toàn bộ quá trình thiết lập. Script sẽ tải image container dựng sẵn nếu có, tải checkpoint khoảng 106 GiB, xác minh checkpoint và biên dịch kernel CUDA cho GB10. Image dựng sẵn có dung lượng khoảng 11 GB, còn checkpoint chiếm khoảng 114 GB trong bộ nhớ đệm Hugging Face.

Trong quá trình khởi động, script hiển thị tiến trình thiết lập, nhật ký máy chủ, tiến trình tải trọng số và các ước tính bộ nhớ. Sau đó, script chạy một bài kiểm tra nhanh. Khởi chạy thành công sẽ kết thúc bằng thông báo cho biết Qwen3.8-Flash-Next đang hoạt động trên cổng 8888.

Theo README, các lần khởi chạy sau sẽ bỏ qua những phần thiết lập đã hoàn tất và mất khoảng 2,5 phút để tải trọng số.

3. Chuẩn bị mà không khởi chạy

Nếu muốn tải xuống và xây dựng mọi thứ trước, hãy chạy:

scripts/prepare.sh

Để xây dựng lại image container từ đầu:

scripts/prepare.sh --rebuild

Script chuẩn bị sẽ kiểm tra Docker, runtime NVIDIA và dung lượng đĩa. Sau đó, script lấy hoặc xây dựng image TensorFold, tải checkpoint vào bộ nhớ đệm Hugging Face và xác thực mô hình bằng tensorfold info.

Sử dụng API cơ bản

Kiểm tra mô hình khả dụng

curl -s http://<spark-address>:8888/v1/models

Thay <spark-address> bằng hostname hoặc địa chỉ IP của DGX Spark. Khi gọi từ chính Spark, bạn có thể sử dụng 127.0.0.1.

Gửi yêu cầu hoàn tất trò chuyện

curl -s http://<spark-address>:8888/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3.8-Flash-Next",
    "messages": [
      {
        "role": "user",
        "content": "Write a Python fibonacci function."
      }
    ],
    "max_tokens": 1000
  }'

Theo mặc định, mô hình sẽ suy nghĩ trước khi trả lời và phần suy luận sử dụng hạn mức token của phản hồi. Đặt max_tokens đủ cao để chứa cả phần suy luận và câu trả lời cuối cùng. Phần suy luận được trả về trong reasoning_content, còn phản hồi cuối cùng xuất hiện trong content.

Kết nối client tương thích với OpenAI

Cấu hình client bằng các giá trị sau:

Base URL: http://<spark-address>:8888/v1
Mô hình: Qwen3.8-Flash-Next

API hỗ trợ truyền phát, các lệnh gọi công cụ có kiểu, nội dung suy luận, đầu vào hình ảnh và đầu vào video. Các tham số công cụ như mảng được trả về bằng các kiểu JSON tương ứng.

Gửi hình ảnh

Theo mặc định, media phải được cung cấp dưới dạng data URL. Ví dụ shell sau mã hóa một tệp JPEG và yêu cầu mô hình mô tả tệp đó:

IMG=$(base64 -w0 photo.jpg)
curl -s http://<spark-address>:8888/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "Qwen3.8-Flash-Next",
    "messages": [{
      "role": "user",
      "content": [
        {
          "type": "image_url",
          "image_url": {
            "url": "data:image/jpeg;base64,'"$IMG"'"
          }
        },
        {
          "type": "text",
          "text": "Có gì trong bức ảnh này?"
        }
      ]
    }],
    "max_tokens": 2000
  }'

Mỗi yêu cầu có thể chứa tối đa bốn hình ảnh. Mỗi hình ảnh có thể có kích thước tối đa 10 MB, với giới hạn tổng cộng là 20 MB. Tất cả hình ảnh cộng lại có thể sử dụng tối đa 4.096 token. Đặt "detail": "low" sẽ giới hạn một hình ảnh ở mức 256 token.

Gửi video

Video sử dụng một phần nội dung video_url:

{
  "type": "video_url",
  "video_url": {
    "url": "data:video/mp4;base64,..."
  }
}

Mỗi yêu cầu có thể chứa tối đa hai video. Một video có thể có kích thước tối đa 64 MB, với giới hạn tổng cộng cho mỗi yêu cầu là 96 MB và thời lượng tối đa một giờ. Theo mặc định, máy chủ lấy mẫu hai khung hình mỗi giây, tối đa 256 khung hình được phân bổ trên toàn video, và cho phép tối đa 16.384 token video cho mỗi yêu cầu.

Các prompt hình ảnh và video không được lưu để tái sử dụng tiền tố. Các yêu cầu văn bản thông thường không bị ảnh hưởng khi bật khả năng thị giác.

Cho phép URL media HTTPS công khai

Data URL là mặc định. Để máy chủ có thể tải các URL hình ảnh và video HTTPS công khai, hãy khởi động lại máy chủ bằng:

VISION_URLS=1 ./start.sh restart

Chỉ bật tính năng tải từ xa khi phù hợp với chính sách bảo mật và mạng trong môi trường triển khai của bạn.

Chạy ở chế độ chỉ văn bản

Tắt vision tower để chỉ cung cấp văn bản:

VISION=0 ./start.sh restart

Chế độ chỉ văn bản không tải vision tower 0.84 GiB và sử dụng các khối prompt 4.096 hàng thay vì mặc định 2.048 hàng khi bật khả năng thị giác.

Quản lý máy chủ

Sử dụng các script wrapper của repository cho các thao tác thường ngày:

./start.sh restart
./stop.sh
docker logs -f qwen38-flash-next-tf
curl -s http://<spark-address>:8888/health

./start.sh restart xác thực thiết lập và các đối số trước khi thay thế máy chủ đang chạy.
./stop.sh dừng container và giải phóng bộ nhớ GPU. Các yêu cầu đang hoạt động sẽ bị gián đoạn.
docker logs -f theo dõi nhật ký máy chủ TensorFold.
/health báo cáo trạng thái bận và tổng số token hiện tại.

Nếu máy chủ đã chạy, ./start.sh thông thường sẽ giữ nguyên trạng thái đó. Đối với trình quản lý tiến trình như systemd, hãy sử dụng chế độ foreground:

FOREGROUND=1 ./start.sh

Cấu hình ngữ cảnh, tính đồng thời và độ chính xác KV

Các giá trị mặc định được lưu trong scripts/config.sh. Ghi đè chúng bằng biến môi trường hoặc truyền cờ TensorFold sau start.sh.

Giảm tính đồng thời để có thêm dung lượng dự phòng

PARALLEL=4 ./start.sh restart

Bốn luồng int8 cung cấp pool KV 1.048.576 token và có mức ước tính khởi động được báo cáo là khoảng 97.7 GiB.

Sử dụng cửa sổ ngữ cảnh ngắn hơn

./start.sh restart --context 131072

Các đối số dòng lệnh bổ sung được truyền đến tensorfold serve sau các giá trị mặc định, vì vậy chúng được ưu tiên. Chạy ./start.sh --help để xem các tùy chọn khả dụng.

Chọn loại bộ nhớ đệm KV khác

KV_DTYPE chấp nhận bf16, int8 hoặc int4:

PARALLEL=6 KV_DTYPE=int4 ./start.sh restart

README lưu ý rằng int4 làm thay đổi đầu ra đôi chút và không cung cấp phép đo chất lượng. Sử dụng int8 nếu bạn muốn cân bằng mặc định của dự án. Sử dụng bf16 khi việc lưu trữ KV với độ chính xác đầy đủ quan trọng hơn số lượng luồng.

Hiểu cơ chế bảo vệ khi khởi động

TensorFold tính ngân sách từ bộ nhớ khả dụng sau khi trừ phần dự trữ cho máy chủ bằng một phần mười RAM. Nếu cấu hình được yêu cầu không phù hợp, quá trình khởi động sẽ bị từ chối trước khi tải trọng số, và lỗi sẽ xác định một cửa sổ ngữ cảnh phù hợp.

Kiểm soát suy luận và lấy mẫu

Các giá trị lấy mẫu mặc định ở chế độ suy luận là nhiệt độ 1.0, top-p 0.95 và top-k 20. Các yêu cầu có thể ghi đè temperature, top_p, top_k và seed. Nhiệt độ 0 bật giải mã tham lam.

Tắt suy luận cho một yêu cầu

{
  "model": "Qwen3.8-Flash-Next",
  "messages": [
    {"role": "user", "content": "Trả lời trong một câu."}
  ],
  "chat_template_kwargs": {
    "enable_thinking": false
  },
  "max_tokens": 200
}

Thiết lập mức độ suy luận

{
  "chat_template_kwargs": {
    "reasoning_effort": "low"
  }
}

Mẫu cũng chấp nhận "xhigh". Nếu không chỉ định mức độ suy luận, mẫu sẽ sử dụng giá trị mặc định medium. Trường reasoning_effort ở cấp cao nhất theo kiểu OpenAI sẽ bị bỏ qua, vì vậy hãy đặt trường này bên trong chat_template_kwargs.

Mẹo hiệu năng nâng cao

Giữ các bảng n-gram trên SSD

PLE_ON_SSD=1 mặc định giữ 29.8 GiB bảng n-gram trên SSD thay vì đặt chúng trong bộ nhớ hợp nhất. Điều này dành lại bộ nhớ cho bộ nhớ đệm KV. Vì vậy, thiết bị lưu trữ cục bộ nhanh rất quan trọng đối với cấu hình mặc định.

Điều chỉnh cẩn thận kích thước khối prompt

Khi bật vision, TENSORFOLD_PREFILL_ROWS mặc định là 2048 để dành chỗ cho vision tower. Chế độ chỉ văn bản mặc định là 4096. README cho biết 4.096 hàng có thể cải thiện khoảng 2–5% tốc độ xử lý prompt với các prompt khoảng 3.000 token, nhưng cần thêm khoảng 0,94 GiB bộ nhớ.

TENSORFOLD_PREFILL_ROWS=4096 ./start.sh restart

Chỉ tăng giá trị này khi còn đủ dung lượng bộ nhớ dự phòng.

Điều khiển MTP và bản nháp sao chép

Cấu hình MTP mặc định tạo tối đa sáu bản nháp mỗi vòng và dừng chuỗi trước khi độ tin cậy của bản nháp giảm dưới 60%. Tối ưu hóa bản nháp sao chép được bật bằng TENSORFOLD_MTP_COPY=1 và yêu cầu ít nhất hai luồng song song. Tính năng này nhằm cải thiện các câu trả lời trích dẫn hoặc chỉnh sửa văn bản prompt trước đó.

Yêu cầu giải mã tham chiếu tuần tự

Để bỏ qua bước tạo bản nháp cho một yêu cầu cụ thể và sử dụng đường dẫn tham chiếu từng token một của TensorFold, hãy thêm:

{
  "draft": false
}

Tùy chọn này hữu ích khi so sánh giải mã suy đoán với tham chiếu tuần tự.

Bắt buộc hoặc bỏ qua bước chuẩn bị

PREPARE=1 ./start.sh restart
PREPARE=0 ./start.sh restart
PULL=0 scripts/prepare.sh

PREPARE=1 buộc kiểm tra bước chuẩn bị trước khi khởi động lại.
PREPARE=0 bỏ qua bước chuẩn bị.
PULL=0 xây dựng image cục bộ thay vì thử sử dụng image dựng sẵn trong registry.

Sau khi thay đổi các tệp trong patches/, hãy xây dựng lại image để các bản vá đó được tích hợp vào TensorFold.

Xác thực và đo điểm chuẩn

Kho lưu trữ bao gồm các tiện ích gọi đến máy chủ đang chạy. URL API mặc định là http://127.0.0.1:8888.

tools/bench.py local-test
tools/needle.py
tools/toolcheck.py
tools/visioncheck.py

tools/bench.py đo nhiều kích thước prompt và thực hiện kiểm tra giải mã ngắn.
tools/needle.py ẩn một cụm mật khẩu trong prompt khoảng 195.000 token và xác minh khả năng truy xuất.
tools/toolcheck.py kiểm tra xem tham số công cụ có giá trị là mảng có được trả về dưới dạng mảng JSON hay không.
tools/visioncheck.py gửi một hình ảnh được tạo có chứa hình tròn màu đỏ và hình vuông màu xanh, sau đó kiểm tra xem cả hai có được nhận diện hay không.

Để kiểm tra từ một máy khác, hãy đặt API_URL:

API_URL=http://<spark-address>:8888 tools/bench.py remote-test

Hiệu năng dự kiến

Kho lưu trữ báo cáo các kết quả giải mã sau trên một DGX Spark với bộ nhớ đệm KV int8, bảng n-gram trên SSD và tạo bản nháp MTP:

Một yêu cầu: 62,4 token mỗi giây, với thời gian nhận token đầu tiên là 152 ms.
Hai yêu cầu: tổng tốc độ 90,5 token mỗi giây.
Bốn yêu cầu: tổng tốc độ 106,7 token mỗi giây.
Năm yêu cầu: tổng tốc độ 119,3 token mỗi giây, tương đương 27,0 token mỗi giây cho mỗi yêu cầu.

Tốc độ prefill được báo cáo dao động từ khoảng 2.503 token mỗi giây với prompt 8.229 token đến 2.200 token mỗi giây với prompt 131.110 token. Đây là các số đo của dự án chứ không phải mức bảo đảm và có thể thay đổi tùy theo cấu hình, cấu trúc prompt, dữ liệu media đầu vào, bộ nhớ lưu trữ và dung lượng bộ nhớ khả dụng.

Kết luận

Kho lưu trữ này đóng gói mô hình, runtime TensorFold, thiết lập dành riêng cho CUDA, các bản vá hiệu năng và các script vận hành cần thiết để phục vụ Qwen3.8 Flash Next trên một DGX Spark. Hãy bắt đầu với cấu hình mặc định int8, năm luồng, xác minh dịch vụ qua API tương thích OpenAI, sau đó điều chỉnh mức đồng thời, kích thước ngữ cảnh, vision và độ chính xác KV theo khối lượng công việc cũng như dung lượng bộ nhớ dự phòng.