首页/AI/大模型部署与运维速查

大模型部署与运维速查

推理部署框架选型（vLLM/Ollama 等）、GPU 与显存估算、推理参数与量化、并发吞吐测算、服务网关与监控排障：私有化部署速查。

共 267 条更新于 2026-10-12所属领域：AI

共 267 条

部署形态与选型

API 调用与私有化部署、推理框架对比

vLLM 推理引擎与 PagedAttention热门

vLLM 是 GPU 上的高吞吐推理与服务引擎：用 PagedAttention 按块管理 KV 缓存、连续批处理提升 GPU 利用率，并自带 OpenAI 兼容 HTTP 接口，是把开源权重封装成在线 API 的常用方案。

Ollama 本地模型运行工具热门

Ollama 面向单机场景，把模型下载、GGUF 量化格式、运行与 API 服务打包为一条命令，默认监听 127.0.0.1:11434，适合开发调试与轻量内网服务。

vllm serve 常用启动参数

vllm serve 的关键参数集中在显存、并行与量化三组：--tensor-parallel-size 多卡切分、--gpu-memory-utilization 显存预算、--max-model-len 上下文上限、--quantization 指定量化内核。

主流推理框架横向对照

按部署形态与调度机制对照 vLLM、SGLang、TGI、Ollama、llama.cpp：前三者面向服务端吞吐，Ollama 与 llama.cpp 面向单机与边缘；对照表用于快速缩小候选范围。

大模型部署形态对比（云 API / 自建 / 混合）

常见三种部署形态：直接调用云端 API、完全私有化部署、本地为主云端兜底的混合形态。选择依据包括数据合规要求、并发规模、预算形态与运维能力。

llama.cpp 与 GGUF 生态

llama.cpp 对 CPU 与消费级 GPU 友好，用 GGUF 量化格式在单机跑模型；配套 llama-cli（交互）、llama-server（HTTP 服务）、llama-quantize（量化）等工具。

vLLM 官方 Docker 镜像部署

用官方镜像 vllm/vllm-openai 部署可以免去 CUDA 环境配置：挂载模型缓存目录、透传 GPU、共享 IPC，即可启动 OpenAI 兼容服务。

Hugging Face 模型下载（huggingface-cli）

用 huggingface-cli（新版命令 hf）把模型权重下载到本地目录，支持断点续传与指定文件；大模型配合 hf_transfer 提升带宽利用率。

推理服务栈分层总览

从硬件到应用，一条推理服务链路通常分为 GPU 硬件层、驱动与 CUDA 运行时层、推理引擎层、网关层和应用层；排障与选型都按这五层逐层定位，能快速缩小问题范围。

Ollama 常用命令速查

pull / run / list / ps / show / rm / create / push 覆盖模型生命周期的主要操作；create 配合 Modelfile 可以固化默认参数与系统提示。

TGI（Text Generation Inference）定位与部署

Hugging Face 出品的推理服务：内置连续批处理、张量并行与 token 流式输出，Docker 镜像开箱可用，默认监听 8080，适合标准 Transformers 权重。

云 API 与私有化部署取舍清单

把「是否自建」拆成六个可核对问题：数据能否出域、并发峰值多大、延迟要求多严、模型是否可控、团队能否值班、预算偏 CAPEX 还是 OPEX。

Ollama API：原生接口与 OpenAI 兼容接口

Ollama 同时提供原生 REST（/api/generate、/api/chat）与 OpenAI 兼容端点（/v1/chat/completions），后者可直接用 OpenAI SDK 连接，便于切换后端。

模型权重格式：safetensors / bin / GGUF / ONNX

权重格式决定能上哪些推理框架：safetensors 是服务端主流（vLLM、TGI 直接支持）；GGUF 面向 llama.cpp 与 Ollama；ONNX 多用于跨平台与编译部署栈。

SGLang 与 RadixAttention 前缀缓存

SGLang 运行时用基数树（RadixAttention）复用请求间共享的 KV 前缀，多轮对话与固定系统提示场景的缓存收益明显；内置 OpenAI 兼容服务，默认端口 30000。

推理框架选型检查清单

选框架按六项核对：模型架构支持、量化格式支持、硬件后端、并发与延迟目标、运维成熟度、团队熟悉度；逐项打勾后再进测试环境验证。

GGUF 格式与量化档位

GGUF 是 llama.cpp 生态的单文件格式，文件名里的 Q4_K_M、Q5_K_M、Q8_0 等后缀表示量化档位：数字越小体积越小、质量损失越大。

Ollama Modelfile 固化参数

Modelfile 把基础模型、系统提示与默认采样参数打包成自定义模型；其中 num_ctx 决定上下文窗口，是排查「上下文被截断」问题的起查点。

推理服务常用默认端口速查

把常见推理组件与网关的默认监听端口汇总成表，用于防火墙规划、安全组核对与端口占用排查。

TensorRT-LLM 与引擎编译部署

NVIDIA 官方的 LLM 推理优化库：把模型编译为针对特定 GPU 架构的 TensorRT 引擎再运行，风格接近「编译部署」；引擎与架构绑定，换卡需要重编。

内网离线部署完整流程

离线部署的关键是把「模型 + 镜像 + Python 依赖」三样东西在联网环境准备齐，再整体搬运；任何一项缺失都会在内网表现为加载失败。

safetensors 加载与常见问题

safetensors 以内存映射方式加载权重，启动快且避免 pickle 反序列化风险；多分片模型依赖 .index.json 描述分片与张量映射关系。

冷启动、预热与常驻策略

推理服务冷启动包含权重加载、KV 缓存分配与 CUDA Graph 捕获，动辄数十秒到数分钟；上线切流前先预热，并让常驻实例保持热状态。

LMDeploy 推理工具箱

LMDeploy 提供 API 服务、离线推理与量化工具链，对国产模型与 AWQ 权重支持较积极；api_server 默认监听 23333，同样提供 OpenAI 兼容接口。

HF 镜像与离线下载策略

网络受限环境用 HF_ENDPOINT 指向镜像站或统一走代理；完全离线环境则先在可达网络下载完整模型目录，再整体拷贝进内网。

docker compose 部署推理服务

