Phục vụ DeepSeek-V4.1-Flash trên hai DGX Spark bằng vLLM và Pi

Bạn sẽ xây dựng gì

Dự án này cung cấp các script để phục vụ DeepSeek-V4.1-Flash trên hai nút NVIDIA DGX Spark bằng vLLM. Tensor parallelism chạy trên cả hai nút thông qua kết nối QSFP/RoCE, trong khi nút head cung cấp API tương thích với OpenAI trên cổng 8000.

Bản triển khai sử dụng checkpoint 0xSero/DeepSeek-V4.1-Flash-Spark. Các chuyên gia backbone được định tuyến được mã hóa dưới dạng dữ liệu trellis EXL3, với mức trung bình được báo cáo là 2.77 bit trên mỗi trọng số. Attention, các chuyên gia dùng chung, router, bảng Engram, các lớp draft, thành phần vision, embedding và output head vẫn được giữ nguyên từ checkpoint upstream.

Sau khi triển khai, bạn có thể sử dụng trực tiếp mô hình thông qua API hoặc kết nối mô hình với tác nhân lập trình Pi cho các quy trình lập trình và sử dụng công cụ.

Hiệu năng và khả năng

README báo cáo các phép đo từ hai nút DGX Spark GB10, sử dụng tensor parallelism qua RoCE, bộ nhớ đệm KV FP8, giải mã suy đoán DSpark bảy token, bảng Engram lưu trên đĩa và hai chuỗi đồng thời.

• Prefill prompt 8k: khoảng 2.050 token mỗi giây.
• Prefill prompt 32k: khoảng 2.061 token mỗi giây.
• Giải mã mã nguồn: khoảng 39–41 token mỗi giây cho một luồng.
• Giải mã mã nguồn hai luồng: tổng cộng 60 token mỗi giây.
• Giải mã văn bản: khoảng 29 token mỗi giây cho một luồng.
• Ngữ cảnh tối đa mỗi yêu cầu: 262.144 token.
• Pool bộ nhớ đệm KV: 2.023.717 token.
• Đầu vào vision, lời gọi công cụ và suy luận: smoke test thành công.
• Khả năng truy hồi ngữ cảnh 175k token: vượt qua cả sáu cổng kiểm tra được báo cáo trong phòng thí nghiệm.

Lần khởi động đầu tiên mất khoảng 11–13 phút vì trọng số và các ngân hàng EXL3 được tải, kernel được biên dịch và đồ thị CUDA được ghi lại.

Điều kiện tiên quyết

Bạn cần hai nút DGX Spark chạy DGX OS. Chọn một nút làm head, chịu trách nhiệm cung cấp API, và nút còn lại làm worker.

• Cáp QSFP kết nối hai nút, với RoCE được bật.
• Ít nhất một cổng RDMA ở trạng thái ACTIVE trên mỗi nút, được xác minh bằng rdma link.
• Một địa chỉ IPv4 trên mạng fabric tương ứng cho mỗi nút, chẳng hạn 10.10.10.13 và 10.10.10.11.
• SSH không cần mật khẩu từ head đến worker thông qua địa chỉ fabric của worker.
• Docker với runtime NVIDIA được cài đặt trên cả hai nút.
• Người dùng của bạn phải thuộc nhóm docker.
• Khoảng 700 GB dung lượng NVMe trống trên head và 470 GB trên worker.
• python3, rsync và curl trên cả hai nút.
• Node.js và npm trên máy sẽ chạy Pi.

Sao chép repository và xác định worker

Chạy các lệnh sau trên nút head. Thay đích SSH bằng địa chỉ fabric của worker.

git clone https://github.com/0xSero/DeepSeek-V4.1-Flash-Two-Sparks
cd DeepSeek-V4.1-Flash-Two-Sparks
export WORKER=user@10.10.10.11

Các script sử dụng WORKER để kết nối với Spark thứ hai. Hãy đảm bảo xác thực bằng khóa SSH hoạt động trước khi tiếp tục.

Tải xuống và phân phối checkpoint

Tải checkpoint có dung lượng khoảng 462 GB vào thư mục mô hình mặc định trên head:

scripts/download.sh

Script tải xuống cũng ghép lại các shard Engram. Vì Hugging Face giới hạn kích thước từng tệp ở 50 GB, hai shard gốc được lưu dưới dạng các tệp .partNN. Script sẽ ghép lại chúng, xác minh sáu shard gốc với sha256-manifest.txt và xóa các tệp part. Đặt KEEP_PARTS=1 nếu bạn muốn giữ lại các phần này.

Sao chép mô hình hoàn chỉnh sang worker qua mạng fabric:

scripts/copy-to-peer.sh

Ngoài ra, bạn cũng có thể chạy trực tiếp scripts/download.sh trên worker. Đường dẫn mô hình mặc định là ~/models/DeepSeek-V4.1-Flash-Spark. Nếu worker sử dụng đường dẫn khác, hãy cấu hình WORKER_MODEL_DIR trước khi khởi chạy.

