LMDeploy 2026 前沿大模型部署手册

00导读

LMDeploy 的定位

LMDeploy 是上海人工智能实验室（OpenMMLab 团队）开源的推理工具箱。它在 2026 年的处境比较特殊：

优势

双引擎：TurboMind（C++/CUDA，极致性能）+ PyTorch（Python，易扩展、模型覆盖广）
INT8 KV Cache 做得早：TurboMind 很早就实现了 INT8 KV，在显存受限场景性价比高
--cp 上下文并行：解决了 num_key_value_heads < tp_size 时 KV 副本被复制的问题
国产硬件路径完整：Ascend、CAM、MACA 都有官方安装文档
接口兼容 Anthropic：api_server_anthropic 可以直接接 Claude Code

局限

前沿模型支持通常滞后于 vLLM / SGLang
TurboMind 对新架构（MLA、稀疏注意力、线性注意力）支持不如 PyTorch 引擎
社区规模与生态集成弱于前两家

选型建议：如果你要跑的是 Qwen / InternLM / Llama 系的标准 GQA 模型，且对显存极度敏感，LMDeploy 的 INT8 KV 值得考虑；如果要跑 2026 年的 1.6T MoE 旗舰，优先看 vLLM 或 SGLang。

数据基准

组件	基线
LMDeploy	0.18.0（2026-09-28）
Python	3.9+
CUDA	11.8+
ROCm	6.x / 7.x
昇腾	CANN 8.x（见 Ascend 安装页）

三个必须先建立的心智模型

① 两个引擎不是替代关系，是分工关系。

	TurboMind	PyTorch
语言	C++ / CUDA	Python
来源	基于 FasterTransformer 改造	原生 PyTorch + patched model
性能	更高（手写 kernel）	略低
模型覆盖	有限（需逐个适配）	广（直接支持 HF 架构）
新特性	滞后	领先（投机解码、CP 等先在这里）
前缀缓存	支持	支持
S-LoRA	不支持	支持

默认策略：TurboMind 优先，不支持时回退 PyTorch。可以手动指定。

② cache_max_entry_count 是显存闸门。

它的语义是「模型权重加载后，空闲显存的多少比例给 KV Cache」。默认 0.8。

这与 vLLM 的 gpu_memory_utilization 完全不同（后者是总显存比例）。理解错会差出一大截。

③ TurboMind 的 KV 管理是「内存池 + LRU」而非纯分页。

官方架构文档写得很清楚：TurboMind 的 KV 管理器是一个带 LRU 的内存池。当空间不足时，最久未使用的序列被驱逐，其显存被新序列直接复用。被驱逐的序列不会完全丢失——它被转成最紧凑的形式（token IDs），下次以同一 session id 请求时再解码回来。这就是「cache-hit / cache-miss」机制。

这带来一个独特的能力：从用户视角看，设备内存是「无限」的。代价是 cache-miss 时要重算。

012026 的部署格局

前沿模型与 LMDeploy 的适配现状

这是本文最需要诚实说明的部分。

2026 年的旗舰模型（DeepSeek-V4、Qwen3.5、Kimi-K3、GLM-5、MiniMax-M3）大量使用：

MLA（多头潜注意力）
稀疏注意力（DSA / MSA / CSA）
线性注意力混合（GDN / KDA）

LMDeploy 的官方文档与模型支持矩阵主要覆盖到 Qwen3 / InternLM / Llama / DeepSeek-V3 系。对于上述新架构：

模型族	TurboMind	PyTorch 引擎	建议
Qwen3 / Qwen3-MoE	部分支持	支持	可用
DeepSeek-V3 / R1（MLA）	支持（有专门优化）	支持	可用
Qwen3.5 / Qwen3.8（GDN）	未验证	需确认	建议先小规模验证
DeepSeek-V4（CSA/HCA）	未支持	未验证	不建议
GLM-5（MLA+DSA）	未支持	未验证	不建议
Kimi-K3（KDA）	未支持	未验证	不建议
MiniMax-M3（MSA）	未支持	未验证	不建议

