Hướng dẫn setup vLLM local với Gemma 4 từ A đến Z

Nếu anh em đã từng dùng OpenAI API cho production rồi nhìn vào hóa đơn cuối tháng mà choáng - chúng tôi hiểu cảm giác đó. Tháng trước team BKGlobal bắt đầu nghiêm túc tìm hiểu self-hosted LLM, và câu trả lời hiện tại là: vLLM + Gemma 4. Chi phí về 0, latency kiểm soát được, không lo rate limit - nghe có vẻ quá đẹp nhưng đây là thực tế đang chạy trên máy chủ của chúng tôi.

Bài này là bản hướng dẫn đầy đủ, từ lúc chưa có gì cho đến khi có một server sẵn sàng nhận request - bằng tiếng Việt, dành cho developer Việt Nam.

1. Gemma 4 và vLLM là gì - tại sao lại chọn cặp đôi này

Gemma 4 là dòng model mở của Google DeepMind (ra mắt đầu tháng 4/2026), được cấp phép Apache 2.0 - dùng commercial được. Có 4 variant:

Variant Parameters thực Context Đặc điểm
E2B 2.3B active 128K Chạy được trên laptop GPU 8GB
E4B 4.5B active 128K Ngưỡng cân bằng chất lượng/tài nguyên
26B-A4B 26B / 3.8B active 256K MoE, VRAM yêu cầu thấp hơn dense
31B 31B dense 256K Flagship, cần GPU lớn

Tất cả đều hỗ trợ multimodal (text, ảnh, video, audio), thinking mode, function calling và 140+ ngôn ngữ.

vLLM là inference server dạng OpenAI-compatible API, sử dụng kỹ thuật PagedAttention để quản lý KV cache như bộ nhớ ảo - giúp throughput cao hơn 5-20x so với naive implementation. vLLM có Day-0 support cho Gemma 4 ngay từ ngày release.

2. Yêu cầu phần cứng và môi trường

GPU - điểm khởi đầu thực tế

Model VRAM tối thiểu GPU gợi ý
gemma-4-2b-it (E2B) 6 GB RTX 3060, RTX 4060
gemma-4-4b-it (E4B) 10 GB RTX 3080, RTX 4070
gemma-4-27b-it (26B MoE) 24–32 GB RTX 3090/4090, A100 40GB
gemma-4-31b-it 40–80 GB A100 80GB, H100, multi-GPU

Note từ team: Nếu chỉ có RTX 4060 8GB, chạy E2B với quantization AWQ 4-bit là hoàn toàn khả thi. Chúng tôi đã test - đủ dùng cho chatbot nội bộ.

Hệ điều hành và phần mềm

  • OS: Linux (Ubuntu 22.04/24.04 khuyến nghị). Windows cần WSL2 + CUDA - xem phần Docker bên dưới
  • Python: 3.10, 3.11, hoặc 3.12
  • CUDA: 12.1 trở lên (vLLM 0.8.x mặc định ship binaries CUDA 12.9)
  • RAM: Tối thiểu 16GB, khuyến nghị 32GB+
  • Disk: 20–80GB tùy model (Gemma 4 31B khoảng 60GB weights)

Kiểm tra CUDA version:

nvidia-smi
nvcc --version

3. Cài đặt vLLM

Cách 1: Pip install (nhanh nhất)

# Tạo virtual environment
python -m venv vllm-env
source vllm-env/bin/activate  # Linux/Mac
# vllm-env\Scripts\activate   # Windows

# Cài vLLM (bản stable)
pip install vllm

# Hoặc cài pre-release để có support Gemma 4 mới nhất
pip install -U vllm --pre
pip install transformers>=4.50.0

Lưu ý: Lần đầu pip install vllm sẽ tải về khoảng 5-8GB dependencies (PyTorch + CUDA kernels). Chuẩn bị kết nối tốt hoặc đặt timeout cao hơn.

Cách 2: Dùng uv (nhanh hơn pip)

# Cài uv nếu chưa có
curl -LsSf https://astral.sh/uv/install.sh | sh

# Tạo môi trường Python 3.12
uv venv vllm-env --python 3.12 --seed
source vllm-env/bin/activate

pip install vllm

Kiểm tra cài đặt thành công

python -c "import vllm; print(vllm.__version__)"
# Output: 0.8.x hoặc mới hơn

4. Cài đặt qua Docker (khuyến nghị cho Windows / production)

Docker là cách nhanh nhất để tránh conflict dependency, đặc biệt nếu đang dùng Windows với WSL2.

NVIDIA GPU

# Pull image chuyên dụng cho Gemma 4
docker pull vllm/vllm-openai:gemma4

