Linux 知识库

Appearance

大模型部署参数说明 ​

部署和运行大语言模型（LLM）需要正确配置各种启动参数，这些参数直接影响模型的显存占用、推理性能和稳定性。本文档详细介绍 vLLM、Transformers 等主流推理框架的部署参数配置。

部署框架概览 ​

一、vLLM 启动参数详解 ​

vLLM 是目前最流行的高性能 LLM 推理服务框架，采用 PagedAttention 技术优化显存管理。

基本启动命令结构 ​

bash
python -m vllm.entrypoints.openai.api_server \
    --model <model_path> \
    [其他参数...]

1. 模型与硬件相关参数 ​

参数类型默认值说明
--modelstr必填模型路径或 HuggingFace ID（如 Qwen/Qwen2.5-7B-Instruct）
--tokenizerstr同 modelTokenizer 路径（可单独指定）
--trust-remote-codeboolFalse是否信任远程代码（自定义模型通常需要开启）
--dtypestrauto模型数据类型：auto/half/float16/bfloat16/float32
--tensor-parallel-sizeint1张量并行度（多GPU时使用）
--pipeline-parallel-sizeint1流水线并行度

dtype 选择指南：

bash
# 大多数 GPU 推荐 bfloat16（A100/H100/RTX30+）
--dtype bfloat16

# 较老的 GPU 使用 float16
--dtype float16

# 自动选择（推荐）
--dtype auto

2. 显存管理参数（关键！） ​

--max-model-len / --max-seq-len ​

最大序列长度：控制模型能处理的最大上下文长度（含输入+输出）。

bash
# 默认值取决于模型配置
--max-model-len 8192     # 最大支持 8K tokens 上下文
--max-model-len 32768    # 支持 32K tokens（需更多显存）
--max-model-len 128000   # 支持 128K tokens（超大显存需求）

⚠️ OOM 高危参数：此值越大，KV Cache 占用显存越多！

--gpu-memory-utilization ​

GPU 显存利用率：控制 vLLM 可使用的 GPU 显存比例。

bash
# 常用值范围 0.0-1.0
--gpu-memory-utilization 0.9   # 使用90%显存（默认，激进）
--gpu-memory-utilization 0.85  # 保守一些，留余量给系统
--gpu-memory-utilization 0.7   # 非常保守，适合多进程场景

OOM 调优建议：

  • 出现 OOM → 降低此值（0.9→0.85→0.8）
  • 多个服务共享同一 GPU → 设置为 0.5-0.7
  • 单独占用整张卡 → 可设 0.9-0.95

--max-num-batched-tokens ​

批量 token 上限：一次迭代中处理的最大 token 数。

bash
--max-num-batched-tokens 2048    # 保守
--max-num-batched-tokens 8192    # 平衡（默认）
--max-num-batched-tokens 32768   # 高吞吐

--max-num-seqs ​

最大并发请求数：同时处理的请求数量。

bash
--max-num-seqs 64      # 默认值
--max-num-seqs 256     # 高并发场景
--max-num-seqs 16      # 低延迟优先

3. KV Cache 参数（高级） ​

--block-size ​

KV Cache 分块大小：PagedAttention 的内存页大小。

bash
--block-size 16    # 默认，适用于大多数情况
--block-size 8     # 更精细的分配，减少浪费但增加元数据开销

--enable-prefix-caching ​

前缀缓存：自动缓存重复的前缀（system prompt 等），大幅提升效率。

bash
--enable-prefix-caching    # 开启（强烈推荐生产环境使用）

适用场景：所有请求有相同的 system prompt 时效果显著。

--num-lookahead-slots ​

预计算槽位数：解码时提前计算的 slot 数量。

bash
--num-lookahead-slots 0     # 关闭（默认）
--num-lookahead-slots 64    # 开启 speculative decoding

4. 量化相关参数 ​

--quantization ​

量化方法：加载量化模型。

bash
# AWQ 量化（4-bit，质量好）
--quantization awq

# GPTQ 量化（4-bit）
--quantization gptq

# FP8 量化（H100/A800 支持）
--quantization fp8

# BitsAndBytes（NF4/QLoRA）
--quantization bitsandbytes