诚实结论

如果你的目标是 2026 年的万亿级 MoE 旗舰，LMDeploy 不是合适的选择。它的价值在于中小规模模型的高性价比部署和国产硬件的完整路径。

LMDeploy 真正的优势场景

场景一：显存极度受限

INT8 KV Cache 是 TurboMind 的看家本领。官方文档的原话：

To maximize the throughput, we implement INT8 KV cache support to increase the max batch size. It's effective because in real-world serving scenarios, KV cache costs more memory and consumes more memory bandwidth than weights or other activations.

场景二：num_key_value_heads < tp_size

这是 LMDeploy 独有的 --cp 参数要解决的问题。详见 05 章。

场景三：国产硬件

Ascend（昇腾）、CAM（寒武纪）、MACA（摩尔线程）都有官方安装路径。

场景四：需要 Anthropic 兼容接口

api_server_anthropic 可以直接把 Claude Code 指向本地服务。

覆盖模型一览

模型	总参 / 激活	上下文	注意力	LMDeploy 状态
Qwen3-235B-A22B	235B / 22B	262,144	GQA	支持（含 CP 部署）
Qwen3-32B	32B	131,072	GQA	支持
InternLM / Intern-S1	多样	多样	GQA	支持
DeepSeek-V3 / R1	671B / 37B	128K	MLA	支持（TurboMind 有专门实现）
Llama-3.3-70B	70B	128K	GQA	支持
InternVL 系	多样	多样	—	支持（VLM）

02显存预算与 KV 计算

显存划分

CODE

┌────────────────────────────────────────────────────────┐
│  Weights  │        KV Cache Pool        │  Activations │
└────────────────────────────────────────────────────────┘
              └── cache_max_entry_count × 空闲显存 ──┘

公式：

CODE

KV_pool_bytes = (GPU_total − weights) × cache_max_entry_count

默认 0.8。官方明确警告：

The parameter "cache_max_entry_count" significantly influences the GPU memory usage. It means the proportion of FREE GPU memory occupied by the K/V cache after the model weights are loaded. The K/V cache memory is allocated once and reused repeatedly.

关键点：KV 显存是一次性预分配的。所以你会看到「刚启动就吃掉大量显存」——这是正常现象，不是泄漏。

OOM 的处理顺序

官方给的建议很直接：遇到 OOM 就降低 cache_max_entry_count。

完整顺序：

降 --cache-max-entry-count（0.8 → 0.6 → 0.5）
降 --session-len
降 --max-batch-size
开 INT8 KV：--quant-policy 4（TurboMind）
加 TP

KV Cache 计算

MHA / GQA / MQA（统一公式）

三种架构共用同一个公式，差异只在 n_kv_heads：

CODE

KV_bytes_per_token = 2 × n_layers × n_kv_heads × head_dim × dtype_bytes

架构	`n_kv_heads`	相对 MHA
MHA	`= n_heads`	1×
GQA	`= n_heads / g`	1/g
MQA	`= 1`	1/n_heads

GQA 不是「另一种算法」，而是把 KV head 数除以分组比 g。Llama-3-70B 是 64 q-heads / 8 kv-heads，KV 只有 MHA 的 1/8。

MLA（DeepSeek 系）

CODE

KV_bytes_per_token = n_layers × (kv_lora_rank + qk_rope_head_dim) × dtype_bytes

INT8 KV 的收益

TurboMind 的 INT8 KV 把每 token 从 2 bytes 降到 1 byte，容量直接翻倍。

例：Llama-3.3-70B，FP16 KV → INT8 KV

CODE

FP16: 2 × 80 × 8 × 128 × 2 = 327,680 B ≈ 320 KiB/token
INT8: 2 × 80 × 8 × 128 × 1 = 163,840 B ≈ 160 KiB/token

