# LMDeploy 2026 前沿大模型部署手册

> 版本基准：LMDeploy 0.18.0（2026-09-28）　·　文档核验：2026-11-06
> 参数与命令取自 lmdeploy.readthedocs.io 官方文档，架构说明取自 TurboMind / PyTorch 引擎设计文档。

---

## 目录

- [00 导读](#00-导读)
- [01 2026 的部署格局](#01-2026-的部署格局)
- [02 显存预算与 KV 计算](#02-显存预算与-kv-计算)
- [03 架构与参数作用点](#03-架构与参数作用点)
- [04 核心参数详解](#04-核心参数详解)
- [05 并行策略选型](#05-并行策略选型)
- [06 逐模型实战配置](#06-逐模型实战配置)
- [07 调优方法论](#07-调优方法论)
- [08 生产化与排错](#08-生产化与排错)
- [09 附录](#09-附录)

---

## 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 时要重算。

---

## 01 2026 的部署格局

### 前沿模型与 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 章](#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 计算

### 显存划分

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

公式：

```
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`**。

完整顺序：

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

### KV Cache 计算

#### MHA / GQA / MQA（统一公式）

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

```
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 系）

```
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

```
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 与传统分页方案最大的差异，理解它才能理解行为。

```
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 架构

```
┌─────────────────────────────────────────┐
│  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 引擎架构

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

**调度循环**：

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

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

### 一次请求的路径

```
① 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 章](#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 并行策略选型

<!-- engine-topologies:start -->
### 本引擎的推理拓扑与 KV 存放

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

#### LMDeploy · GQA 的 TP4

配置要点：`--tp 4；示例 KV head 数 = 8`（机制示例，须满足模型与硬件约束）。

![LMDeploy · GQA 的 TP4](assets/topologies/lmdeploy/topology-1.svg)

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

#### LMDeploy · TurboMind TP4 + CP2

配置要点：`--tp 4 --cp 2；机制示例 KV head 数 = 2`（机制示例，须满足模型与硬件约束）。

![LMDeploy · TurboMind TP4 + CP2](assets/topologies/lmdeploy/topology-2.svg)

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

#### LMDeploy · 独立服务副本

配置要点：`4 个独立 api_server + 外部请求路由`（机制示例，须满足模型与硬件约束）。

![LMDeploy · 独立服务副本](assets/topologies/lmdeploy/topology-3.svg)

不是 attention-DP + MoE TP/EP；箭头不表示副本间通信。

官方依据：[LMDeploy](https://lmdeploy.readthedocs.io/en/latest/advance/context_parallel.html)。
<!-- engine-topologies:end -->


### 三种并行

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

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

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

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

**代价**（官方原文）：

1. **可用的 KV cache 减半**，降低最大支持的 session 长度
2. **最大推理 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`）：

```
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。

### 选型决策

```
模型能装进单卡？
├─ 是 → 单卡
└─ 否 → 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.2 Qwen3-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.3 DeepSeek-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.4 Llama-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.5 VLM：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.2 Kubernetes

官方提供了 `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 之外的稀疏/线性注意力）的支持状态需要以官方模型支持矩阵的最新版本为准，本文中的"未验证"判断建议在目标环境实测确认。*