LMDeploy 离线推理 Pipeline 实战指南：从 Hello World 到 PPL 计算与多后端配置

人工智能大模型模型推理服务推理引擎本地部署模型量化【免费下载链接】lmdeployLMDeploy is a toolkit for compressing, deploying, and serving LLMs.项目地址https://gitcode.com/gh_mirrors/lm/lmdeploy点击查看免费下载LMDeploy 的pipeline是一套面向离线推理场景的 Python 高层 API它屏蔽了 TurboMind 与 PyTorch 两种后端、张量并行、KV cache 管理等底层细节让开发者可以用几行代码完成批量对话、流式生成、logits/hidden states 提取、困惑度PPL评估、LoRA 推理等任务。本篇以官方文档 docs/zh_cn/llm/pipeline.md 为骨架结合仓库源码逐例讲解 API 用法与参数语义帮助读者快速在自己的脚本中落地可复现的离线推理方案。1. 认识 Pipeline一次调用多请求批量推理pipeline的入口封装位于 lmdeploy/pipeline.pyPipeline类对外暴露的核心方法包括__call__等价于infer非流式批量推理stream_infer流式批量推理返回迭代器chat带 session 管理的多轮对话get_logits/get_ppl面向打分与评估场景的专用接口close显式释放资源也支持with语句自动释放。其内部会先通过autoget_backend_config见 lmdeploy/archs.py自动判断模型该走 TurboMind 还是 PyTorch 后端若模型不满足 TurboMind 的supported_models列表或 TurboMind 未被编译都会自动回退到 PyTorch 引擎。之后由get_task根据模型架构识别是纯文本 LLMAsyncEngine还是视觉语言模型VLAsyncEngine例如 InternVL、Qwen2.5-VL、Gemma3 等多模态架构会在 lmdeploy/archs.py#L84-L113 的check_vl_llm中被识别为 VLM 任务。1.1 Hello, world 示例from lmdeploy import pipeline pipe pipeline(internlm/internlm2_5-7b-chat) response pipe([Hi, pls intro yourself, Shanghai is]) print(response)几点说明pipeline的第一个参数可以是 Hugging Face 上的模型 ID也可以是本地模型目录。当传入的路径本地不存在时Pipeline.__init__会调用get_model自动下载权重见 lmdeploy/pipeline.py#L63-L67。传入的是一个字符串列表infer内部会将其统一转换为 OpenAI 风格的 messages 格式后再提交引擎见 lmdeploy/pipeline.py#L117-L119。单条 prompt 返回单个Response对象prompt 列表则返回Response列表。Response定义在 lmdeploy/messages.py#L666-L701包含text、generate_token_len、input_token_len、finish_reason、token_ids、logits、last_hidden_state等字段。1.2 更精细的批量控制infer的参数中gen_config既可以是一个GenerationConfig对所有请求生效也可以是与其长度一致的GenerationConfig列表逐请求定制use_tqdmTrue会显示进度条。这一点在Pipeline._request_generator中做了显式校验当gen_config列表长度与 prompt 数不一致时会抛出ValueError见 lmdeploy/pipeline.py#L363-L372。2. KV cache 显存占比理解cache_max_entry_count在 Hello, world 示例中pipeline 默认会为推理过程中产生的 KV cache 预留一定比例的显存比例由TurbomindEngineConfig.cache_max_entry_count控制。LMDeploy 在研发过程中这一策略发生过变更v0.2.0 lmdeploy v0.2.1默认比例为0.5表示占用GPU 总显存的 50% 用于 KV cache。对 7B 模型而言若显存小于 40G 很容易 OOM。遇到 OOM 时可按如下方式调低占比from lmdeploy import pipeline, TurbomindEngineConfig # 将 k/v cache 占比调整为总显存的 20% backend_config TurbomindEngineConfig(cache_max_entry_count0.2) pipe pipeline(internlm/internlm2_5-7b-chat, backend_configbackend_config) response pipe([Hi, pls intro yourself, Shanghai is]) print(response)lmdeploy v0.2.1当前版本分配策略改为从空闲显存中按比例为 KV cache 开辟空间默认值调整为0.8。若仍遇到 OOM按同样的方式减少比例值即可。从当前仓库源码可以确认这一行为在 lmdeploy/messages.py#L305-L314 的TurbomindEngineConfig文档注释中明确写道——cache_max_entry_count表示 KV cache 所占 GPU 内存比例v0.2.1 之后默认为0.8指空闲显存的比例当传入大于 0 的整数时它还可以被解释为 KV block 的总数量此时按 block 计数而不是按比例。PytorchEngineConfig同样持有该字段默认值也是0.8见 lmdeploy/messages.py#L555但它的取值范围被校验在0 cache_max_entry_count 1见 lmdeploy/messages.py#L608-L609即 PyTorch 后端只接受比例值。在 TurboMind 端该比例最终会换算为 KV block 数量传入 C 引擎ec.cache_max_block_count engine_config.cache_max_entry_count见 lmdeploy/turbomind/turbomind.py#L248。而 PyTorch 后端则在 executor 中按空闲显存计算可用 KV cache 大小available_mems [int((free_mem - runtime_cache_size) * cache_max_entry_count) ...]见 lmdeploy/pytorch/engine/executor/base.py#L222-L234可以看到它会先从空闲显存中扣除运行时缓存再乘比例。3. 多卡并行设置张量并行tpTurboMind 与 PyTorch 后端都支持张量并行tensor parallelism通过TurbomindEngineConfig(tp2)即可将模型切分到 2 张 GPU 上from lmdeploy import pipeline, TurbomindEngineConfig backend_config TurbomindEngineConfig(tp2) pipe pipeline(internlm/internlm2_5-7b-chat, backend_configbackend_config) response pipe([Hi, pls intro yourself, Shanghai is]) print(response)从源码看TurbomindEngineConfig的并行维度不仅限于tp还包括dp数据并行、cp上下文并行、ep专家并行以及attn_tp_size、mlp_tp_size、nnodes、node_rank、dist_init_addr等多机多卡相关字段见 lmdeploy/messages.py#L381-L395多机场景可配合dist_init_addr指定分布式初始化地址。PytorchEngineConfig也提供tp、dp、ep与distributed_executor_backend可选uni、mp、ray三种分布式执行后端见 lmdeploy/messages.py#L460-L546满足从单机多卡到多机 Ray 集群的部署需求。4. 采样参数GenerationConfig全面解析GenerationConfig在 lmdeploy/messages.py#L78-L201 中定义是控制生成行为的核心配置。文档示例from lmdeploy import pipeline, GenerationConfig, TurbomindEngineConfig backend_config TurbomindEngineConfig(tp2) gen_config GenerationConfig(top_p0.8, top_k40, temperature0.8, max_new_tokens1024) pipe pipeline(internlm/internlm2_5-7b-chat, backend_configbackend_config) response pipe([Hi, pls intro yourself, Shanghai is], gen_configgen_config) print(response)常用参数与默认值来自源码字段定义参数默认值说明max_new_tokens512单次生成的最大 token 数do_sampleFalse是否采样False时走贪心解码top_p1.0核采样概率质量取值范围[0, 1]top_k50候选 token 数须为非负整数min_p0.0最小概率阈值按最可能 token 概率缩放典型取值0.01~0.2temperature0.8采样温度取值范围[0, 2]repetition_penalty1.0重复惩罚大于 1 抑制重复ignore_eosFalse是否忽略 EOS tokenstop_words/stop_token_idsNone停止词 / 停止 token命中即终止生成且不计入输出bad_words/bad_token_idsNone禁止生成的词 / tokenmin_new_tokensNone最少生成的 token 数skip_special_tokensTrue解码时是否移除特殊 tokenrandom_seedNone采样随机种子用于可复现实验response_formatNone结构化输出支持json_schema、regex_schema、XGrammar 结构标签__post_init__中会对这些参数做合法性校验例如temperature必须在[0, 2]、top_p必须在[0, 1]见 lmdeploy/messages.py#L259-L273非法值会在构造时直接断言失败。stop_words/bad_words字符串会在推理前由 tokenizer 转换为 token id 并合并进stop_token_ids/bad_token_ids同时自动追加 tokenizer 的eos_token_id与模型 generation_config 中的 EOS id见 lmdeploy/messages.py#L219-L257。5. 使用 OpenAI 格式的 prompt除纯字符串外pipeline 原生支持 OpenAI 风格的 messages 列表便于携带role语义from lmdeploy import pipeline, GenerationConfig, TurbomindEngineConfig backend_config TurbomindEngineConfig(tp2) gen_config GenerationConfig(top_p0.8, top_k40, temperature0.8, max_new_tokens1024) pipe pipeline(internlm/internlm2_5-7b-chat, backend_configbackend_config) prompts [[{ role: user, content: Hi, pls intro yourself }], [{ role: user, content: Shanghai is }]] response pipe(prompts, gen_configgen_config) print(response)从实现上看MultimodalProcessor.format_prompts会统一将字符串、dict或 messages 嵌套列表规范化为标准格式之后引擎会依据模型对应的 chat template 把 messages 拼装为完整的 prompt见 lmdeploy/pipeline.py#L169-L177。这意味着你可以在同一个批次里混用不同形式的输入由 pipeline 负责归一化。6. 流式输出stream_infer将pipe(...)换成pipe.stream_infer(...)即可逐 token 获取结果from lmdeploy import pipeline, GenerationConfig, TurbomindEngineConfig backend_config TurbomindEngineConfig(tp2) gen_config GenerationConfig(top_p0.8, top_k40, temperature0.8, max_new_tokens1024) pipe pipeline(internlm/internlm2_5-7b-chat, backend_configbackend_config) prompts [[{ role: user, content: Hi, pls intro yourself }], [{ role: user, content: Shanghai is }]] for item in pipe.stream_infer(prompts, gen_configgen_config): print(item)流式模式下每次迭代产出一个Response对象。它的底层是异步事件循环驱动的Pipeline会启动一个后台_EventLoopThread运行 asyncio 事件循环请求在循环中经AsyncEngine.preprocess与AsyncEngine.generate处理结果通过Queue回传到同步调用方见 lmdeploy/pipeline.py#L384-L448因此对调用方来说是简单的同步迭代器。当某个请求发生RequestError时流中会返回一个finish_reasonerror且带error_code、error_message的Response方便业务层做容错处理见 lmdeploy/pipeline.py#L395-L416。7. 提取生成 token 的 logits 与最后一层 hidden statespipeline 支持把模型推理过程中的中间结果透传出来这对 logits 分析、奖励模型、后续精排等场景非常有用。获取生成 token 的 logitsfrom lmdeploy import pipeline, GenerationConfig pipe pipeline(internlm/internlm2_5-7b-chat) gen_configGenerationConfig(output_logitsgeneration, max_new_tokens10) response pipe([Hi, pls intro yourself, Shanghai is], gen_configgen_config) logits [x.logits for x in response]获取生成 token 最后一层的 hidden statesfrom lmdeploy import pipeline, GenerationConfig pipe pipeline(internlm/internlm2_5-7b-chat) gen_configGenerationConfig(output_last_hidden_stategeneration, max_new_tokens10) response pipe([Hi, pls intro yourself, Shanghai is], gen_configgen_config) hidden_states [x.last_hidden_state for x in response]GenerationConfig中output_logits与output_last_hidden_state的可选值均为all或generation见 lmdeploy/messages.py#L200-L201generation只返回生成 token 的结果all则覆盖包括输入在内的全部位置。获取到的logits、last_hidden_state会分别填充到Response.logits与Response.last_hidden_state字段见 lmdeploy/messages.py#L693-L694。需要注意的是这两个开关会带来额外的显存与计算开销实际使用时建议仅在需要的推理步开启并配合较小的max_new_tokens。8. 计算 PPL困惑度pipeline 提供get_ppl与get_logits两个面向评估的接口可以直接对一段 token 序列打分from transformers import AutoTokenizer from lmdeploy import pipeline model_repoid_or_path internlm/internlm2_5-7b-chat pipe pipeline(model_repoid_or_path) tokenizer AutoTokenizer.from_pretrained(model_repoid_or_path, trust_remote_codeTrue) messages [ {role: user, content: Hello, how are you?}, ] input_ids tokenizer.apply_chat_template(messages) # logits is a list of tensor logits pipe.get_logits(input_ids) print(logits) # ppl is a list of float numbers ppl pipe.get_ppl(input_ids) print(ppl)使用注意原文档明确给出当input_ids过长时可能出现 OOM 错误请小心使用get_ppl返回的是cross entropy loss即返回前没有执行exp操作若要得到严格意义上的 perplexity 需要自行对结果取指数。从源码可以进一步了解其实现细节Pipeline.get_ppl对每个输入序列调用引擎的async_get_ppl支持传入单条list[int]或批量list[list[int]]见 lmdeploy/pipeline.py#L288-L312。在 lmdeploy/serve/core/async_engine.py#L932-L972 中可以看到位置i的 logits 用于预测位置i1的 token因此输入至少要包含 2 个 token 才能计算num_scored len(input_ids) - 1开启 prefix caching 或投机采样speculative decoding时async_get_ppl会直接抛出ValueError拒绝执行引擎以GenerationConfig(max_new_tokens1, return_pplTrue, top_k1)运行一次前向拿到未归一化的交叉熵和ce_loss再除以可打分的 token 数得到平均 loss。get_logits内部则使用output_logitsall逐 token 提取整个输入序列的 logits见 lmdeploy/serve/core/async_engine.py#L896-L930可用于奖励模型、数据筛选等自定义打分逻辑。此外针对 InternLM2/Qwen2 架构的奖励模型Pipeline.get_reward_score还提供了直接获取 reward score 的快捷入口见 lmdeploy/pipeline.py#L265-L286。9. 使用 PyTorchEngineTurboMind 之外pipeline 支持通过PytorchEngineConfig切换到纯 PyTorch 后端。使用前需要先安装 Tritonpip install triton2.1.0from lmdeploy import pipeline, GenerationConfig, PytorchEngineConfig backend_config PytorchEngineConfig(session_len2048) gen_config GenerationConfig(top_p0.8, top_k40, temperature0.8, max_new_tokens1024) pipe pipeline(internlm/internlm2_5-7b-chat, backend_configbackend_config) prompts [[{ role: user, content: Hi, pls intro yourself }], [{ role: user, content: Shanghai is }]] response pipe(prompts, gen_configgen_config) print(response)PytorchEngineConfig的核心配置项见 lmdeploy/messages.py#L451-L598session_len最大会话长度None时由引擎自动推导max_batch_size最大 batch缺省时按设备自动设置cache_max_entry_countKV cache 占空闲显存比例默认0.8block_sizepaging cache block 大小默认64kernel_block_size必须是不小于 16 的 2 的幂且能被block_size整除quant_policyKV cache 量化策略4/8/16/17分别对应 INT4/INT8/FP8/FP8_E5M2枚举定义见 lmdeploy/messages.py#L20-L27device_type支持cuda、ascend、maca、cambadaptersLoRA adapter 配置见下文enable_prefix_caching前缀缓存开关eager_mode是否关闭 CUDA graph 的 eager 模式thread_safe多线程环境下是否使用线程安全实例distributed_executor_backend分布式执行后端可选uni/mp/rayenable_mp_engine多进程模式运行引擎。另外即使没有显式指定PytorchEngineConfig当模型不被 TurboMind 支持时pipeline 也会自动回退到 PyTorch 后端因此 PyTorchEngine 实际是所有新架构模型的默认兜底路径。10. LoRA 模型推理PyTorch 后端支持加载多个 LoRA adapter 并在推理时按需切换。通过PytorchEngineConfig.adapters传入一个{adapter 名: 权重路径/模型 ID}的字典调用时用adapter_name指定使用哪一个from lmdeploy import pipeline, GenerationConfig, PytorchEngineConfig backend_config PytorchEngineConfig(session_len2048, adaptersdict(lora_name_1chenchi/lora-chatglm2-6b-guodegang)) gen_config GenerationConfig(top_p0.8, top_k40, temperature0.8, max_new_tokens1024) pipe pipeline(THUDM/chatglm2-6b, backend_configbackend_config) prompts [[{ role: user, content: 您猜怎么着 }]] response pipe(prompts, gen_configgen_config, adapter_namelora_name_1) print(response)adapters字段类型为dict[str, str]见 lmdeploy/messages.py#L561支持同时注册多个 LoRA推理时通过infer/stream_infer的adapter_name参数动态选择。如果 LoRA 权重带有对应的对话模板可以先将其注册到 LMDeploy然后把对话模板名直接作为adapter_name使用。11. 释放 pipeline 资源Pipeline内部持有 GPU 显存、后台事件循环线程与引擎实例使用完毕后应当释放。两种方式from lmdeploy import pipeline # 方式一with 语句自动释放 with pipeline(internlm/internlm2_5-7b-chat) as pipe: response pipe([Hi, pls intro yourself, Shanghai is]) print(response)# 方式二显式调用 close() pipe pipeline(internlm/internlm2_5-7b-chat) ... pipe.close()with语句依赖Pipeline.__enter__/__exit__实现退出时自动调用close()见 lmdeploy/pipeline.py#L320-L324close()会依次关闭内部事件循环线程与异步引擎见 lmdeploy/pipeline.py#L179-L182。在多轮实验、批量跑评测等长驻进程中及时释放 pipeline 能避免显存碎片化与句柄泄漏。12. 常见问题FAQRuntimeError: An attempt has been made to start a new process before the current process has finished its bootstrapping phase当tp1且使用 PyTorch 后端时引擎会拉起多进程或依赖多进程初始化。如果脚本直接以顶层代码方式执行子进程可能在主进程完成 bootstrap 前被创建从而触发该错误。解决办法是确保 Python 脚本以if __name__ __main__:作为入口if __name__ __main__: # 初始化 pipeline 并执行推理 ...这样可以保证初始化代码只在主程序执行而不会在每个新创建的进程/线程中被重复执行。自定义对话模板pipeline 依据模型对应的 chat template 将 messages 拼装为输入。需要自定义时参考自定义对话模板可编写一个 JSON 模板文件定义system、user、assistant等字段的拼接规则通过 CLI 的--chat-template参数或ChatTemplateConfig接口传入也可以用lmdeploy提供的注册机制将模板注册后按名字引用。LoRA 模板注册若 LoRA 权重有对应的对话模板可先将模板注册到 LMDeploy之后直接用模板名作为adapter_name调用无需每次显式传入完整模板配置。13. 与多模态、长文本场景的衔接尽管本文聚焦 LLM 离线推理理解Pipeline的架构对扩展场景同样重要get_task会根据架构自动选择VLAsyncEngine处理视觉语言模型如 InternVL、Qwen2.5-VL、Gemma3 等见 lmdeploy/archs.py#L116-L131此时infer支持传入(prompt, image)元组形式的多模态输入PytorchEngineConfig.session_len配合长上下文配置可支持长序列推理。pipeline的接口形态保持一致切换模型只需更换model_path与backend_config这正是离线推理 API 设计的主要价值——用统一入口覆盖不同架构、不同后端、不同输入模态。14. 小结pipeline是 LMDeploy 面向离线推理的统一入口自动选择 TurboMind/PyTorch 后端支持批量、流式、多模态输入显存紧张时优先检查并调低cache_max_entry_count当前默认取空闲显存的 0.8TurboMind 也支持按 block 数指定GenerationConfig覆盖采样、停止词、结构化输出等全量生成控制参数合法性在构造时即被校验output_logits/output_last_hidden_state/get_ppl/get_logits为评估与后处理场景提供了直接从引擎取中间结果的能力多卡场景使用tp以及dp/ep/cpPyTorch 后端还支持 LoRA、Ray 分布式执行与多进程模式记得用with或close()释放 pipeline多进程推理请使用if __name__ __main__:保护入口。如需查阅更完整的 API 文档可阅读仓库内的 docs/zh_cn/api/pipeline.rst想深入理解后端差异可进一步阅读 docs/zh_cn/inference/turbomind.md 与 docs/zh_cn/inference/pytorch.md。赞分享人工智能大模型模型推理服务推理引擎本地部署模型量化【免费下载链接】lmdeployLMDeploy is a toolkit for compressing, deploying, and serving LLMs.项目地址https://gitcode.com/gh_mirrors/lm/lmdeploy点击查看免费下载相关推荐LMDeploy 部署 Gemma3 多模态模型实战从离线推理 Pipeline 到源码级原理解析LMDeploy 部署 Gemma3 多模态模型实战从离线推理 Pipeline 到源码级原理解析 LMDeploy 已原生支持 Google Gemma3人工智能大模型模型推理服务推理引擎本地部署模型量化LMDeploy 奖励模型Reward Model推理指南离线 Pipeline 与在线 /pooling API 实战LMDeploy 奖励模型Reward Model推理指南离线 Pipeline 与在线 /pooling API 实战 LMDeploy 原生支持 Re人工智能大模型模型推理服务推理引擎本地部署模型量化EvoDiff vs 传统方法为什么离散扩散模型是下一代蛋白质设计的优选EvoDiff vs 传统方法为什么离散扩散模型是下一代蛋白质设计的优选 在蛋白质工程领域传统方法如结构预测模型如AlphaFold和基于模板的设计工MLOps机器学习后端工作流自动化AI Agent上一篇3小时从零到动如何亲手打造你的智能轮腿机器人下一篇如何用549元打造FOC轮腿平衡机器人开源DIY完整指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考