本地部署模型 --vLLM + Docker 部署+封裝接口

vLLM的介紹?

vLLM的核心特性：

? ? ? ? 最先進的服務吞吐量

? ? ? ? 使用PageAttention高效管理注意力鍵和值的內存

? ? ? ? 量化：GPTQ，AWQ，INT4，INT8和FP8

VLLM的靈活性和易用性體現在以下方面：

? ? ? ? 具有高吞吐量服務以及各種解碼算法，包括并行采樣，束搜索等

? ? ? ? 支持張量并行和流水線并行的分布式推理

? ? ? ? 提供與OpenAI兼容的API服務器

? ? ? ? 支持很多顯卡：NVIDIA GPU、AMD CPU和GPU、Intel GPU和CPU、PowerPC CPU、TPU及AWS Neuron

? ? ? ? 前綴緩存支持

? ? ? ? 支持多LoRA

基礎

量化

量化是將模型中的 高精度參數（如 FP32）轉為低位寬整數或浮點數（如 INT4、INT8、FP8） 的過程，以達到：

減少模型大小
降低顯存占用
加速推理速度
提升部署效率（尤其在邊緣設備）

方法	全稱 / 意義	類型	是否需訓練	簡要說明
INT8	8-bit Integer Quant.	權重+激活量化	?（PTQ）或 ?（QAT）	最基礎，兼容性好，精度較高，速度/壓縮比適中
INT4	4-bit Integer Quant.	權重量化	?（PTQ）	更小顯存，損失更大，適合結合 GPTQ/AWQ 使用
FP8	8-bit Floating Point	權重+激活量化	?（需訓練支持）	精度高于 INT8，部署需硬件支持（如 H100）
GPTQ	GPT Quantization	權重量化（INT4）	?（Post-training）	自動通道選擇，適合大模型，兼顧速度與精度
AWQ	Activation-aware Weight Quantization	權重量化（INT4）	?（Post-training）	感知激活分布，專為 LLM 優化，精度更好

AWQ（Activation-aware Weight Quantization）是一種 后訓練量化（Post-Training Quantization, PTQ） 方法，它的核心創新在于：

分析每層神經元激活分布
對不同通道的權重做“有選擇的”量化
避免激活和權重之間的量化誤差共振（量化時考慮激活值），保持模型性能

誤差共振：量化權重引入的誤差與激活值在某些層發生耦合或放大效應，導致模型輸出誤差顯著放大，從而嚴重影響整體推理精度的現象。

例如：假設模型某一層的激活值比較大且集中（例如都是正數），此時：

如果權重量化誤差也呈現某種集中偏向（比如整體偏負）；
乘積操作就可能系統性偏離真實輸出；
偏差在下一層繼續放大，最終影響整個推理精度。

這在 LLM 中尤為嚴重，因為 LLM 的結構深、層數多，誤差一層層累積，可能導致模型完全輸出錯誤的回答。

KV Cache

KV Cache 就是 Transformer 中**注意力機制（Self-Attention）**模塊中，每一層的 Key（K）和 Value（V）向量的緩存，它可以在每一步生成時重復使用，而不用重新計算前面所有的 K/V。

前一步生成 token 的 K/V 會被緩存起來。
下一步只需計算
當前 token 的 Q，再用之前緩存的 K/V 來做注意力計算。
效果：每一步只計算一次 Q，大大減少了計算和內存開銷。

優勢：提升速度、降低資源占用、支持長文本生成、易于實現（大多數框架（如 Transformers、vLLM）都有內置支持）

優化：

PagedAttention（vLLM）

把 KV Cache 分頁管理（像虛擬內存頁表），支持多用戶并發、動態上下文切換

?FlashAttention

?利用 CUDA kernel 和序列并行優化注意力計算，也有專門版本支持 KV Cache。

使用：use_cache=True ?# 開啟 KV Cache

估算GPU資源

推理（Inference）與訓練（Training）兩部分之和

每個參數所占內存：

