大模型推理优化实战：从PyTorch到TensorRT的七步工程化落地

1. 项目概述：Model-Optimizer不是工具名，而是一类工程实践的统称

“Model-Optimizer”这个标题乍看像某个开源库或商业软件的代号，但结合NVIDIA、TensorRT-LLM、vLLM、PT文件转换TensorRT等热搜词，它实际指向的是大模型推理服务落地过程中，围绕GPU加速器（尤其是NVIDIA GPU）所展开的一整套模型压缩、格式转换、运行时调度与硬件协同优化的工程方法论。它不依赖某一个具体工具，而是由TensorRT、vLLM、ONNX Runtime、CUDA Graphs、FP16/INT4量化、PagedAttention、Kernel Fusion等技术模块组合而成的系统性解决方案。我做AI推理服务落地三年，从最早用PyTorch原生加载7B模型跑出2.3 token/s，到现在在单张RTX 4090上部署Qwen2-7B实现158 token/s吞吐、首token延迟压到87ms，核心就是把“Model-Optimizer”这四个字拆解成可执行、可验证、可复现的几十个操作节点——不是调一个API就完事，而是要懂显卡寄存器怎么读、CUDA Stream怎么配、显存碎片怎么清、KV Cache页怎么分。

这类优化真正解决的是三个硬痛点：第一是成本不可控——没优化前，跑一个7B模型要租4张A10，月成本2.4万；优化后单卡A10就能扛住日均5000并发，成本砍掉73%；第二是响应不可靠——未优化模型在高并发下P99延迟跳变剧烈，有时120ms，有时2.3秒，用户直接关网页；第三是部署不可持续——模型更新一次就得重写整个服务链路，新版本TensorRT一升级，原来写的custom op全报错。而Model-Optimizer的本质，就是把模型从“能跑起来”推进到“跑得稳、跑得省、跑得快、跑得久”。它适合三类人：一是正在把自研大模型推向生产环境的算法工程师，二是负责AI服务SLO保障的运维/平台工程师，三是需要在边缘设备（如Jetson Orin、RTX 40系列笔记本）上部署轻量模型的嵌入式开发者。你不需要是CUDA专家，但必须愿意打开nvidia-smi盯着显存曲线调参数，愿意花两小时编译一个TensorRT engine而不是只复制粘贴pip install命令。

2. 核心设计思路：为什么必须放弃“一键优化”，转向分层解耦式工程架构

很多人看到“Model-Optimizer”第一反应是找一个万能脚本，输入模型路径，输出优化后engine。我试过所有标榜“全自动”的工具——包括NVIDIA官方的trtexec封装、社区版tensorrt_llm_builder、甚至某些付费SaaS平台，结果无一例外：要么在Qwen2-1.5B上生成的engine比原始PyTorch还慢17%，要么对DeepSeek-Coder-33B的MoE结构直接报错“Unsupported layer type: MoEExpertRouter”，要么生成的engine在A10上能跑，在H100上启动就OOM。根本原因在于，模型优化不是图像滤镜式的批量处理，而是对计算图、内存布局、硬件特性和业务负载四者进行强耦合建模的过程。就像给一辆赛车改装，不能只换轮胎就宣称“已优化”，必须同步调整悬挂刚度、ECU点火时机、进气道流速、变速箱齿比——每个环节都影响最终圈速。

我们团队最终确立的Model-Optimizer架构是五层解耦设计：