compose 把引擎、网关、监控编排在一个文件里，适合单机多服务部署；GPU 通过 reservations.devices 声明，避免容器拿不到显卡。

Embedding 模型服务化（TEI）

文本向量化服务用 Hugging Face 的 TEI（Text Embeddings Inference）部署较省心：面向 embedding 优化，容器内监听 80 端口，适配主流向量检索链路。

推理成本测算：每百万 token 成本

成本测算的实操公式：GPU 小时成本 ÷ 每小时产出 token 数 = 每 token 成本；产出取决于吞吐（tokens/s），因此吞吐实测是成本核算的输入项。

ModelScope 模型下载

国内模型（Qwen、GLM 等）多数在魔搭社区同步发布，用 modelscope 命令行可直接下载，网络条件通常更稳定。

模型 revision 锁定与可复现部署

仓库内容会更新：锁定 revision（commit 号或标签）能让每次部署拿到同一份权重，是灰度与回滚的基础。

Kubernetes 部署推理服务要点

K8s 上跑推理服务的三件事：安装 NVIDIA device plugin 暴露 nvidia.com/gpu 资源、在 Pod 里申请 GPU、给推理服务配就绪探针与优雅退出。

OpenWebUI 接入本地推理服务

OpenWebUI 是自托管的对话前端，通过环境变量指向任意 OpenAI 兼容后端（vLLM、Ollama、网关），常作为团队使用本地模型的入口页面。

混合形态：本地为主、云端兜底

把本地推理作为主通道、云端 API 作为故障与峰值兜底：网关层统一入口，本地不健康或队列过长时按策略切换，业务代码无需感知。

Xinference 多模型统一服务

Xinference 用统一接口托管 LLM、Embedding、Rerank、语音等多类模型，支持本地与集群调度，默认端口 9997，适合需要「一个平台挂多种模型」的轻量场景。

LoRA 适配器热加载服务化

vLLM 支持在基础模型上挂载多个 LoRA 适配器并动态切换：一份基座权重服务多个微调变体，显存增量远小于各存一份完整模型。

模型许可证与商用合规核对

开源权重不等于可以随意商用：常见有 Apache-2.0（宽松）、社区许可（如 Llama 系列自定条款，含规模与场景限制）以及各类自定义条款，商用前逐条核对。

CPU 推理场景与要点

没有 GPU 或只做低并发验证时，CPU 推理可用 llama.cpp、Ollama 等方案；吞吐低但部署简单，适合功能验证、小规模内网与离线批处理。

选型必读：模型卡核对清单

每个模型仓库的 README 或 model card 是选型的一手资料：参数量、上下文长度、许可、支持语言、推荐推理配置与量化版本都在其中。

MLC-LLM 编译式部署概念

MLC-LLM 基于 TVM 把模型编译为面向目标平台的可执行产物，覆盖 NVIDIA、AMD、Apple、移动端等多种后端；部署形态更接近「为设备编译」，产物与平台绑定。

单卡多模型混合部署

一张卡上同时服务多个模型（如对话模型 + Embedding + Rerank）时，按「常驻小模型 + 按需大模型」分配显存，并限制并发加载数量防止互相挤占。

Rerank 模型服务化

重排模型（如 bge-reranker）对召回候选二次打分；较新的 TEI 提供 /rerank 接口，Xinference 等平台也可直接托管 rerank 类模型。

LocalAI 本地 OpenAI 替代服务

LocalAI 用 Go 编写的本地推理服务，兼容 OpenAI API，可挂载多种后端（llama.cpp 等），默认端口 8080，适合需要轻量自托管与多模态接口的实验环境。

边缘与端侧部署要点

边缘设备（Jetson 系列、迷你主机、手机）的常见思路是「小模型 + 强量化 + 平台专用运行时」：显存与功耗受限时优先 3B~8B 级模型与 INT4 量化。

推理环境与 GPU

显卡选型、驱动 CUDA 与算力要点

nvidia-smi 基础用法

GPU 运维的瑞士军刀：直接执行查看显存、利用率、温度与进程表；配合 -l 秒级刷新，是排查服务行为的起点。

驱动与 CUDA 版本的关系

两处版本号含义不同：nvidia-smi 显示的 CUDA Version 是「驱动支持的上限运行时版本」，nvcc --version 是「实际安装的工具箱版本」；工具箱版本不能超过驱动上限。

NVIDIA 驱动：安装方式与版本查看

驱动是 GPU 与上层 CUDA 之间的桥：服务器环境优先用发行版仓库包（apt/dnf）安装并启用 DKMS，便于内核升级后自动重建模块；.run 文件适合需要特定版本的场景。

按显存选卡：选型要点

显卡选型先看显存容量：要放下「权重 + KV 缓存 + 框架开销」；再看向上空间（长上下文与并发）与带宽（影响解码速度）。容量不够时量化或多卡切分是两条路。

定位谁在占用 GPU 显存

服务 OOM 或显存对不上账时，先列出占用显存的进程：PDB 进程表看不懂就用 --query-compute-apps 输出 CSV，再回查进程归属。

常见推理卡显存与带宽速查

把常用推理卡的显存容量与标称带宽列成表：容量决定能放下多大的模型，带宽决定单请求解码速度的量级。数值取自官方数据手册。

CUDA_VISIBLE_DEVICES：指定进程可见的 GPU

通过环境变量控制进程可见的 GPU 集合与编号重排：适合单机多卡隔离、指定卡跑任务、容器内只暴露部分卡的场景；用 GPU UUID 可以避免序号变化带来的映射漂移。

GPU 计算能力（Compute Capability）速查

Compute Capability 用主次版本号标记 GPU 指令集能力（如 8.0、8.9、9.0），决定了能运行哪些预编译内核；装框架前先核对算力是否在支持矩阵内。

容器用不了 GPU 的排查顺序

容器报「could not select device driver」时按固定顺序排查：宿主机驱动是否正常、工具链是否安装、运行时是否配置、命令是否带 --gpus。

PyTorch 显存观测：allocated 与 reserved

torch.cuda 把显存分成 allocated（张量实际占用）与 reserved（缓存分配器持有总量）：排查显存问题先看这两个数，再区分模型占用、缓存保留与被占用的差异。

nvidia-smi 结构化查询（CSV）

