Triển khai Qwen3.5 với vLLM (2026 mới nhất)

Bài hướng dẫn này bao gồm các bước **tải mô hình Qwen3.5, cài đặt vLLM, khởi động dịch vụ, cấu hình tham số chính, gọi API, tối ưu hóa lượng tử, và triển khai đa GPU**. Hướng dẫn này áp dụng cho môi trường Linux/WSL2.

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

1.1 Đề xuất cấu hình phần cứng

Quy mô mô hình	Dung lượng VRAM tối thiểu	Cấu hình đề xuất	Dung lượng VRAM sau khi lượng tử hóa (4bit AWQ)
Qwen3.5-0.8B/2B	6GB	RTX 3060/4060 (12GB)	~3GB
Qwen3.5-4B/7B	10GB	RTX 3090/4080 (16GB+)	~5GB
Qwen3.5-9B/14B	16GB	RTX 4090/A10 (24GB)	~8GB
Qwen3.5-27B/35B	24GB×2	A100 (40GB/80GB)×2	~15GB

- Hệ điều hành: Linux / WSL2 (Ubuntu 20.04+) - CUDA: **11.8+ / 12.1+** (cần cài đặt NVIDIA driver + CUDA Toolkit) - RAM: ≥32GB (càng nhiều càng tốt) - Lưu trữ: ≥50GB SSD (dung lượng tệp mô hình lớn)

Loại	Tên	Mục đích	Hỗ trợ vLLM
Mô hình cơ bản	Qwen3.5-7B	Viết tiếp, hoàn thiện, vi điều chỉnh thứ cấp	Hoàn toàn hỗ trợ
Vi điều chỉnh chỉ thị	Qwen3.5-7B-Instruct	Đối thoại, hỏi đáp, tuân theo chỉ thị	Hoàn toàn hỗ trợ (thường dùng nhất)
Phiên bản đối thoại	Qwen3.5-7B-Chat	Đối thoại nhiều vòng, nhớ lịch sử	Hoàn toàn hỗ trợ

1.2 Cài đặt phụ thuộc phần mềm

# 1. Cài đặt công cụ cơ bản
sudo apt update && sudo apt install -y python3-pip python3.10-venv git git-lfs

# 2. Tạo môi trường ảo (khuyến nghị)
python3 -m venv vllm-qwen
source vllm-qwen/bin/activate  # Kích hoạt môi trường

# 3. Cài đặt vLLM (phù hợp với Qwen3.5, khuyến nghị ≥0.17.0)
pip install vllm>=0.17.0 transformers>=4.41.0 accelerate sentencepiece protobuf

# 4. Nâng tốc độ trong nước (tùy chọn)
pip config set global.index-url https://mirror.baidu.com/pypi/simple

II. Tải mô hình Qwen3.5 (3 cách)

Kho lưu trữ chính thức của Qwen3.5: - Hugging Face: https://huggingface.co/Qwen - ModelScope (nâng tốc độ trong nước): https://modelscope.cn/models/Qwen

2.1 Cách 1: Tải từ ModelScope (khuyến nghị trong nước)

# Cài đặt ModelScope
pip install modelscope

# Tải Qwen3.5-9B-Instruct (ví dụ, có thể thay đổi kích thước khác)
modelscope download \
  --model Qwen/Qwen3.5-9B-Instruct \
  --local_dir ./models/Qwen3.5-9B-Instruct \
  --exclude "*.bin"  # Chỉ tải safetensors

2.2 Cách 2: Clone bằng Git LFS (cân nặng đầy đủ)

git lfs install
git clone https://www.modelscope.cn/Qwen/Qwen3.5-9B-Instruct.git ./models/Qwen3.5-9B-Instruct

2.3 Cách 3: Tải từ Hugging Face Hub (ngoài nước)

pip install huggingface-hub
huggingface-cli download \
  Qwen/Qwen3.5-9B-Instruct \
  --local-dir ./models/Qwen3.5-9B-Instruct \
  --exclude "*.bin"

2.4 Tải mô hình lượng tử (tiết kiệm VRAM)

AWQ 4bit lượng tử (hỗ trợ tốt nhất bởi vLLM)

# Ví dụ: Qwen3.5-9B-Instruct-AWQ-4bit
modelscope download --model Qwen/Qwen3.5-9B-Instruct-AWQ-4bit --local_dir ./models/Qwen3.5-9B-AWQ

III. Khởi động Qwen3.5 với vLLM (lệnh chính)

3.1 Khởi động đơn GPU (phiên bản cơ bản)

python -m vllm.entrypoints.openai.api_server \
  --model ./models/Qwen3.5-9B-Instruct \  # Đường dẫn mô hình
  --host 0.0.0.0 \                         # Cho phép truy cập từ bên ngoài
  --port 8000 \                            # Cổng
  --dtype auto \                           # Độ chính xác tự động (bf16/fp16)
  --trust-remote-code \                    # Phải thêm (đối với mã tùy chỉnh Qwen)
  --max-model-len 32768 \                  # Chiều dài ngữ cảnh (Qwen3.5 hỗ trợ 32k/128k)
  --gpu-memory-utilization 0.9 \           # Tỷ lệ sử dụng VRAM (0.8–0.95)
  --max-num-seqs 64                        # Số chuỗi đồng thời tối đa

3.2 Khởi động đa GPU (tương tác song song) (bắt buộc cho 27B/35B)

