Chuyển đến nội dung chính
Hướng dẫn AI

Triển khai GLM-5.3 Flash EXL3 trên hai hệ thống NVIDIA DGX Spark

Tìm hiểu cách cài đặt, cấu hình, khởi chạy, kiểm thử và tinh chỉnh GLM-5.3 Flash EXL3 trên hai hệ thống NVIDIA GB10 DGX Spark. Hướng dẫn này bao gồm môi trường chạy hai nút, giải mã suy đoán DFlash2, bộ nhớ đệm KV MLA fp8, các yêu cầu tương thích với OpenAI, bộ nhớ đệm tiền tố, đo điểm chuẩn, phân tích loại bỏ tùy chọn và các ràng buộc cấu hình quan trọng.

Thời gian đọc khoảng 34 phút
Triển khai GLM-5.3 Flash EXL3 trên hai hệ thống NVIDIA DGX Spark

Tổng quan

GLM-5.3 Flash EXL3 cho 2x DGX Sparks là công thức triển khai và lớp phủ vLLM để phục vụ phiên bản lượng tử hóa EXL3/TR3 4 bpw của GLM-5.3 Flash trên hai hệ thống NVIDIA GB10. Công cụ cung cấp API tương thích OpenAI trên cổng 8888 và phục vụ mô hình với mã định danh GLM-5.3-Flash-EXL3.

Công thức này sử dụng song song tensor với một rank trên mỗi máy. Nó kết hợp các routed expert EXL3 được đóng gói, kernel gốc sm_121a, bộ nhớ đệm KV sparse-MLA fp8, CUDA graph và giải mã suy đoán DFlash2 với bảy token nháp.

Checkpoint mặc định được sử dụng là Mia-AiLab/GLM-5.3-Flash-EXL3-TR3-4bpw, một bản sao công khai giống từng byte với snapshot Brandon Music được tham chiếu. Checkpoint này có dung lượng khoảng 164 GiB, gồm 120 shard. Kho lưu trữ mô hình có giấy phép riêng, trong khi các script phục vụ và lớp phủ được cấp phép MIT.

Vì sao cần lớp phủ

Image ARM64 GLM-5.3 vLLM gốc có thể tải checkpoint này, nhưng bị lỗi ở lượt forward đầu tiên vì GLM-5.3 Flash sử dụng NoPE MLA, trong khi backend sparse-MLA SM12x hiện có yêu cầu hình học đóng gói khác. Lớp phủ đệm latent NoPE 512 chiều vào hình học mà FLASHINFER_MLA_SPARSE_SM120 yêu cầu mà không thay đổi tích vô hướng QK.

Lớp phủ cũng đăng ký phương thức lượng tử hóa EXL3 hoạt động đầy đủ. Nhờ đó, các routed expert vẫn giữ biểu diễn trellis, SUH, SVH và MCG được đóng gói thay vì mở rộng thành BF16. Khi bật đường dẫn hợp nhất, mỗi layer sử dụng một lần khởi chạy exllamav3_ext.exl3_moe.

Ngoài ra, lớp phủ cung cấp tích hợp dành riêng cho GLM với DFlash2, bao gồm thu thập hidden state phụ EAGLE3, cơ chế chú ý cửa sổ trượt cho bản nháp dùng chung các vị trí KV MLA của mô hình đích và cơ chế chú ý phi nhân quả trong khối bản nháp suy đoán.