# Chạy server
docker run --gpus all \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    --env "HF_TOKEN=$HF_TOKEN" \
    -p 8000:8000 \
    --ipc=host \
    vllm/vllm-openai:gemma4 \
    --model google/gemma-4-4b-it \
    --dtype bfloat16 \
    --max-model-len 32768

--ipc=host là bắt buộc - PyTorch cần shared memory giữa các process. Bỏ flag này sẽ gây lỗi ngẫu nhiên.

Docker với bản vLLM stable (không chỉ Gemma 4)

docker run -d --name vllm-server \
    --gpus all \
    --ipc=host \
    -p 8000:8000 \
    -v ~/.cache/huggingface:/root/.cache/huggingface \
    -e HF_TOKEN="$HF_TOKEN" \
    vllm/vllm-openai:latest \
    --model google/gemma-4-4b-it \
    --dtype bfloat16 \
    --gpu-memory-utilization 0.90 \
    --max-model-len 8192

5. Lấy model Gemma 4 từ HuggingFace

Bước 1: Tạo tài khoản và lấy HF Token

  1. Đăng ký tại huggingface.co
  2. Vào Settings > Access Tokens > New token
  3. Chọn loại Read - đủ để download model
  4. Chấp nhận license Gemma 4 tại trang model: google/gemma-4-4b-it

Bước 2: Cấu hình token

# Export vào environment (cách phổ biến nhất)
export HF_TOKEN="hf_your_token_here"

# Hoặc dùng huggingface-cli
pip install huggingface_hub
huggingface-cli login
# Paste token khi được hỏi

Bước 3: Download model thủ công (optional - vLLM tự download khi start)

# Download về cache local trước
huggingface-cli download google/gemma-4-4b-it \
    --local-dir ./models/gemma-4-4b-it \
    --token $HF_TOKEN

Model sẽ được cache tại ~/.cache/huggingface/hub/ theo mặc định.

6. Khởi động vLLM server với Gemma 4

Start server cơ bản

# Gemma 4 E4B - phù hợp cho GPU 12-16GB
python -m vllm.entrypoints.openai.api_server \
    --model google/gemma-4-4b-it \
    --dtype bfloat16 \
    --max-model-len 8192

# Hoặc dùng lệnh ngắn hơn (vLLM 0.8+)
vllm serve google/gemma-4-4b-it \
    --dtype bfloat16 \
    --max-model-len 8192

Start với Gemma 4 E2B (GPU nhỏ 6-8GB)

vllm serve google/gemma-4-2b-it \
    --dtype bfloat16 \
    --max-model-len 4096 \
    --gpu-memory-utilization 0.85

Start với Gemma 4 26B MoE (multi-GPU hoặc GPU lớn)

vllm serve google/gemma-4-27b-it \
    --dtype bfloat16 \
    --max-model-len 32768 \
    --tensor-parallel-size 2 \
    --gpu-memory-utilization 0.90

Start với Gemma 4 31B (A100 80GB hoặc multi-GPU)

vllm serve google/gemma-4-31b-it \
    --dtype bfloat16 \
    --max-model-len 32768 \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.92

Server khởi động thành công sẽ in ra:

INFO:     Started server process [12345]
INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)

7. Test server bằng curl và Python

Test bằng curl

# Kiểm tra server health
curl http://localhost:8000/health

# Xem danh sách models đang serve
curl http://localhost:8000/v1/models

# Gửi request chat
curl http://localhost:8000/v1/chat/completions \
    -H "Content-Type: application/json" \
    -d '{
        "model": "google/gemma-4-4b-it",
        "messages": [
            {"role": "user", "content": "Giải thích PagedAttention là gì trong 3 câu?"}
        ],
        "max_tokens": 200,
        "temperature": 0.7
    }'

Test bằng Python OpenAI client

from openai import OpenAI

# Kết nối tới vLLM local - không cần API key thật
client = OpenAI(
    base_url="http://localhost:8000/v1",
    api_key="token"  # bất kỳ string nào cũng được
)

# Chat completion đơn giản
response = client.chat.completions.create(
    model="google/gemma-4-4b-it",
    messages=[
        {"role": "system", "content": "Bạn là trợ lý kỹ thuật của team BKGlobal."},
        {"role": "user", "content": "Xin chào! Giải thích vLLM cho tôi nghe."}
    ],
    max_tokens=500,
    temperature=0.8
)

print(response.choices[0].message.content)

Streaming response

# Streaming - nhận token từng chút như ChatGPT
stream = client.chat.completions.create(
    model="google/gemma-4-4b-it",
    messages=[{"role": "user", "content": "Viết một đoạn code Python đọc file CSV"}],
    max_tokens=1000,
    stream=True
)