同样 100 GiB 预算：

FP16：约 327K token
INT8：约 655K token

代价

INT8 KV 会有轻微精度损失。官方文档没有给出具体的精度对比数据，建议在业务数据集上做 A/B 验证。

TurboMind 的 KV 池机制（重要）

这是 LMDeploy 与传统分页方案最大的差异，理解它才能理解行为。

CODE

KV Cache Manager
├── 预分配固定数量的 slot（按显存和序列长度算出）
├── 每个 slot 对应一条序列的 KV 空间
├── 分配 chunk-size 可配置（预分配 / 按需 / 折中）
└── 空间不足时：
    ├── 驱逐 LRU 序列
    ├── 被驱逐序列转成 token IDs（最紧凑形式）
    ├── 其显存被新序列直接复用
    └── 下次同一 session id 请求 → cache-miss → 重新解码 token IDs

cache-hit 的含义：请求的序列正好在某个 slot 里，历史 KV 直接返回，不需要重新 decode context。这是多轮对话的巨大优势。

cache-miss 的代价：序列被驱逐过，需要用 FMHA context decoder 重新把 token IDs 解码成 KV。

实践建议

多轮对话场景下，保持 session id 稳定能最大化 cache-hit。如果客户端每次生成新的 session id，这个机制就失效了。

03架构与参数作用点

TurboMind 架构

CODE

┌─────────────────────────────────────────┐
│  API（Python 接口 / OpenAI Server）       │
└───────────────┬─────────────────────────┘
                │ request / stream callback
                ▼
┌───────────────────────────┐   fetch    ┌──────────────────┐
│  Persistent Batch         │ ◄────────► │  KV Cache Manager │
│  （持续批处理）             │   update   │  （内存池 + LRU）  │
└───────────────┬───────────┘            └──────────────────┘
                ▼
┌─────────────────────────────────────────┐
│  LLaMA implementation                   │
│  · cutlass FMHA（支持 Q/K 长度不匹配）    │
│  · 间接 buffer 指针（支持 KV 不连续）      │
│  · INT8 KV Cache                        │
└───────────────┬─────────────────────────┘
                ▼
┌─────────────────────────────────────────┐
│  FT kernels & utilities                 │
└─────────────────────────────────────────┘

Persistent Batch 就是其他框架说的 continuous batching：

预配置 N 个 batch slot
有空位时请求加入
请求生成完毕，slot 释放可复用
cache-hit 时，历史 token 不需要每轮重新 decode
batch 自动增减，减少无用计算

PyTorch 引擎架构

CODE

┌─────────────────────────────────────────┐
│  EngineInstance（线程安全的发送端）        │
└───────────────┬─────────────────────────┘
                ▼
┌─────────────────────────────────────────┐
│  Engine                                 │
│  ├─ RequestManager  收发请求             │
│  ├─ Scheduler       序列管理 + 块分配     │
│  └─ ModelAgent      模型 + 缓存 + TP     │
│      ├─ patched_model  注入 TP/量化/kernel│
│      └─ cache_engine   host-device 换页  │
└─────────────────────────────────────────┘

调度循环：

CODE

① RequestManager 收新请求 → 缓存
② Scheduler 决定哪些请求参与本步 → 分配资源
③ ModelAgent 按 Scheduler 指令换缓存 → 前向
④ Scheduler 根据结果更新状态
⑤ RequestManager 回包 → 回到 ①

Scheduler 的分页：官方文档明确说「我们的 Scheduler 模块与 vLLM 的 paging 设计类似」——按序列长度分块分配，驱逐无用块，支持更大 batch 和更长 session。

一次请求的路径

CODE

① HTTP 接入      api_server（FastAPI）
                   ↓
② 输入处理       分词 → chat template
                   ↓  --chat-template
③ 调度           Persistent Batch / Scheduler
                   ↓  --max-batch-size