Tính năng chính

  • Dịch vụ tương thích OpenAI: vLLM cung cấp /v1/chat/completions và các endpoint liên quan trên node đầu.
  • Song song tensor trên hai node: triển khai sử dụng --nnodes 2 và --tensor-parallel-size 2.
  • Trọng số EXL3 nhỏ gọn: checkpoint 4 bpw có dung lượng tải xuống khoảng 164 GiB và được ghi nhận là 176 GB trong bảng chất lượng được tham chiếu.
  • Giải mã suy đoán DFlash2: mô hình nháp mặc định là incoai/GLM-5.3-Flash-DFlash2 với k=7.
  • Ngữ cảnh dài: độ dài mô hình tối đa mặc định là 900.000 token, được hỗ trợ bởi pool MLA fp8 được ghi nhận có 982.612 token trong cấu hình bộ nhớ đã tài liệu hóa.
  • Hỗ trợ đa phương thức: đầu vào hình ảnh và video được bật, với giới hạn mặc định cho mỗi prompt là bốn hình ảnh và một video.
  • Phân tích công cụ và suy luận: launcher bật tự động chọn công cụ cùng các trình phân tích lệnh gọi công cụ và suy luận tương thích GLM.
  • Cache tiền tố: các tiền tố căn chỉnh theo block có thể được tái sử dụng khi các hash liên quan vẫn còn trong cache.
  • Loại bỏ hướng từ chối tùy chọn: ABLIT=1 áp dụng chỉnh sửa trong bộ nhớ cho các trọng số native BF16 output-projection được chọn tại thời điểm tải.

Yêu cầu phần cứng và phần mềm

Công thức này được thiết kế riêng cho hai hệ thống NVIDIA GB10 cấp DGX Spark, kết nối thông qua fabric CX7 được tài liệu hóa. Đây không phải là triển khai GPU đơn lẻ phổ quát.

  • Hai hệ thống NVIDIA GB10 với khoảng 180 GiB dung lượng lưu trữ trống trên mỗi node cho quá trình thiết lập ban đầu.
  • Docker có thể sử dụng mà không cần sudo trên cả hai hệ thống.
  • SSH không yêu cầu mật khẩu từ node đầu đến worker.
  • Đã cài đặt hf hoặc huggingface-cli, curl và rsync trên node đầu.
  • Đúng giao diện mạng CX7 và thiết bị RDMA trên cả hai máy.
  • Vị trí cache Hugging Face đủ chứa checkpoint 120 shard và mô hình DFlash2 khoảng 2,3 GiB.

Giữ nguyên các thiết lập giao diện CX7 và HCA của kho lưu trữ, trừ khi hệ thống cáp vật lý của bạn khác biệt. README cảnh báo rằng NCCL không thể sử dụng các bí danh loopback 10.0.0.x và có thể bị treo trong ncclCommInitRank nếu các chân fabric không chính xác.

Cài đặt và cấu hình triển khai

1. Sao chép kho lưu trữ

git clone https://github.com/MiaAI-Lab/GLM-5.3-Flash-EXL3-2x-DGX-Sparks.git
cd GLM-5.3-Flash-EXL3-2x-DGX-Sparks

2. Tạo tệp môi trường

cp .env.example .env

Chỉnh sửa .env nếu các máy không sử dụng địa chỉ hoặc tên tài khoản mặc định của công thức. Các thiết lập quan trọng nhất là:

  • HEAD_IP=10.0.0.1 cho node đầu và vLLM master.
  • WORKER_IP=10.0.0.2 cho Spark thứ hai.
  • WORKER_USER khi tài khoản SSH khác nhau giữa các node.
  • WORKER_HOME khi thư mục home hoặc vị trí cache Hugging Face của worker khác.
  • PORT=8888 cho bộ lắng nghe API.

Launcher tự động tạo .env từ .env.example nếu tệp này chưa tồn tại. Các giá trị được cung cấp trực tiếp trước một lệnh sẽ được ưu tiên hơn các giá trị trong tệp.

3. Tùy chọn chuẩn bị trước trọng số

./download.sh

Lệnh này tải checkpoint EXL3 và mô hình DFlash2 vào cache Hugging Face của node đầu. Lệnh không chạy Docker, kết nối đến worker hoặc đồng bộ tệp. Hãy sử dụng khi bạn muốn hoàn tất việc tải mô hình khoảng 164 GiB trước khi worker sẵn sàng.

Để làm mới rõ ràng các tệp đã lưu trong cache, hãy chạy:

REFRESH_WEIGHTS=1 ./download.sh

Tránh làm mới không cần thiết. Cả download.sh và start.sh đều bỏ qua các kho lưu trữ đã hoàn tất.

4. Khởi động cả hai rank và API

./start.sh