# Chạy 27B trên 2 GPU
python -m vllm.entrypoints.openai.api_server \
  --model ./models/Qwen3.5-27B-Instruct \
  --host 0.0.0.0 --port 8000 \
  --trust-remote-code \
  --tensor-parallel-size 2 \  # Số GPU
  --dtype bfloat16 \
  --kv-cache-dtype fp8 \      # KV cache lượng tử (tiết kiệm 50% VRAM)
  --max-model-len 32768 \
  --gpu-memory-utilization 0.85

3.3 Khởi động mô hình lượng tử (AWQ 4bit)

python -m vllm.entrypoints.openai.api_server \
  --model ./models/Qwen3.5-9B-AWQ \
  --quantization awq \        # Bật lượng tử AWQ
  --host 0.0.0.0 --port 8000 \
  --trust-remote-code \
  --tensor-parallel-size 1 \
  --max-model-len 32768

3.4 Triển khai bằng Docker (khuyến nghị)

# 1. Pull image vLLM (hỗ trợ Qwen3.5)
docker pull vllm/vllm-openai:v0.17.0

# 2. Khởi động container
docker run -d --name qwen3.5 \
  --gpus all \
  -p 8000:8000 \
  -v ./models:/models \       # Mount thư mục mô hình
  --ipc=host \
  vllm/vllm-openai:v0.17.0 \
  --model /models/Qwen3.5-9B-Instruct \
  --host 0.0.0.0 --port 8000 \
  --trust-remote-code \
  --max-model-len 32768

IV. Giải thích tham số chính của vLLM (chuyên dùng cho Qwen3.5)

Tham số	Vai trò	Giá trị khuyến nghị cho Qwen3.5
`--trust-remote-code`	**Phải**, để tải cấu trúc mô hình tùy chỉnh Qwen	`true`
`--tensor-parallel-size`/`-tp`	Chia mô hình ra N GPU	27B→2, 35B→4
`--dtype`	Độ chính xác trọng số	A100/40 series: `bf16`; 30 series: `fp16`
`--kv-cache-dtype`	Độ chính xác bộ đệm KV	`fp8` (tiết kiệm VRAM, tăng tốc)
`--quantization`	Phương pháp lượng tử	`awq` (4bit), `fp8`
`--max-model-len`	Chiều dài ngữ cảnh	7B/9B: `32768`; 27B/35B: `16384`
`--gpu-memory-utilization`	Tỷ lệ sử dụng VRAM	`0.8–0.9` (để tránh OOM)
`--max-num-seqs`	Số yêu cầu đồng thời tối đa	9B: `64`; 27B: `32`
`--enable-chunked-prefill`	Xử lý trước văn bản dài thành các khối	`true`
`--served-model-name`	Tên mô hình API	`qwen3.5`

V. Xác minh dịch vụ và gọi API tương thích OpenAI

5.1 Xác minh dịch vụ

# Xem danh sách mô hình
curl http://localhost:8000/v1/models

# Kết quả mong đợi
{
  "data": [
    {
      "id": "qwen3.5-9b-instruct",
      "object": "model",
      "created": 1743998800,
      "owned_by": "vllm"
    }
  ]
}

5.2 Gọi API đối thoại

curl http://localhost:8000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen3.5-9b-instruct",
    "messages": [
      {"role": "user", "content": "Giới thiệu về Qwen3.5"}
    ],
    "temperature": 0.7,
    "max_tokens": 1024,
    "stream": false
  }'

5.3 Gọi API bằng Python

from openai import OpenAI

client = OpenAI(
  api_key="dummy",
  base_url="http://localhost:8000/v1"
)

response = client.chat.completions.create(
  model="qwen3.5-9b-instruct",
  messages=[{"role": "user", "content": "Viết một bài thơ về mùa xuân"}]
)
print(response.choices[0].message.content)

VI. Các vấn đề thường gặp và tối ưu hóa

6.1 Lỗi: `KeyError: 'qwen3_5'`

- Giải quyết: **Cập nhật transformers ≥4.41.0** + **Phải thêm `--trust-remote-code`**

pip install -U transformers

6.2 Thiếu VRAM (OOM)

- Phương án 1: Sử dụng **mô hình lượng tử 4bit AWQ** - Phương án 2: Thêm `--kv-cache-dtype fp8` - Phương án 3: Giảm `--max-model-len`, `--gpu-memory-utilization 0.8` - Phương án 4: Sử dụng đa GPU `--tensor-parallel-size N`

6.3 Tối ưu hóa tốc độ

- Kích hoạt `--enable-prefix-caching` (bộ đệm tiền tố) - Tăng `--max-num-seqs` - Sử dụng `--dtype bfloat16` (A100/4090)

VII. Danh sách phiên bản mô hình (có thể sao chép trực tiếp)

Qwen/Qwen3.5-0.8B-Instruct
Qwen/Qwen3.5-2B-Instruct
Qwen/Qwen3.5-4B-Instruct
Qwen/Qwen3.5-7B-Instruct
Qwen/Qwen3.5-9B-Instruct
Qwen/Qwen3.5-14B-Instruct
Qwen/Qwen3.5-27B-Instruct
Qwen/Qwen3.5-35B-A3B-Instruct

# Phiên bản lượng tử
Qwen/Qwen3.5-9B-Instruct-AWQ-4bit
Qwen/Qwen3.5-27B-Instruct-AWQ-4bit