④ KV 分配        slot 查找 → cache-hit？→ 直接复用
                   ↓  --cache-max-entry-count
⑤ 前向           FMHA + TP 同步
                   ↓  --tp / --cp
⑥ 输出           反分词 → 流式
                   ↓  --session-len

04核心参数详解

4.1引擎选择

参数	值	说明
`--backend`	`turbomind` / `pytorch`	服务化时的引擎选择
`backend_config`	`TurbomindEngineConfig` / `PytorchEngineConfig`	Python API 的引擎配置

Python API 示例：

PYTHON

from lmdeploy import pipeline, TurbomindEngineConfig

pipe = pipeline('internlm/internlm2_5-7b-chat',
                backend_config=TurbomindEngineConfig(
                    max_batch_size=32,
                    enable_prefix_caching=True,
                    cache_max_entry_count=0.8,
                    session_len=8192,
                ))

不指定时，LMDeploy 自动按能力选择，TurboMind 优先。

4.2显存与批处理

参数	默认	含义与取舍
`--cache-max-entry-count`	0.8	空闲显存的多少给 KV 池。调低解决 OOM，调高提升并发
`--max-batch-size`	32	最大并发序列数
`--session-len`	模型默认	单序列最大长度（prompt + output）
`--tp`	1	张量并行度
`--cp`	1	上下文并行度（见 05 章）
`--max-prefill-token-num`	—	单次 prefill 的最大 token 数

4.3缓存

参数	默认	说明
`enable_prefix_caching` / `--enable-prefix-caching`	False（TurboMind）	前缀缓存
`--quant-policy`	0	TurboMind 专用：0 = 不量化；4 = INT8 KV Cache；8 = KV int8 + 权重 int8

--quant-policy 4 是 LMDeploy 最有价值的参数之一。它只量化 KV Cache，权重不动，所以精度损失可控，而显存直接翻倍。

4.4量化

参数	说明
`--model-format`	TurboMind：`hf` / `awq` / `gptq`
`--quant-policy`	见上
`--quantization`	PyTorch 引擎：在线量化方法

TurboMind 支持的量化：AWQ、GPTQ、INT8 KV、W8A8。

4.5推理与采样

参数	默认	说明
`--backend`	自动	引擎
`--server-port`	23333	默认端口不是 8000
`--model-name`	路径	对外暴露的模型名
`--chat-template`	自动	自定义对话模板
`--reasoning-parser`	—	推理内容解析（`api_server_reasoning`）
`--tool-call-parser`	—	工具调用（`api_server_tools`）
`--api-keys`	—	鉴权
`--enable-metrics`	关闭	Prometheus 指标

4.6投机解码

参数	说明
`--speculative-draft-model`	草稿模型路径
`--speculative-algorithm`	`eagle3` / `deepseek_mtp`
`--speculative-num-draft-tokens`	草稿 token 数

官方标注这是实验特性。

05并行策略选型

本引擎的推理拓扑与 KV 存放

为便于阅读，下图使用小规模设备组解释机制，不代表旗舰模型能装入这些设备。

此处只画有文档依据的 TP、TurboMind CP 和独立服务副本，不将其他引擎的 EP/attention-DP 配置移植过来。具体模型与 TurboMind/PyTorch 后端支持需分别确认。

LMDeploy · GQA 的 TP4 · 无需给稠密模型虚构共享专家或路由专家；MoE 适配按后端另核对。

LMDeploy · TurboMind TP4 + CP2 · 此图是交错缓存机制示意；官方具体模型例子为 --tp 8 --cp 2，不能照搬其他引擎的 DCP 参数。

LMDeploy · 独立服务副本 · 不是 attention-DP + MoE TP/EP；箭头不表示副本间通信。

官方依据：LMDeploy 并行与配置文档。图示策略存在不代表某个模型、精度、硬件组合已实测。

三种并行

CODE