• 第0层：硬件感知层——不是简单检测GPU型号，而是实测PCIe带宽（用nvidia-smi -q -d PCI | grep "Bus Bandwidth"）、显存带宽（用nvbandwidth工具跑GDDR6X实测）、L2缓存命中率（nsys profile抓取cache__inst_executed_per_1000_cycles）。比如RTX 4090的PCIe 5.0 x16理论带宽128GB/s，但实测模型权重加载时仅跑出73GB/s，说明瓶颈在CPU侧DMA控制器，这就决定了后续必须启用weight streaming而非全量加载。
• 第1层：模型语义层——解析模型结构语义，区分dense层、MoE层、RMSNorm、RoPE位置编码等。TensorRT-LLM自带的model parser会把Qwen2的RMSNorm误判为LayerNorm，导致量化后精度崩塌；我们改用HuggingFace transformers的model.config.architectures字段+手动校验onnx graph node name双保险。
• 第2层：算子融合层——不是盲目fuse所有相邻op，而是按GPU SM单元特性决策。例如在H100上，将Qwen2的QKV投影+RoPE+Attention softmax三步融合为单个kernel，能减少2次global memory读写；但在A10上，因SM数量少、寄存器文件小，强行fusion反而增加register spilling，实测慢了11%。
• 第3层：内存调度层——vLLM的PagedAttention本质是把KV Cache虚拟化为离散页，但页大小必须匹配GPU显存页粒度。我们发现A10默认页大小4KB，而H100是64KB，若沿用同一套page table配置，H100上会出现大量TLB miss，延迟飙升。
• 第4层：服务编排层——vLLM scheduler逻辑不是黑盒，其max_num_seqs、block_size、swap_space参数必须根据业务请求分布反推。比如客服对话场景，92%请求长度<128，但有8%长尾请求达2048，若设max_num_seqs=256，会导致短请求排队等待长请求释放block，P95延迟恶化3倍。

这种分层不是理论空谈。去年我们优化Qwen2-7B时，按此架构逐层调试：先用nsys确认PCIe瓶颈，改weight streaming；再用onnxruntime debug mode定位RMSNorm精度问题，重写plugin；接着在H100上测试不同fusion策略，找到最优kernel组合；然后根据实测显存页大小调整vLLM block_size；最后用真实流量回放压测，动态调节scheduler参数。全程耗时11天，但最终性能提升不是线性叠加，而是乘积效应——吞吐从89 token/s升至158 token/s，首token延迟从112ms降至87ms，显存占用从14.2GB压至10.8GB。关键在于，每一层优化都可独立验证、独立回滚，不会因某一层失败导致全盘崩溃。

3. 核心细节解析：从PT文件到TensorRT engine的七道硬核工序

把PyTorch .pt模型转成TensorRT engine，远不止trtexec --onnx=model.onnx --saveEngine=model.engine这么简单。我整理出七道必须亲手操刀的关键工序，每一道都藏着让性能翻倍或归零的细节。这些步骤在官方文档里往往一笔带过，但实操中踩坑率超80%。

3.1 工具链版本锁死：为什么TensorRT 10.2.0.11 + CUDA 12.2 + cuDNN 8.9.7是当前最稳组合

TensorRT版本兼容性是隐形杀手。去年我们用TensorRT 10.3部署Qwen2-7B，在H100上跑出158 token/s，但切换到A10时engine加载失败，报错“Assertion!isDynamic()failed”。查源码发现10.3新增的dynamic shape支持在A10驱动栈里触发了旧版cuBLAS的bug。最终锁定TensorRT 10.2.0.11——这是最后一个对A10/H100双平台稳定支持的版本。配套CUDA必须12.2，因为12.3的nvcc编译器在生成int4 quantization kernel时会产生非法指令；cuDNN选8.9.7而非最新8.9.8，因后者在处理Qwen2的GroupNorm时有精度溢出bug。版本锁死不是保守，而是用nvidia-smi -q -d DRIVER确认驱动版本后，反向推导出的唯一安全组合。我们用docker build构建基础镜像时，会把这三者哈希值写入LABEL：

LABEL trt_version="10.2.0.11" cuda_version="12.2.2" cudnn_version="8.9.7.76"

这样任何人在任何环境拉取镜像，都能保证底层一致。别信“最新版最好”，在AI推理领域，稳定压倒一切。

3.2 ONNX导出的三大禁忌：shape inference、opset选择、dynamic axis定义

PyTorch模型导出ONNX是第一道生死关。常见错误：

• 禁忌1：用torch.onnx.export(model, dummy_input, "model.onnx", export_params=True)直接导出。这会让ONNX runtime无法推断dynamic batch size。正确做法是显式声明dynamic_axes：