用 --query-gpu 输出机器可读的 CSV，便于脚本采集与二次处理；常用字段覆盖显存、利用率、温度、功耗与降频状态。

NVIDIA 容器工具链安装与验证

让 Docker 能用 GPU 的关键组件：安装 nvidia-container-toolkit、配置容器运行时、重启 Docker，然后用官方测试镜像验证透传。

NCCL 带宽测试：nccl-tests 用法

多卡与多机通信能力的基线工具：编译 nccl-tests 后运行 all_reduce_perf，观察不同消息大小下的 busbw 与耗时，判断 NVLink、PCIe 或 RDMA 链路是否达到预期。

GPU 上架自检：快速验证脚本

新机器或换卡后的快速自检：先确认识别与驱动版本，再跑一次真实矩阵乘验证计算路径，最后做多卡通信基线；三步覆盖硬件、驱动与框架栈的常见问题。

CUDA Toolkit 安装与验证

服务器上装 CUDA Toolkit 有三种常见路径：发行版（NVIDIA 官方仓库）、conda/venv 环境内安装、以及直接用容器镜像；推理部署推荐后者，避免污染宿主机。

PyTorch 与 CUDA 版本匹配

PyTorch 的每个版本都绑定特定的 CUDA 构建：装错组合的典型症状是 torch.cuda.is_available() 返回 False 或加载库失败；用官方索引地址安装可避免手工拼装。

显存带宽决定解码速度上限

自回归解码是内存受限型计算：每生成一个 token 要读一遍权重，因此单请求解码速度的理论上限约等于显存带宽除以每 token 需读取的权重字节数。

NCCL 常用环境变量与调试输出

NCCL 通过环境变量控制选网、P2P 与调试输出：排查挂起或带宽异常时先开 NCCL_DEBUG=INFO，看日志里实际使用的网卡与链路类型（NVLink/PCIe/IB）。

nvidia-smi topo -m 查看 GPU 拓扑

topo -m 一张表看清卡与卡、卡与网卡之间的连接方式：NV# 表示 NVLink、PIX/PXB 表示同一 PCIe 交换树、SYS 表示跨 NUMA；多卡部署选卡与调优的输入。

K8s GPU 调度：device plugin 与资源申请

Kubernetes 通过 NVIDIA device plugin 把 GPU 暴露为扩展资源 nvidia.com/gpu，调度器按节点可分配数分配；MIG 切片与整卡以不同资源名呈现，申请写法一致。

GPU 降频原因查看

推理速度突然下降先看降频：-q -d PERFORMANCE 列出 Clocks Throttle Reasons，常见为 SW Power Cap（功耗墙）与 HW Thermal（温度），个别还有 SW Thermal Slowdown。

数据中心卡与消费卡取舍

数据中心卡（A100/H100/L40S 等）面向 7×24 高负载：被动散热、ECC、部分型号带 NVLink；消费卡（RTX 系列）单价低，适合开发与轻量服务，但多卡互联与运维特性受限。

nvidia-smi dmon 与 pmon：滚动监控

dmon 按固定间隔滚动输出功耗、利用率、显存、温度等汇总指标，pmon 输出进程级利用率：压测时观察降频、掉卡与进程行为都靠它们现场留痕。

GPU 利用率偏低的排查顺序

服务端 GPU 利用率偏低常见原因：批太小、请求稀疏、CPU 侧预处理或分词瓶颈、采样环节占用、以及网关限流排队；按请求链路逐层定位效率更高。

驱动升级流程与回滚点

驱动升级的稳妥流程：记录当前版本 → 停掉 GPU 任务 → 升级 → 重启 → 验证 nvidia-smi 与容器透传 → 再逐步恢复服务。

GPU 架构代号与特性差异

Ampere 引入 BF16 张量核，Ada 增强 FP8 支持，Hopper 面向大模型做了 Transformer 优化；选卡与选量化方案时先看架构代际。

nvtop 实时监控工具

nvtop 是终端里的 GPU 版 top：滚动展示利用率、显存、功耗曲线与逐进程占用，比反复刷 nvidia-smi 直观，适合交互式排查。

功耗、温度与降频排查

GPU 触及功耗墙或温度阈值时会自动降频，表现为吞吐下滑；用 nvidia-smi -q -d 查询温度、功耗、时钟以及降频原因（Clocks Throttle Reasons）逐项对照。

多机互连：RDMA/IB 状态与带宽检查

跨机多卡部署依赖 RDMA（InfiniBand 或 RoCE）互连：上线前用 ibstat / ibv_devinfo 核对端口状态与速率，再用 perftest 做带宽基线，避免通信链路成为瓶颈。

ECC 显存错误查看与处置

数据中心卡带 ECC 保护显存：用 -q -d ECC 查看单比特（已纠正）与双比特（未纠正）错误计数；未纠正错误持续的卡不可继续承载生产任务。

FlashAttention 概念与架构要求

FlashAttention 把注意力计算融合为 IO 友好的实现，是推理引擎提速的关键组件之一；第二代主要面向 Ampere 及更新架构，安装的版本需要与 torch、CUDA 三者匹配。

NVLink 与卡间高速互联

NVLink 是 GPU 间的直连高速通道：A100 平台约 600 GB/s 双向、H100 平台约 900 GB/s 双向，高于 PCIe 代际带宽；张量并行每步都要跨卡通信，互联质量直接影响吞吐。

DCGM Exporter 与 GPU 指标入监控栈

DCGM Exporter 把 GPU 指标转成 Prometheus 格式，默认端口 9400，配合 Prometheus 与 Grafana 形成 GPU 监控闭环；K8s 上常用 Helm 部署。

GPU 虚拟化与共享形态速览

常见共享形态各有取舍：PCIe 直通整卡给虚机、MIG 做硬件隔离切片、容器分时共享降低门槛；隔离性、粒度与运维复杂度差异明显，按场景选择。

MIG 多实例 GPU 概念与命令

MIG 把一张数据中心卡切成多个隔离实例（各自有显存与算力），适合多租户或大小模型混部；消费卡不支持，切分档位随型号而定。

DCGM：数据中心 GPU 管理工具

DCGM（Data Center GPU Manager）提供 GPU 健康检查、诊断与指标采集，适合生产环境的批量监控与巡检；dcgmi 是它的命令行入口。