Tập lệnh khởi động thực hiện theo trình tự sau:

  1. Kiểm tra Docker, SSH và dung lượng đĩa khả dụng trên cả hai nút.
  2. Tải image công khai ghcr.io/miaai-lab/glm-5.3-flash-2x-dgx-sparks:exl3 trên head.
  3. Truyền image container sang worker khi digest của image đã thay đổi.
  4. Tải các tệp mô hình còn thiếu vào bộ nhớ đệm Hugging Face của head.
  5. Đồng bộ bộ nhớ đệm sang worker bằng rsync.
  6. Khởi động rank 1 ở chế độ không có giao diện trên worker.
  7. Khởi động rank 0 và API tương thích OpenAI trên head.
  8. Liên tục kiểm tra endpoint health cho đến khi quá trình tải mô hình và warmup hoàn tất.

Thời gian chờ sẵn sàng mặc định là 3.600 giây vì việc tải trọng số và ghi lại các CUDA graph có thể mất nhiều thời gian.

5. Kiểm tra trạng thái và nhật ký

./start.sh status
./start.sh logs
./start.sh logs worker

Dừng cả hai container bằng:

./start.sh stop

Bạn cũng có thể dùng ./stop.sh.

Gửi yêu cầu trò chuyện cơ bản

Trên nút head, URL API cơ sở là http://127.0.0.1:8888/v1. Với các địa chỉ LAN được ghi trong tài liệu, các máy khác có thể sử dụng http://10.0.0.1:8888/v1.

curl -s http://127.0.0.1:8888/v1/chat/completions \
  -H 'Content-Type: application/json' \
  -d '{
    "model": "GLM-5.3-Flash-EXL3",
    "messages": [
      {"role": "user", "content": "Explain tensor parallelism briefly."}
    ],
    "chat_template_kwargs": {
      "enable_thinking": false
    }
  }'

Giá trị model trong yêu cầu phải khớp với tên được cung cấp, mặc định là GLM-5.3-Flash-EXL3. Chế độ suy luận được bật theo mặc định. Để tắt, hãy đặt chat_template_kwargs ở cấp cao nhất của yêu cầu JSON như minh họa ở trên.

Không gửi một đối tượng extra_body lồng trực tiếp qua HTTP thô. Trong OpenAI Python SDK, extra_body là một tùy chọn của SDK, nội dung của nó được hợp nhất vào yêu cầu cấp cao nhất.

Cấu hình sinh của checkpoint có thể cung cấp temperature=1.0 và top_p=0.95. Hãy đặt các giá trị lấy mẫu trong từng yêu cầu khi cần hành vi khác.

Tìm hiểu runtime mặc định

Các giá trị mặc định của quá trình triển khai được phối hợp có chủ ý. Việc thay đổi một thành phần có thể khiến tổ hợp kernel không hợp lệ hoặc làm giảm tỷ lệ chấp nhận suy đoán.

  • Trọng số: Mia-AiLab/GLM-5.3-Flash-EXL3-TR3-4bpw, dự phòng sang kho Brandon Music khi mirror không khả dụng hoặc không đầy đủ.
  • Song song hóa: hai nút và kích thước tensor-parallel bằng hai, sử dụng multiprocessing executor.
  • Lượng tử hóa: exl3, với các expert định tuyến được đóng gói cùng trọng số native cho dense, shared-expert, attention, embedding và output-head.
  • Bộ nhớ đệm KV đích: fp8, được biểu diễn nội bộ dưới dạng fp8_ds_mla đóng gói.
  • Suy đoán: DFlash2 với bảy token suy đoán và tensor parallelism của mô hình nháp được đặt bằng một.
  • Bộ nhớ đệm KV của mô hình nháp: tự động chọn, tạo ra BF16 cho mô hình nháp dense thay vì bố cục MLA của mô hình đích.
  • Attention: sparse MLA cho mô hình đích và FLASH_ATTN được tự động chọn cho attention của mô hình nháp DFlash2.
  • Ngữ cảnh: MAX_MODEL_LEN=900000.
  • Đồng thời: MAX_NUM_SEQS=4.
  • Prefill: MAX_NUM_BATCHED_TOKENS=1024.
  • Mức sử dụng bộ nhớ: GPU_MEM_UTIL=0.87.

