vLLM Docker: Kiến trúc, Hiệu năng và Hướng dẫn Triển khai Đám mây

vLLM Docker: Kiến trúc, Hiệu năng và Hướng dẫn Triển khai Đám mây

Docker là cách trực tiếp nhất để đặt vLLM phía sau một điểm cuối tương thích OpenAI trên các GPU do bạn kiểm soát. Tuy nhiên, một triển khai vLLM Docker tốt không chỉ là một lệnh docker run: nó cần một môi trường chạy GPU tương thích, kế hoạch bộ nhớ và đồng thời có giới hạn, xác thực ở lớp biên, cùng một cách có thể lặp lại để kiểm tra hiệu năng trước khi lưu lượng truy cập đến.

Hướng dẫn này trình bày kiến trúc, một lần triển khai ban đầu an toàn, các tham số thực sự thay đổi năng lực phục vụ, và lộ trình từ một GPU đến một cụm GPU trên đám mây.

Sử dụng vLLM Docker khi bạn cần kiểm soát trọng số mô hình, vị trí triển khai, cài đặt thời gian chạy hoặc một khối lượng công việc tự lưu trữ ổn định. Nếu chi phí vận hành lớn hơn lợi ích của sự kiểm soát đó, API mô hình được quản lý hoặc cổng hợp nhất thường là ranh giới phù hợp hơn.

vLLM Docker mang lại cho bạn điều gì

vLLM phát hành image Docker chính thức vllm/vllm-openai để khởi động một máy chủ tương thích OpenAI. Điều này biến vLLM Docker thành cầu nối hữu ích giữa kho lưu trữ mô hình và các ứng dụng vốn đã sử dụng cấu trúc client OpenAI: việc liệt kê mô hình, chat completions, completions, embeddings và các điểm cuối tương thích liên quan phụ thuộc vào mô hình cùng phiên bản máy chủ mà bạn triển khai. Tài liệu Docker của vLLM có các ví dụ mới nhất về image và thời gian chạy.

Hàm ý thực tế rất đơn giản: ứng dụng của bạn không cần một client máy chủ mô hình riêng biệt chỉ vì bạn chuyển khối lượng công việc sang GPU của chính mình. Tuy vậy, ứng dụng vẫn cần tên mô hình rõ ràng, khóa API, thời gian chờ và hành vi thử lại phù hợp với mục tiêu tính sẵn sàng của bạn.

Kiến trúc vLLM Docker hoạt động như thế nào

Ở cấp độ cao, vLLM Docker có năm lớp:

1. Client của bạn gửi một yêu cầu đã xác thực đến điểm cuối tương thích OpenAI.
2. Máy chủ API xác thực và mã hóa thành token yêu cầu, sau đó chuyển nó cho engine vLLM.
3. Bộ lập lịch gom nhóm công việc tương thích và phân phối chúng đến một hoặc nhiều worker GPU.
4. Các worker GPU lưu giữ trọng số mô hình và bộ nhớ đệm key-value (KV) trong khi tạo token.
5. Phản hồi được truyền trực tuyến qua máy chủ API về client.

Ý tưởng hiệu năng cốt lõi là PagedAttention. Thay vì dành trước một vùng bộ nhớ đệm KV liền mạch lớn cho độ dài tối đa có thể của yêu cầu, vLLM quản lý trạng thái KV theo các khối. Điều đó giúp dễ đóng gói các khối lượng công việc có độ dài thay đổi vào bộ nhớ sẵn có hơn, đồng thời cho phép các yêu cầu hoàn tất giải phóng khối cho công việc sau. Bài báo PagedAttention gốc mô tả bộ lập lịch, các worker GPU, các khối KV logic-vật lý và sự đánh đổi giữa việc sử dụng bộ nhớ đệm với xử lý theo lô.

Kiến trúc đó có một hệ quả vận hành quan trọng: VRAM không chỉ là “kích thước mô hình”. Nó được chia sẻ giữa trọng số mô hình, chi phí thời gian chạy, activation và bộ nhớ đệm KV có nhu cầu tăng theo độ dài ngữ cảnh và số yêu cầu đồng thời. Hãy coi ngữ cảnh, tính đồng thời và mức sử dụng bộ nhớ là một quyết định duy nhất—không phải ba tác vụ tinh chỉnh riêng biệt.

Trước khi chạy vLLM Docker trên GPU đám mây

Bắt đầu với bốn kiểm tra:

1. Chọn thẻ image đã được kiểm thử. Hãy cố định thẻ phát hành vLLM trong môi trường production thay vì mù quáng chạy theo latest. Đọc tài liệu khớp với thẻ đó trước khi dựa vào một cờ hoặc giá trị mặc định.
2. Sử dụng mô hình mà bạn được phép tải xuống và phục vụ. Một số kho lưu trữ yêu cầu token Hugging Face hoặc chấp nhận giấy phép mô hình. Cố định bản sửa đổi mô hình sau khi bạn xác thực nó.
3. Xác minh quyền truy cập GPU bên ngoài container mô hình. Cài đặt driver NVIDIA trên máy chủ và NVIDIA Container Toolkit, sau đó xác thực một container hỗ trợ GPU bằng nvidia-smi. Hướng dẫn cài đặt của NVIDIA bao gồm các điều kiện tiên quyết phía máy chủ và cấu hình thời gian chạy.
4. Giữ cổng ở chế độ riêng tư lúc đầu. Liên kết với loopback cho bản thử nghiệm khái niệm trên một máy chủ, hoặc giữ dịch vụ trong một mạng con riêng phía sau TLS, xác thực và reverse proxy/load balancer. Đừng coi máy chủ mô hình thuần túy là một ranh giới bảo mật hướng ra Internet.

Hãy sử dụng lệnh mẫu của NVIDIA trước khi gỡ lỗi chính vLLM:

docker run --rm --runtime=nvidia --gpus all ubuntu nvidia-smi

Nếu lệnh đó không thể thấy GPU dự kiến, hãy dừng tại đó. Nhật ký máy chủ mô hình sẽ không khắc phục được driver bị thiếu, môi trường chạy container chưa được cấu hình hoặc GPU chưa từng được gán cho VM đám mây.

Chạy máy chủ vLLM Docker trên một GPU

Dưới đây là một điểm khởi đầu được chủ ý giữ ở mức tối giản. Cấu hình này phản ánh mẫu image chính thức, nhưng bổ sung khóa API và liên kết cổng được công bố với loopback. Hãy thay các phần giữ chỗ bằng một mô hình và thẻ image mà bạn đã kiểm thử.

export HF_TOKEN="your_hugging_face_token"
export VLLM_API_KEY="replace-with-a-long-random-secret"
export VLLM_IMAGE="vllm/vllm-openai:<tested-version>"
export MODEL="Qwen/Qwen3-0.6B"

docker run -d \
  --name vllm-api \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --dtype auto \
  --api-key "$VLLM_API_KEY"

Thiết lập bộ nhớ dùng chung và điểm gắn bộ nhớ đệm Hugging Face tuân theo ví dụ vLLM Docker chính thức. Điểm gắn bộ nhớ đệm giúp tránh tải lại cùng trọng số mô hình khi vùng chứa được tạo lại. Khóa API là một biện pháp kiểm soát ở cấp ứng dụng, không thay thế cho cô lập mạng, TLS, giới hạn tốc độ hoặc trình quản lý bí mật.

Xác minh rằng máy chủ đang phục vụ đúng mô hình dự kiến trước khi kết nối ứng dụng:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/models \
  -H "Authorization: Bearer $VLLM_API_KEY"

Sau đó, gửi một yêu cầu nhỏ với cùng mã định danh mô hình được /v1/models trả về:

curl --fail --silent --show-error \
  http://127.0.0.1:8000/v1/chat/completions \
  -H "Authorization: Bearer $VLLM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Qwen/Qwen3-0.6B",
    "messages": [{"role": "user", "content": "Reply with the word ready."}],
    "max_tokens": 16
  }'

Nếu mô hình của bạn không có mẫu chat có thể sử dụng, các yêu cầu chat-completion có thể thất bại ngay cả khi vùng chứa đã khởi động. vLLM hướng dẫn cách cung cấp --chat-template cho các mô hình có cấu hình tokenizer không chứa mẫu này; hãy kiểm thử trước khi triển khai ứng dụng. Xem hướng dẫn về chat-template.

Thiết lập giới hạn hiệu năng trước khi thay đổi các cờ

Không có lệnh vLLM Docker nào đúng trong mọi trường hợp. Cấu hình phù hợp phụ thuộc vào kiến trúc mô hình, loại và bộ nhớ GPU, phân bố độ dài đầu vào/đầu ra, mức đồng thời và mục tiêu độ trễ. Hãy thiết lập đường cơ sở bằng một khối lượng công việc đại diện, sau đó chỉ thay đổi từng biến một.

Ghi nhận ít nhất các chỉ số sau:

• Tỷ lệ yêu cầu thành công/lỗi và các sự kiện khởi động lại/OOM.
• Thời gian đến token đầu tiên (TTFT) và thời gian cho mỗi token đầu ra (TPOT), được phân đoạn theo độ dài prompt.
• Độ trễ đầu cuối tại p50 và p95/p99 dưới mức đồng thời dự kiến.
• Token đầu vào, token đầu ra, thời gian chờ hàng đợi, yêu cầu đang hoạt động và mức sử dụng bộ nhớ GPU.
• Thông lượng chỉ đi kèm với mục tiêu độ trễ và chất lượng mà nó đáp ứng.

Các cờ vLLM Docker làm thay đổi đáng kể năng lực phục vụ

Giá trị mặc định và hành vi chính xác của các tùy chọn phụ thuộc vào phiên bản. Tài liệu tham chiếu đối số engine hiện tại của vLLM xác định các cơ chế kiểm soát bộ lập lịch, bộ nhớ đệm, tính song song và hàng đợi; tài liệu tham chiếu cấu hình bộ nhớ đệm giải thích các thiết lập sử dụng bộ nhớ và prefix-cache.

Trình tự tinh chỉnh thực tế

1. Đặt --max-model-len thực tế dựa trên các giới hạn của ứng dụng.
2. Bắt đầu thận trọng với mức sử dụng bộ nhớ và chừa khoảng trống cho phần chi phí của trình điều khiển/thời gian chạy.
3. Kiểm thử tải --max-num-seqs và --max-num-batched-tokens bằng độ dài prompt và completion thực tế.
4. Chỉ thêm song song hóa tensor khi một GPU không thể chứa mô hình hoặc không đáp ứng mục tiêu cho mô hình đó.
5. Thêm các bản sao phía sau bộ cân bằng tải khi nhu cầu về khả dụng hoặc tổng lưu lượng yêu cầu các miền lỗi độc lập.

Trình tự này ngăn ngừa một sai lầm phổ biến: thêm GPU hoặc tăng mức đồng thời trước khi bạn biết liệu tải công việc thực sự bị giới hạn bởi ngữ cảnh, hàng đợi, bộ nhớ hay năng lực tính toán.

Mở rộng vLLM Docker trên nhiều GPU

Đối với một mô hình cần nhiều GPU, vLLM hỗ trợ phục vụ song song tensor và song song pipeline. Trên một máy chủ, hãy cho container truy cập các GPU và đặt kích thước song song tensor bằng số GPU mà bạn chủ động gán cho máy chủ mô hình đó:

docker run -d \
  --name vllm-tp \
  --restart unless-stopped \
  --runtime=nvidia \
  --gpus all \
  --ipc=host \
  -p 127.0.0.1:8000:8000 \
  -v "$HOME/.cache/huggingface:/root/.cache/huggingface" \
  -e HF_TOKEN \
  -e VLLM_API_KEY \
  "$VLLM_IMAGE" \
  --model "$MODEL" \
  --tensor-parallel-size 4 \
  --api-key "$VLLM_API_KEY"

Hướng dẫn về song song hóa và mở rộng quy mô của vLLM trình bày song song hóa tensor, song song hóa pipeline, cùng các lựa chọn thực thi một nút so với nhiều nút. Đừng sao chép 4 từ ví dụ vào một nút hai GPU: hãy khớp cờ này với các GPU được cấp phát cho máy chủ này và xác thực cấu trúc liên kết giao tiếp, sự cân bằng bộ nhớ và hành vi khi xảy ra lỗi.

Để biết chi tiết triển khai, kiểm tra cấu trúc liên kết và cách quyết định giữa song song hóa tensor và pipeline, hãy xem hướng dẫn suy luận vLLM đa GPU của Flatkey. Để đưa ra quyết định về runtime phục vụ thay vì quyết định triển khai Docker, hãy xem vLLM so với SGLang.

Cấu trúc triển khai đám mây cho môi trường production

Một triển khai vLLM Docker trong môi trường production thường tách lớp biên công khai khỏi việc thực thi trên GPU:

Đặt bộ nhớ đệm Hugging Face trên vùng lưu trữ bền vững hoặc được làm nóng có chủ đích để một lần khởi động lại thông thường không biến thành việc tải mô hình xuống ngoài dự kiến. Lưu giấy phép và các biện pháp kiểm soát truy cập của mô hình trong hồ sơ triển khai. Chỉ ghim tag image là chưa đủ nếu kho lưu trữ mô hình trỏ đến một nhánh có thể thay đổi.