拷机与稳定性验证（gpu-burn / DCGM）

新卡或疑似故障卡的长稳验证：gpu-burn 持续满载跑矩阵运算并校验结果，DCGM 提供分级自检；上架验收与返修场景都常用这一组合。

NVML 与 pynvml：脚本化采集 GPU 指标

nvidia-smi 底层是 NVML 库；Python 侧常用 nvidia-ml-py（导入名 pynvml）读取显存、温度、功耗与进程信息，适合自建轻量监控与巡检脚本。

GPU 重置（--gpu-reset）的正确使用

设备卡死、显存无法释放时可用 --gpu-reset 软重置；它要求设备上没有在用进程（部分机型限制更多），风险高，属于「先记录、再操作」的应急手段。

cuDNN 的角色与版本匹配

cuDNN 是深度学习原语库（卷积、归一化等）；LLM 推理主要吃自研 attention kernel 与 PyTorch 集成，但部分算子路径仍依赖 cuDNN，版本错配会以报错或性能回退的形式出现。

PCIe 直连（P2P）与拓扑影响

多卡通信走 PCIe 时是否支持 P2P（点对点直传）影响明显：数据中心卡通常支持，部分消费卡被限制；不支持时数据经主机内存中转，延迟与带宽都变差。

持久化模式：减少 GPU 初始化开销

默认情况下 GPU 无任务时驱动会卸载其状态，首个任务承担初始化延迟；开启持久化模式让驱动保持加载，适合推理服务常驻、任务频繁拉起的场景。

容器内 CUDA 兼容（前向兼容）

容器里 toolkit 版本高于宿主机驱动上限时，可借助 CUDA Forward Compatibility 兼容包（如 cuda-compat-<版本>）在数据中心卡上运行；属于受限场景的方案，不是常规路径。

MPS 多进程服务概念

MPS（Multi-Process Service）允许同一张卡上多个进程共享 GPU 计算资源，适合多进程小任务并发的场景；它做的是资源复用而非硬隔离，与 MIG 定位不同。

模型盘与加载 IO：本地盘与页缓存

大模型加载受磁盘读带宽与页缓存命中影响：模型放本地 NVMe 能缩短冷启动，多实例共用同一模型文件时页缓存命中与否差异明显。

多版本 CUDA 并存与切换

同一台机器可以并存多个 CUDA Toolkit：安装到 /usr/local/cuda-<版本>，通过 /usr/local/cuda 软链切换默认版本；conda 环境也可以各自装独立版本，互不影响。

AMD ROCm 推理环境概念

AMD GPU 走 ROCm 软件栈（对应 CUDA 的生态位），PyTorch 提供 ROCm 构建版，部分推理框架（如 vLLM、llama.cpp）提供 ROCm 支持；选型时先查目标框架对该卡的适配状态。

NUMA 与 GPU 亲和性检查

多路 CPU 机器上每张 GPU 挂在特定 NUMA 节点下：进程跨节点访问会引入额外开销；单机多实例部署按拓扑分配 CPU 与卡，行为更可预期。

PCIe 链路检查：协商是否降级

GPU 与主机的 PCIe 链路影响模型加载与主机侧数据搬运：用 nvidia-smi 与 lspci 核对当前链路宽度、代数与上限，确认没有被降级到低带宽协商。

Intel GPU 推理生态入门

Intel 数据中心 GPU 与核显走 oneAPI/Level Zero 栈，PyTorch 提供 XPU 支持，llama.cpp 系工具链有 SYCL 后端；选型前先核对目标框架对该硬件的算子与量化支持。

推理参数与优化

采样参数、批处理、量化与 KV 缓存

temperature：控制输出随机性

采样前对 logits 做缩放：温度越低分布越尖锐、输出更确定，温度越高越发散；接近 0 时基本退化为贪心解码（以框架实现为准）。

top_p：核采样阈值

按概率从高到低累积到阈值 p，只在集合内采样：p=1 相当于不裁剪，p 越小候选越窄；常见取值 0.9~0.95。

max_tokens：限制生成长度

限制单次响应生成的 token 数：太小会把回答截断，太大在高并发下拉长占用；它与输入长度共同受上下文窗口约束（输入+输出不超过窗口上限）。

KV 缓存是什么：显存的主要变量

KV 缓存保存每层注意力已生成 token 的 Key/Value 张量，避免重复计算：随序列长度、层数、KV 头数、精度与批大小线性增长，显存规划必须单独为它留空间。

top_k：固定候选数量截断

每步只在概率靠前的 k 个 token 中采样：k=1 等于贪心，k 增大多样性上升；不少推理栈默认关闭该参数，需要显式设置才生效。

量化总览：位宽、对象与格式

量化用更低位数存权重或激活来省显存、提吞吐：先分「权重量化」还是「权重+激活」，再定位宽（8/4 位）与格式（FP8/GPTQ/AWQ/GGUF 等），最后用评测集验证质量取舍。

repetition_penalty：重复惩罚

对已出现 token 的 logits 做惩罚来抑制复读：取值大于 1 抑制、等于 1 不生效；各实现数值口径略有差异，迁移时要小样本对比。

prefill 与 decode：两阶段性能特征

推理分两阶段：prefill 一次并行处理整段输入（计算密集，决定首字延迟），decode 逐 token 生成（访存与带宽密集，决定每 token 延迟）；两阶段特征不同，优化手段也不同。

连续批处理（continuous batching）

每个解码步动态并入新请求、完成的请求立即退出，替代「一批跑完再开下一批」：混合长度请求下 GPU 利用率与总吞吐提升明显，是主流推理引擎的默认调度方式。

stream：流式返回（SSE）

stream=true 时响应以 SSE 分块下发增量 token，降低首字等待、改善交互体验；网关需关闭响应缓冲，客户端按 data: 事件逐个解析。

stop：停止序列

生成命中指定字符串时立即停止：OpenAI 兼容字段 stop 支持单个字符串或数组，常用于切割多轮对话与服务端分节输出。

受约束解码：JSON/Schema/正则

受约束解码让输出在生成时就符合目标语法：OpenAI 兼容的 response_format（JSON 模式）与 vLLM 的 guided decoding（底层 xgrammar/outlines 等后端）是常见入口，可降低解析失败率。