for chunk in stream:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="", flush=True)

Test multimodal (gửi ảnh)

Gemma 4 hỗ trợ vision - gửi ảnh cùng text:

import base64

# Đọc ảnh và encode
with open("screenshot.png", "rb") as f:
    image_data = base64.b64encode(f.read()).decode("utf-8")

response = client.chat.completions.create(
    model="google/gemma-4-4b-it",
    messages=[{
        "role": "user",
        "content": [
            {"type": "text", "text": "Mô tả chi tiết ảnh này:"},
            {
                "type": "image_url",
                "image_url": {"url": f"data:image/png;base64,{image_data}"}
            }
        ]
    }],
    max_tokens=500
)

8. Quản lý model - chuyển đổi và tối ưu bộ nhớ

Chuyển đổi model không cần restart

vLLM chưa hỗ trợ hot-swap model trong cùng một process. Để chuyển model, cần restart server với --model khác. Cách thực tế nhất khi cần nhiều model:

# Chạy nhiều instance trên port khác nhau
# Terminal 1: Gemma 4 E2B trên port 8001
vllm serve google/gemma-4-2b-it --port 8001 --max-model-len 4096 &

# Terminal 2: Gemma 4 E4B trên port 8002
vllm serve google/gemma-4-4b-it --port 8002 --max-model-len 8192 &

Kiểm tra VRAM đang dùng

# Theo dõi realtime
watch -n 1 nvidia-smi

# Hoặc query metrics vLLM
curl http://localhost:8000/metrics | grep gpu_cache

Giải phóng VRAM khi tắt server

# Kill process vLLM
pkill -f "vllm.entrypoints"

# Nếu dùng Docker
docker stop vllm-server

9. Quantization - chạy model lớn trên GPU nhỏ

Khi VRAM không đủ cho bfloat16 đầy đủ, quantization là giải pháp. vLLM hỗ trợ AWQ và GPTQ.

AWQ (khuyến nghị)

AWQ (Activation-aware Weight Quantization) cho throughput cao hơn GPTQ với quality tương đương:

# Tìm model AWQ trên HuggingFace (cộng đồng đã quantize)
# Ví dụ: gemma-4-4b AWQ 4-bit
vllm serve <username>/gemma-4-4b-it-AWQ \
    --quantization awq \
    --dtype half \
    --max-model-len 8192

# Hoặc chỉ định quantization_param_path nếu tự quantize

GPTQ

vllm serve <username>/gemma-4-4b-it-GPTQ-4bit \
    --quantization gptq \
    --dtype half \
    --max-model-len 8192

So sánh VRAM khi dùng quantization

Format Gemma 4 E4B Gemma 4 27B
BFloat16 (full) ~10 GB ~54 GB
AWQ 4-bit ~4 GB ~18 GB
GPTQ 4-bit ~4 GB ~18 GB

Kinh nghiệm team: AWQ 4-bit Gemma 4 E4B chạy ổn trên RTX 3070 8GB. Chất lượng giảm nhẹ so với full precision nhưng đủ cho hầu hết use case.

10. Các lỗi thường gặp và cách fix

CUDA out of memory

torch.cuda.OutOfMemoryError: CUDA out of memory. Tried to allocate X GiB

Fix:

# Giảm max_model_len
vllm serve google/gemma-4-4b-it \
    --max-model-len 4096 \        # giảm từ 8192 xuống
    --gpu-memory-utilization 0.80  # giảm từ 0.90 xuống

# Nếu vẫn lỗi - dùng quantization AWQ hoặc model nhỏ hơn

Tokenizer error / mismatch

ValueError: The tokenizer class does not match the expected model

Fix:

pip install --upgrade transformers tokenizers
# Với Gemma 4 cần transformers >= 4.50.0
pip install transformers>=4.50.0

Model download bị lỗi 401 (Unauthorized)

huggingface_hub.errors.RepositoryNotFoundError: 401 Client Error

Fix:

# Kiểm tra token đã được export chưa
echo $HF_TOKEN

# Thử đăng nhập lại
huggingface-cli login

# Đảm bảo đã accept license tại HuggingFace
# Vào https://huggingface.co/google/gemma-4-4b-it và bấm "Agree"

Server chậm - throughput thấp

Fix:

# Bật async scheduling (vLLM 0.8+)
vllm serve google/gemma-4-4b-it \
    --enable-async-scheduling \
    --max-num-seqs 256 \
    --max-model-len 8192

Port 8000 đã bị chiếm

# Tìm process đang dùng port
lsof -i :8000
# Kill nếu cần
kill -9 <PID>

# Hoặc đổi port vLLM
vllm serve google/gemma-4-4b-it --port 8080