Kéo image phục vụ

Dự án sử dụng image vLLM chứa đường dẫn mixture-of-experts EXL3 và các kernel B12X Spark. Kéo image đã ghim trên cả hai nút:

docker pull ghcr.io/0xsero/deepseek-v4.1-flash-spark@sha256:5668e35e5ee021da4b9ce88a1964caf0e082e8ca01d81d1d64b6213a55c6add5

Script khởi chạy sẽ tự động kéo image nếu image chưa có sẵn, vì vậy bước này cũng có thể được thực hiện trong lúc khởi động.

Khởi chạy cả hai hạng tensor-parallel

Khởi động máy chủ hai nút từ head:

scripts/launch.sh

Launcher phát hiện các giao diện fabric đang hoạt động, tạo khóa API tại ~/.dsv41-two-sparks/api_key, khởi động bộ bảo vệ bộ nhớ trên cả hai nút, chạy rank 1 trên worker và chạy rank 0 trên head. Launcher chờ API khả dụng và cho phép tối đa 45 phút để khởi động.

Sử dụng cùng script để kiểm tra hoặc quản lý bản triển khai:

scripts/launch.sh status
scripts/launch.sh logs r0
scripts/launch.sh logs r1
scripts/launch.sh stop

Máy chủ lắng nghe trên head tại http://127.0.0.1:8000 ở cục bộ. Client có thể sử dụng địa chỉ có thể truy cập của head, trong khi lưu lượng giữa các rank phải sử dụng fabric QSFP/RoCE.

Chạy smoke test

Xác thực khả năng sinh văn bản, lời gọi công cụ và đầu vào vision bằng:

python3 scripts/smoke.py http://127.0.0.1:8000

Mỗi bước kiểm tra sẽ báo cáo PASS hoặc FAIL. Bạn cũng có thể chạy benchmark tùy chọn:

python3 scripts/bench.py --out bench.json --conc 1 2

Bài kiểm tra bao quát tốc độ prefill, decode và ngữ cảnh dài mà không áp đặt giới hạn đầu ra.

Sử dụng endpoint tương thích với OpenAI

Máy chủ cung cấp các thông tin API sau:

• URL cơ sở: http://<head-ip>:8000/v1
• Tên mô hình: deepseek-v4.1-flash
• Xác thực: bearer token từ ~/.dsv41-two-sparks/api_key

Ví dụ, lấy khóa từ head bằng lệnh:

ssh <head> cat ~/.dsv41-two-sparks/api_key

Sau đó, bạn có thể sử dụng endpoint với bất kỳ client nào tương thích với OpenAI bằng cách cấu hình URL cơ sở, tên mô hình và bearer key.

Kết nối Pi với mô hình

Trên máy có Node.js và npm, hãy cài đặt và đăng ký provider Pi. Lệnh này nhận URL cơ sở của API không có phần đường dẫn mô hình ở cuối:

pi/install.sh http://<head-ip>:8000/v1

Đặt API key trong shell sẽ khởi động Pi:

export DSV41_API_KEY=$(ssh <head> cat ~/.dsv41-two-sparks/api_key)
pi --model dsv41-sparks/deepseek-v4.1-flash

Trình cài đặt sẽ cài Pi nếu Pi chưa có trong PATH, sau đó chỉ thêm hoặc thay thế provider dsv41-sparks trong cấu hình mô hình của Pi. Trình cài đặt tạo bản sao lưu có dấu thời gian trước khi thay đổi và giữ nguyên các provider khác.

Nếu bạn sử dụng danh sách enabledModels, trình cài đặt sẽ thêm mô hình được phục vụ vào danh sách đó. Đặt SET_DEFAULT=1 để đặt mô hình này làm mô hình khởi động của Pi.

Extension được cài đặt sẽ loại bỏ giới hạn token đầu ra của Pi cho provider này, cho phép phản hồi kết thúc tự nhiên. Extension đọc DSV41_API_KEY tại thời điểm gửi yêu cầu và không ghi khóa vào cấu hình Pi.

Tìm hiểu cấu hình mặc định

scripts/launch.sh tái hiện cấu hình phục vụ đã được đo kiểm. Các thiết lập quan trọng gồm:

• Bộ nhớ đệm KV FP8 với KV_BYTES=2700000000.
• Độ dài ngữ cảnh tối đa 262144 token.
• Tối đa hai sequence chạy đồng thời.
• Số token theo batch tối đa được đặt là 2048.
• Giải mã suy đoán DSpark với bảy token dự đoán và cơ chế xác minh thích ứng.
• Các bảng Engram được lưu trên đĩa.
• Các kernel attention, linear và MoE của B12X.
• Các expert được định tuyến EXL3 với ST_EXL3_PREFILL=st.
• CUDA graph FULL_DECODE_ONLY.
• All-reduce một lần B12X RoCE và NCCL qua RoCE cho các thao tác phân tán còn lại.
• Một hình ảnh cho mỗi prompt đa phương thức.
• Các parser suy luận và gọi công cụ deepseek_v41.