seed：可复现性的边界

固定 seed 让采样序列可复现（尽力而为）：OpenAI 兼容字段 seed、vLLM SamplingParams 也有 seed；但并行度、批组合与算子实现变化仍可能带来差异。

chat template：消息到 prompt 的渲染

Chat 模型要求把消息列表按模板渲染成带角色标记的 prompt：标准做法是用 tokenizer 自带 chat template（Jinja）渲染；模板与模型训练格式不一致是输出异常的常见根因。

前缀缓存：复用相同前缀的 KV

相同前缀（系统提示、模板、few-shot 示例）的 KV 缓存直接复用、跳过重复 prefill：多请求共享同一系统提示的网关场景收益明显，命中率可从服务指标观察。

min_p：按峰值比例过滤候选

按当步概率峰值比例过滤：只保留概率不低于「峰值 x min_p」的候选；相对固定阈值更能跟随分布形态变化，vLLM 与 llama.cpp 均支持。

presence/frequency penalty：出现次数惩罚

两个按出现次数调节 logits 的惩罚：presence_penalty 只在 token 出现过时施加固定调整，frequency_penalty 随出现次数线性累计；常见范围 -2~2。

chunked prefill：长输入分块执行

把长输入的 prefill 切块，与 decode 步骤交错执行：避免长请求独占一步、阻塞其他请求的解码，降低尾延迟；由 enable_chunked_prefill 与 max_num_batched_tokens 等参数控制。

FP16 与 BF16 的选择

两种 16 位精度显存占用相同：BF16 指数位宽、数值范围大，溢出风险低；FP16 尾数位多，精度略高但在部分老卡之外存在溢出风险。

generation_config.json：默认采样参数的来源

模型目录里的 generation_config.json 记录作者设定的默认采样参数；请求未显式指定时，实际生效值由服务端默认与模型生成配置共同决定，可能与模型卡推荐不一致。

工具调用：服务端解析与启用

函数调用让模型按约定输出结构化调用请求；自托管服务需启用对应解析器（如 vLLM 的 --tool-call-parser，解析器与模型族配套），网关再把 tool_calls 交给业务执行。

KV 缓存精度：fp8 选项

KV 缓存可降精度存储以降低显存占用、抬高并发上限：vLLM 提供 --kv-cache-dtype fp8（还有平台相关的 fp8 变体）；对长上下文场景的效果直接，但需评估精度影响。

GPTQ：4 位权重量化

GPTQ 用校准数据逐层最小化量化误差，产出 4 位权重（W4A16）：推理时反量化回高精度参与计算，权重显存降至 FP16 的四分之一量级，质量影响需实测。

GGUF 量化档位与选择

GGUF 是 llama.cpp 生态的权重格式，内置多档量化（Q4_K_M、Q5_K_M、Q8_0 等）：K 系列带混合精度策略，档位越高越接近原精度、文件越大。

采样参数的作用顺序

采样参数并非各自独立生效：经典流水线顺序为 logits 惩罚（repetition 类）→ temperature 缩放 → top_k → top_p，最后才做采样；顺序决定叠加后的真实候选集。

token 计数：预算与截断的基准

发送前按 token 数做预算：输入上限、输出预留与计费都按 token 计；用目标模型的 tokenizer 或服务端 /tokenize 接口实测，不要用字符数折算。

PagedAttention：KV 分页管理

把 KV 缓存按固定大小块（block）分页管理，类似操作系统虚拟内存：减少碎片、支持非连续存储与跨请求共享，是 vLLM 高并发吞吐的基础机制。

推测解码：用小模型加速生成

用草稿模型（或 n-gram 等）先预测若干候选 token，主模型一次前向校验并接受：接受率高时每步产出多个 token，TPOT 明显下降；适合显存有余的延迟敏感场景。

FP8 量化：新代 GPU 的加速选项

FP8 在 H 系列及更新的 GPU 上有原生算力：支持权重+激活的 W8A8 量化与 KV 缓存量化，显存与吞吐改善明显；前提是硬件与推理栈同时支持。

AWQ：激活感知的 4 位量化

AWQ（激活感知权重量化）按激活分布保护重要通道，4 位权重（W4A16）通常质量保持较好、对校准集依赖相对小；主流推理框架内置支持。

bitsandbytes：即用量化（int8/NF4）

bitsandbytes 在加载时做 8 位或 4 位（NF4）量化，无需预量化权重：上手快，常用于实验与显存紧张的单机场景；推理吞吐通常不及面向推理优化的量化内核。

推理模型输出：分离思维过程

带思维链输出的推理模型需要把思维过程与最终回答分开：vLLM 用 --reasoning-parser 按模型族解析，响应中 reasoning_content 与 content 分字段返回。

离线批推理：吞吐优先的跑法

对不需要实时返回的任务（标注、批量摘要、离线评测）用批处理跑：吞吐优先、延迟放宽；vLLM 的离线接口直接接收 prompt 列表批量输出。

超窗请求的处理策略

输入超过上下文窗口时的处理因服务实现而异：拒绝并报错、截断输入或前端摘要压缩；在入口统一长度策略，行为才可预期。

注意力头结构：KV 规模的关键变量

注意力变体直接决定 KV 缓存规模：MHA 每头独立 KV、GQA 多个查询头共享一组 KV、MQA 全部共享一组；共享程度越高，KV 越小、推理越省显存。

logprobs：输出置信度观测

返回生成 token 的对数概率用于置信度检查：OpenAI 兼容参数 logprobs=true，配合 top_logprobs=N 可看每个位置的前 N 个候选；vLLM 同样支持。

KV swap：用 CPU 内存做缓冲

KV 显存不足时把被抢占请求的 KV 换出到 CPU 内存，需要时再换回：vLLM 提供 swap-space 配置交换空间大小，属于缓冲手段而非常态扩容方案。

长上下文部署的三个关注点

长上下文上线关注：KV 显存随长度线性增长、prefill 时间随输入增大、超窗请求的处理策略；常用手段是 KV 降精度、分块预填充与入口处截断/摘要。

AWQ 与 GPTQ 的取舍对照

两种主流 4 位权重量化思路不同：GPTQ 逐层最小化量化误差、生态成熟；AWQ 按激活保护重要通道、对校准集依赖相对小；最终以同模型实测为准。