Chuyển đổi chế độ giải mã suy đoán

DFlash2 là mặc định và sử dụng incoai/GLM-5.3-Flash-DFlash2. Để chuyển về đường dẫn MTP của checkpoint với hai token suy đoán, hãy khởi động lại bằng:

SPEC_METHOD=mtp ./start.sh restart

Môi trường cũng hỗ trợ SPEC_METHOD=none. Tensor parallelism mặc định của mô hình nháp DFlash2 là một, giữ mô hình nháp nhỏ trên rank 0 và tránh giao tiếp CX7 ở mỗi bước nháp.

Không ép dùng TRITON_ATTN cho DFlash2. Theo các phép đo trong README, backend đó khiến attention có tính nhân quả trong block nháp và làm tỷ lệ chấp nhận ở các vị trí suy đoán về sau sụt giảm mạnh. Hãy để attention của mô hình nháp không được đặt để SM121 chọn FLASH_ATTN.

Cấu hình bộ nhớ đệm KV và ngữ cảnh dài

Bộ nhớ đệm KV đích phải duy trì ở fp8. Trên kiến trúc này, kernel sparse-MLA chấp nhận fp8_ds_mla đóng gói; BF16 không có sparse kernel tương thích, còn các kernel KV NVFP4 áp dụng cho dense MHA thay vì sparse MLA.

Với DFlash2, hỗ trợ vision, mức sử dụng bộ nhớ 0.87 và độ dài mô hình tối đa 900.000, README báo cáo một pool 982.612 token sử dụng khoảng 15.67 GiB cho fp8 MLA. Con số này cung cấp dung lượng xấp xỉ 1.09 lần một yêu cầu đầy đủ 900.000 token. Cấu hình native một triệu token vẫn không thể cấp phát với thiết lập được ghi trong tài liệu.

Giữ nguyên các thiết lập này trừ khi bạn đang thử nghiệm một thay đổi runtime có chủ đích:

KV_CACHE_DTYPE=fp8
GPU_MEM_UTIL=0.87
MAX_MODEL_LEN=900000
MAX_NUM_BATCHED_TOKENS=1024
SKIP_MM_PROFILING=1
LIMIT_MM={"image":4,"video":1}

SKIP_MM_PROFILING=1 rất quan trọng vì việc lập hồ sơ cho đầu vào giả hình ảnh và video có kích thước tối đa có thể làm cạn kiệt bộ nhớ hợp nhất. README cũng cảnh báo rằng việc tăng giới hạn token theo batch lên 8.192 sẽ làm quá tải đường dẫn indexer top-k của GB10 trong quá trình vận hành với ngữ cảnh dài.

Cách hoạt động của bộ nhớ đệm tiền tố

Bộ nhớ đệm tiền tố đã được bật, nhưng API OpenAI vẫn không lưu trạng thái. Client phải gửi lại toàn bộ lịch sử hội thoại ở mỗi lượt. vLLM băm tiền tố được gửi lên và có thể sử dụng lại các block đã lưu đệm khi chúng vẫn còn khả dụng.

  • Chỉ các token được căn chỉnh theo block mới được tính là lượt truy cập bộ nhớ đệm theo trình quản lý bộ nhớ đệm MLA được tài liệu hóa.
  • MAX_NUM_SEQS=4 cho phép bốn lượt sinh đang được xử lý; tùy chọn này không dành riêng bốn phiên trò chuyện liên tục.
  • Không có đảm bảo rằng các cuộc trò chuyện không hoạt động sẽ tiếp tục được lưu trong bộ nhớ đệm.
  • Các activation của cuộc trò chuyện này không bị trộn lẫn với cuộc trò chuyện khác.
  • Một cuộc trò chuyện cũ có thể cần prefill mới sau khi một workload khác loại bỏ tiền tố của nó khỏi bộ nhớ đệm.

Bài kiểm tra trực tiếp trong README đã sử dụng lại 3.584 token từ phần tiếp nối gồm 7.760 token, tương đương khoảng 46 phần trăm prompt. Hãy xem bộ nhớ đệm tiền tố là cơ chế tăng tốc mang tính cơ hội, không phải nơi lưu trữ phiên lâu dài.

