# LMDeploy **上海人工智能实验室 的 高效 大型模型 部署 工具包** — 面向生产的推理、量化与服务，支持连续批处理与页式注意力（PagedAttention）。 > 🏛️ 开发者 **OpenMMLab / 上海人工智能实验室** | Apache-2.0 许可证 | 4000+ GitHub 收藏 *** ## 什么是 LMDeploy？ LMDeploy 是一个用于在生产环境中压缩、部署和服务大型语言模型的综合工具包。由 OpenMMLab（MMDetection、MMSeg）背后的团队构建，将研究级的优化带入实际部署： * **TurboMind 引擎** — 具有 CUDA 优化的高性能 C++ 推理后端 * **PyTorch 引擎** — 基于 Python 的灵活引擎，具有广泛的模型兼容性 * **连续批处理** — 在并发请求间最大化 GPU 利用率 * **PagedAttention** — 高效的 KV 缓存管理（类似于 vLLM） * **4 位 / 8 位 量化** — 支持 AWQ 和 SmoothQuant * **视觉-语言 模型** — 支持 InternVL、LLaVA、Qwen-VL 与 vLLM 相比，LMDeploy 的 TurboMind 引擎在 Llama 3 8B、batch=32 时提供约 1.36× 更高的吞吐量，其 AWQ 量化也是一流的 — 并非事后补充。对于 VLM（尤其是 InternVL2），LMDeploy 是参考部署栈。 ### 为什么选择 LMDeploy？ | 功能 | LMDeploy | vLLM | TGI | | ---------------- | -------- | ---- | --- | | 连续批处理 | ✅ | ✅ | ✅ | | AWQ 量化 | ✅ | ✅ | ❌ | | 推测式解码 | ✅ | ✅ | ✅ | | 视觉-语言 | ✅ | 有限 | 有限 | | OpenAI API | ✅ | ✅ | ✅ | | TurboMind（自定义引擎） | ✅ | ❌ | ❌ | *** ## 在 Clore.ai 上快速开始 ### 第 1 步：选择 GPU 服务器 在 [clore.ai](https://clore.ai) 市场： * **最低要求：** NVIDIA GPU，8GB 显存（适用于 7B 模型） * **推荐：** RTX 3090/4090（24GB）或 A100（40/80GB） * **CUDA：** 需要 11.8 或 12.x ### 第 2 步：部署 LMDeploy Docker ``` Docker 镜像：openmmlab/lmdeploy ``` **端口映射：** | 容器端口 | 用途 | | ------- | ---------------- | | `22` | SSH 访问 | | `23333` | LMDeploy API 服务器 | **环境变量：** ``` HUGGING_FACE_HUB_TOKEN=your_hf_token_here # 用于受限模型 ``` ### 第 3 步：SSH 并验证 ```bash ssh root@ -p # 验证安装 python -c "import lmdeploy; print(lmdeploy.__version__)" lmdeploy --help ``` *** ## 启动 API 服务器 ### 兼容 OpenAI 的服务器（推荐） ```bash # 使用 TurboMind 引擎 服务 Llama 3 8B lmdeploy serve api_server \ meta-llama/Meta-Llama-3-8B-Instruct \ --server-port 23333 \ --server-name 0.0.0.0 \ --model-name llama3-8b # 指定引擎 lmdeploy serve api_server \ meta-llama/Meta-Llama-3-8B-Instruct \ --backend turbomind \ --server-port 23333 \ --server-name 0.0.0.0 \ --tp 1 \ --max-batch-size 128 \ --cache-max-entry-count 0.8 ``` ### PyTorch 引擎（更广的兼容性） ```bash # 对于 TurboMind 不支持的模型使用 PyTorch 引擎 lmdeploy serve api_server \ mistralai/Mistral-7B-Instruct-v0.2 \ --backend pytorch \ --server-port 23333 \ --server-name 0.0.0.0 ``` ### 服务器启动输出 ``` [2024-01-01 12:00:00,000] INFO: 加载模型: meta-llama/Meta-Llama-3-8B-Instruct [2024-01-01 12:00:20,000] INFO: TurboMind 引擎 已初始化 [2024-01-01 12:00:20,000] INFO: 服务器已在 http://0.0.0.0:23333 启动 [2024-01-01 12:00:20,000] INFO: API 文档: http://0.0.0.0:23333/docs ``` {% hint style="success" %} 启动后，LMDeploy 在以下地址暴露交互式 API 文档： `http://:23333/docs` — 方便直接从浏览器测试端点。 {% endhint %} *** ## 支持的模型 ### 文本模型 ```bash # Llama 3 meta-llama/Meta-Llama-3-8B-Instruct meta-llama/Meta-Llama-3-70B-Instruct # Mistral / Mixtral mistralai/Mistral-7B-Instruct-v0.2 mistralai/Mixtral-8x7B-Instruct-v0.1 # Qwen Qwen/Qwen2-7B-Instruct Qwen/Qwen2-72B-Instruct # InternLM internlm/internlm2-chat-7b internlm/internlm2-chat-20b # Yi 01-ai/Yi-1.5-9B-Chat 01-ai/Yi-1.5-34B-Chat # Gemma google/gemma-7b-it google/gemma-2b-it ``` ### 视觉-语言 模型 ```bash # InternVL（推荐的 VLM） OpenGVLab/InternVL2-8B OpenGVLab/InternVL2-26B # LLaVA llava-hf/llava-1.5-7b-hf # Qwen-VL Qwen/Qwen-VL-Chat ``` *** ## 量化 ### AWQ 4 位 量化 LMDeploy 的 AWQ（感知激活的权重量化）在 4 位下能产生出色的质量： ```bash # 将模型量化为 AWQ 4 位 lmdeploy lite auto_awq \ meta-llama/Meta-Llama-3-8B-Instruct \ --calib-dataset ptb \ --calib-samples 128 \ --calib-seqlen 2048 \ --w-bits 4 \ --w-group-size 128 \ --work-dir ./quantized/llama3-8b-awq # 服务量化后的模型 lmdeploy serve api_server \ ./quantized/llama3-8b-awq \ --server-port 23333 \ --server-name 0.0.0.0 ``` ### SmoothQuant W8A8 8 位权重与激活量化（对吞吐量要求高的部署更佳）： ```bash lmdeploy lite smooth_quant \ meta-llama/Meta-Llama-3-8B-Instruct \ --work-dir ./quantized/llama3-8b-sq \ --calib-dataset ptb \ --calib-samples 512 ``` ### 量化影响 | 量化 | 显存（7B） | 质量损失 | 吞吐量增益 | | ---------------- | ------ | ---- | ----- | | 无（bf16） | ≈14GB | 无 | 基线 | | SmoothQuant W8A8 | ≈8GB | 极小 | +20% | | AWQ W4A16 | ≈4GB | 低 | +15% | | GPTQ W4A16 | ≈4GB | 低 | +10% | {% hint style="info" %} **AWQ 建议：** 对于大多数使用场景，AWQ 4 位在质量与显存节省之间提供最佳平衡。使用 `--w-group-size 128` 可在略高内存使用下获得更好的质量。 {% endhint %} *** ## API 使用示例 ### Python 客户端 ```python from openai import OpenAI client = OpenAI( base_url="http://:/v1", api_key="none" ) # 聊天补全 response = client.chat.completions.create( model="llama3-8b", messages=[ {"role": "system", "content": "You are a helpful assistant."}, {"role": "user", "content": "Summarize the history of AI in 3 sentences."} ], temperature=0.7, max_tokens=512 ) print(response.choices[0].message.content) ``` ### 流式传输 ```python stream = client.chat.completions.create( model="llama3-8b", messages=[{"role": "user", "content": "Write a poem about space."}], stream=True ) for chunk in stream: delta = chunk.choices[0].delta if delta.content: print(delta.content, end="", flush=True) print() ``` ### LMDeploy 原生 Python 客户端 ```python from lmdeploy import pipeline, TurbomindEngineConfig # 直接管道（无需服务器） pipe = pipeline( 'meta-llama/Meta-Llama-3-8B-Instruct', backend_config=TurbomindEngineConfig(max_batch_size=16) ) # 单次推理 response = pipe("What is the capital of France?") print(response.text) # 批量推理 responses = pipe([ "Explain gravity", "What is DNA?", "How does Bitcoin work?" ]) for r in responses: print(r.text) print("---") ``` ### 视觉-语言 模型 ```python from lmdeploy import pipeline from lmdeploy.vl import load_image pipe = pipeline('OpenGVLab/InternVL2-8B') image = load_image('https://example.com/photo.jpg') response = pipe(('Describe this image in detail', image)) print(response.text) ``` *** ## 多 GPU 部署 ### 张量并行 ```bash # 在 4 个 GPU 上分布一个 70B 模型 lmdeploy serve api_server \ meta-llama/Meta-Llama-3-70B-Instruct \ --backend turbomind \ --server-port 23333 \ --server-name 0.0.0.0 \ --tp 4 \ --max-batch-size 64 ``` ```python from lmdeploy import pipeline, TurbomindEngineConfig pipe = pipeline( 'meta-llama/Meta-Llama-3-70B-Instruct', backend_config=TurbomindEngineConfig(tp=4) ) ``` *** ## 高级配置 ### TurboMind 引擎 配置 ```python from lmdeploy import pipeline, TurbomindEngineConfig engine_config = TurbomindEngineConfig( max_batch_size=64, # 最大并发请求数 cache_max_entry_count=0.8, # KV 缓存比例（0.0-1.0） quant_policy=0, # 0=不量化, 4=4 位 KV 缓存, 8=8 位 KV 缓存 rope_scaling_factor=1.0, # 用于扩展上下文 num_tokens_per_iter=4096, # 预填充分块大小 max_prefill_token_num=8192, # 最大预填充长度 ) pipe = pipeline('meta-llama/Meta-Llama-3-8B-Instruct', backend_config=engine_config) ``` ### 生成配置 ```python from lmdeploy import GenerationConfig gen_config = GenerationConfig( temperature=0.7, top_p=0.9, top_k=40, repetition_penalty=1.1, max_new_tokens=1024, stop_words=['<|eot_id|>', '<|end_of_text|>'], ) response = pipe("Hello, world!", gen_config=gen_config) ``` *** ## 监控与指标 ### 检查服务器健康状态 ```bash # 健康检查端点 curl http://localhost:23333/health # 列出可用模型 curl http://localhost:23333/v1/models # 服务器统计信息 curl http://localhost:23333/stats ``` ### GPU 监控 ```bash # 实时 GPU 状态 watch -n 1 'nvidia-smi --query-gpu=name,memory.used,memory.free,utilization.gpu --format=csv' ``` *** ## Docker Compose 示例 ```yaml version: '3.8' services: lmdeploy: image: openmmlab/lmdeploy:latest runtime: nvidia environment: - NVIDIA_VISIBLE_DEVICES=all - HUGGING_FACE_HUB_TOKEN=${HF_TOKEN} ports: - "23333:23333" - "22:22" volumes: - hf-cache:/root/.cache/huggingface - ./models:/models command: > lmdeploy serve api_server meta-llama/Meta-Llama-3-8B-Instruct --server-port 23333 --server-name 0.0.0.0 --model-name llama3-8b --max-batch-size 64 restart: unless-stopped shm_size: '2g' volumes: hf-cache: ``` *** ## 基准测试 ```bash # 内置基准工具 lmdeploy benchmark \ meta-llama/Meta-Llama-3-8B-Instruct \ --backend turbomind \ --concurrency 1 4 8 16 32 \ --num-prompts 1000 \ --prompt-len 128 \ --output-len 256 ``` 示例输出（RTX 4090，TurboMind，bf16）： ``` 并发=1： 吞吐量=42.3 tokens/s，延迟 p50=23ms 并发=8： 吞吐量=287.1 tokens/s，延迟 p50=156ms 并发=32： 吞吐量=412.6 tokens/s，延迟 p50=621ms ``` 在 A100 80GB 上，由于 HBM2e 内存带宽（2 TB/s vs 1 TB/s），在高并发下预计吞吐量比 RTX 4090 高约 2.2×。 *** ## Clore.ai 的 GPU 建议 根据目标模型规模和服务负载进行选择： | 在 Clore.ai 上的预估费用 | GPU | 显存（VRAM） | 为什么 | | ------------------ | --------------------- | -------- | --------------------------------------------- | | 7–13B 模型，开发/预发布 环境 | **RTX 3090** | 24 GB | 最佳 $/显存 比；可处理 7B bf16 或 13B AWQ | | 7–13B 模型，生产环境 | **RTX 4090** | 24 GB | 在相同显存下比 3090 快约 40%；在 Llama 3 8B 上为 412 tok/s | | 70B 模型，团队服务 | **A100 40GB** | 40 GB | 适配 70B AWQ；使用 ECC 内存以提高可靠性 | | 70B 模型，高吞吐量 | **💡 本指南中的所有示例均可部署在** | 80 GB | 适配 70B bf16；在 batch=32 时吞吐量为 A100 40GB 的 2× | **预算推荐：** RTX 3090 + AWQ 4 位 — 在 batch=8 时可为 Llama 3 8B 提供约 280 tok/s，覆盖大多数 API 用例。 **速度首选：** RTX 4090 — 在 7–13B 模型上每美元性能最高；TurboMind 最大化利用其 1 TB/s 带宽的每 GB/s 性能。 **生产首选：** A100 80GB — 可在不牺牲量化质量的情况下以完整 bf16 运行 Qwen2-72B 或 Llama 3 70B；易于部署到多实例 GPU 服务中。 *** ## 故障排除 ### 模型无法加载 ```bash # 检查 HuggingFace token 是否设置 echo $HUGGING_FACE_HUB_TOKEN # 手动下载模型 pip install huggingface_hub huggingface-cli download meta-llama/Meta-Llama-3-8B-Instruct --local-dir ./llama3-8b # 使用本地路径替代 lmdeploy serve api_server ./llama3-8b --server-port 23333 ``` ### CUDA 内存不足（Out of Memory） ```bash # 减少 KV 缓存分配 lmdeploy serve api_server MODEL \ --cache-max-entry-count 0.5 # 从 0.8 降低 # 使用量化的 KV 缓存 lmdeploy serve api_server MODEL \ --quant-policy 8 # 8 位 KV 缓存 ``` ### 端口已被占用 ```bash # 检查哪个进程在使用端口 23333 ss -tlnp | grep 23333 fuser 23333/tcp # 杀掉已有进程 kill -9 $(fuser 23333/tcp) ``` {% hint style="warning" %} **Docker 网络模式：** 在 Docker 中运行时，确保容器使用 `--network host` 或正确的端口映射（`-p 23333:23333`）以便 API 可从外部访问。 {% endhint %} *** ## Clore.ai 的 GPU 建议 LMDeploy 的 TurboMind 引擎和 W4A16 量化在吞吐量方面表现卓越 — 尤其在 Ampere/Hopper GPU 上。 | GPU | 显存（VRAM） | Clore.ai 价格 | Llama 3 8B 吞吐量 | Llama 3 70B Q4 | | ----------------- | -------- | ----------- | ---------------- | ---------------- | | RTX 3090 | 24 GB | \~$0.12/小时 | ≈120 tok/s（fp16） | ❌ 太大 | | RTX 4090 | 24 GB | \~$0.70/小时 | ≈200 tok/s（fp16） | ❌ 太大 | | A100 40GB | 40 GB | \~$1.20/小时 | ≈160 tok/s（fp16） | ≈55 tok/s（W4A16） | | 💡 本指南中的所有示例均可部署在 | 80 GB | \~$2.00/小时 | ≈175 tok/s（fp16） | ≈80 tok/s（fp16） | | 2× RTX 4090 | 48 GB | ≈$1.40/小时 | ≈380 tok/s（张量并行） | ≈60 tok/s | {% hint style="info" %} **RTX 3090 约 $0.12/小时** 是 7B–13B 模型的首选。LMDeploy 的 TurboMind 引擎能从消费级 GPU 中挖掘出接近最大化的吞吐量。单张 RTX 3090 服务 Llama 3 8B 可处理 120 tok/s — 足以支持 10–20 并发用户的生产 API。 对于 70B 模型：A100 40GB（≈$1.20/小时）配合 W4A16 量化可提供约 55 tok/s — 比两张 RTX 4090 更具成本效益。 {% endhint %} *** ## 资源 * 📦 **Docker Hub：** [hub.docker.com/r/openmmlab/lmdeploy](https://hub.docker.com/r/openmmlab/lmdeploy) * 🐙 **GitHub：** [github.com/InternLM/lmdeploy](https://github.com/InternLM/lmdeploy) * 📚 **文档：** [lmdeploy.readthedocs.io](https://lmdeploy.readthedocs.io) * 💬 **Discord：** [discord.gg/xa29JuW84p](https://discord.gg/xa29JuW84p) * 🤗 **预先量化的模型：** [huggingface.co/lmdeploy](https://huggingface.co/lmdeploy)