--load-format ​

加载格式：控制模型权重加载方式。

bash
--load-format auto           # 自动检测
--load-format pt             # PyTorch 格式
--load-format safetensors    # SafeTensors 格式（更快更安全）
--load-format dummy          # 仅测试不加载权重
--load-format sharded_stateful  # 分片加载（超大模型）
--load-format mmhf           # Megatron 格式

--enforce-eager ​

强制 eager 模式：禁用 CUDA Graph 加速。

bash
--enforce-eager    # 开发调试用，关闭后性能下降但更容易排查问题

5. 性能与调度参数 ​

参数默认值说明
--swap-space4 (GB)CPU 内存作为 KV Cache 的 swap 空间
--max-log-len无限日志中打印的最大 prompt 长度
--disable-log-statsFalse禁用统计日志输出
--log-levelINFO日志级别：DEBUG/INFO/WARNING/ERROR

swap-space 详解：

bash
# 当 GPU 显存不足时，将部分 KV Cache 卸载到 CPU 内存
--swap-space 8       # 使用 8GB CPU 内存做交换空间
--swap-space 0       # 禁用交换（纯 GPU 模式）
--swap-space 16      # 大容量交换（适合长上下文）

何时增大 swap-space：

  • ✅ 处理超长上下文（>32K tokens）
  • ✅ GPU 显存有限但 CPU 内存充足
  • ✅ 允许一定程度的延迟换取更大容量

6. 服务端参数 ​

参数默认值说明
--host0.0.0.0监听地址
--port8000监听端口
--api-keyNoneAPI 密钥认证
--enable-auto-tool-choiceToolCall 模块启用自动工具选择
--tool-call-parsermistral工具调用解析器
--taskgenerate任务类型：generate/encode/embed/spawn
--served-model-namemodel 名称对外暴露的模型名称

完整启动示例：

bash
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-7B-Instruct \
    --trust-remote-code \
    --dtype bfloat16 \
    --max-model-len 32768 \
    --gpu-memory-utilization 0.9 \
    --max-num-seqs 128 \
    --enable-prefix-caching \
    --swap-space 8 \
    --host 0.0.0.0 \
    --port 8000 \
    --api-key your-api-key-here

二、HuggingFace Transformers 推理参数 ​

使用 Transformers 库直接运行模型时的常用参数。

基础推理代码 ​

python
from transformers import AutoModelForCausalLM, AutoTokenizer, pipeline
import torch

# 加载模型
model = AutoModelForCausalLM.from_pretrained(
    "Qwen/Qwen2.5-7B-Instruct",
    torch_dtype=torch.bfloat16,
    device_map="auto",         # 自动设备映射
    trust_remote_code=True,
)

tokenizer = AutoTokenizer.from_pretrained("Qwen/Qwen2.5-7B-Inference")

# 创建管道
pipe = pipeline(
    "text-generation",
    model=model,
    tokenizer=tokenizer,
)

关键加载参数 ​

device_map 设备映射 ​

python
# 自动映射到可用 GPU
device_map="auto"

# 手动指定
device_map={"": 0}              # 全部放到 GPU 0
device_map="balanced"            # 均衡分布到多个 GPU
device_map={"layer.0": 0, "layer.1": 1}  # 精细控制每层位置

# CPU 卸载（低显存方案）
device_map="auto"
offload_folder="./offload"       # 卸载到此目录

torch_dtype 数据类型 ​

python
torch_dtype=torch.float16       # FP16，广泛兼容
torch_dtype=torch.bfloat16      # BF16，推荐 A100+/RTX30+
torch_dtype=torch.float32       # FP32，精度最高但慢且占显存
torch_dtype="auto"              # 自动选择

low_cpu_mem_usage 低 CPU 内存占用 ​

python
model = AutoModelForCausalLM.from_pretrained(
    ...,
    low_cpu_mem_usage=True,      # 减少加载时的 CPU 内存峰值
)

量化加载参数 ​

BitsAndBytes (4-bit/8-bit) ​

python
from transformers import BitsAndBytesConfig

# 4-bit NF4 量化（推荐）
bnb_config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_quant_type="nf4",       # NormalFloat 4-bit
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,   # 双重量化，提升精度
)