Đo hiệu năng giải mã

Kho lưu trữ bao gồm tests/bench_decode.py để giải mã theo luồng và kiểm tra tính nhất quán. Chạy bài kiểm tra số lượng có cấu trúc bằng lệnh:

python3 tests/bench_decode.py \
  --phase structured \
  --structured \
  --runs 5 \
  --max-tokens 400 \
  --skip-coherence \
  --out /tmp/glm53-structured.json

Chạy bài kiểm tra giải thích hash map bằng văn xuôi bằng lệnh:

python3 tests/bench_decode.py \
  --phase prose \
  --runs 5 \
  --max-tokens 400 \
  --skip-coherence \
  --out /tmp/glm53-prose.json

Theo giao thức warm, empty-KV được tài liệu hóa trong README, workload có cấu trúc đạt 62,9 token mỗi giây ở mức đồng thời một, 103,3 token mỗi giây tổng ở mức đồng thời hai và 146,5 token mỗi giây tổng ở mức đồng thời bốn. Hiệu năng phụ thuộc mạnh vào tỷ lệ chấp nhận suy đoán: trung vị trong phòng thí nghiệm là 61,7 token mỗi giây đối với đầu ra có cấu trúc nhưng chỉ 26,9 đối với văn xuôi. Các bài kiểm tra hỗn hợp hoặc ngữ cảnh dài với khoảng 60.000 đến 100.000 token được lưu trong bộ nhớ đệm đạt 24 đến 27 token mỗi giây.

Các số liệu này mô tả cụ thể thiết lập hai GB10, loại prompt, cấu hình nhiệt độ bằng không, chế độ suy nghĩ bị tắt, DFlash2 k=7 và lượt sinh 400 token trong README. Không nên diễn giải chúng là bảo đảm thông lượng phổ quát.

Phân tích loại bỏ hướng từ chối tùy chọn

Kho lưu trữ có thể áp dụng phân tích loại bỏ hướng từ chối trong thời gian tải trọng số mà không cần ghi lại hoặc lượng tử hóa lại checkpoint EXL3. Bật tính năng này bằng:

ABLIT=1 ./start.sh restart
./start.sh logs | grep ablit

Công thức mặc định chỉnh sửa từng self_attn.o_proj BF16 gốc trong các layer từ 15 đến 45. Các layer từ 0 đến 14 được giữ nguyên làm neo an toàn. Scale mặc định là ABLIT_ALPHA=3.0; đặt thành 1.0 sẽ áp dụng phép chiếu thuần túy, loại bỏ thành phần theo hướng được cung cấp.

Các tùy chọn hữu ích gồm:

  • ABLIT=0 hoặc để trống để giữ nguyên trọng số gốc.
  • ABLIT_DIRECTION=dealign cho hướng mặc định đã công bố.
  • ABLIT_LAYERS=15-45 cho phạm vi layer được chỉnh sửa, bao gồm cả hai đầu.
  • ABLIT_ALPHA=3.0 cho scale của phép chiếu.
  • ABLIT_INCLUDE_MTP=1 để đưa block MTP của checkpoint vào khi sử dụng MTP.

Các kết quả chất lượng KLD trong README được đo khi chưa áp dụng phân tích loại bỏ. Bật tính năng này sẽ thay đổi hành vi từ chối và có thể ảnh hưởng đến tính nhất quán hoặc tỷ lệ chấp nhận suy đoán, vì bộ soạn thảo DFlash2 vẫn không thay đổi trong khi đầu ra mục tiêu thay đổi. Nếu tính nhất quán giảm, README đề xuất trước tiên hạ ABLIT_ALPHA.

Quy trình khởi chạy nâng cao

Sau khi image và model cache đã tồn tại trên cả hai máy, bạn có thể bỏ qua các thao tác truyền lặp lại:

SKIP_DOWNLOAD=1 SKIP_SYNC=1 ./start.sh

Để giữ image container cục bộ và bỏ qua toàn bộ thao tác pull, tải xuống và đồng bộ hóa:

SKIP_PULL=1 SKIP_DOWNLOAD=1 SKIP_SYNC=1 ./start.sh restart