TP  张量并行：层内切权重
CP  上下文并行：KV 交错存储到多个 rank（LMDeploy 特色）
DP  数据并行：多实例 + 前置负载均衡

`--cp` 解决什么问题（LMDeploy 最有价值的设计）

这是一个在其它框架里容易被忽略、但在实际部署中很痛的问题。

问题：当 num_key_value_heads < tp_size 时，KV head 无法均分到所有 TP rank。常规做法是复制 KV head 到多余的 rank 上。

代价（官方原文）：

可用的 KV cache 减半，降低最大支持的 session 长度
最大推理 batch size 降低，吞吐下降

LMDeploy 的解法：TurboMind 支持 attn_dp_size 避免复制 KV head，但这会引入数据不均衡。为了消除不均衡，TurboMind 实现了序列并行（sequence parallelism）——把 KV Cache 交错存储在不同的 cp_rank 上。

官方示例（cp_rank=2, prompt_len=5, generation_len=4）：

CODE

cp_rank0 存：token 0, 2, 4, 6, 8
cp_rank1 存：token 1, 3, 5, 7

实际用法：

BASH

# Intern-S1 / Qwen3-235B-A22B 的 num_key_value_heads = 4
# 想用 TP=8 但不想复制 KV head
lmdeploy serve api_server internlm/Intern-S1 --tp 8 --cp 2
lmdeploy serve api_server Qwen/Qwen3-235B-A22B --tp 8 --cp 2

约束

cp 必须能整除 tp。上面例子里 tp=8, cp=2，即每个 cp 组有 4 个 TP rank。

选型决策

CODE

模型能装进单卡？
├─ 是 → 单卡
└─ 否 → num_key_value_heads 能被 tp 整除？
        ├─ 能 → 直接 --tp N
        └─ 不能 → --tp N --cp M
                  （M 为 num_key_value_heads 的约数）

多实例 + 负载均衡

LMDeploy 的 DP 不走单进程多 rank，而是起多个实例 + 前置代理：

BASH

# 实例 1
lmdeploy serve api_server <model> --server-port 23333 --tp 2

# 实例 2
lmdeploy serve api_server <model> --server-port 23334 --tp 2

# 代理（官方提供 proxy_server）
lmdeploy serve proxy --server-port 8080 \
  --backend http://localhost:23333 \
  --backend http://localhost:23334

官方文档标题写的是「single LLM model across multiple GPUs on a single node」，多模型并行服务需要参考 Request Distribution Server 的指南。

06逐模型实战配置

6.1入门：InternLM / Qwen 小模型

BASH

# 安装
pip install lmdeploy

# 离线推理
python -c "
from lmdeploy import pipeline
pipe = pipeline('internlm/internlm2_5-7b-chat')
print(pipe(['Hi, introduce yourself', 'Shanghai is']))
"

# 服务化
lmdeploy serve api_server internlm/internlm2_5-7b-chat --server-port 23333

6.2Qwen3-235B-A22B（官方 CP 示例模型）

235B 总参 / 22B 激活，GQA，num_key_value_heads = 4。

BASH

# TP8 + CP2：避免 KV head 复制
lmdeploy serve api_server Qwen/Qwen3-235B-A22B \
  --tp 8 \
  --cp 2 \
  --cache-max-entry-count 0.85 \
  --session-len 131072 \
  --max-batch-size 64 \
  --enable-prefix-caching \
  --enable-metrics

参数解释：

参数	取值依据
`--tp 8`	235B 用 BF16 约 470 GB，8×80G 可装
`--cp 2`	KV head 只有 4 个，TP8 会导致 2 倍复制；CP2 消除复制
`--cache-max-entry-count 0.85`	追求吞吐；若 OOM 降到 0.7
`--session-len 131072`	模型原生上下文
`--max-batch-size 64`	大 MoE 模型的合理起点

6.3DeepSeek-V3 / R1

671B 总参 / 37B 激活，MLA。TurboMind 有专门的 MLA 实现。