float32（默認）：每個參數 4 Bytes
float16（混合精度訓練）：每個參數 2 Bytes
int8/in4（量化推理）：每個參數 1 Byte

顯存估算公式（粗略）：

顯存(MB)≈參數量(B)×4(FP16)+KV緩存大小(基于長上下文)+其他緩存

例如：總參數量：0.6B（6億參數）；上下文長度（Context Length）：32,768 tokens（超長上下文）

推理總顯存需求估算（FP16）：

模型參數：0.6B × 2 Bytes ≈ 1.2 GB
KV 緩存：~1 GB
其他激活緩存、臨時變量等：~1 GB

?推理最低顯存需求：約 3–4 GB（FP16）

訓練資源預估

訓練比推理顯存需求高很多，主要因為：

需要存儲梯度、前向激活值
反向傳播時顯存翻倍
長上下文會加重 attention 的計算開銷

粗略訓練顯存估算：

1. 參數模型體積（FP16）：

0.6B × 2 Bytes = 1.2 GB

2. 激活值 + 梯度緩存（訓練中需占 2-4 倍模型體積）

Batch size 越大，顯存占用越高

最終估算：

訓練所需單卡顯存 ≈ 30–40GB+（保守估計）

安裝vLLM

建議使用uv，地址：GPU - vLLM

uv pip install "vllm[cuda]"
##這個命令會自動選擇適合你的 CUDA 版本的 prebuilt 版本（12.1 及以上）

Docker部署

將需要下載的大模型下載到對應的項目中
編寫配置文件Dockerfile

??獲取鏡像：https://hub.docker.com/search?q=&type=image

# 基礎鏡像，帶CUDA 12.1 + cuDNN + Python 3.10（我們后面升級Python）
FROM pytorch/pytorch:2.2.0-cuda12.1-cudnn8-runtimeENV DEBIAN_FRONTEND=noninteractive
# 安裝Python 3.11及相關工具
RUN apt-get update && apt-get install -y software-properties-common \&& add-apt-repository ppa:deadsnakes/ppa \&& apt-get update && apt-get install -y \python3.11 python3.11-distutils python3.11-venv python3-pip curl \&& rm -rf /var/lib/apt/lists/*# 設置python3指向python3.11
RUN update-alternatives --install /usr/bin/python3 python3 /usr/bin/python3.11 1# 升級pip，安裝對應PyTorch和vllm
RUN python3 -m pip install --upgrade pip# 重新安裝兼容CUDA 12.1的PyTorch，避免版本沖突（覆蓋基礎鏡像的PyTorch）
RUN python3 -m pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121# 安裝vLLM
RUN python3 -m pip install vllm# 創建工作目錄
WORKDIR /app# 拷貝啟動腳本
COPY entrypoint.sh /app/entrypoint.sh
RUN chmod +x /app/entrypoint.sh# 掛載模型目錄
VOLUME ["/qwen"]# 開放8000端口
EXPOSE 8000# 啟動命令
CMD ["/app/entrypoint.sh"]

? ? ?3. 編寫shell腳本文件

#!/bin/bash
# 啟動 vLLM OpenAI 兼容 API 服務，加載掛載的本地模型路徑python3 -m vllm.entrypoints.openai.api_server \--model /qwen \--tokenizer /qwen \--served-model-name Qwen-3 \--host 0.0.0.0 \--port 8000

???????4. 構建鏡像運行

## 構建鏡像DOCKER_BUILDKIT=1 docker build -f [本地磁盤上的 Dockerfile 文件所在位置] -t qwen-vllm:latest .
## 最后的路徑參數表示構建上下文目錄，Docker從這里找文件構建鏡像 .代表當前目錄
## -t 給鏡像打標簽（tag）<鏡像名>:<標簽>##查看鏡像
docker images# 刪除容器
docker rm {容器名稱}## 運行容器
docker run -d --gpus '"device=1"' -p 8000:8000 \-v /home/featurize/qwen:/qwen \--name qwen-vllm-container1 \qwen-vllm:latest
#-v:表示把本地 /home/featurize/qwen 目錄掛載到容器里的 /qwen
#--name：給容器起名字
#qwen-vllm:latest--鏡像名
#-d :讓容器在后臺運行
#-p 8000:8000--把宿主機（本機）的 8000 端口，映射到容器內的 8000 端口##持續監聽日志：
docker logs -f qwen-vllm-container1
##退出日志的持續監聽
Ctrl + C

參數：DOCKER_BUILDKIT 是 Docker 提供的一個環境變量，用來控制是否啟用 BuildKit 構建引擎?

DOCKER_BUILDKIT=1 表示啟用 Docker 的 BuildKit 功能。
DOCKER_BUILDKIT=0 或不設置則使用傳統的 Docker 構建引擎。

BuildKit 是 Docker 官方推出的一個更高效、更靈活的鏡像構建引擎，具備以下優勢：

并行構建：能夠并行執行 Dockerfile 中的多條命令，提高構建速度。
更好的緩存管理：緩存機制更智能，減少重復構建時間。
更小的鏡像層：生成的鏡像層更合理，減少鏡像體積。
內置更強大的語法支持：支持更復雜的 Dockerfile 語法，比如 --mount=type=cache 等。
安全隔離：提高構建過程的安全性。

測試

方式一：curl

curl -X POST http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{"model":"Qwen-3","messages":[{"role":"user","content":"你好"}]}'

方式二：python

import requests
import jsondef chat_with_model(prompt, model_name="Qwen-3", server_url="http://localhost:8000/v1/chat/completions"):headers = {"Content-Type": "application/json",}data = {"model": model_name,"messages": [{"role": "user", "content": prompt}]}response = requests.post(server_url, headers=headers, data=json.dumps(data))if response.status_code == 200:res_json = response.json()answer = res_json.get("choices", [{}])[0].get("message", {}).get("content", "")return answerelse:return f"Error: {response.status_code} - {response.text}"if __name__ == "__main__":prompt = "你好，今天天氣怎么樣"reply = chat_with_model(prompt)print("模型回復:", reply)

Fast API封裝

#示例 test.py
from fastapi import FastAPI, HTTPException
from pydantic import BaseModel
import httpxapp = FastAPI()# 請求輸入格式
class ChatRequest(BaseModel):prompt: strtemperature: float = 0.7max_tokens: int = 512# 響應格式可自定義
class ChatResponse(BaseModel):response: str# 本地大模型的 API 地址
LLM_API_URL = "http://localhost:8000/v1/chat/completions"@app.post("/api/chat", response_model=ChatResponse)
async def chat_with_model(req: ChatRequest):# 轉換為大模型 API 所需要的格式（假設你在用 OpenAI 格式接口）payload = {"model": "your-model-name",  # 視情況設置或移除"messages": [{"role": "user", "content": req.prompt}],"temperature": req.temperature,"max_tokens": req.max_tokens}try:async with httpx.AsyncClient() as client:response = await client.post(LLM_API_URL, json=payload, timeout=60.0)response.raise_for_status()data = response.json()# 從大模型返回中提取內容（OpenAI 格式）reply_text = data['choices'][0]['message']['content']return ChatResponse(response=reply_text)except Exception as e:raise HTTPException(status_code=500, detail=str(e))

運行

uvicorn test:app --host 0.0.0.0 --port 9000 --reload
#test:app-模塊名:變量名 是告訴 Uvicorn 去哪里找 FastAPI 實例來運行服務。

測試

curl -X POST http://localhost:9000/api/chat \
-H "Content-Type: application/json" \
-d '{"prompt": "你好，請介紹一下你自己", "temperature": 0.7, "max_tokens": 200}'

大模型量化

AWQ：https://github.com/casper-hansen/AutoAWQ

python -m awq.entry \--model_path /home/featurize/qwen \              --w_bit 4 \                                            --q_group_size 128 \                                  --q_backend real \                                     --dump_quant quant_cache/qwen3-awq-int4.pt