MoE 模型推理：激活与驻留

混合专家模型单 token 只激活部分专家：计算量按激活参数走，但权重显存按全量专家驻留；部署前确认框架对 MoE 的算子与并行支持，并用真实路由分布压测。

n 与 best_of：多候选生成

n 表示单请求返回多个候选；vLLM SamplingParams 还提供 best_of：采样多个结果后按累计概率挑选后返回；生成量随参数成倍放大。

tokenizer 版本与一致性

分词器决定 token 切分与特殊 token 表：部署时把 tokenizer 与权重一起固定版本，能避免「换了个远端小版本、行为悄然变化」的隐蔽问题。

CUDA Graphs：降低解码步启动开销

把解码阶段的多步小算子序列捕获成 CUDA Graph 一次提交，减少内核启动开销：vLLM 默认对解码启用，可用 enforce-eager 关闭做对照排查。

采样与束搜索：解码策略取舍

贪心与采样逐 token 决策、单路径推进；束搜索同时维护多条候选路径，质量可能更稳但计算量按束宽成倍放大：生成类任务多用采样，候选精挑场景才考虑束搜索。

量化效果评估：质量与性能一起看

量化上线前同时验证两条线：质量（业务评测集通过率、格式遵循、长文一致性）与性能（吞吐、TTFT、TPOT、显存水位、可并发序列数），缺一不可。

logit_bias：按 token 施加偏置

对指定 token 的 logits 加固定偏置：正值提升、负值抑制，-100 常用来硬性排除特定 token；字段为 token id 到偏置值的映射。

权重卸载：部分层放 CPU 内存

把模型部分权重放在 CPU 内存、按需换入显存，用时间换空间：vLLM 提供 cpu-offload-gb 参数按 GiB 指定卸载量，适合显存与目标模型差一口气的场景。

服务端 INT8（W8A8）路径

把激活也压到 8 位（W8A8，常配合 SmoothQuant 类技术）以利用整型算力：TensorRT-LLM 等栈提供支持；相比纯权重量化，对算子与部署流程要求更高。

RoPE 位置缩放：扩展上下文窗口

通过 RoPE 缩放（线性、NTK、YaRN 等）拉长模型可用上下文：需要模型配置与推理栈同时支持，属于「扩窗」而非训练时的原生窗口，质量要专门评测。

Prefill/Decode 分离部署

把 prefill 与 decode 拆到不同实例执行：两阶段各自扩缩容、互不干扰；大规模服务与负载构成差异明显的场景会采用，配套需要 KV 传输与两级调度。

显存与并发估算

显存占用计算、上下文长度与并发吞吐

显存预算四块构成

单卡显存预算分四块：权重、KV 缓存、激活与工作区、框架/驱动开销；权重决定「跑不跑得起来」，KV 决定「能并发多少」，两张表分开估算再合账。

KV 缓存公式：逐项拆解

KV 总量 = 每 token 字节数 × 序列长度 × 并发序列数；每 token 字节数 = 2 × 层数 × KV 头数 × 头维度 × 精度字节（2 对应 K 与 V 两组张量）。

权重显存公式：参数量 × 字节数

权重显存 = 参数量 × 每参数字节：FP16/BF16 每参数 2 字节、INT8 约 1 字节、4 位约 0.5 字节；张量并行后每卡按分片折减，通信缓冲另计。

并发估算流程：从 KV 池倒推

并发估算四步：算 KV 池（显存 × 引擎比例 − 权重 − 工作区预留）、算单序列 KV、相除得上限、再用 P95 长度保守重算；理论值再按折算系数落地。

TTFT：首 token 延迟拆解

TTFT = 排队时间 + 输入 prefill + 首个解码步：输入越长 prefill 越重，队列越深等待越久；它是交互体验的首要指标，也很容易被排队拖垮。

每 token KV 心算算例

把公式压成「每 token 大小」做心算：拿到层数、KV 头数与头维度后一次算出量级，再乘窗口与并发；fp8 KV 直接减半。

张量并行：单卡装不下的标准解法

把每层权重与计算切到多卡：每卡只需驻留约 1/TP 的权重与对应 KV；vLLM 用 --tensor-parallel-size 指定，是「单卡装不下」场景的常规扩展方式。

TPOT：每输出 token 的时间

TPOT 是解码阶段平均步时：受显存带宽、批大小与算子效率影响；与 TTFT 组合能还原用户感知的总时长（流式场景主要看生成速率）。

窗口与并发：同一预算的两种花法

窗口与并发共享同一份 KV 预算：总量固定时窗口翻倍、并发约减半；max-model-len 的选择本质是「长文能力」与「同时服务量」的业务取舍。

vllm bench serve：服务端压测

vLLM 自带基准：vllm bench serve 对 OpenAI 兼容端点发压，输出吞吐与延迟分位，支持控制请求数与到达速率，是容量标定的起点工具。

gpu-memory-utilization：显存用量比例

vLLM 的 --gpu-memory-utilization 控制引擎对单卡显存的用量比例（默认 0.9）：比例越高 KV 池越大、并发上限越高，留给同卡其他进程的余量越小。

容量规划：从业务指标到卡数

容量规划链条：业务 QPS 与长度画像 → 换算总 token 吞吐 → 用单实例实测吞吐折算 → 得实例数与卡数 → 叠加冗余与峰谷系数。

max-num-seqs：在批序列数上限

限制同一时刻在批的序列数：调大提高吞吐上限但可能拉长排队，调小降低尾延迟与峰值压力；与 KV 池容量联动，是并发策略的主拨杆。

批大小与吞吐曲线：找饱和点

批大小与吞吐是曲线关系：小批近似线性、大批进入饱和，同时 KV 压力与抢占开始出现；工程上找饱和点比一味加大参数有效。

起步配置算例：8B 模型 24G 卡

一个可抄的起步组合：8B 模型在 24G 卡上按利用率 0.9、窗口 8K、批上限 128 起步，然后用启动日志与压测微调，不追求一次到位。

显存曲线：峰值出现在哪个阶段

显存峰值可能出现在三个阶段：模型加载（含精度转换缓冲）、大输入 prefill、并发爬坡后的 KV 高位；估算与排查都按阶段看曲线。