BASH

# 8×H200，TP8
lmdeploy serve api_server deepseek-ai/DeepSeek-V3 \
  --backend turbomind \
  --tp 8 \
  --cache-max-entry-count 0.9 \
  --session-len 65536 \
  --max-batch-size 128 \
  --quant-policy 4 \
  --enable-prefix-caching

--quant-policy 4（INT8 KV）在 DeepSeek 这类 MLA 模型上收益尤其大，因为 MLA 的 KV 已经很紧凑，INT8 再翻倍后可以支撑更长的上下文。

MTP 投机解码（PyTorch 引擎）：

BASH

# 需要先装 FlashMLA
git clone https://github.com/deepseek-ai/FlashMLA.git flash-mla
cd flash-mla && git submodule update --init --recursive && pip install -v .

lmdeploy serve api_server deepseek-ai/DeepSeek-V3 \
  --backend pytorch \
  --tp 16 \
  --speculative-algorithm deepseek_mtp \
  --speculative-num-draft-tokens 3 \
  --max-batch-size 128 \
  --enable-metrics

6.4Llama-3.3-70B（标准 GQA 基线）

BASH

lmdeploy serve api_server meta-llama/Llama-3.3-70B-Instruct \
  --tp 4 \
  --cache-max-entry-count 0.85 \
  --session-len 131072 \
  --max-batch-size 128

+ INT8 KV：

BASH

lmdeploy serve api_server meta-llama/Llama-3.3-70B-Instruct \
  --tp 4 \
  --quant-policy 4 \
  --cache-max-entry-count 0.85 \
  --session-len 131072

6.5VLM：InternVL

PYTHON

from lmdeploy import pipeline, VisionConfig
from lmdeploy.vl import load_image

pipe = pipeline('OpenGVLab/InternVL2-8B',
                vision_config=VisionConfig(max_batch_size=8))

image = load_image('https://example.com/tiger.jpeg')
print(pipe(('describe this image', image)))

BASH

# 服务化
lmdeploy serve api_server OpenGVLab/InternVL2-8B --server-port 23333

重要提醒

LMDeploy 不包含上游 VLM 仓库的依赖。遇到 ImportError 说明需要手动安装对应 VLM 的依赖包。

vision_config.max_batch_size 越大，OOM 风险越高——因为 VLM 内部的 LLM 组件会预分配大量显存。

6.6接入 Claude Code（Anthropic 兼容）

LMDeploy 提供 api_server_anthropic：

BASH

lmdeploy serve api_server <model> \
  --server-port 23333 \
  --backend pytorch \
  --tp 4

然后：

BASH

ANTHROPIC_BASE_URL=http://localhost:23333 \
ANTHROPIC_API_KEY=dummy \
ANTHROPIC_AUTH_TOKEN=dummy \
claude

具体端点路径与模型名映射请以 api_server_anthropic 文档为准。

6.7配置速查

场景	引擎	TP	CP	关键参数
小模型单卡	自动	1	1	`--cache-max-entry-count 0.8`
70B 标准 GQA	TurboMind	4	1	`--session-len 131072`
235B（KV head 少）	TurboMind	8	2	`--cp 2`
DeepSeek-V3	TurboMind	8	1	`--quant-policy 4`
DeepSeek-V3 + MTP	PyTorch	16	1	`--speculative-algorithm deepseek_mtp`
显存紧张	TurboMind	—	—	`--quant-policy 4` + 降 `cache-max-entry-count`
多轮对话	任意	—	—	`--enable-prefix-caching` + 稳定 session id

07调优方法论

先定义指标

指标	定义
TTFT	首 token 时间
TPOT / ITL	每输出 token 时间
RPS	每秒请求数
tokens/s	总吞吐

LMDeploy 的 benchmark 工具有独立的文档页（benchmark/benchmark.html），支持多种数据集。

调优顺序

第一步：确定引擎

