SGLang Prefill Decode Disaggregation: Hướng dẫn kiến trúc và triển khai
Xác minh lần cuối: ngày 16 tháng 10 năm 2026. Các cờ SGLang và tổ hợp tính năng được hỗ trợ thay đổi nhanh chóng; hãy ghim image hoặc commit SGLang đã được kiểm thử trước khi áp dụng hướng dẫn này trong môi trường production.
Phân tách prefill decode của SGLang tách biệt hai tác vụ rất khác nhau trong việc phục vụ LLM: xử lý prompt chạy trên một nhóm prefill, trong khi tạo token chạy trên một nhóm decode. Các nhóm trao đổi KV cache của yêu cầu, và một router cung cấp một endpoint suy luận duy nhất cho client.
Sự tách biệt đó có thể bảo vệ độ trễ giữa các token khi prompt dài xuất hiện, đồng thời cho phép bạn mở rộng năng lực prefill nặng về tính toán khác với năng lực decode bị giới hạn bởi bộ nhớ. Nó cũng bổ sung một đường truyền, một ranh giới scheduler khác và bề mặt tương thích lớn hơn. Hãy xem đây là một kiến trúc phục vụ cần được đo lường—không phải một công tắc tự động làm mọi workload nhanh hơn.
Hướng dẫn này giải thích kiến trúc phân tách prefill decode của SGLang, một mô hình triển khai tối thiểu, những gì cần đo lường và các điều kiện nên dừng rollout.
Câu trả lời nhanh: khi phân tách PD xứng đáng với độ phức tạp của nó
Tài liệu upstream của SGLang mô tả prefill là tác vụ tiêu tốn nhiều tính toán, còn decode tiêu tốn nhiều KV cache và bộ nhớ. Trong một scheduler hợp nhất, công việc prefill đến có thể làm gián đoạn công việc decode; với attention song song dữ liệu, các worker khác nhau cũng có thể mất cân bằng giữa hai giai đoạn. Phân tách PD tách riêng các giai đoạn đó để mỗi giai đoạn có thể được lập lịch và cấp phát độc lập. Tài liệu PD của SGLang là nguồn đáng tin cậy cho các tổ hợp hiện được hỗ trợ.
| Tín hiệu workload | Phân tách prefill decode của SGLang có phải là ứng viên phù hợp? | Lý do |
|---|---|---|
| Prompt dài hoặc biến thiên lớn, với người dùng nhạy cảm với độ mượt của streaming | Thường là có | Prefill dài ít có khả năng làm gián đoạn một nhóm decode đang hoạt động hơn. |
| Áp lực bộ nhớ decode khác biệt đáng kể so với áp lực tính toán của prompt | Thường là có | Bạn có thể định cỡ các nhóm và giới hạn đồng thời theo điểm nghẽn thực tế của chúng. |
| Một triển khai GPU đa node đã có fabric truyền KV độ trễ thấp được xác thực | Thường là có | Ranh giới truyền bổ sung là thực tế về mặt vận hành. |
| Một máy chủ GPU nhỏ, prompt ngắn đồng đều hoặc lưu lượng thấp | Thường không phải lựa chọn đầu tiên | Một server hợp nhất đơn giản hơn và có thể tránh overhead truyền dữ liệu. |
| Một workload phụ thuộc vào lịch sử phản hồi cục bộ theo process hoặc các công cụ server tích hợp sẵn | Không, cho đến khi được xác thực | Tài liệu PD upstream hiện tại liệt kê các quy trình Response API có trạng thái và các công cụ tích hợp sẵn trong số những workflow không được hỗ trợ. |
Quyết định không phải là “prefill nhanh, decode chậm”. Đó là liệu việc cô lập hàng đợi và giới hạn phần cứng của chúng có cải thiện mục tiêu mà người dùng nhìn thấy và bạn quan tâm hay không—thường là thời gian đến token đầu tiên (TTFT), độ trễ giữa các token (ITL), độ trễ tail hoặc số yêu cầu hoàn thành trong một ngân sách năng lực cố định.
Phân tách prefill decode hoạt động như thế nào trong SGLang
Topology PD của SGLang có ba vai trò logic:
- Router: nhận yêu cầu từ client, chọn đường prefill và decode, rồi stream phản hồi đã hợp nhất trở lại client.
- Worker prefill: token hóa và xử lý toàn bộ prompt, sau đó tạo trạng thái KV-cache cần thiết để tiếp tục sinh.
- Worker decode: nhận trạng thái KV đó và tạo các token đầu ra cho đến khi yêu cầu hoàn tất.
Việc bàn giao là phần quan trọng. Worker prefill không gửi văn bản đến một decoder mới rồi bắt nó lặp lại prompt. Nó truyền trạng thái KV-cache để decode có thể tiếp tục từ cùng ngữ cảnh attention. SGLang hiện ghi nhận Mooncake và NIXL là các engine truyền PD; hãy chọn transport và đường mạng mà phiên bản đã ghim cùng phần cứng của bạn thực sự hỗ trợ.
client
│
▼
PD router ──► prefill pool ──► KV-cache transfer ──► decode pool ──► streamed tokens
compute-heavy fabric memory-sensitive
Trong một cluster đa node, mỗi vai trò có thể có số lượng replica, cấu hình GPU, giới hạn hàng đợi, chính sách autoscaling và ngân sách lỗi riêng. Điều đó chỉ hữu ích nếu router và fabric truyền KV được xem là các dependency production thay vì phần kết nối vô hình.
Trước khi triển khai: năm kiểm tra giúp ngăn kết quả gây hiểu lầm
1. Ghim chính xác bản phát hành SGLang và cấu hình mô hình
Chạy cùng image hoặc commit SGLang đã được kiểm thử trên router, worker prefill và worker decode. Giữ rõ ràng model revision, tokenizer, quantization, attention backend, chiến lược song song hóa và các cờ dành riêng cho mô hình trong manifest. Một lệnh hoạt động ở phiên bản này có thể không hợp lệ hoặc có ngữ nghĩa khác ở phiên bản khác.
2. Chứng minh đường truyền KV trước khi mở rộng lưu lượng
PD là một kiến trúc mặt phẳng dữ liệu. Hãy xác thực ánh xạ NIC hoặc kết nối liên thông, khả năng hiển thị thiết bị trong container, giới hạn máy chủ và backend truyền dữ liệu trước khi diễn giải độ trễ của mô hình. Các triển khai dành riêng cho Mooncake có thể yêu cầu cấu hình InfiniBand/RDMA; tài liệu SGLang cũng nêu việc lựa chọn backend NIXL cho hạ tầng tương thích. Đừng suy luận rằng một đường truyền thông tập thể nhanh tự động chứng minh đường truyền KV đang hoạt động tốt.
3. Thiết lập đường cơ sở máy chủ hợp nhất
Sử dụng cùng mô hình, prompt, độ dài sinh, tổ hợp mức đồng thời, cài đặt lấy mẫu và ngân sách phần cứng cho cả đường cơ sở lẫn thử nghiệm PD. Đo tối thiểu TTFT p50/p95, ITL p50/p95, thông lượng yêu cầu, hành vi hủy và tỷ lệ lỗi. Chỉ số sử dụng GPU cao hơn tự nó không phải là một kết quả phục vụ.
4. Xác định ranh giới vai trò trong bộ lập lịch của bạn
Giữ cho pod, dịch vụ, nhật ký và cảnh báo của prefill và decode có thể được định địa chỉ riêng biệt. Nếu bạn không thể biết vai trò nào đang xếp hàng, hết dung lượng KV hoặc đang chờ truyền dữ liệu, kiến trúc này sẽ khó vận hành hơn một cụm hợp nhất.
5. Đọc các ràng buộc tương thích hiện tại—không chỉ khối khởi động nhanh
Tài liệu phân tách prefill decode của SGLang bao gồm các hạn chế đối với những chính sách và quy trình công việc có trạng thái cụ thể. Ví dụ, chính sách phân bổ decode prefill_complete được tài liệu hóa có phạm vi hỗ trợ hẹp hơn chính sách mặc định. Hãy xác thực mọi tổ hợp tính năng nâng cao trong lần chạy staging trước khi biến chúng thành một phần của cam kết về tính sẵn sàng.
Một triển khai phân tách prefill decode SGLang tối thiểu
Bắt đầu với một worker prefill, một worker decode và một router trên máy chủ hai GPU. Đây là bài kiểm tra nghiệm thu chức năng, không phải khẳng định rằng hai GPU là cấu hình cho môi trường sản xuất. Ví dụ NIXL sau đây tuân theo mẫu đơn nút upstream hiện tại; hãy sử dụng cú pháp lệnh chính xác từ tài liệu dành cho phiên bản SGLang đã ghim của bạn.
# GPU 0: prefill role
python -m sglang.launch_server \
--model-path meta-llama/Llama-3.1-8B-Instruct \
--disaggregation-mode prefill \
--disaggregation-transfer-backend nixl \
--port 30000
# GPU 1: decode role
python -m sglang.launch_server \
--model-path meta-llama/Llama-3.1-8B-Instruct \
--disaggregation-mode decode \
--disaggregation-transfer-backend nixl \
--base-gpu-id 1 \
--port 30001
# Client-facing PD router
python -m sglang_router.launch_router \
--pd-disaggregation \
--prefill http://127.0.0.1:30000 \
--decode http://127.0.0.1:30001 \
--host 0.0.0.0 \
--port 8000
Gửi một yêu cầu ngắn qua router thay vì trực tiếp đến một trong hai worker:
curl http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{
"model": "meta-llama/Llama-3.1-8B-Instruct",
"prompt": "Explain why KV-cache handoff matters in one sentence.",
"max_tokens": 64
}'
Thành công không chỉ đơn giản là nhận được văn bản. Hãy xác nhận router đã chọn cả hai vai trò, quá trình truyền KV đã hoàn tất, hành vi streaming vẫn nguyên vẹn và mỗi tiến trình báo cáo đúng cài đặt mô hình cũng như tương thích dự kiến. Hãy duy trì triển khai phân tách prefill decode SGLang nhỏ này trong CI hoặc môi trường tiền sản xuất để một bản nâng cấp không âm thầm làm hỏng đường dẫn PD.
Đối với triển khai Mooncake, hãy sử dụng hướng dẫn SGLang PD hiện tại để biết cách cài đặt transfer engine cần thiết và cấu hình thiết bị IB. Không sao chép các biến môi trường Mooncake từ một phương thức truyền tải, đám mây hoặc bản phát hành SGLang khác.
Chuyển từ một cặp sang cấu trúc liên kết sản xuất
Khi cặp cơ bản hoạt động tốt, hãy mở rộng từng vai trò dựa trên dữ liệu hàng đợi và tài nguyên thay vì giả định tỷ lệ 1:1.
| Lớp | Mở rộng dựa trên quan sát này | Biện pháp kiểm soát thực tế |
|---|---|---|
| Nhóm prefill | Hàng đợi prompt tăng, năng lực tính toán prefill bão hòa hoặc các giá trị đuôi TTFT tăng | Thêm bản sao prefill hoặc thay đổi cấu hình GPU cho prefill sau một thử nghiệm có kiểm soát. |
| Nhóm decode | Các chuỗi đang hoạt động làm cạn dung lượng KV, các giá trị đuôi ITL tăng hoặc việc tiếp nhận decode phải chờ | Thêm bản sao decode, giảm mức đồng thời hoặc chỉ tăng bộ nhớ cho mỗi worker sau khi xác thực kích thước bộ nhớ của mô hình. |
| Hạ tầng truyền KV | Thời gian truyền hoặc lỗi truyền chiếm ưu thế trong dòng thời gian yêu cầu | Xác thực ánh xạ thiết bị, backend, tình trạng hạ tầng và tính cục bộ của cấu trúc liên kết trước khi thêm bản sao mô hình. |
| Router | Xảy ra hiện tượng worker không khỏe bị thay thế liên tục, hàng đợi không đồng đều hoặc độ trễ định tuyến | Sử dụng cấu trúc liên kết và chính sách router cho môi trường sản xuất được bản phát hành SGLang của bạn hỗ trợ. |
Đối với các mẫu đa nút, SGLang công bố các ví dụ khởi chạy prefill và decode riêng biệt cho triển khai lớp DeepSeek, bao gồm khởi tạo phân tán và các đối số song song hóa theo từng vai trò. Những ví dụ đó là một mẫu tham khảo hữu ích, nhưng mô hình, phần cứng và phiên bản SGLang vẫn cần bài kiểm tra nghiệm thu riêng. Hãy xem các ví dụ PD đa nút upstream trước khi điều chỉnh manifest cụm.
Nếu Kubernetes quản lý vòng đời, hãy cấp cho prefill và decode các nhãn, dịch vụ, ngân sách gián đoạn, bảng điều khiển và probe sẵn sàng riêng biệt. Các điều kiện tiên quyết ở cấp cụm rộng hơn—khả năng truy cập GPU, xếp hàng, lưu trữ, mạng và khả năng quan sát—được trình bày trong hướng dẫn về cụm GPU Kubernetes của chúng tôi.
Các chỉ số cho việc tách rời prefill decode của SGLang
Tách rời prefill decode của SGLang cần cải thiện một kết quả tải công việc đã chọn, chứ không chỉ tạo ra một biểu đồ tài nguyên khác. Hãy đo lường dòng thời gian yêu cầu với các khoảng thời gian riêng biệt cho prefill, truyền, nhận decode và tạo sinh.
| Chỉ số | Cho biết điều gì | Đọc cùng với |
|---|---|---|
| TTFT, p50 và p95 | Xếp hàng prompt cộng với thực thi prefill và bàn giao | Các nhóm theo độ dài prompt và độ sâu hàng đợi prefill |
| ITL, p50 và p95 | Nhịp token sau khi quá trình tạo sinh bắt đầu | Các chuỗi decode đang hoạt động và mức sử dụng KV decode |
| Thời lượng và lỗi truyền KV | Liệu quá trình bàn giao có là nút thắt hoặc nguồn lỗi hay không | Thông lượng fabric, số lần thử lại, tình trạng NIC và nhật ký backend |
| Tuổi hàng đợi prefill/decode | Liệu tỷ lệ các pool có sai hay không | Số replica theo vai trò và giới hạn đồng thời |
| Số yêu cầu hoàn thành mỗi giây | Năng lực hữu ích theo tổ hợp thực tế | Tỷ lệ lỗi, tỷ lệ hủy và các SLO độ trễ |
| Mức sử dụng GPU compute, HBM và CPU máy chủ | Hỗ trợ chẩn đoán, không phải kết quả | Bốn thời điểm theo giai đoạn yêu cầu ở trên |
Chạy hai bộ kiểm thử. Một bộ nên dùng tổ hợp lưu lượng bạn dự kiến hiện tại; bộ còn lại nên chủ ý bao gồm các prompt dài, độ dài tạo sinh biến thiên, các lần hủy và các đợt tăng đột biến. PD có thể trông rất tốt với một prompt tổng hợp trung bình nhưng không đạt được mục đích thực tế khi gặp tổ hợp production lệch.
Chính sách cấp phát decode: một cơ chế kiểm soát có mục tiêu, không phải mẹo tinh chỉnh mặc định
Theo mặc định, SGLang ghi nhận hành vi cấp phát decode early: các slot KV đích được giữ chỗ trước khi prefill hoàn tất. Do đó, các prefill dài có thể chiếm năng lực decode trong khi phía decode chờ dữ liệu KV.
Giải pháp thay thế được ghi nhận là:
--disaggregation-decode-allocation-policy prefill_complete
Với prefill_complete, SGLang trì hoãn cấp phát tại đích cho đến khi prefill sẵn sàng. Điều này có thể hữu ích khi các prompt dài cạnh tranh với lưu lượng decode đang hoạt động để giành năng lực KV đích, nhưng cũng thay đổi phạm vi chồng lấp và hỗ trợ. Tài liệu upstream cho biết cần đặt chính sách trên cả prefill và decode, đồng thời liệt kê một số tổ hợp không tương thích. Hãy coi đây là một thử nghiệm được kiểm soát với các tiêu chí rollback, không phải một tối ưu hóa phổ quát.
Các chế độ lỗi phổ biến và bước kiểm tra tiếp theo nhanh nhất
| Triệu chứng | Ranh giới có khả năng cần kiểm tra | Bước kiểm tra tiếp theo nhanh |
|---|---|---|
| Router nhận yêu cầu nhưng không có token nào trả về | Khả năng kết nối đến worker hoặc quá trình bàn giao vai trò bị lỗi | Kiểm tra nhật ký router, tình trạng worker và một trace bao trùm từ prefill đến decode. |
| Thời gian chờ decode tăng trong khi prefill vẫn ổn | Nhận decode hoặc áp lực KV đích | Kiểm tra các chuỗi đang hoạt động, mức sử dụng KV và chính sách cấp phát trước khi thêm năng lực prefill một cách tùy tiện. |
| TTFT cải thiện nhưng ITL xấu đi | Nút thắt ở pool decode hoặc truyền KV | So sánh tuổi hàng đợi decode, thời lượng truyền và số lượng chuỗi hoạt động với baseline hợp nhất. |
| Lưu lượng đa nút thỉnh thoảng bị treo hoặc thử lại | Network fabric, ánh xạ thiết bị hoặc cấu hình worker không nhất quán | Xác minh chính xác bản build SGLang, backend truyền, ánh xạ NIC và manifest vai trò trên mọi nút. |
| Một tính năng nâng cao hoạt động ở chế độ hợp nhất nhưng lỗi trong PD | Tổ hợp tính năng không được hỗ trợ | Đọc phần tương thích PD hiện tại và tái hiện với topology được hỗ trợ nhỏ nhất. |
| Mức sử dụng GPU tăng nhưng độ trễ người dùng không cải thiện | Tối ưu hóa nhắm vào sai giai đoạn | Quay lại TTFT, ITL, tuổi hàng đợi, lỗi và thông lượng công việc hoàn thành. |
Việc triển khai tách rời prefill decode của SGLang cần có khả năng đảo ngược. Hãy duy trì một tuyến phục vụ hợp nhất hoặc một bản sửa đổi triển khai đã biết là tốt cho đến khi cấu hình PD đạt các ngưỡng độ trễ và độ tin cậy đã xác định trên tổ hợp tải công việc quan trọng.
Trình tự triển khai an toàn
- Baseline: Thu thập benchmark SGLang hợp nhất với các prompt, đầu ra, mức đồng thời và tình huống lỗi tương tự production.
- Một cặp: Khởi chạy một worker prefill, một worker decode và một router; vượt qua các bước kiểm tra chức năng, streaming, hủy và khởi động lại.
- Khả năng quan sát theo vai trò: Tách nhật ký, bảng điều khiển, cảnh báo và giới hạn năng lực theo router, prefill, truyền và decode.
- Tải được kiểm soát: So sánh PD với baseline theo nhóm độ dài prompt và độ dài đầu ra, không chỉ theo giá trị trung bình.
- Mở rộng từng ràng buộc một: Điều chỉnh kích thước pool, cấu hình GPU, mức đồng thời hoặc cấu hình truyền trong các thử nghiệm riêng biệt.
- Canary và rollback: Điều hướng một phần lưu lượng có giới hạn, xác định ngưỡng rollback về độ trễ/lỗi và giữ lại cấu hình lành mạnh gần nhất.
Trình tự này biến PD disaggregation prefill decode của SGLang từ một sơ đồ kiến trúc đầy hứa hẹn thành một thay đổi có thể kiểm thử trong vận hành.
Câu hỏi thường gặp
PD disaggregation có luôn tăng thông lượng không?
Không. Nó có thể cải thiện một khối lượng công việc mà tranh chấp giữa prefill và decode là nút thắt, nhưng cũng làm phát sinh chi phí truyền KV, lập lịch router và vận hành. Hãy kiểm thử so với đường cơ sở hợp nhất bằng cùng hỗn hợp lưu lượng và ngân sách năng lực.
Prefill có chạy trên mô hình khác với decode không?
Không. Các vai trò tiếp tục một yêu cầu logic duy nhất. Hãy duy trì sự nhất quán giữa cặp này về mô hình, tokenizer, revision, lượng tử hóa và cấu hình phục vụ đã được kiểm thử, trừ khi tài liệu upstream nêu rõ hỗ trợ một cách sắp xếp khác.
Tôi nên sử dụng backend truyền nào?
Hãy sử dụng backend được bản phát hành SGLang mà bạn đã ghim hỗ trợ và đã được xác thực trên fabric thực tế của bạn. Tài liệu SGLang hiện tại mô tả Mooncake và NIXL, nhưng lựa chọn đúng phụ thuộc vào nền tảng, image container, thiết bị và mức hỗ trợ vận hành mà bạn đã xác minh.
Tôi có thể kết hợp SGLang prefill decode disaggregation với mọi tính năng nâng cao không?
Không. Hỗ trợ PD phụ thuộc vào tính năng và phiên bản. Hãy kiểm tra các ghi chú tương thích upstream hiện tại trước khi kết hợp nó với phản hồi có trạng thái, thực thi công cụ, tính năng bộ nhớ đệm, chế độ suy đoán hoặc hành vi vai trò không tiêu chuẩn.
Bước tiếp theo thiết thực
Hãy bắt đầu với môi trường chấp nhận một cặp, ghi lại các ngưỡng TTFT/ITL/lỗi đủ để biện minh cho kiến trúc này, và chỉ triển khai rộng hơn sau khi các luồng truyền và lỗi có thể quan sát được. Đối với các quyết định phục vụ liên quan, hãy so sánh vLLM và SGLang, xem xét suy đoán decoding cho suy luận LLM, và lập kế hoạch riêng cho cụm GPU Kubernetes nền tảng khỏi quá trình triển khai PD.