# 8-bit 量化
bnb_config = BitsAndBytesConfig(
    load_in_8bit=True,
    llm_int8_threshold=6.0,           # 离散化阈值
)

model = AutoModelForCausalLM.from_pretrained(
    ...,
    quantization_config=bnb_config,
)

AutoGPTQ (GPTQ 4-bit) ​

python
from transformers import AutoModelForCausalLM, GPTQConfig

# 量化配置
gptq_config = GPTQConfig(
    bits=4,                    # 3/4/8 bit
    dataset="c4",              # 校准数据集
    group_size=128,            # 通道分组大小
)

# 加载已量化模型
model = AutoModelForCausalLM.from_pretrained(
    "model-gptq-path",
    device_map="auto",
)

推理生成参数 ​

python
outputs = model.generate(
    input_ids,
    max_new_tokens=512,            # 最大生成长度
    do_sample=True,                # 采样模式（False 为贪婪解码）
    temperature=0.7,               # 温度
    top_p=0.9,                    # 核采样
    top_k=50,                     # Top-K 采样
    repetition_penalty=1.1,        # 重复惩罚
    pad_token_id=tokenizer.pad_token_id,
    eos_token_id=tokenizer.eos_token_id,
)

三、常见 OOM 问题与解决方案 ​

OOM（Out Of Memory）是大模型部署中最常见的问题。以下是系统化的排查和解决流程。

OOM 问题诊断流程 ​

方案一：使用量化（最有效） ​

显存节省对比（以 7B 模型为例）：

方法显存占用相比 FP16质量损失
FP16/BF16~14 GB基准无
INT8 (BitsAndBytes)~7.5 GB-47%极小
INT4 (NF4/GPTQ/AWQ)~4.5 GB-68%小
FP8~7.5 GB-47%极小（需 H100）
EXL2 (2-bit)~3 GB-79%中等

vLLM 启动量化模型：

bash
# AWQ 量化（推荐，质量好）
python -m vllm.entrypoints.openai.api_server \
    --model TheBloke/Llama-2-7B-Chat-AWQ \
    --quantization awq \
    --max-model-len 8192

# GPTQ 量化
python -m vllm.entrypoints.openai.api_server \
    --model TheBloke/Llama-2-7B-Chat-GPTQ \
    --quantization gptq

# FP8 量化（H100/A800）
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Meta-Llama-3-8B-Instruct-FP8 \
    --quantization fp8

Transformers 量化加载：

python
from transformers import BitsAndBytesConfig

config = BitsAndBytesConfig(
    load_in_4bit=True,
    bnb_4bit_compute_dtype=torch.bfloat16,
    bnb_4bit_use_double_quant=True,
)

model = AutoModelForCausalLM.from_pretrained(
    "model_name",
    quantization_config=config,
    device_map="auto",
)

方案二：调整 vLLM 显存参数 ​

场景 1：单卡部署 7B 模型出现 OOM ​

bash
# ❌ 初始配置（可能 OOM）
--gpu-memory-utilization 0.95
--max-model-len 16384

# ✅ 调整后（逐步尝试）
--gpu-memory-utilization 0.90      # 第一步：降低利用率
--max-model-len 8192               # 第二步：缩短上下文
--max-num-seqs 32                  # 第三步：减少并发

场景 2：单卡 24GB 部署 13B/14B 模型 ​

bash
# 24GB 显卡（如 RTX 4090/3090/A5000）运行 13B 模型

# 方案 A：4-bit 量化 + 保守参数
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-13B-Instruct-AWQ \
    --quantization awq \
    --dtype half \
    --gpu-memory-utilization 0.88 \
    --max-model-len 4096 \
    --max-num-seqs 16

# 方案 B：启用 swap 到 CPU
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-13B-Instruct-GPTQ \
    --quantization gptq \
    --gpu-memory-utilization 0.92 \
    --max-model-len 8192 \
    --swap-space 16 \              # 用 16GB CPU 内存补充
    --max-num-seqs 8

场景 3：超长上下文导致 OOM ​

bash
# 需求：32K 上下文，但显存不够

# ❌ 直接设置会 OOM
--max-model-length 32768