11. Tips cho production

Tối ưu hiệu năng tổng thể

vllm serve google/gemma-4-4b-it \
    --dtype bfloat16 \
    --max-model-len 32768 \
    --gpu-memory-utilization 0.92 \
    --max-num-seqs 512 \
    --enable-prefix-caching \
    --enable-async-scheduling \
    --tensor-parallel-size 1   # tăng lên số GPU nếu có nhiều

Multi-GPU với tensor parallelism

# 2 GPU - tăng gấp đôi throughput / VRAM khả dụng
vllm serve google/gemma-4-27b-it \
    --tensor-parallel-size 2 \
    --gpu-memory-utilization 0.90 \
    --max-model-len 32768

# 4 GPU cho model 31B
vllm serve google/gemma-4-31b-it \
    --tensor-parallel-size 4 \
    --max-model-len 65536

Lưu ý: tensor-parallel-size phải chia hết số attention heads của model. Gemma 4 31B có 32 heads → hỗ trợ TP=1, 2, 4, 8.

Giới hạn context để tiết kiệm KV cache

# Nếu ứng dụng không cần context dài
--max-model-len 4096   # Chat đơn giản
--max-model-len 8192   # RAG, function calling
--max-model-len 32768  # Long document analysis

Bật Prometheus metrics để monitor

vllm serve google/gemma-4-4b-it \
    --enable-metrics

# Query metrics
curl http://localhost:8000/metrics | grep -E "(cache|request|token)"

Bảo mật API (thêm layer nginx / FastAPI)

vLLM không có built-in auth - với production, nên đặt phía trước một reverse proxy:

# nginx config đơn giản
server {
    listen 80;
    location /v1/ {
        if ($http_authorization != "Bearer sk-your-secret") {
            return 401;
        }
        proxy_pass http://localhost:8000;
    }
}

12. Một số use case thực tế của team BKGlobal

Kể từ khi triển khai vLLM + Gemma 4 nội bộ, chúng tôi đang dùng cho:

  • Code review bot: Gemma 4 E4B analyze PR diff, đề xuất cải tiến
  • Document Q&A: RAG pipeline với context 32K - phân tích tài liệu kỹ thuật dài
  • Chatbot hỗ trợ nội bộ: E2B chạy liên tục 24/7 trả lời câu hỏi HR/IT
  • Test case generation: Input là API spec, output là unit test skeleton

Điểm quan trọng nhất: vLLM tự batching request - khi có 10 user gửi đồng thời, không phải xử lý tuần tự mà batch lại, throughput tăng đáng kể so với dùng transformers pipeline trực tiếp.

Tổng kết

Setup vLLM + Gemma 4 local không quá phức tạp nhưng cần chú ý một số điểm then chốt:

  1. Hardware trước tiên - xác định VRAM có bao nhiêu để chọn variant phù hợp
  2. Docker là con đường ít đau khổ nhất trên Windows/môi trường không chuẩn
  3. Bắt đầu với max-model-len nhỏ (4096-8192), tăng dần khi cần
  4. Quantization AWQ khi bị giới hạn VRAM - giảm 60% bộ nhớ, chất lượng chấp nhận được
  5. Enable prefix caching nếu nhiều request có system prompt giống nhau

Từ đây anh em có thể tích hợp vào bất kỳ stack nào dùng OpenAI SDK mà không cần thay đổi code - chỉ đổi base_url là xong.

Nếu có câu hỏi hoặc gặp lỗi kỳ lạ, để lại comment bên dưới - team sẽ hỗ trợ.

BKGlobal Tech Team

Ứng dụng & Xu hướng AI

Xem tất cả
So sánh GPT-5.5 vs Claude Opus 4.7 vs DeepSeek V4: chọn model nào cho dự án Việt Nam?

So sánh GPT-5.5 vs Claude Opus 4.7 vs DeepSeek V4: chọn model nào cho dự án Việt Nam?

AI test generation trong .NET — từ zero đến 80% coverage tự động

AI test generation trong .NET — từ zero đến 80% coverage tự động

AI-powered sprint planning: dự đoán scope creep trước khi nó xảy ra

AI-powered sprint planning: dự đoán scope creep trước khi nó xảy ra

RAG pipeline với Gemma 4 và Elasticsearch: từ concept đến production

RAG pipeline với Gemma 4 và Elasticsearch: từ concept đến production

OWASP LLM Top 10: hướng dẫn test và vá lỗi cho .NET developer

OWASP LLM Top 10: hướng dẫn test và vá lỗi cho .NET developer

Xây dựng AI governance framework nội bộ: từ model registry đến audit trail

Xây dựng AI governance framework nội bộ: từ model registry đến audit trail