模型在 TurboMind 支持列表里 → 用 TurboMind（性能更好）
不在 → PyTorch
需要投机解码 / CP / 新特性 → 先查 PyTorch 引擎

第二步：调 cache-max-entry-count

观察点：

KV 池够大时，max-batch-size 能跑满
频繁 cache-miss + 重算 → 池太小
OOM → 池太大

第三步：考虑 INT8 KV

如果瓶颈是「显存不够导致并发上不去」，--quant-policy 4 是最直接的手段（容量翻倍）。先在小流量下验证精度。

第四步：调 batch 与 session 长度

max-batch-size 提升吞吐但增加 ITL
session-len 直接决定单请求能跑多长，设大了会浪费 KV 池

第五步：并行

num_kv_heads < tp → 加 --cp

按场景的配方

场景	配置	理由
低延迟对话	`--max-batch-size 8`<br>`--cache-max-entry-count 0.7`	小 batch 降 ITL
高吞吐批处理	`--max-batch-size 256`<br>`--cache-max-entry-count 0.9`	大 batch 摊薄开销
长上下文	`--session-len 131072`<br>`--quant-policy 4`	INT8 KV 支撑更长序列
多轮对话	`--enable-prefix-caching`<br>稳定 session id	TurboMind 的 cache-hit 机制
显存受限	`--quant-policy 4`<br>`--cache-max-entry-count 0.6`	双管齐下

压测

BASH

# 参考官方 benchmark 文档
python benchmark/profile_gpu_utilization.py ...

LMDeploy 的 benchmark 工具参数较多，建议直接查阅 benchmark/benchmark.html。

08生产化与排错

8.1容器

BASH

docker run --runtime nvidia --gpus all \
  -v ~/.cache/huggingface:/root/.cache/huggingface \
  --env "HUGGING_FACE_HUB_TOKEN=<secret>" \
  -p 23333:23333 \
  --ipc=host \
  openmmlab/lmdeploy:latest \
  lmdeploy serve api_server internlm/internlm2_5-7b-chat

8.2Kubernetes

官方提供了 k8s/deployment.yaml 和 k8s/service.yaml：

BASH

sed 's/{{HUGGING_FACE_HUB_TOKEN}}/<your token>/' k8s/deployment.yaml | kubectl create -f - \
  && kubectl create -f k8s/service.yaml

示例用 hostPath 挂载模型。多副本时需要换成共享存储 + PersistentVolume。

8.3端点

端点	说明
`/v1/chat/completions`	对话
`/v1/completions`	补全
`/v1/models`	模型列表
`/openapi.json`	OpenAPI 规范（可用 openapi-generator 生成客户端）
`/metrics`	Prometheus（需 `--enable-metrics`）

默认端口 23333。

8.4故障排查

现象	原因	处理
启动 OOM	`cache-max-entry-count` 太高	降到 0.6 或 0.5
运行中 OOM	batch 太大	降 `--max-batch-size`
VLM `ImportError`	缺上游依赖	手动安装对应 VLM 的依赖
VLM OOM	vision batch 太大	降 `VisionConfig.max_batch_size`
长序列跑不动	KV 池不够	`--quant-policy 4` + 降 `--session-len`
多轮对话慢	cache-miss 频繁	保持 session id 稳定；提高 `cache-max-entry-count`
TP 后 KV 容量反而变小	KV head 被复制	加 `--cp`
模型不支持	TurboMind 未适配	改 `--backend pytorch`

8.5安全

默认无鉴权：用 --api-keys
api_server 暴露了 Swagger UI（根路径），生产环境建议关闭或加网关
VLM 支持通过 URL 加载图片，注意 SSRF

09附录

A. 参数速查

