Triển khai Pixtral (LLM) với vLLM và Docker: Dễ như ăn kẹo!

Lê Lân

16/08/2025

Hướng Dẫn Triển Khai Pixtral Với vLLM Và Docker Hiệu Quả

Mở Đầu

Việc triển khai các mô hình ngôn ngữ lớn (LLM) thường đòi hỏi sức mạnh tính toán rất cao và cần có hệ thống tối ưu để phục vụ inference hiệu quả. Trong bài viết này, bạn sẽ học cách đóng gói Pixtral — một mô hình ngôn ngữ hiện đại — trong Docker và chạy nó qua inference engine vLLM để tạo ra endpoint API tương thích OpenAI, sẵn sàng phục vụ bên ngoài.

Giải pháp này giúp bạn tận dụng tối đa GPU NVIDIA với CUDA, dễ dàng quản lý môi trường và tăng khả năng mở rộng cho ứng dụng AI của bạn. Hướng dẫn bao gồm các bước từ chuẩn bị môi trường, xây dựng Docker image, chạy container đến kiểm thử và thiết lập truy cập API từ bên ngoài.

📦 Chuẩn Bị

Yêu cầu:

Docker phiên bản mới nhất đã cài đặt

GPU NVIDIA hỗ trợ CUDA (nếu muốn tăng tốc phần cứng)

Model weights đã tải sẵn từ repo Pixtral trên Hugging Face hoặc đã có sẵn trên máy

Việc đảm bảo đủ các thành phần trên là bước nền tảng để tránh lỗi phát sinh khi chạy mô hình trong container.

🛠 Bước 1: Tạo Dockerfile

Dưới đây là nội dung mẫu Dockerfile cơ bản giúp bạn xây dựng môi trường chạy vLLM cùng Pixtral:

FROM nvidia/cuda:12.2.2-runtime-ubuntu22.04

# Cài đặt các thư viện hệ thống cần thiết
RUN apt-get update && apt-get install -y \
    git wget curl python3 python3-pip && \
    rm -rf /var/lib/apt/lists/*

# Cập nhật pip và cài đặt vLLM
RUN pip3 install --upgrade pip
RUN pip3 install vllm

# Đặt thư mục làm việc
WORKDIR /app

# Mở cổng 8000 để phục vụ API
EXPOSE 8000

# Khởi chạy bash theo mặc định (có thể override khi chạy container)
CMD ["bash"]

Việc chọn base image nvidia/cuda:12.2.2-runtime-ubuntu22.04 giúp tận dụng driver CUDA mới nhất cho tối ưu GPU.

⚙️ Bước 2: Xây Dựng Docker Image

Chạy câu lệnh sau trong thư mục chứa Dockerfile để tạo image:

docker build -t pixtral-vllm .

Quá trình này sẽ kéo image base, cài đặt các phụ thuộc và tạo môi trường chạy vLLM.

📂 Bước 3: Chạy Container Với Truy Cập Mô Hình

Để chạy vLLM phục vụ Pixtral, dùng lệnh:

docker run --gpus all -it -p 8000:8000 pixtral-vllm \
python3 -m vllm.entrypoints.openai.api_server \
--model <huggingface_repo_or_local_path_to_pixtral>

Thay <huggingface_repo_or_local_path_to_pixtral> bằng đường dẫn tới model Pixtral bạn đã chuẩn bị.

Giải thích:

--gpus all : Cho phép container sử dụng toàn bộ GPU trên máy

-p 8000:8000 : Bản đồ cổng container sang host để truy cập API qua cổng 8000

Lệnh python khởi động server API OpenAI-compatible do vLLM cung cấp

Điều này giúp bạn chạy mô hình Pixtral như một dịch vụ sẵn sàng phục vụ request bên ngoài.

🌐 Bước 4: Kiểm Tra API Endpoint

Sau khi container đang chạy, bạn có thể test API bằng công cụ curl:

curl http://localhost:8000/v1/completions \
-H "Content-Type: application/json" \
-d '{"model": "pixtral", "prompt": "Hello Pixtral!"}'

Kết quả mong đợi:

{
  "id": "cmpl-1234",
  "object": "text_completion",
  "choices": [
    {"text": "Hello there!"}
  ]
}

API sẽ trả về câu trả lời dưới định dạng chuẩn của OpenAI Completion, rất tiện lợi để tích hợp với nhiều ứng dụng khác.

📡 Bước 5: Mở Cổng Cho Truy Cập Từ Bên Ngoài

Nếu bạn muốn dịch vụ API có thể truy cập từ internet hoặc mạng ngoài:

Đảm bảo đã map cổng container sang host ( -p 8000:8000 )

Mở cổng 8000 trên tường lửa hoặc nhóm bảo mật (Security Group)

Trong môi trường sản xuất, khuyến nghị:

Dùng reverse proxy như NGINX hoặc Traefik để quản lý HTTPS, caching, rate limiting

Bổ sung xác thực (authentication) bảo mật trước khi mở API công khai nhằm phòng chống lạm dụng

Việc bảo mật và quản lý truy cập rất quan trọng với API phục vụ mô hình AI có thể tốn kém tài nguyên.

✅ Kết Luận

Bạn đã hoàn thành quá trình triển khai Pixtral chạy qua vLLM trong môi trường Docker. Cách làm này:

Tối ưu hiệu suất inference trên GPU hiệu quả

Mang lại môi trường triển khai đơn giản, đồng nhất, dễ dàng mở rộng

API tương thích theo chuẩn OpenAI giúp tích hợp linh hoạt với hệ sinh thái phần mềm hiện có

Áp dụng hướng dẫn này sẽ giúp bạn nhanh chóng xây dựng dịch vụ AI ngôn ngữ mạnh mẽ và chuyên nghiệp.

🔗 Tham Khảo

vLLM Documentation

Pixtral Model (Hugging Face)

NVIDIA CUDA Toolkit: https://developer.nvidia.com/cuda-toolkit

Docker Documentation: https://docs.docker.com/

June 20, 2024