vLLM có hỗ trợ GGUF, nhưng cách thiết lập đúng phụ thuộc vào bản phát hành vLLM, checkpoint GGUF và tokenizer của nó. Tài liệu ổn định hiện tại hướng người dùng đến vllm-gguf-plugin riêng biệt; các hướng dẫn cũ mô tả một trình tải tích hợp sẵn. Hãy bắt đầu bằng cách xác định ngăn xếp đã cài đặt của bạn, sau đó xác thực một mô hình nhỏ trước khi chuyển sang khối lượng công việc sản xuất.
Hướng dẫn này tập trung vào việc tải và phục vụ chính xác một checkpoint GGUF. Để lựa chọn giữa GGUF, AWQ, GPTQ và FP8, hãy sử dụng hướng dẫn lượng tử hóa vLLM toàn diện hơn của chúng tôi.
Hỗ trợ GGUF trong vLLM hiện nay có nghĩa là gì
GGUF là một định dạng tệp mô hình. Tên tệp kết thúc bằng .gguf không chứng minh rằng một runtime hỗ trợ mọi kiến trúc, loại lượng tử hóa hoặc thành phần phụ trợ bên trong tệp đó. Hãy coi khả năng tương thích là sự kết hợp của runtime + plugin + kiến trúc mô hình + lượng tử hóa + tokenizer + phần cứng.
Tài liệu GGUF của vLLM hiện tại mô tả một quy trình thử nghiệm với các giới hạn về hiệu năng và tính năng. Tài liệu này nêu bộ chọn Hugging Face repo_id:quant_type cũng như các tệp cục bộ, đồng thời khuyến nghị sử dụng tokenizer của mô hình gốc. Điều này khác với hướng dẫn v0.8.4, vốn mô tả quy trình tệp cục bộ cũ hơn. Hãy khớp tài liệu với phiên bản mà bạn thực sự đang chạy.
| Những gì bạn tìm thấy | Điều cần kiểm tra tiếp theo |
|---|---|
| Một bản cài đặt ổn định gần đây | Liệu plugin GGUF có được cài đặt trong cùng môi trường Python với vLLM hay không |
| Một container cũ hoặc bản phát hành được ghim phiên bản | Tài liệu tương ứng theo phiên bản; tránh trộn trình tải cũ với các cờ hiện tại |
| Một GGUF hoạt động trong runtime khác | Kiến trúc, ánh xạ tensor, tokenizer và các tính năng bắt buộc trong ngăn xếp vLLM của bạn |
Một ví dụ dùng --omni |
Liệu bạn có đang dùng vLLM-Omni thay vì quy trình phục vụ văn bản trong hướng dẫn này hay không |
Hướng dẫn GGUF cho vLLM-Omni đề cập đến các cấu hình đa phương thức riêng biệt và adapter dành riêng cho từng mô hình. Các ví dụ diffusion của nó không phải là lệnh có thể dùng trực tiếp cho máy chủ vLLM chỉ phục vụ văn bản.
1. Ghi lại môi trường trước khi cài đặt bất kỳ thứ gì
Hãy sử dụng một môi trường kiểm thử sạch trên máy GPU dự định sử dụng. Trước tiên, xác nhận rằng bản cài đặt vLLM cơ sở phù hợp với máy đó bằng hướng dẫn cài đặt GPU chính thức. Chỉ cài đặt thành công gói Python không thôi chưa xác lập được khả năng tương thích của driver hoặc thiết bị.
Ghi lại phiên bản gói mà không cần nhập mô hình:
from importlib.metadata import version, PackageNotFoundError
for package in ("vllm", "vllm-gguf-plugin", "torch", "transformers"):
try:
print(package, version(package))
except PackageNotFoundError:
print(package, "not installed")
Trên máy chủ NVIDIA, cũng hãy lưu lại nvidia-smi, mẫu GPU, bộ nhớ khả dụng, cùng thẻ image container hoặc lockfile môi trường. Lưu bản ghi này cùng với bản sửa đổi của kho mô hình và tên lượng tử hóa. Nếu một lần nâng cấp trong tương lai thất bại, các chi tiết này giúp bạn so sánh hai môi trường đã biết thay vì đoán xem phụ thuộc nào đã thay đổi.
2. Cài đặt plugin GGUF trong môi trường phục vụ
Khi môi trường vLLM tương thích đã được chuẩn bị, tài liệu ổn định hiện tại đưa ra lệnh cài đặt gói sau:
uv pip install vllm-gguf-plugin
Kiểm tra rằng uv đang hoạt động trên môi trường chứa tệp thực thi vllm. Việc cài plugin vào một môi trường ảo rồi khởi chạy máy chủ từ một môi trường khác sẽ không khiến plugin khả dụng cho máy chủ đó.
Đối với bản dựng từ mã nguồn, hãy làm theo hướng dẫn cài đặt của kho plugin. Chúng yêu cầu bộ công cụ CUDA hoặc ROCm và xây dựng dựa trên bản cài đặt PyTorch mà vLLM sử dụng; vì lý do đó, quy trình cài đặt editable được tài liệu hóa của chúng sẽ tắt build isolation. Hãy dùng hướng dẫn của kho cho bản sửa đổi mà bạn chọn, thay vì thêm các cờ trình biên dịch không liên quan trước khi bản dựng thành công.
Kho plugin cũng liệt kê các họ mô hình và mức lượng tử hóa đã được kiểm thử tạo sinh. Hãy dùng các kiểm thử đó làm điểm khởi đầu cho canary đầu tiên. Chúng không phải là bằng chứng rằng mọi chuyển đổi GGUF của mọi mô hình đều hoạt động.
3. Tải một checkpoint nhỏ với tokenizer được chỉ định rõ ràng
Lệnh sau sử dụng ví dụ Qwen nhỏ được dự án plugin tài liệu hóa, thêm một listener chỉ cục bộ và đặt cho API một tên mô hình có thể dự đoán:
vllm serve Qwen/Qwen3-0.6B-GGUF:Q8_0 \
--tokenizer Qwen/Qwen3-0.6B \
--served-model-name gguf-canary \
--host 127.0.0.1 \
--port 8000
Đây là kiểm thử nhanh về khả năng tương thích, không phải benchmark hiệu năng. Lệnh này tải xuống các tài nguyên mô hình và cần một runtime cùng thiết bị được hỗ trợ. Đừng diễn giải việc chọn checkpoint nhỏ là khuyến nghị mô hình cho ứng dụng của bạn.
Đối với tệp cục bộ, hãy thay bộ chọn mô hình bằng đường dẫn GGUF thực tế của bạn và giữ tokenizer của mô hình cơ sở tương ứng. Xác nhận rằng tệp đầy đủ và việc xử lý mọi tệp bị chia nhỏ được phiên bản đã cài đặt của bạn hỗ trợ trước khi phục vụ tệp đó. Việc đổi tên một checkpoint bất kỳ không chuyển đổi định dạng của nó.
Nếu không thể phân giải siêu dữ liệu cấu hình, tài liệu hiện tại cung cấp --hf-config-path làm đầu vào cấu hình tường minh. Hãy dùng cấu hình thực sự thuộc về kiến trúc cơ sở của checkpoint. Một cấu hình thuận tiện nhưng không liên quan có thể biến lỗi tải rõ ràng thành các lỗi tensor hoặc đầu ra khó chẩn đoán hơn.
4. Tách riêng các bước kiểm tra tải, API và đầu ra
Khi máy chủ báo đã sẵn sàng, hãy truy vấn danh sách mô hình từ một terminal thứ hai:
curl --fail --silent --show-error http://127.0.0.1:8000/v1/models
Sau đó gửi một completion nhỏ đến tên được phục vụ tường minh:
curl --fail --silent --show-error \
http://127.0.0.1:8000/v1/completions \
-H 'Content-Type: application/json' \
-d '{"model":"gguf-canary","prompt":"The capital of France is","max_tokens":16,"temperature":0}'
Tài liệu máy chủ tương thích OpenAI mô tả các endpoint được hỗ trợ và hành vi yêu cầu. Một completion thuần giúp bước kiểm tra đầu tiên độc lập với cấu hình chat template. Sau khi bước đó thành công, hãy kiểm tra riêng lẻ chat template thực tế, các yêu cầu đầu ra có cấu trúc, streaming và các tính năng ứng dụng khác của bạn.
Hãy lưu ba kết quả riêng biệt trong hồ sơ triển khai của bạn:
- Tải: trọng số và tokenizer khởi tạo mà không có lỗi lớp không được hỗ trợ hoặc lỗi tensor.
- Phục vụ: endpoint bắt buộc trả về phản hồi hợp lệ cho tên mô hình được phục vụ.
- Sử dụng: đầu ra đáp ứng một bộ tiêu chí đúng đắn nhỏ, đặc thù cho ứng dụng.
Một phản hồi HTTP 200 chỉ vượt qua phần API. Văn bản trống, token lặp lại, định dạng không đúng hoặc câu trả lời tác vụ thất bại vẫn cần được điều tra. Giữ máy chủ ban đầu liên kết với localhost; thêm các biện pháp xác thực và kiểm soát mạng thông thường của bạn trước khi mở nó cho các client khác.
Khắc phục sự cố theo giai đoạn thất bại đầu tiên
| Triệu chứng | Kiểm tra trước | Thay đổi có kiểm soát tiếp theo |
|---|---|---|
| Plugin hoặc phương thức lượng tử hóa không được nhận diện | Môi trường Python đang hoạt động và các phiên bản gói đã cài đặt | Tái tạo trong môi trường tương thích, sạch |
| Import thất bại với lỗi nhị phân hoặc ký hiệu | Sự tương thích giữa PyTorch, CUDA/ROCm và bản dựng plugin | Xây dựng lại theo quy trình được plugin ghi trong tài liệu |
| Không tìm thấy bộ chọn mô hình hoặc lượng tử hóa | Chính tả repository, lượng tử hóa đã chọn, quyền truy cập, độ đầy đủ của bản tải xuống | Thử checkpoint nhỏ được dự án ghi trong tài liệu |
| Tên hoặc hình dạng tensor không khớp | Kiến trúc mô hình, nguồn gốc chuyển đổi, cấu hình | Dùng bản chuyển đổi được hỗ trợ của cùng mô hình cơ sở |
| Quá trình tải bị treo quanh tokenizer | Danh tính và phiên bản của tokenizer | Cung cấp tường minh tokenizer của mô hình cơ sở tương ứng |
| Completion hoạt động nhưng chat thất bại | Chat template và định dạng yêu cầu của ứng dụng | Kiểm tra một yêu cầu chat tối giản trước khi thêm các tính năng bổ sung |
| Mô hình tải được nhưng hết bộ nhớ khi có lưu lượng | Độ dài ngữ cảnh, yêu cầu đang hoạt động, bộ nhớ runtime, KV cache | Giảm một chiều khối lượng công việc và lặp lại cùng phép kiểm tra |
Lưu lỗi có ý nghĩa đầu tiên và lệnh chính xác. Thay đổi đồng thời mô hình, tokenizer, driver và mức độ đồng thời có thể loại bỏ một lỗi nhưng che giấu nguyên nhân của nó.
Quyết định có tiếp tục dùng GGUF sau khi vượt qua các bước tương thích hay không
Một tệp nhỏ hơn hữu ích khi việc lưu trữ trọng số hoặc bộ nhớ là ràng buộc của bạn. Điều đó không chứng minh lợi thế về độ trễ. Hãy so sánh cùng mô hình cơ sở và bộ tác vụ với một checkpoint thay thế được hỗ trợ trước khi chọn định dạng phục vụ.
Hãy dùng độ dài đầu vào, độ dài đầu ra và mức yêu cầu đồng thời dự kiến của bạn. Ghi lại mức độ thành công của tác vụ, thời gian đến token đầu tiên, độ trễ đuôi, thông lượng và bộ nhớ đỉnh. CLI benchmark phục vụ chính thức có thể tạo lưu lượng có kiểm soát; các tùy chọn và tập dữ liệu của nó cần phù hợp với phiên bản bạn đã cài đặt. Một lượt kiểm tra tải tổng hợp và một bài kiểm thử chấp nhận ứng dụng trả lời các câu hỏi khác nhau, vì vậy hãy lưu riêng cả hai kết quả.
Nếu các tính năng hoặc đầu ra bắt buộc của GGUF thất bại, trước hết hãy hỏi liệu bạn có cần chính xác checkpoint này hay không. Khi một định dạng khác đáp ứng khối lượng công việc với ít bất định vận hành hơn, việc chuyển đổi hoặc một bản phân phối được hỗ trợ khác có thể là lựa chọn đơn giản hơn. Hãy giữ bài so sánh định dạng của chúng tôi làm công cụ hỗ trợ quyết định tổng quát hơn thay vì lặp lại một khảo sát lượng tử hóa đầy đủ tại đây.
Lập kế hoạch dung lượng GPU đám mây dựa trên khối lượng công việc đã được chấp nhận
Sau khi mô hình vượt qua các bước kiểm tra ở trên, hãy định cỡ môi trường GPU cho yêu cầu bộ nhớ và mức đồng thời đã kiểm thử. Cloud GPU Compute của Flatkey cung cấp các tùy chọn thuê GPU NVIDIA. Xác nhận cấu hình khả dụng, khu vực, dung lượng, thông tin truy cập và điều khoản thuê cho thử nghiệm dự kiến. Hướng dẫn này không khẳng định ví dụ đã được benchmark trên dịch vụ thuê của Flatkey hoặc một card cụ thể luôn sẵn có.
Chuẩn bị một bản bàn giao ngắn gọn: bản sửa đổi mô hình, phương pháp lượng tử hóa, phiên bản phần mềm, nhu cầu ổ đĩa ước tính, giới hạn ngữ cảnh, mức đồng thời mục tiêu và các ngưỡng chấp nhận. Điều đó giúp cuộc thảo luận về hạ tầng trở nên cụ thể và tránh nhầm lẫn một vấn đề tương thích phần mềm với nhu cầu thuê GPU lớn hơn.
Câu hỏi thường gặp
vLLM có hỗ trợ mọi mô hình GGUF không?
Không. Hãy xác thực đồng thời kiến trúc, phương pháp lượng tử hóa, tokenizer, phần cứng và các tính năng. Hỗ trợ một định dạng tệp không đồng nghĩa với việc hỗ trợ phổ quát mọi mô hình được lưu trữ ở định dạng đó.
Tại sao các hướng dẫn cũ hơn lại nói cần truyền một tệp cục bộ?
Chúng có thể mô tả một bản phát hành trước đó. Tài liệu vLLM theo phiên bản và hướng dẫn plugin hiện tại có thể mô tả các đường dẫn tải khác nhau. Hãy sử dụng hướng dẫn phù hợp với ngăn xếp bạn đã cài đặt.
Tôi có thể tái sử dụng tokenizer từ một mô hình khác không?
Hãy sử dụng tokenizer thuộc mô hình cơ sở của checkpoint, trừ khi nhà phát hành của mô hình đó ghi rõ một lựa chọn tương thích khác. Một máy chủ khởi động với tokenizer không liên quan vẫn có thể tạo ra kết quả không chính xác.
Tải thành công có đủ để đưa vào môi trường production không?
Không. Hãy hoàn tất các kiểm tra về endpoint, chất lượng tác vụ, tính năng và tải thực tế. Câu trả lời thực tế cho việc hỗ trợ GGUF trong vLLM là một cấu hình có thể tái lập và vượt qua các kiểm tra, chứ không chỉ đơn thuần là cài đặt gói thành công.