Hầu hết thiết lập có thể được ghi đè thông qua các biến môi trường. Thư mục mô hình được điều khiển bởi MODEL_DIR, thư mục mô hình của worker bởi WORKER_MODEL_DIR, còn dữ liệu runtime lâu dài bởi STATE_DIR. Thư mục state mặc định là ~/.dsv41-two-sparks.

Launcher mount mô hình ở chế độ chỉ đọc vào /model. Launcher sao chép kế hoạch phân bổ EXL3 vào thư mục state và ghi lại các đường dẫn bank để trỏ đến những thư mục EXL3 đã được mount.

Giữ lưu lượng trên đúng mạng

Các tiến trình vLLM, NCCL và Gloo phải bind vào các địa chỉ QSFP/RoCE thay vì các interface Wi-Fi, Ethernet hoặc Tailscale. Launcher thường tự phát hiện các cổng RoCE đang hoạt động và đặt những biến như:

• VLLM_HOST_IP
• NCCL_SOCKET_IFNAME
• GLOO_SOCKET_IFNAME
• NCCL_IB_HCA

Nếu tính năng tự động phát hiện chọn sai interface, hãy đặt rõ HEAD_IP, WORKER_IP, HEAD_IFNAME, WORKER_IFNAME, HEAD_HCAS hoặc WORKER_HCAS. Sử dụng ip -br a và rdma link để xác định đúng địa chỉ và thiết bị RDMA.

Quản lý bộ nhớ an toàn

Một DGX Spark chia sẻ pool bộ nhớ 128 GB giữa CPU và GPU. Nếu bộ nhớ khả dụng giảm xuống 0, máy chủ có thể không phản hồi thay vì dừng container một cách bình thường. Launcher khởi động scripts/memguard.sh trên cả hai node để dừng các container dsv41-r* khi bộ nhớ khả dụng giảm xuống dưới ngưỡng đã cấu hình.

Xem log memory guard tại:

~/.dsv41-two-sparks/memguard.log

Với cấu hình mặc định, bộ nhớ khả dụng ở trạng thái ổn định được báo cáo khoảng 2–3 GiB. Nếu guard được kích hoạt, hãy giảm KV_BYTES hoặc GPU_UTIL trước khi tăng MEMGUARD_GIB.

Khắc phục các vấn đề thường gặp

Khởi động chậm

Lần khởi động đầu tiên có thể mất khoảng 12 phút trong khi trọng số được tải, các bank EXL3 được chuẩn bị, kernel B12X được biên dịch và CUDA graph được ghi lại. Cache kernel được lưu dưới STATE_DIR/cache, vì vậy các lần khởi động sau có thể nhanh hơn.

Thiếu tệp Engram

Nếu quá trình khởi động báo thiếu một tệp như model-00005-of-00006.safetensors, có thể các shard Engram chưa được ghép lại. Hãy chạy lại scripts/download.sh. Lệnh này tiếp tục công việc chưa hoàn tất và bỏ qua các bước đã hoàn thành.

Phát hiện fabric chọn sai interface

Kiểm tra địa chỉ bằng ip -br a và trạng thái RDMA bằng rdma link. Sau đó cung cấp rõ các biến interface, IP và HCA của head và worker như mô tả ở trên.

Tải xuống chậm

Nếu một Spark chỉ truy cập internet qua Wi-Fi, hãy tải checkpoint trên node có đường uplink tốt nhất và sử dụng scripts/copy-to-peer.sh để truyền qua fabric.

Pi không nhìn thấy mô hình

Đảm bảo DSV41_API_KEY được export trong cùng shell khởi động Pi. Chạy /model bên trong Pi để tải lại danh sách mô hình.

Chế độ in của Pi chờ vô thời hạn

Khi đầu vào chuẩn không phải là một terminal, pi -p cũng đọc dữ liệu từ stdin. Trong các script, hãy chuyển hướng stdin từ /dev/null:

pi -p < /dev/null

Kết luận

Kho lưu trữ này đóng gói mô hình, image phục vụ, các script khởi chạy phân tán, cơ chế bảo vệ bộ nhớ, công cụ xác thực và tích hợp Pi cần thiết để chạy DeepSeek-V4.1-Flash trên hai DGX Spark. Hãy chuẩn bị fabric RoCE, tải xuống và xác minh checkpoint trên cả hai nút, khởi chạy hai rank, chạy các bài kiểm tra smoke, sau đó trỏ các ứng dụng tương thích hoặc Pi tới endpoint tương thích OpenAI trên nút đầu.