dynamic_axes = { 'input_ids': {0: 'batch', 1: 'seq_len'}, 'attention_mask': {0: 'batch', 1: 'seq_len'}, 'output': {0: 'batch', 1: 'seq_len'} } torch.onnx.export(model, dummy_input, "model.onnx", dynamic_axes=dynamic_axes, opset_version=18)

• 禁忌2：opset版本乱选。Qwen2的RoPE需要opset 18的ConstantOfShape和Slice新行为，用opset 17会生成错误的position_ids。但opset 18又不支持某些老模型的ScatterND，所以必须按模型架构查TensorRT支持矩阵。
• 禁忌3：忽略shape inference。导出后必须用onnx.shape_inference.infer_shapes_path("model.onnx")补全shape，否则TensorRT parser会因维度未知报错“Cannot infer shape for node XXX”。我们写了个check脚本，自动扫描ONNX graph里所有node的output_shape是否为空，为空则中断流程。

3.3 TensorRT builder配置的六个致命参数

trtexec只是封装，真正起作用的是TensorRT C++ API里的IBuilderConfig。这六个参数决定engine能否生成、生成多快、跑得多稳：

• max_workspace_size：不是越大越好。设4GB（4<<30）在A10上够用，但在H100上必须设16GB，否则builder会因workspace不足跳过某些fusion。我们用nvidia-smi -q -d MEMORY | grep "Total Memory" * 0.3动态计算。
• set_flag(BuilderFlag.FP16)：开启FP16必须配合set_flag(BuilderFlag.STRICT_TYPES)，否则TensorRT可能在某些layer里偷偷切回FP32，导致精度崩塌。
• set_flag(BuilderFlag.INT8)：INT4量化需额外set_flag(BuilderFlag.QAT)，且必须提供calibration dataset。我们用Qwen2训练集的1024个样本做calibration，而非随机采样。
• min_timing_iterations/max_timing_iterations：设为20/20，避免冷启动cache干扰timing。
• set_memory_pool_limit(MemoryPoolType.WORKSPACE, workspace_size)：与max_workspace_size呼应，但更底层。
• add_optimization_profile(profile)：必须为每个dynamic axis定义profile范围，如batch_size从1到128，seq_len从16到2048。漏定义会导致runtime报错“Optimization profile is not valid”。

3.4 自定义Plugin开发：绕过TensorRT不支持的Qwen2算子

Qwen2的RMSNorm和SwiGLU在TensorRT 10.2原生不支持。有人用ONNX算子替换，但精度损失超1.2%。我们选择写custom plugin：

• RMSNorm plugin继承IPluginV2DynamicExt，重写enqueue()函数，用CUDA kernel实现：

__global__ void rmsnorm_kernel(float* input, float* output, float* weight, int hidden_size, float eps) { int idx = blockIdx.x * blockDim.x + threadIdx.x; if (idx < hidden_size) { float sum = 0.0f; for (int i = 0; i < hidden_size; i++) sum += input[i] * input[i]; float norm = sqrtf(sum / hidden_size + eps); output[idx] = input[idx] / norm * weight[idx]; } }

• 编译时用nvcc -arch=sm_80（A10）或sm_90（H100）指定compute capability，生成librmsnorm.so。
• 在builder里注册：config->add_plugin_v2(&plugin, &plugin_size)。
  关键经验：plugin kernel必须用float而非half计算中间值，否则RMSNorm的数值稳定性崩塌。我们实测过，half中间计算在Qwen2上会让PPL从7.23恶化到11.89。

3.5 Engine序列化与反序列化的内存陷阱

生成的engine文件不是直接load就能用。常见坑：

• 序列化时未对齐内存：TensorRT要求serialized engine buffer地址8字节对齐，否则deserialize失败。我们用posix_memalign(&buffer, 8, size)分配内存。
• 反序列化时context创建失败：必须确保createExecutionContext()前，engine已完整加载到GPU显存。用cudaMalloc分配显存，memcpyHtoD拷贝，而非直接用host buffer。
• 多线程加载冲突：10个线程同时deserialize同一engine，会因CUDA context竞争卡死。我们用std::mutex保护deserialize过程，并预热：先用dummy input run一次，再正式服务。

3.6 vLLM集成中的TensorRT engine注入技巧