Để xây dựng lại overlay từ kho lưu trữ hiện tại thay vì sử dụng image công khai:

BUILD=1 SKIP_DOWNLOAD=1 SKIP_SYNC=1 ./start.sh restart

Bạn cũng có thể xây dựng trực tiếp Dockerfile:

docker build -t glm53-flash-sm121:local .

Thông thường, script khởi động sẽ chạy tự kiểm tra overlay GPU trước khi chuyển image đến worker. Chỉ đặt SKIP_OVERLAY_VERIFY=1 khi bạn thực sự muốn bỏ qua bước kiểm tra đó.

Cảnh báo cấu hình quan trọng

  • Không truyền --moe-backend marlin. Triển khai này sử dụng trọng số EXL3 và phương pháp expert được đóng gói riêng.
  • Không đặt bộ nhớ đệm KV mục tiêu thành NVFP4 hoặc BF16. Giữ KV_CACHE_DTYPE=fp8.
  • Không cố định attention draft suy đoán ở TRITON_ATTN.
  • Không thay image bằng triển khai NVFP4/Ray cũ glm53-flash-sm121:v8.
  • Không tùy tiện thay đổi tensor parallelism, số lượng node, pin CX7 hoặc USE_HOST_NCCL. Đây là các thành phần thiết yếu của công thức hai node.
  • Không xóa hoặc lượng tử hóa lại cache checkpoint Hugging Face trừ khi bạn định tải lại toàn bộ model.
  • Không tắt các cơ chế bảo vệ lập hồ sơ đa phương thức nếu chưa tính đến việc sử dụng bộ nhớ hợp nhất.
  • Không trỏ ABLIT_DIRECTION đến vector của checkpoint không liên quan mà chưa xác minh hidden size của vector đó.

Khắc phục sự cố

Dịch vụ không bao giờ chuyển sang trạng thái khỏe mạnh

Kiểm tra cả hai log bằng ./start.sh logs và ./start.sh logs worker. Kiểm tra SSH không cần mật khẩu, dung lượng đĩa khả dụng, quyền Docker, tính đầy đủ của cache và tên interface CX7. Việc tải trọng số ban đầu và capture graph diễn ra chậm, vì vậy chỉ nên để thời gian chờ readiness mặc định hết sau khi đã xem tiến trình trong log.

NCCL bị treo trong quá trình khởi tạo rank

Hãy xác minh HEAD_CX7_IF, WORKER_CX7_IF, HEAD_CX7_IB và WORKER_CX7_IB. Các giá trị mặc định được ghi trong tài liệu gắn với các cổng vật lý của phòng thí nghiệm và có thể cần điều chỉnh nếu hệ thống đi dây của bạn khác.

Worker không thể truy cập GHCR

Worker không cần truy cập GHCR trực tiếp. Head sẽ tải image công khai rồi truyền image qua SSH. Nếu head gặp giới hạn tốc độ đối với truy cập ẩn danh, hãy cấu hình GHCR_USER và GHCR_TOKEN.

Giải mã suy đoán chậm bất thường

Hãy xác nhận rằng SPEC_METHOD=dflash, DFLASH_TOKENS=7 và attention bản nháp không bị buộc sử dụng TRITON_ATTN. Cũng cần nhớ rằng hiệu năng giải mã suy đoán thay đổi tùy loại đầu ra: các chuỗi có cấu trúc chặt chẽ có thể đạt tỷ lệ chấp nhận cao hơn nhiều so với văn xuôi không bị ràng buộc.

Kết luận

Dự án này biến một cặp hệ thống NVIDIA GB10 thành máy chủ GLM-5.3 Flash tương thích với OpenAI, sử dụng trọng số EXL3 nhỏ gọn, bộ nhớ đệm sparse-MLA fp8 và giải mã suy đoán DFlash2. Cách nhanh nhất là giữ nguyên các giá trị mặc định được cung cấp cho mạng, KV, attention và lượng tử hóa, khởi chạy bằng ./start.sh, rồi xác thực quá trình triển khai thông qua endpoint kiểm tra tình trạng, API trò chuyện, log và các benchmark giải mã đi kèm.