按长度分布做容量表

估算用的「长度」不是单点：输入与输出分布不同、P50 与 P95 常差数倍；按业务分档做容量表比一个平均数更接近真实表现。

延迟与吞吐：方向先定再调参

两个目标此消彼长：批越大吞吐越高、单请求延迟越差；先定服务定位——交互产品守 P95 延迟，离线任务压单 token 成本，调参才有方向。

选型算例：8B 与 70B 两档

两个常见体量的起点算例：8B 级单卡可承载、70B 级需要多卡切分；先按权重定卡数，再按 KV 定窗口与并发，最后压测定参数。

激活与工作区：不可忽略的第三块

推理同样需要临时缓冲：算子工作区、中间张量、多卡通信缓冲、CUDA Graph 捕获占位等；随批次与后端实现变化，引擎通常按比例预留。

量化收益的正确预期

量化省的是权重一栏：4 位权重把权重降到约 1/4，但 KV、激活与工作区不随之缩小；总占用降幅由权重占比决定，长上下文场景降幅有限。

KV 降精度：减半的并发账

KV 用 fp8 存储时字节数减半：等效于同一 KV 池下并发翻倍或窗口翻倍；vLLM 用 kv-cache-dtype 启用，需硬件与版本支持，质量影响需评测验证。

TP 大小怎么选：三步决策

选 TP 三步走：先按单卡显存定「可启动的 TP 下限」，再按互联条件定「实际可用的 TP 上限」，最后用压测比较吞吐与 TPOT，而不是只求能启动。

吞吐口径：把账算对

吞吐口径必须先定义：输出 tokens/s、总 tokens/s 还是 req/s；对外承诺与容量规划用同一口径，否则网关与引擎的数字永远对不上。

上线前 OOM 检查表

上线前逐项列账：权重（按精度与 TP 折减）、KV（按 P95 长度 × 目标并发）、工作区预留、同卡其它进程、加载阶段内存与磁盘、以及启动日志的 KV 容量核对。

估算余量：理论值到落地值

落地留余量：块粒度、碎片、监控与异构进程都会消耗显存；把理论并发按 70%~80% 折算评估，并给突发批次保留小额余量。

流水并行：按层分段跨卡

把不同层段放到不同卡（或节点）：通信量小于 TP，适合跨机扩展；代价是流水气泡，需要足够批次填充才能打满算力。

压测数据：随机与真实脱敏

压测数据决定结论可信度：vllm bench 支持随机长度生成与 ShareGPT 类数据集；随机数据便于跨配置对比，真实脱敏数据更贴近生产画像。

估算与实测闭环

用三份数据互相校准：启动日志的 KV 容量与并发估计、运行期 nvidia-smi 水位、公式计算值；偏差超出预期就回查系数（KV 头数、精度、长度口径）并更新容量表。

TP 与 PP 取舍对照

并行策略的取舍在通信与切法：TP 逐层切分、通信频繁但负载均衡；PP 按层段切分、通信较少但有流水气泡；实践常见「机内 TP + 跨机 PP」组合。

vllm bench latency：单请求延迟标定

固定形状请求的端到端延迟测试：vllm bench latency 按输入/输出长度与批大小逐档测单流时间，用于建立 TPOT 基线与退化曲线。

主机内存需求：别只盯显存

主机内存常被低估：模型加载缓冲（分片拼接/格式转换）、页缓存、swap-space 预留都吃内存；加载阶段的 OOM-killer 常被误读为模型问题。

genai-perf：跨引擎压测工具

NVIDIA genai-perf 面向生成式服务压测：对 OpenAI 兼容端点输出吞吐、TTFT 与逐 token 延迟分位，支持并发与合成输入输出长度配置，便于跨引擎对比。

长稳观察：显存漂移与延迟漂移

在目标并发下持续跑数小时：观察显存水位、P95 延迟与吞吐是否漂移；碎片与缓存行为随时间显现，短时压测覆盖不到。

磁盘与下载空间的估算

磁盘容量按权重文件同算法估算（参数 × 精度字节），另加 tokenizer、配置与日志；下载与转换阶段需要临时空间，预留倍量更稳。

单卡多实例：先做减法再分配

同卡跑多个实例时先切分总量：每实例显存上限 ÷ n，再各自扣权重与 KV；各实例 gpu-memory-utilization 之和要小于 1。

推测解码的显存附加账

推测解码要额外装草稿模型与它自己的 KV 缓存：草稿越小开销越低，收益与接受率挂钩；估算时当作主模型预算之外的独立小账。

专家并行：MoE 的额外切法

MoE 模型可用专家并行把不同专家分布到不同卡：降低单卡权重驻留，与 TP 组合使用；vLLM 提供 expert parallel 开关，支持范围以版本文档为准。

多模态模型显存：加上视觉侧账目

多模态模型还要算视觉开销：编码器权重与激活、图像 token 化后进入上下文的 KV、预处理缓冲；图 token 随分辨率增长，按「等效文本 token」折算。

MIG 切片的显存预算

MIG 按档位给固定显存与算力：预算直接按切片规格算（如 1g.10gb 量级的档位），不共享整卡 KV 池；隔离性好但弹性差。

服务化与网关

兼容 API、鉴权限流与多实例负载

OpenAI 兼容接口总览

自托管引擎普遍提供 OpenAI 兼容接口：/v1/chat/completions、/v1/completions、/v1/embeddings、/v1/models 等；客户端只换 base_url 与 key，生态工具可直接复用。

chat/completions：请求结构要点

主端点围绕 messages 数组：role（system/user/assistant/tool）与 content 是必填骨架；采样参数、stream、tools 都是同级字段，服务端按模型模板渲染。

Nginx 反代 SSE：流式不缓冲

流式接口经 Nginx 常见坑是响应被缓冲：需要关闭 proxy_buffering、使用 HTTP/1.1、放宽读超时，并把到上游的连接头清空以复用长连接。

API Key 鉴权：引擎与网关两层

鉴权有引擎自带与网关统一两层：vLLM 用 --api-key（或环境变量）开启 Bearer 校验；生产建议网关统一鉴权，引擎只监听内网。

超时链：逐层对齐

