3. 模型加载基础

3.1 核心原理：从Hugging Face Hub到本地推理的完整链路

vLLM本身不存储任何模型权重，它依赖Hugging Face（HF）生态完成模型的获取与解析。理解这条链路是后续调优吞吐的前提：HF Hub → 本地缓存 → 格式解析 → 权重加载 → 显存布局。当调用 vLLM(model_path) 时，vLLM会通过 transformers 的 from_pretrained 逻辑定位模型文件，但vLLM并不直接使用transformers的模型实例，而是仅借用其配置解析与权重加载器，随后将权重转换为自研的高效张量布局。

3.2 模型下载：HF Hub的三种获取方式

下载模型是加载的第一步。根据使用场景，可选择以下三种方式之一：

方式	命令/代码	适用场景	注意事项
CLI下载	huggingface-cli download meta-llama/Llama-2-7b-chat-hf --local-dir ./model	一次性完整下载	需先登录HF账号获取
Python API	snapshot_download(repo_id, local_dir)	脚本化/自动化流程	支持断点续传
vLLM直接传repo_id	LLM(model="meta-llama/Llama-2-7b-chat-hf")	快速原型验证	vLLM自动触发下载

3.3 模型格式对比：safetensors vs bin

HF仓库中常见两种权重格式，它们的差异直接影响加载安全性与速度：

• bin（PyTorch原生格式）：基于 pickle 序列化，存在任意代码执行漏洞风险；加载时需要先反序列化Python对象，再转换为张量，速度较慢且内存峰值高。
• safetensors（安全张量格式）：由HF团队开发，采用扁平化二进制存储，不执行任何代码；支持内存映射（mmap）加载，可实现零拷贝读取，加载速度提升约2~5倍。

# 查看模型文件结构
$ ls -lh ./llama-2-7b/
total 13G
-rw-r--r-- 1 user user  609B Nov 20 10:00 config.json
-rw-r--r-- 1 user user 6.7G Nov 20 10:00 model-00001-of-00002.safetensors
-rw-r--r-- 1 user user 6.3G Nov 20 10:00 model-00002-of-00002.safetensors
-rw-r--r-- 1 user user  25K Nov 20 10:00 tokenizer.json
-rw-r--r-- 1 user user  2.3K Nov 20 10:00 tokenizer_config.json

from transformers import AutoModelForCausalLM
model = AutoModelForCausalLM.from_pretrained("path/to/bin_model")
model.save_pretrained("path/to/safetensors_model", safe_serialization=True)

3.4 加载参数配置：vLLM关键参数详解

vLLM的 LLM 类提供了丰富的加载控制参数，合理配置能显著影响显存占用与吞吐上限：

from vllm import LLM

llm = LLM(
    model="./llama-2-7b",           # 本地路径或HF repo_id
    tokenizer="hf-internal-testing/llama-tokenizer",
    tokenizer_mode="auto",          # auto/trust_remote_code/slow
    trust_remote_code=False,        # 是否信任远程代码
    dtype="auto",                   # auto/half/bfloat16/float16
    max_model_len=4096,             # 最大序列长度
    gpu_memory_utilization=0.90,    # GPU显存利用率
    enforce_eager=False,            # 是否禁用CUDA graph
    max_num_batched_tokens=8192,    # 单批次最大数
    quantization=None,              # awq//squeezellm
    load_format="auto",             # auto/safetensors/pt
    revision=None,                  # HF模型版本
    download_dir=None,              # 下载缓存目录
    seed=0,
    disable_log_stats=False,
)

参数	默认值	作用	调优建议
dtype	auto	权重精度	V100用fp16，A100/H100用bf16
load_format	auto	权重加载格式	优先safetensors，自动回退pt
gpu_memory_utilization	0.90	显存分配上限	预留KV cache空间，不宜设满
enforce_eager	False	是否禁用CUDA graph	调试时设True，生产保持False

3.5 案例：从HF下载到vLLM加载的完整流程

以下演示一个实际场景：加载 meta-llama/Llama-2-7b-chat-hf 到vLLM并执行推理。

# 步骤1：设置镜像（国内环境）
export HF_ENDPOINT=https://hf-mirror.com

# 步骤2：登录HF账号（需先在官网申请）
huggingface-cli login -- hf_xxxxx

# 步骤3：下载模型到指定目录
huggingface-cli download meta-llama/Llama-2-7b-chat-hf \
    --local-dir /data/models/llama-2-7b-chat \
    --local-dir-use-symlinks False

# 步骤4：验证文件完整性
ls -lh /data/models/llama-2-7b-chat/*.safetensors

# 步骤5：vLLM加载推理
python -c "
from vllm import LLM, SamplingParams

llm = LLM(
    model='/data/models/llama-2-7b-chat',
    dtype='bfloat16',
    gpu_memory_utilization=0.85,
    max_model_len=2048,
)
output = llm.generate('Hello, how are you?', SamplingParams(max_tokens=50))
print(output[0].outputs[0].text)
"

3.6 常见误区与复盘