# ✅ 组合策略
--max-model-len 32768 \
--gpu-memory-utilization 0.80 \     # 保留更多余量
--swap-space 24 \                   # 大量使用 CPU swap
--max-num-seqs 4 \                  # 低并发
--enable-prefix-caching             # 缓存复用

方案三：CPU Offloading（极端情况） ​

当 GPU 显存严重不足时，可将部分层卸载到 CPU。

使用 Accelerate 进行 offloading ​

python
from accelerate import init_empty_weights
from accelerate.utils import load_and_quantize_model
from transformers import AutoConfig, AutoModelForCausalLM

config = AutoConfig.from_pretrained("model-name")
with init_empty_weights():
    model = AutoModelForCausalLM.from_config(config)

# 加载并自动 offload
model = load_and_quantize_model(
    "model-name",
    device_map="auto",
    max_memory={0: "12GiB", "cpu": "60GiB"},  # GPU 12GB + CPU 60GB
)

vLLM 不支持 CPU Offloading 的替代方案 ​

如果必须使用 vLLM 但显存不够：

  1. 换用更小的模型（7B → 3B → 1.8B）
  2. 使用 llama.cpp（支持 CPU+GPU 混合推理）
  3. 使用 OLLAMA（自动管理资源）

方案四：多 GPU 张量并行 ​

当单卡无法容纳模型时，使用多卡张量并行。

bash
# 2 卡部署 70B 模型
python -m vllm.entrypoints.openai.api_server \
    --model Qwen/Qwen2.5-72B-Instruct \
    --tensor-parallel-size 2 \          # 使用 2 张 GPU
    --gpu-memory-utilization 0.92 \
    --max-model-len 8192

# 4 卡部署超大模型
python -m vllm.entrypoints.openai.api_server \
    --model meta-llama/Meta-Llama-3.1-405B-Instruct \
    --tensor-parallel-size 4 \
    --gpu-memory-utilization 0.95 \
    --max-model-len 4096

各规模模型所需 GPU 参考：

模型规模FP16 所需显存INT4 所需显存推荐配置
7B~14 GB~4.5 GB1× RTX 3090/4090 (24GB)
14B~28 GB~8 GB1× A6000 (48GB) 或 2×3090
32B~64 GB~18 GB2× A100 (80GB) 或 4×3090
70B~140 GB~38 GB2× A100 (80GB) 或 4×A6000
405B~810 GB~220 GB8× H100 (80GB)

四、其他框架部署参数 ​

llama.cpp 参数 ​

llama.cpp 是轻量级推理引擎，支持 CPU 和 GPU 混合推理。

bash
./llama-server \
    -m ./models/qwen2.5-7b-q4_k_m.gguf \   # GGUF 模型文件
    -c 8192 \                                # 上下文长度
    --threads 8 \                            # CPU 线程数
    -ngl 35 \                                # GPU 层数（-1=全部offload）
    -b 512 \                                 # batch size
    -np 4 \                                  # 并行提示数量
    --host 0.0.0.0 \
    --port 8080

关键参数说明：

  • -ngl (n-gpu-layers)：卸载到 GPU 的层数，-1 表示全部
  • -c (ctx-size)：上下文窗口大小
  • -b (batch-size)：批处理大小
  • --gpu-split：多 GPU 显存分配比例（如 0,1 表示均分）

GGUF 量化格式对比：

后缀类型大小质量
q4_04-bit小一般
q4_k_m4-bit k-means中好（推荐）
q5_k_m5-bit k-means中大很好
q6_k6-bit大极好
q8_08-bit很大接近原始
f16FP16最大完全无损

OLLAMA 参数 ​

OLLAMA 是简化的大模型运行工具。

bash
# 创建自定义 Modelfile
cat > Modelfile << 'EOF'
FROM ./qwen2.5-7b-q4_k_m.ggUF

PARAMETER temperature 0.7
PARAMETER top_p 0.9
PARAMETER num_ctx 8192        # 上下文长度
PARAMETER num_batch 512       # batch size
PARAMETER num_thread 8        # CPU线程

SYSTEM """你是一个有用的助手。"""
EOF

# 运行
ollama create mymodel -f Modelfile
ollama run mymodel