vLLM默认用PyTorch backend，要注入TensorRT engine需修改其model_runner.py：

• 在__init__里加载engine：self.trt_engine = load_trt_engine("qwen2_7b.engine")
• 重写forward()函数，当input_ids进入时，调用self.trt_engine.execute_async(...)而非原生model.forward()
• 关键是tensor shape适配：vLLM的input_ids是[batch, seq_len]，但TRT engine期望[batch, seq_len, hidden_size]，需在forward里插入embedding lookup layer。我们用vLLM内置的get_model_config().hf_config.hidden_size获取维度，避免硬编码。
• 性能瓶颈常在数据搬运：从vLLM的PagedAttention输出的key/value tensor到TRT engine输入，需cudaMemcpyAsync异步拷贝，否则同步拷贝吃掉30% GPU时间。

3.7 模型验证的黄金三指标：PPL、token/s、显存占用率

生成engine后，必须用三指标交叉验证：

• PPL（Perplexity）：用WikiText-2测试集，PPL偏差>5%即精度失效。我们写脚本自动对比TRT engine与PyTorch原模型的logits输出，cosine similarity <0.999则reject。
• token/s：用固定prompt长度（如128）测throughput，但必须跑满5分钟，排除cache warmup干扰。
• 显存占用率：nvidia-smi -q -d MEMORY | grep "Used Memory"，但要注意vLLM的swap_space会占用host memory，需用free -h看实际GPU显存。
  曾有个engine PPL合格、token/s达标，但显存占用14.2GB（超A10上限），上线后OOM。后来发现是TRT builder没设max_workspace_size，builder偷偷用了16GB workspace——这提醒我们，三指标缺一不可。

4. 实操全流程：从Ubuntu裸机到vLLM+TensorRT服务的12步手把手

以下是我们团队标准化的Model-Optimizer实操流程，已在Rocky Linux 10、Ubuntu 22.04、Windows WSL2三种环境验证。每一步都标注了“为什么这么做”和“不做会怎样”，拒绝黑盒操作。

4.1 环境初始化：驱动、CUDA、容器工具链的原子级安装

1. NVIDIA驱动安装：绝不用ubuntu自带的nvidia-driver-535，因其对RTX 40系支持不全。从NVIDIA官网下载.run包（如NVIDIA-Linux-x86_64-535.129.03.run），执行sudo ./NVIDIA-Linux-x86_64-535.129.03.run --no-opengl-files --no-x-check。--no-opengl-files防止覆盖系统OpenGL库，--no-x-check避免X server冲突。
2. CUDA Toolkit安装：用runfile而非deb包，因deb包会强制装driver。执行sudo ./cuda_12.2.2_535.104.05_linux.run --silent --override --toolkit --samples，--silent静默安装，--override跳过driver检查（因已装好）。
3. NVIDIA Container Toolkit安装：这是docker调GPU的关键。执行curl -fsSL https://nvidia.github.io/libnvidia-container/gpgkey | sudo gpg --dearmor -o /usr/share/keyrings/nvidia-container-toolkit-keyring.gpg，再curl -fsSL https://nvidia.github.io/libnvidia-container/ubuntu22.04/libnvidia-container.list | sudo tee /etc/apt/sources.list.d/nvidia-container-toolkit.list，最后sudo apt-get update && sudo apt-get install -y nvidia-container-toolkit。验证：docker run --rm --gpus all nvidia/cuda:12.2.2-base-ubuntu22.04 nvidia-smi，应显示GPU信息。

提示：若nvidia-smi报错“Failed to initialize NVML”，八成是驱动没装好或secure boot开启。关闭secure boot或重装驱动。

4.2 基础镜像构建：Dockerfile的精简与加固

我们不用nvidia/cuda:12.2.2-base，因其含大量无用包（如texlive）。自建Dockerfile：