参数	一句话
`--backend`	`turbomind` / `pytorch`
`--tp`	张量并行度
`--cp`	上下文并行度（解决 KV head 复制）
`--cache-max-entry-count`	空闲显存的多少给 KV 池
`--max-batch-size`	最大并发序列数
`--session-len`	单序列最大长度
`--quant-policy`	TurboMind 量化策略：0 / 4 / 8
`--model-format`	`hf` / `awq` / `gptq`
`--enable-prefix-caching`	前缀缓存
`--max-prefill-token-num`	单次 prefill token 上限
`--server-port`	服务端口（默认 23333）
`--speculative-algorithm`	`eagle3` / `deepseek_mtp`
`--speculative-num-draft-tokens`	草稿 token 数
`--enable-metrics`	Prometheus 指标

B. Python API 对照

PYTHON

from lmdeploy import pipeline, TurbomindEngineConfig, PytorchEngineConfig
from lmdeploy import GenerationConfig, VisionConfig
from lmdeploy.messages import SpeculativeConfig

# 引擎配置
cfg = TurbomindEngineConfig(
    max_batch_size=32,
    enable_prefix_caching=True,
    cache_max_entry_count=0.8,
    session_len=8192,
    tp=4,
    cp=1,
    quant_policy=4,
)

# 生成配置
gen = GenerationConfig(
    max_new_tokens=1024,
    top_p=0.8,
    top_k=40,
    temperature=0.6,   # 0.0 或 top_k=1 表示贪心
)

pipe = pipeline('model_path', backend_config=cfg)
print(pipe(['prompt1', 'prompt2'], gen_config=gen))

C. 来源

来源	用途
lmdeploy.readthedocs.io/en/latest/get_started	安装与快速开始
lmdeploy.readthedocs.io/en/latest/inference/turbomind	TurboMind 架构与 KV 机制
lmdeploy.readthedocs.io/en/latest/inference/pytorch	PyTorch 引擎设计
lmdeploy.readthedocs.io/en/latest/advance/context_parallel	CP 原理与用法
lmdeploy.readthedocs.io/en/latest/advance/spec_decoding	投机解码
lmdeploy.readthedocs.io/en/latest/llm/api_server	服务化
pypi.org/project/lmdeploy	版本核验

本文档基于 2026-11-06 可获取的公开资料整理。LMDeploy 对 2026 年前沿架构（MLA 之外的稀疏/线性注意力）的支持状态需要以官方模型支持矩阵的最新版本为准，本文中的"未验证"判断建议在目标环境实测确认。

00导读

LMDeploy 的定位

数据基准

三个必须先建立的心智模型

012026 的部署格局

前沿模型与 LMDeploy 的适配现状

LMDeploy 真正的优势场景

覆盖模型一览

02显存预算与 KV 计算

显存划分

OOM 的处理顺序

KV Cache 计算

MHA / GQA / MQA（统一公式）

MLA（DeepSeek 系）

INT8 KV 的收益

TurboMind 的 KV 池机制（重要）

03架构与参数作用点

TurboMind 架构

PyTorch 引擎架构

一次请求的路径

04核心参数详解

4.1引擎选择

4.2显存与批处理

4.3缓存

4.4量化

4.5推理与采样

4.6投机解码

05并行策略选型

本引擎的推理拓扑与 KV 存放

三种并行

--cp 解决什么问题（LMDeploy 最有价值的设计）

选型决策

多实例 + 负载均衡

06逐模型实战配置

6.1入门：InternLM / Qwen 小模型

6.2Qwen3-235B-A22B（官方 CP 示例模型）

6.3DeepSeek-V3 / R1

6.4Llama-3.3-70B（标准 GQA 基线）

6.5VLM：InternVL

6.6接入 Claude Code（Anthropic 兼容）

6.7配置速查

07调优方法论

先定义指标

调优顺序

按场景的配方

压测

08生产化与排错

8.1容器

8.2Kubernetes

8.3端点

8.4故障排查

8.5安全

09附录

A. 参数速查

B. Python API 对照

C. 来源

`--cp` 解决什么问题（LMDeploy 最有价值的设计）