Để có kiến thức nền tảng về lựa chọn GPU, lập kế hoạch bộ nhớ dựa trên ngữ cảnh và khi nào hạ tầng đám mây là lựa chọn phù hợp, hãy liên kết runbook này với hướng dẫn yêu cầu bộ nhớ GPU cho LLM, hướng dẫn GPU cloud và GPU cloud so với framework API mô hình của Flatkey.

Khắc phục sự cố vLLM Docker mà không phỏng đoán

Khi máy chủ chạy nhưng hành vi của ứng dụng vẫn khác với một API được lưu trữ, hãy xác nhận rõ ràng khả năng tương thích của endpoint và tham số. Hướng dẫn về máy chủ suy luận tương thích OpenAI của Flatkey trình bày quá trình di chuyển phía máy khách và phạm vi kiểm thử khả năng tương thích.

Khi nào không nên tự vận hành vLLM Docker

Tự lưu trữ là một cam kết về hạ tầng. Bạn chịu trách nhiệm về cập nhật image, nguồn gốc mô hình, dung lượng GPU, lỗi nút, kiểm soát truy cập, xác thực độ trễ và quy trình trực vận hành. Đây có thể là sự đánh đổi phù hợp khi yêu cầu là kiểm soát thời gian chạy.

Đối với các khối lượng công việc mà lựa chọn mô hình, tính sẵn sàng của nhà cung cấp hoặc sự đơn giản trong vận hành quan trọng hơn việc kiểm soát GPU trực tiếp, hãy duy trì một luồng API được quản lý trong kiến trúc. Flatkey được thiết kế cho quy trình công việc bổ trợ: một tích hợp tương thích OpenAI duy nhất để truy cập các mô hình từ nhiều nhà cung cấp với thanh toán tập trung, trong khi endpoint vLLM tự lưu trữ vẫn là một lựa chọn cho những khối lượng công việc thực sự cần đến nó.

Bước tiếp theo đúng đắn không phải là tối đa hóa một benchmark một cách riêng lẻ. Trước khi đưa vLLM Docker vào phục vụ lưu lượng production, hãy cố định image và mô hình, chứng minh môi trường chạy GPU hoạt động, thiết lập chính sách rõ ràng về context và hàng đợi, kiểm thử bằng các yêu cầu có đặc điểm giống production và ghi lại quy trình xử lý lỗi.

Câu hỏi thường gặp

vLLM Docker có giống API LLM được quản lý không?

Không. vLLM Docker cung cấp cho bạn môi trường phục vụ mô hình trên các GPU do bạn vận hành. Một API được quản lý sẽ trừu tượng hóa việc lưu trữ mô hình và vận hành GPU. Cả hai đều có thể cung cấp giao diện máy khách tương thích OpenAI, nhưng trách nhiệm vận hành là khác nhau.

vLLM Docker có cần NVIDIA Container Toolkit không?

Đối với container GPU NVIDIA, máy chủ cần trình điều khiển NVIDIA tương thích và một môi trường chạy container GPU đã được cấu hình. NVIDIA Container Toolkit là phương án tiêu chuẩn được NVIDIA tài liệu hóa để cung cấp GPU cho các container Docker.

Tôi nên tinh chỉnh cờ vLLM Docker nào trước?

Trước tiên, hãy đặt độ dài context tối đa thực tế, sau đó kiểm thử mức sử dụng bộ nhớ, độ đồng thời và các giới hạn batch-token bằng một tập hợp yêu cầu đại diện. Thay đổi các cờ mà không có đường cơ sở về khối lượng công việc chủ yếu chỉ tạo ra các kết quả không thể lặp lại.

vLLM Docker có thể chạy một mô hình trên nhiều GPU không?

Có. vLLM hỗ trợ phục vụ song song tensor và song song pipeline. Hãy bắt đầu với một máy chủ duy nhất, đồng thời xác thực chính xác số lượng GPU, cấu trúc liên kết và hành vi giao tiếp trước khi mở rộng thiết kế.

Nguồn và tài liệu đọc thêm

• vLLM: Sử dụng Docker
• vLLM: Song song hóa và mở rộng quy mô
• vLLM: Đối số Engine
• Hướng dẫn cài đặt NVIDIA Container Toolkit
• Quản lý bộ nhớ hiệu quả để phục vụ mô hình ngôn ngữ lớn với PagedAttention