# 运行时指定 GPU
CUDA_VISIBLE_DEVICES=0 ollama serve

环境变量调优：

bash
# 显式控制显存
OLLAMA_MAX_LOADED_MODELS=1      # 同时加载的最大模型数
OLLAMA_NUM_PARALLEL=4           # 并行处理数
OLLAMA_MAX_QUEUE=512            # 请求队列长度
OLLAMA_KEEP_ALIVE=5m            # 模型保活时间

# GPU 控制
OLLAMA_GPU_MEMORY_OVERRIDE=24  # 强制限制显存使用(GB)
CUDA_VISIBLE_DEVICES=0,1        # 指定使用的 GPU

Text Generation WebUI (Oobabooga) ​

基于 Gradio 的 Web UI，支持多种后端。

bash
# 启动命令示例
python server.py \
    --model Qwen2.5-7B \
    --loader ExLlamaV2 \          # 加载器选择
    --gpu-memory 20GiB \          # 限制显存使用
    --context-size 8192 \
    --threads 8 \
    --bf16 \                      # 使用 BF16
    --auto-devices \              # 自动分配设备
    --listen-port 7860

常用加载器（Loader）：

加载器适用场景特点
Transformers通用最兼容，速度一般
AutoGPTQGPTQ 模型快速
ExLlamaV2EXL2/GPTQ最快，显存效率高
llama.cppGGUF 模型支持混合推理

五、性能调优最佳实践 ​

1. 显存监控与诊断 ​

bash
# 实时监控 GPU 状态
watch -n 1 nvidia-smi

# 详细显存使用分析
nvitop  # 更友好的界面

# PyTorch 显存分析
python -c "
import torch
print('CUDA available:', torch.cuda.is_available())
print('Device count:', torch.cuda.device_count())
print('Current device:', torch.cuda.current_device())
print('Memory allocated:', torch.cuda.memory_allocated() / 1024**3, 'GB')
print('Memory reserved:', torch.cuda.memory_reserved() / 1024**3, 'GB')
"

2. 吞吐量 vs 延迟权衡 ​

不同场景的参数配置模板：

🎯 场景 A：在线聊天助手（低延迟优先） ​

bash
--max-model-len 4096 \
--max-num-seqs 32 \
--max-num-batched-tokens 2048 \
--gpu-memory-utilization 0.85

📊 场景 B：批量文本处理（高吞吐优先） ​

bash
--max-model-len 8192 \
--max-num-seqs 256 \
--max-num-batched-tokens 16384 \
--gpu-memory-utilization 0.92 \
--enable-prefix-caching

🔬 场景 C：长文档分析（超长上下文） ​

bash
--max-model-len 32768 \
--max-num-seqs 8 \
--swap-space 24 \
--gpu-memory-utilization 0.80 \
--enable-prefix-caching

💰 场景 D：资源受限环境（最小显存） ​

bash
--quantization awq \
--gpu-memory-utilization 0.88 \
--max-model-len 2048 \
--max-num-seqs 8 \
--swap-space 8

3. 生产环境检查清单 ​

  • [ ] 启用 prefix caching（相同 system prompt 场景必开）
  • [ ] 设置合理的 max-model-len（按业务需求，不要盲目设大）
  • [ ] 配置 API Key 认证
  • [ ] 设置 GPU memory utilization ≤ 0.9（留余量应对碎片）
  • [ ] 监控 GPU 显存使用率（告警阈值建议 90%）
  • [ ] 配置日志级别和持久化
  • [ ] 压力测试验证最大并发能力
  • [ ] 准备 OOM 恢复策略（自动重启、降级等）

4. 常见问题速查表 ​

错误信息原因解决方案
CUDA out of memory显存不足量化 / 降低 gpu-mem-util / 减少 max-model-len
RuntimeError: cuDNN error显存碎片重启服务 / 降低 utilization
Invalid block requestKV Cache 不足增加 swap-space / 减少并发
Too many requests并发超限增加 max-num-seqs / 扩容
Model loading timeout模型太大检查网络 / 使用 sharded loading
ValueError: dtype mismatch类型不匹配明确指定 --dtype

相关资源 ​