FROM ubuntu:22.04 RUN apt-get update && apt-get install -y --no-install-recommends \ python3-pip python3-dev build-essential libglib2.0-0 libsm6 libxext6 libxrender-dev \ && rm -rf /var/lib/apt/lists/* COPY --from=nvidia/cuda:12.2.2-runtime-ubuntu22.04 /usr/local/cuda /usr/local/cuda ENV PATH="/usr/local/cuda/bin:$PATH" ENV LD_LIBRARY_PATH="/usr/local/cuda/lib64:$LD_LIBRARY_PATH" RUN pip3 install --no-cache-dir torch==2.3.0+cu121 torchvision==0.18.0+cu121 --extra-index-url https://download.pytorch.org/whl/cu121 RUN pip3 install --no-cache-dir tensorrt==10.2.0.11 pycuda==2023.1 onnx==1.15.0 onnxruntime-gpu==1.17.1

关键点：

• --no-install-recommends减小镜像体积37%
• COPY --from复用NVIDIA官方CUDA runtime，避免重复下载
• PyTorch版本必须与CUDA 12.2匹配，用+cu121后缀而非+cu122（因CUDA 12.2对应cu121 ABI）

4.3 模型准备：HuggingFace模型的本地化与结构校验

以Qwen2-7B为例：

1. git clone https://huggingface.co/Qwen/Qwen2-7B下载模型
2. python3 -c "from transformers import AutoConfig; c=AutoConfig.from_pretrained('./Qwen2-7B'); print(c.architectures)"确认是['Qwen2ForCausalLM']，非['LlamaForCausalLM']（避免误用Llama插件）
3. ls ./Qwen2-7B/pytorch_model.bin.index.json检查是否为sharded checkpoint，若是，则用transformers的shard_checkpoint工具合并，因TensorRT不支持sharded loading。

注意：不要用git lfs pull，因网络不稳定易中断。用huggingface-cli download Qwen/Qwen2-7B --repo-type model --revision main --include "pytorch_model*.bin"精准下载。

4.4 ONNX导出：动态batch与RoPE的精准控制

写export_qwen2.py：

from transformers import AutoModelForCausalLM, AutoTokenizer import torch model = AutoModelForCausalLM.from_pretrained("./Qwen2-7B", torch_dtype=torch.float16) tokenizer = AutoTokenizer.from_pretrained("./Qwen2-7B") dummy_input = tokenizer("Hello", return_tensors="pt").input_ids.to("cuda") # Qwen2 RoPE需固定max_position_embeddings model.config.max_position_embeddings = 2048 model.config.rope_theta = 1000000.0 # Qwen2专用theta torch.onnx.export( model, dummy_input, "qwen2-7b.onnx", input_names=["input_ids"], output_names=["logits"], dynamic_axes={ "input_ids": {0: "batch_size", 1: "sequence_length"}, "logits": {0: "batch_size", 1: "sequence_length"} }, opset_version=18, do_constant_folding=True )

执行后，用onnxsim qwen2-7b.onnx qwen2-7b-sim.onnx简化graph，减少冗余op。

4.5 TensorRT Engine构建：从trtexec到C++ builder的跃迁

先用trtexec快速验证：

trtexec --onnx=qwen2-7b-sim.onnx \ --fp16 \ --workspace=4096 \ --minShapes=input_ids:1x16 \ --optShapes=input_ids:8x512 \ --maxShapes=input_ids:16x2048 \ --saveEngine=qwen2-7b-fp16.engine

若成功，再用C++ builder精细控制：

• 编写build_engine.cpp，设置BuilderFlag.STRICT_TYPES、add_optimization_profile等
• 编译：nvcc -o build_engine build_engine.cpp -I/usr/include/aarch64-linux-gnu -L/usr/lib/aarch64-linux-gnu -lnvinfer -lnvparsers -lnvonnxparser
• 运行：./build_engine qwen2-7b-sim.onnx qwen2-7b-fp16.engine
  关键：--minShapes设为1x16（最小batch和seq_len），避免engine无法处理短文本。

4.6 vLLM服务集成：修改backend与启动参数

1. 克隆vLLM源码：git clone https://github.com/vllm-project/vllm.git && cd vllm
2. 修改vllm/model_executor/models/qwen2.py，在forward()里注入TRT engine调用
3. 构建wheel：make wheel，安装：pip install dist/vllm-0.4.2-py3-none-any.whl
4. 启动服务：

python -m vllm.entrypoints.api_server \ --model ./Qwen2-7B \ --tensor-parallel-size 1 \ --gpu-memory-utilization 0.9 \ --max-model-len 2048 \ --enforce-eager \ --dtype half \ --quantization awq \ --trt-engine-path ./qwen2-7b-fp16.engine

--enforce-eager禁用CUDA Graph，因TRT engine已高度优化；--quantization awq启用AWQ量化，与TRT INT4互补。

4.7 性能压测：用locust模拟真实流量

写locustfile.py：

from locust import HttpUser, task, between import json class Qwen2User(HttpUser): wait_time = between(0.1, 0.5) @task def generate(self): payload = { "model": "Qwen2-7B", "prompt": "Explain quantum computing in simple terms.", "max_tokens": 512, "temperature": 0.7 } self.client.post("/v1/completions", json=payload)

启动：locust -f locustfile.py --host http://localhost:8000 --users 100 --spawn-rate 10
监控指标：

• vLLM metrics endpoint/metrics抓取vllm:prompt_tokens_total、vllm:generation_tokens_total
• nvidia-smi -l 1 实时记录GPU利用率、显存占用
• time curl http://localhost:8000/v1/completions测单请求延迟

4.8 日志与监控：构建可观测性闭环

• vLLM日志：启动时加--log-level DEBUG，日志输出到/var/log/vllm.log
• GPU监控：用dcgm-exporter暴露metrics，Prometheus抓取DCGM_FI_DEV_GPU_UTIL、DCGM_FI_DEV_MEM_COPY_UTIL
• 请求追踪：在api_server.py里加OpenTelemetry，追踪每个request的model_forward_time、trt_execute_time、kv_cache_hit_rate
• 告警规则：当vllm:time_to_first_token_seconds{quantile="0.95"} > 150或DCGM_FI_DEV_MEM_COPY_UTIL > 95时，企业微信告警。

4.9 故障注入测试：验证优化鲁棒性

用chaos-mesh注入故障：

• kubectl apply -f network-delay.yaml模拟网络延迟，验证vLLM retry机制
• kubectl apply -f pod-failure.yaml随机kill worker pod，验证auto-scaling
• kubectl apply -f stress-cpu.yaml给host打满CPU，观察GPU利用率是否被抢占
  曾发现当host CPU 100%时，vLLM的PagedAttention page allocation变慢，导致P99延迟飙升。解决方案：在vLLM启动参数加--worker-use-ray，让worker进程绑定独立CPU core。

4.10 模型热更新：零停机切换engine

vLLM不支持热reload engine，我们用nginx做流量切分：

• 启动两个vLLM实例：port 8000（旧engine）、port 8001（新engine）
• nginx配置：

upstream backend { least_conn; server 127.0.0.1:8000 weight=100; server 127.0.0.1:8001 weight=0; }

• 更新时，先curl -X POST http://localhost:8001/health确认新实例ready，再nginx -s reload，逐步调高weight至100，旧实例weight降为0。全程用户无感知。

4.11 安全加固：限制GPU资源与模型访问

• GPU资源限制：docker run时加--gpus '"device=0,1" --memory=16g --cpus=8'，防止单容器吃光资源
• 模型访问控制：在vLLM api_server.py里加JWT鉴权，Authorization: Bearer <token>，token由内部密钥签发
• 敏感信息隔离：.env文件不进git，用k8s secret挂载，环境变量名全大写加前缀VLLM_MODEL_

4.12 文档沉淀：生成可执行的runbook

每完成一次Model-Optimizer，生成Markdown runbook：

• hardware_spec.md：GPU型号、驱动版本、PCIe带宽实测值
• model_config.md：模型架构、hidden_size、num_layers、rope_theta
• trt_config.md：builder参数、workspace size、dynamic axes范围
• vllm_config.md：启动参数、scheduler tuning、metrics阈值
• validation_report.md：PPL对比表、token/s benchmark、显存占用截图
  这份runbook是团队知识资产，新人照着runbook，2小时内可复现90%优化效果。

5. 常见问题排查：21个高频故障的根因与速查表

Model-Optimizer实操中，83%的问题集中在环境、配置、数据三类。我把三年踩过的坑整理成速查表，按现象→根因→解决步骤排列，附真实报错日志片段。

现象	根因	解决步骤	真实日志片段
trtexec报错“Assertion!isDynamic()failed”	TensorRT版本与GPU compute capability不匹配	降级TensorRT至10.2.0.11，确认A10用sm_80，H100用sm_90	Assertion failed: !isDynamic() at tensorrt/rtSafe/safeContext.cpp:123
vLLM启动报错“OSError: libcudart.so.12: cannot open shared object file”	CUDA runtime库路径未注入	在Dockerfile中加ENV LD_LIBRARY_PATH="/usr/local/cuda/lib64:$LD_LIBRARY_PATH"	ImportError: libcudart.so.12: cannot open shared object file
engine加载后PPL暴增，logits全为nan	FP16模式下RMSNorm中间值溢出	在custom plugin中用float计算，或加--strict-typesflag	PPL=inf, logits=[nan, nan, ...]
nvidia-smi显示GPU 0% utilization，但token/s极低	PCIe带宽瓶颈，权重加载慢	用nvbandwidth测PCIe带宽，启用--weight-streaming	nvidia-smi -q -d PCI | grep "Bandwidth"显示<50GB/s
vLLM报错“ValueError: max_num_seqs must be >= 1”	scheduler参数未按业务流量设置	根据压测结果设--max-num-seqs=256，非默认128	ValueError: max_num_seqs must be >= 1
docker run --gpus all报错“docker: Error response from daemon: could not select device driver”	NVIDIA Container Toolkit未安装或服务未启	sudo systemctl restart nvidia-container-toolkit-daemon	docker: Error response from daemon: could not select device driver
Qwen2 RoPE位置编码错乱，输出乱码	onnx导出时rope_theta未设	在AutoConfig中显式设rope_theta=1000000.0	output="\u0000\u0000\u0000..."
trtexec生成engine后，load时报“Invalid engine”	序列化buffer未8字节对齐	用posix_memalign(&buffer, 8, size)分配内存	ERROR: INVALID_STATE: Deserialize the engine failed.
vLLM P95延迟忽高忽低，波动超100ms	host CPU被其他进程抢占	htop看CPU usage，加--worker-use-ray绑定core	time_to_first_token_seconds{quantile="0.95"} 87ms → 213ms
engine在A10上OK，在H100上OOM	workspace size未按显存比例设	H100设--workspace=16384，A10设--workspace=4096	CUDA out of memory. Tried to allocate 2.00 GiB

提示：所有问题排查第一步，都是nvidia-smi -q -d MEMORY看显存是否真满，而非凭感觉。曾有个case，显存显示98%，但nvidia-smi -q -d COMPUTE显示compute utilization仅12%，说明是显存泄漏，非计算瓶颈。

6. 实战心得：那些文档里不会写的12条血泪经验

这些经验来自上百次Model-Optimizer实战，是文档、教程、论文里绝不会写的细节，但每一条都价值千金：

1. 永远用nvidia-smi -l 1盯实时显存，而不是看free -h：vLLM的swap_space会占用host memory，但free -h显示正常，GPU显存却已爆。我们曾在生产环境因此OOM三次，直到加了watch -n 1 'nvidia-smi --query-gpu=memory.used --format=csv,noheader,nounits'实时监控。

2. TensorRT engine文件大小≠性能优劣：见过1.2GB的engine比800MB的慢37%，因前者启用了过多fusion，寄存器压力过大。性能只看trtexec --duration=30实测结果。

3. Qwen2的rope_theta必须设为1000000.0，不是10000：官方文档写10000，但Qwen2实际用1000000，设错会导致position_ids错位，输出完全乱码。这是Qwen团队私有实现，未公开。

4. vLLM的--gpu-memory-utilization 0.9不是越高越好：设0.95在A10上会因显存碎片导致OOM，0.9是安全阈值。我们用nvidia-smi dmon -s u监控utilization，动态调整。

5. 不要信ONNX模型的opset_version标签：有些模型导出时标opset 18，但实际