超时要分层对齐：客户端超时 ≥ 网关读超时 ≥ 引擎单请求最长生成时间；任何一层偏短，长输出都会在中途被切断，且各层表现不同。

模型列表与健康探针

/v1/models 返回可用模型；健康检查用专门的活探针端点（如 vLLM 的 /health）：前者走业务与鉴权流程，不适合做高频探活。

finish_reason：结束原因的处理

响应里的 finish_reason 说明生成终止原因：stop（正常或命中停止串）、length（达到上限被截断）、tool_calls（转为工具调用）等；网关与前端按它决定后续动作。

TLS 终结：证书放网关

TLS 在网关终结：证书与握手都在 Nginx 等反代上完成，后端引擎内网明文通信；对外域名用受信 CA 证书，内部链路按威胁模型决定是否再加一层。

背压：429/503 与重试语义

过载要返回明确信号而不是无限排队：限流/过载用 429（可带 Retry-After 提示退避），实例不可用用 503；客户端据此退避或换实例。

LiteLLM Proxy：多后端统一入口

LiteLLM Proxy 提供统一 OpenAI 兼容入口：一个 YAML 把多个上游（自托管引擎、云 API）映射为模型别名，附带密钥与配额管理、负载均衡与日志钩子。

多实例负载均衡：upstream 配置

把请求分发到多个引擎实例：Nginx upstream 声明实例列表并配 keepalive；短请求轮询即可，长连接流式场景关注连接分布而不是单次请求均衡。

限流：Nginx 令牌桶入门

限流在用 GPU 之前先挡住异常流量：Nginx limit_req 按 IP 或 key 做令牌桶限速；网关应用层再做租户级配额与并发控制，两级配合。

客户端重试：范围与预算

重试只针对可重试错误（429/502/503 与连接失败），用指数退避；重试总次数与总时长都要设预算，避免放大故障；流式中断重试要防重复输出。

配额与计量：按 key 对账

配额按 token 而不是请求数：记录 usage 的输入/输出 token 并聚合到 key/租户维度；接近上限预警、超额拒绝，数据同时作为成本分摊依据。

并发限制：在途请求数上闸

并发限制控制同时在途的请求数：Nginx limit_conn 按连接数上闸，应用网关用信号量/队列上限；它约束的是「同时干多少活」，与速率限流互补。

客户端 SDK 接入三件事

接入自托管服务只需三处：base_url 指向网关、api_key 用下发的密钥、timeout 按最长输出设置；再确认 SDK 版本对参数的支持范围。

按模型名路由到不同实例组

网关读取请求里的 model 字段，把流量路由到对应实例组：不同模型、不同量化或不同版本各自成组，对外保持一个统一入口与模型别名表。

灰度发布：按流量比例切分

新版本先接一小部分流量：Nginx split_clients 按客户端特征做权重切分，把 10% 流量导向新实例组；指标达标后再逐步放量到全量。

上游探活与被动摘除

双机制配合：被动摘除（max_fails/fail_timeout 按真实请求失败计数）加上轻量主动探针；探针端点选 /health 类，避免触发推理。

网关日志：元数据与内容分级

日志分两级：元数据（请求 ID、模型、token 用量、延迟、状态码）默认记录；对话内容默认不落盘，需要排查时临时开启并配套脱敏与留存策略。

请求 ID：串起全链路日志

网关生成或透传唯一请求 ID，写入转发头与响应头：排障时用它在网关、引擎与业务日志之间串时间线，用户报障也能直接检索。

版本锁定：权重 revision 与接口双固定

双固定：权重按 revision/commit 锁定下载，接口层把别名映射到具体版本；避免远端更新或本地升级让服务行为悄然变化。

密钥分发网关（one-api 类）

one-api 类网关把多个上游渠道聚合成统一入口：对外发放 key、按令牌计额度、按分组路由渠道；常用于团队内多项目共享一套模型资源。

回滚预案：三件套快照

回滚的前提是留痕：每次发布记录「权重版本 + 启动命令 + 路由配置」三件套快照；回滚即切回旧实例组或按快照重启旧配置。

到上游的连接复用

网关到引擎启用连接复用：upstream 配 keepalive 并清空 Connection 头，减少每次请求的连接建立开销，高 QPS 下对尾延迟有实际收益。

响应缓存与语义缓存

对确定性或高重复场景加缓存：缓存键由模型、消息、采样参数与模板版本哈希而成；语义缓存用向量相似度放宽匹配，收益更高但口径要收紧。

Nginx 配置骨架：一页可抄

完整站点骨架：先建 upstream 与限流区，再在 location 里组合 SSE 不缓冲、超时、请求 ID 与鉴权；逐项替换占位符后先校验再 reload。

SSE 心跳：防中间设备断流

长生成期间链路可能被判空闲而断开：周期发送 SSE 注释行做心跳，并把各层 idle 超时设得大于心跳间隔；客户端需能忽略注释行。

模型别名：对外稳定内部可换

对外只暴露稳定别名（如 llm-chat），网关把别名映射到具体后端与版本；换模型、换量化、换实例组都只改映射表，客户端不动。

数据边界：监听地址与最小化

从监听地址开始收边界：引擎只监听环回/内网，公网入口仅在网关；请求内容最小化与敏感字段替换、日志分级留存，具体合规口径按本单位制度执行。

网关高可用：别让网关成单点

网关按无状态服务部署：两副本起步 + 前置负载均衡/虚拟 IP，配额计数与配置放外部存储；任一副本可随时重启替换。

同机连接：Unix domain socket

网关与引擎同机时可用 Unix socket 替代 TCP 环回：省去少量网络栈开销，且天然不出主机；Nginx upstream 支持 unix 套接字，引擎侧支持情况以版本文档为准。

浏览器直连：CORS 配置要点

浏览器场景要处理 CORS 预检：网关按来源白名单回 Allow-Origin/Allow-Headers，OPTIONS 预检直接返回 204；密钥放前端的方案风险高，优先后端代理。

网关容量：按常驻连接估算

网关容量按常驻连接而非 QPS 估：流式长连接下，连接数 ≈ 最长生成时长 × 并发；核对文件描述符上限、worker 连接数与上游 keepalive 数。

运维监控与排障

延迟指标、OOM 排查与稳定性保障

‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌‌