vLLM 离线推理Offline Inference完全指南基于LLM类打通生成、池化与异步队列全流程【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm本指南系统讲解如何在自有代码中使用 vLLM 的LLM类进行离线推理先厘清生成式Generative与池化式Pooling两类模型再分别演示补全generate、对话chat、池化classify/embed/score/encode以及异步入队enqueue/wait_for_completion等核心 API并延伸到性能剖析、Sleep Mode、缓存管理、指标读取与 RL 训练权重热更新等工程能力。读完你将能够在不启动任何模型服务的前提下直接用 Python 脚本驱动 vLLM 引擎完成批处理推理、向量化检索与大吞吐数据处理。什么是 vLLM 离线推理离线推理Offline Inference指在不依赖独立推理服务器如 OpenAI 兼容的 HTTP API Server的前提下通过 Python 进程内直接调用引擎完成模型的加载、推理与结果回收。它适用于批量离线任务数据清洗、语料扩写、大规模评测、Embedding/检索索引构建等场景。离线推理的唯一入口就是LLM类。它把 tokenizer、语言模型可分布式跨多张 GPU以及用于中间状态缓存KV cache的显存分配全部封装起来给定一批 prompt 和采样参数通过智能批处理intelligent batching与高效显存管理直接产出文本。类的实现位于 vllm/entrypoints/llm.py从源码可见它混入了三个能力 Mixinclass LLM(BeamSearchOfflineMixin, PoolingOfflineMixin, OfflineInferenceMixin):即LLM同时支持束搜索离线推理、池化pooling离线推理与通用离线推理三种能力且经由vllm/__init__.py对外导出用户只需from vllm import LLM, SamplingParams即可使用。模型的两大分类先选对 APIvLLM 中的模型按任务类型可分为两大类这决定了你调用哪一组方法模型类型能力典型代表对应 API生成式模型Generative产出文本补全或对话回复LLaMA、Qwen、DeepSeekLLM.generate()、LLM.chat()池化式模型Pooling不生成内容产出向量/分类/打分bge-m3、Qwen3 RerankerLLM.classify()、LLM.embed()、LLM.score()、LLM.encode()生成式模型完整支持列表与选择指引见 生成式模型文档池化式模型的分类classify.md、Embeddingembed.md、打分scoring.md等细分类型以及各模型适用方法见 池化模型总览。使用前先确认目标模型属于哪一类避免把池化模型传给generate或将生成模型传给embed。仓库在 examples/basic/offline_inference 下为每类 API 提供了可直接运行的独立脚本下文逐一展开。从零开始运行第一个离线推理脚本仓库提供了开箱即用的入门脚本 examples/basic/offline_inference/basic.py这是了解 vLLM 离线推理的最短路径python examples/basic/offline_inference/basic.py脚本核心逻辑如下完整内容见 basic.pyfrom vllm import LLM, SamplingParams prompts [ Hello, my name is, The president of the United States is, The capital of France is, The future of AI is, ] # 构造采样参数对象 sampling_params SamplingParams(temperature0.8, top_p0.95) # 创建 LLM 实例加载 facebook/opt-125m llm LLM(modelfacebook/opt-125m) # 对整批 prompt 生成文本返回 RequestOutput 对象列表 outputs llm.generate(prompts, sampling_params) for output in outputs: prompt output.prompt generated_text output.outputs[0].text print(fPrompt: {prompt!r}) print(fOutput: {generated_text!r})要点LLM.generate()接收单个或一列 promptgenerate.py 中同时演示了把一批 prompt 一次性传入做批处理返回的是RequestOutput列表每个对象包含prompt、outputs含text、token、finish reason 等信息采样参数通过SamplingParams控制常用字段包括temperature、top_p、top_k、max_tokens等。除basic.py外其余脚本都内置了基于FlexibleArgumentParser的参数解析见 examples/basic/offline_inference/README.md可以像运行 CLI 一样给LLM透传引擎参数先跑--help查看全部可选项。chat与generate脚本额外支持--max-tokens、--temperature、--top-p、--top-k采样参数例如# 直接透传 EngineArgs 支持的参数 python examples/basic/offline_inference/generate.py \ --model meta-llama/Llama-3.2-1B-Instruct \ --max-tokens 256 --temperature 0.8 --top-p 0.95实用引擎参数速查LLM.__init__的完整签名覆盖了绝大多数线上需求常用参数如下参数默认值含义与注意事项model必填HuggingFace Transformers 模型名称或本地路径tokenizerNonetokenizer 名称或路径缺省时复用modeltokenizer_modeautoauto优先用 fast tokenizerslow强制慢速trust_remote_codeFalse是否信任远端代码下载并运行模型/分词器tensor_parallel_size1张量并行使用的 GPU 数量dtypeauto支持float32/float16/bfloat16auto时跟随模型 config若 config 为 float32 则退化为 float16quantizationNone权重量化方法如 awq/gptq/fp8为None时优先读取模型quantization_configrevisionNone指定远端模型的 branch/tag/commit idseed0采样随机数种子gpu_memory_utilization0.92为权重、激活与 KV cache 预留的显存比例调大提高吞吐但易 OOMcpu_offload_gb0CPU 显存内存卸载量见下文“大模型装载”小节enforce_eagerFalse关闭 CUDA Graph 捕获便于调试更细的显存控制可用kv_cache_memory_bytes直接按字节指定每卡 KV cache 大小默认None由gpu_memory_utilization自动推导。两个常用进阶玩法在带参数解析的示例脚本generate.py/chat.py等中可以直接体验以下特性1. Generation Config 与采样默认值。构造LLM后调用llm.get_default_sampling_params()会读取服务端默认采样参数llm.py 中的get_default_sampling_params方法。--generation-config控制该配置的来源auto表示从模型路径加载也可指定一个文件夹路径不传则用 vLLM 默认值。注意若 generation config 中写了max_new_tokens它将构成全服务级别的输出 token 上限所有请求都受其约束。2. GGUF 量化模型加载。vLLM 支持 GGUF 量化权重使用repo_id:quant_type格式直接从 HuggingFace 加载python examples/basic/offline_inference/generate.py \ --model unsloth/Qwen3-0.6B-GGUF:Q4_K_M \ --tokenizer Qwen/Qwen3-0.6B3. CPU offload 装载超大模型。--cpu-offload-gb N可视为“虚拟扩大显存”例如单卡 24 GB 再卸载 10 GB 到 CPU可近似按 34 GB 使用从而装载 BF16 下需约 26 GB 显存的 13B 模型python examples/basic/offline_inference/generate.py \ --model meta-llama/Llama-2-13b-chat-hf \ --cpu-offload-gb 10这种方式每次 forward 都会把部分层从 CPU 内存动态搬入 GPU因此对 CPU-GPU 互连带宽要求较高见 examples/basic/offline_inference/README.md。Generative APIs补全与对话生成式模型对应的两个同步 API 是LLM.generate(prompts, sampling_params)对给定输入 prompt 生成补全LLM.chat(messages, sampling_params, ...)基于对话消息生成回复。generate的输入即上一节的basic.py形式而chat接收 OpenAI 风格的消息列表或消息列表的列表以实现对话级批处理并对每个请求应用对话模板。仓库的 chat.py 展示了完整用法from vllm import LLM, EngineArgs llm LLM(modelmeta-llama/Llama-3.2-1B-Instruct) sampling_params llm.get_default_sampling_params() conversation [ {role: system, content: You are a helpful assistant}, {role: user, content: Hello}, {role: assistant, content: Hello! How can I assist you today?}, {role: user, content: Write an essay about the importance of higher education.}, ] # 单段对话 outputs llm.chat(conversation, sampling_params, use_tqdmFalse) # 对话级批处理把同一对话复制 10 份一起跑 conversations [conversation for _ in range(10)] outputs llm.chat(conversations, sampling_params, use_tqdmTrue)从 chat.py 源码可看到llm.chat的关键行为不显式传chat_template时使用模型自带的默认对话模板也可通过文件内容显式覆盖use_tqdm打开时能看到批处理进度条示例中正是用它验证确实执行了 10 路对话推理更底层的模板拼接、add_generation_prompt、continue_final_message、工具调用tools等由 vllm/entrypoints/offline_utils.py 中的_preprocess_chat完成。Asynchronous Queue APIs先入队、后取结果与同步generate/chat不同异步队列 API 把“提交请求”与“等待结果”解耦适合需要精细控制任务编排的场景LLM.enqueue(prompts, sampling_params)把 prompt 加入队列不阻塞等待立即返回请求 ID 列表LLM.enqueue_chat(messages, sampling_params)等价于chat的入队版本LLM.wait_for_completion()阻塞等待所有已入队请求完成并返回结果。典型编排模式如下from vllm import LLM, SamplingParams llm LLM(modelQwen/Qwen2.5-7B-Instruct) params SamplingParams(max_tokens128) # 先把一批请求全部入队不阻塞 request_ids llm.enqueue( [The future of AI is, The capital of France is], sampling_paramsparams, ) print(request_ids) # 例如 [request-0, request-1] # 需要结果时再统一等待 outputs llm.wait_for_completion(use_tqdmTrue) for output in outputs: print(output.prompt, -, output.outputs[0].text)Pooling APIs分类 / 嵌入 / 打分池化式模型不生成文本而是把输入映射为向量、类别分数或两两相关度主要服务分类与检索RAG任务。对应方法按模型类型划分详见 池化模型文档方法适用范围典型任务LLM.classify()仅适用于分类模型文本分类、情感分析LLM.embed()仅适用于 embedding 模型向量化检索、相似度召回LLM.score()score 模型cross-encoder、bi-encoder、late-interaction相关性打分、重排LLM.encode()所有池化模型通用统一入口按模型类型自动处理仓库 examples/basic/offline_inference 下分别提供了 classify.py、embed.py、score.py 三个可运行示例同样支持--help查看可传参数。若不确定某个池化模型属于哪一子类用统一的encode最稳妥实现上相关逻辑封装于LLM混入的PoolingOfflineMixinvllm/entrypoints/pooling/offline.py。Profiling APIs性能剖析当需要定位推理耗时瓶颈如某个算子在 prefill/decode 阶段的开销时可通过LLM直接驱动引擎级性能剖析相关设计见 profiling 文档LLM.start_profile(profile_prefixNone)开始剖析可选自定义 trace 前缀LLM.stop_profile()停止当前剖析会话并产出结果。典型用法llm.start_profile() outputs llm.generate(prompts, sampling_params) # 被剖析的推理区间 llm.stop_profile()Sleep Mode APIs闲置时释放显存在共享 GPU 环境中长时间闲置的离线推理进程常被要求归还显存。Sleep Mode休眠模式正是为此设计机制细节见 sleep_mode.mdLLM.sleep(level1, modeabort)将引擎置入休眠态并释放显存mode可指定对未完成请求的处理方式LLM.wake_up(tagsNone)将引擎从休眠中唤醒重新加载模型与 KV cache 相关资源。在 llm.py 的签名中PauseMode由 vllm/v1/engine 定义实际使用时可结合 vLLM 的VLLM_PAUSE...相关环境变量见 engine_args 文档理解不同mode的语义。它通常与按需部署、GPU 时间片回收配套使用。Cache Management APIs缓存清理多模态与长上下文任务中缓存占用会随请求增长。LLM提供两个同步清理入口LLM.reset_mm_cache()重置多模态缓存LLM.reset_prefix_cache(reset_running_requestsFalse, reset_connectorFalse)重置前缀缓存Prefix Caching可用于热更新数据后强制旧前缀失效。Metrics APIs读取聚合指标离线推理同样可以观测运行指标LLM.get_metrics()返回来自 Prometheus 的聚合指标快照列表形式元素为 vllm/v1/metrics/reader.py 中定义的Metric对象。引擎侧指标体系的完整设计见 metrics 设计文档。典型用法for metric in llm.get_metrics(): print(metric.name, metric.values)Weight Transfer APIs为 RL 训练提供热更新离线推理同样支持强化学习RL训练中的权重热更新场景——权重由训练侧动态生成并写入无需重启推理引擎。相关设计见 Weight Transfer 文档LLM暴露的方法如下LLM.init_weight_transfer_engine(request)初始化权重传输引擎需传入WeightTransferInitRequest或等价 dictLLM.start_weight_update()开始新一轮权重更新周期LLM.update_weights(request)更新模型权重传入WeightTransferUpdateRequest或 dictLLM.finish_weight_update(weight_versionNone)结束当前更新周期可选提交版本号LLM.update_weight_version(new_version)仅设置权重版本号而不真正更新权重配合引擎内的权重版本协商机制LLM.get_weight_version()返回最新已提交的权重版本号。请求/响应数据结构定义于 vllm/distributed/weight_transfer/base.pyWeightTransferInitRequest/WeightTransferUpdateRequest版本管理机制与 RL 异步链路可进一步参考 RLHF 相关示例。Additional APIs跨 worker 的进阶操作面向分布式调试与自定义逻辑LLM还提供两个“直通各 worker”的底层 APILLM.collective_rpc(method, timeoutNone, args(), kwargsNone)在所有 worker 上集体执行某个方法或可调用对象返回各 worker 结果列表LLM.apply_model(func)在每个 worker 内直接对模型对象应用给定函数入参为torch.nn.Module返回结果列表。它们可用于自定义初始化、权重检查、逐层统计等无需重启引擎的诊断任务是 vLLM 分布式运行时下少数能“触达模型内部”的官方入口。API Reference 与更多阅读LLM类的完整字段、方法与类型注解以官方 API 参考为准见 Offline Inference API 文档其中vllm.LLM一节。源码层面LLM类主文件为 vllm/entrypoints/llm.py离线推理请求的预处理tokenize、模板渲染、批处理组装位于 vllm/entrypoints/offline_utils.py 与 vllm/entrypoints/generate/beam_search/offline.py池化逻辑位于 vllm/entrypoints/pooling/offline.py。可直接运行的端到端示例集中在 examples/basic/offline_inference生成/对话/分类/嵌入/打分全覆盖。Ray Data LLM API大规模数据集的分布式离线推理除LLM类外vLLM 官方文档还提供了一条面向超大规模数据集的替代路径——Ray Data LLM API。它以 vLLM 为底层引擎通过 Ray 补齐了若干“开箱即用”的大规模推理能力流式执行可处理超过集群聚合内存上限的数据集自动分片、负载均衡与自动扩缩在 Ray 集群上自动分发任务并内置容错连续批处理持续打满 vLLM 副本最大化 GPU 利用率透明支持张量并行与流水线并行方便多卡推理读写主流文件格式与云对象存储无需改代码即可横向扩展负载。使用前需ray2.44.1代码如下来自 offline_inference.mdimport ray # Requires ray2.44.1 from ray.data.llm import vLLMEngineProcessorConfig, build_llm_processor config vLLMEngineProcessorConfig(model_sourceunsloth/Llama-3.2-1B-Instruct) processor build_llm_processor( config, preprocesslambda row: { messages: [ {role: system, content: You are a bot that completes unfinished haikus.}, {role: user, content: row[item]}, ], sampling_params: {temperature: 0.3, max_tokens: 250}, }, postprocesslambda row: {answer: row[generated_text]}, ) ds ray.data.from_items([An old silent pond...]) ds processor(ds) ds.write_parquet(local:///tmp/data/)其中preprocess负责把数据行转换成对话消息与采样参数postprocess抽取generated_text作为结果字段最终可直接把处理结果落盘到本地或云存储。Ray Data LLM 的更多用法可参考 Ray 官方 Data 文档中“与 LLM 协同工作”的部分。小结如何选型离线推理方案场景推荐方案理由单机少量样本、快速验证LLM.generate/LLM.chat同步语义简单直接返回即结果需要异步编排、按批次收集enqueue/enqueue_chat/wait_for_completion提交与取结果解耦易接入任务调度分类 / Embedding / Rerankclassify/embed/score统一可用encode池化模型专用语义对标样、GPU 被占用告警sleep/wake_up闲置期释放显存可随时恢复RL 训练中在线迭代权重Weight Transfer 系列方法热更新权重而无需重启引擎海量数据 Ray 集群Ray Data LLM API流式、自动分片与故障容错开箱即用从一次LLM(model...)generate的最小闭环到enqueue异步队列、池化 API、Sleep Mode、缓存清理乃至 RL 权重热更新离线推理并不是“只能跑个简单脚本”——把本文梳理的 API 组合起来即可在纯 Python 进程内搭建起一套面向批处理、检索与训练配套的完整离线推理流水线。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 vLLM 离线推理（Offline Inference）完全指南：基于 `LLM` 类打通生成、池化与异步队列全流程
vLLM 离线推理Offline Inference完全指南基于LLM类打通生成、池化与异步队列全流程【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm本指南系统讲解如何在自有代码中使用 vLLM 的LLM类进行离线推理先厘清生成式Generative与池化式Pooling两类模型再分别演示补全generate、对话chat、池化classify/embed/score/encode以及异步入队enqueue/wait_for_completion等核心 API并延伸到性能剖析、Sleep Mode、缓存管理、指标读取与 RL 训练权重热更新等工程能力。读完你将能够在不启动任何模型服务的前提下直接用 Python 脚本驱动 vLLM 引擎完成批处理推理、向量化检索与大吞吐数据处理。什么是 vLLM 离线推理离线推理Offline Inference指在不依赖独立推理服务器如 OpenAI 兼容的 HTTP API Server的前提下通过 Python 进程内直接调用引擎完成模型的加载、推理与结果回收。它适用于批量离线任务数据清洗、语料扩写、大规模评测、Embedding/检索索引构建等场景。离线推理的唯一入口就是LLM类。它把 tokenizer、语言模型可分布式跨多张 GPU以及用于中间状态缓存KV cache的显存分配全部封装起来给定一批 prompt 和采样参数通过智能批处理intelligent batching与高效显存管理直接产出文本。类的实现位于 vllm/entrypoints/llm.py从源码可见它混入了三个能力 Mixinclass LLM(BeamSearchOfflineMixin, PoolingOfflineMixin, OfflineInferenceMixin):即LLM同时支持束搜索离线推理、池化pooling离线推理与通用离线推理三种能力且经由vllm/__init__.py对外导出用户只需from vllm import LLM, SamplingParams即可使用。模型的两大分类先选对 APIvLLM 中的模型按任务类型可分为两大类这决定了你调用哪一组方法模型类型能力典型代表对应 API生成式模型Generative产出文本补全或对话回复LLaMA、Qwen、DeepSeekLLM.generate()、LLM.chat()池化式模型Pooling不生成内容产出向量/分类/打分bge-m3、Qwen3 RerankerLLM.classify()、LLM.embed()、LLM.score()、LLM.encode()生成式模型完整支持列表与选择指引见 生成式模型文档池化式模型的分类classify.md、Embeddingembed.md、打分scoring.md等细分类型以及各模型适用方法见 池化模型总览。使用前先确认目标模型属于哪一类避免把池化模型传给generate或将生成模型传给embed。仓库在 examples/basic/offline_inference 下为每类 API 提供了可直接运行的独立脚本下文逐一展开。从零开始运行第一个离线推理脚本仓库提供了开箱即用的入门脚本 examples/basic/offline_inference/basic.py这是了解 vLLM 离线推理的最短路径python examples/basic/offline_inference/basic.py脚本核心逻辑如下完整内容见 basic.pyfrom vllm import LLM, SamplingParams prompts [ Hello, my name is, The president of the United States is, The capital of France is, The future of AI is, ] # 构造采样参数对象 sampling_params SamplingParams(temperature0.8, top_p0.95) # 创建 LLM 实例加载 facebook/opt-125m llm LLM(modelfacebook/opt-125m) # 对整批 prompt 生成文本返回 RequestOutput 对象列表 outputs llm.generate(prompts, sampling_params) for output in outputs: prompt output.prompt generated_text output.outputs[0].text print(fPrompt: {prompt!r}) print(fOutput: {generated_text!r})要点LLM.generate()接收单个或一列 promptgenerate.py 中同时演示了把一批 prompt 一次性传入做批处理返回的是RequestOutput列表每个对象包含prompt、outputs含text、token、finish reason 等信息采样参数通过SamplingParams控制常用字段包括temperature、top_p、top_k、max_tokens等。除basic.py外其余脚本都内置了基于FlexibleArgumentParser的参数解析见 examples/basic/offline_inference/README.md可以像运行 CLI 一样给LLM透传引擎参数先跑--help查看全部可选项。chat与generate脚本额外支持--max-tokens、--temperature、--top-p、--top-k采样参数例如# 直接透传 EngineArgs 支持的参数 python examples/basic/offline_inference/generate.py \ --model meta-llama/Llama-3.2-1B-Instruct \ --max-tokens 256 --temperature 0.8 --top-p 0.95实用引擎参数速查LLM.__init__的完整签名覆盖了绝大多数线上需求常用参数如下参数默认值含义与注意事项model必填HuggingFace Transformers 模型名称或本地路径tokenizerNonetokenizer 名称或路径缺省时复用modeltokenizer_modeautoauto优先用 fast tokenizerslow强制慢速trust_remote_codeFalse是否信任远端代码下载并运行模型/分词器tensor_parallel_size1张量并行使用的 GPU 数量dtypeauto支持float32/float16/bfloat16auto时跟随模型 config若 config 为 float32 则退化为 float16quantizationNone权重量化方法如 awq/gptq/fp8为None时优先读取模型quantization_configrevisionNone指定远端模型的 branch/tag/commit idseed0采样随机数种子gpu_memory_utilization0.92为权重、激活与 KV cache 预留的显存比例调大提高吞吐但易 OOMcpu_offload_gb0CPU 显存内存卸载量见下文“大模型装载”小节enforce_eagerFalse关闭 CUDA Graph 捕获便于调试更细的显存控制可用kv_cache_memory_bytes直接按字节指定每卡 KV cache 大小默认None由gpu_memory_utilization自动推导。两个常用进阶玩法在带参数解析的示例脚本generate.py/chat.py等中可以直接体验以下特性1. Generation Config 与采样默认值。构造LLM后调用llm.get_default_sampling_params()会读取服务端默认采样参数llm.py 中的get_default_sampling_params方法。--generation-config控制该配置的来源auto表示从模型路径加载也可指定一个文件夹路径不传则用 vLLM 默认值。注意若 generation config 中写了max_new_tokens它将构成全服务级别的输出 token 上限所有请求都受其约束。2. GGUF 量化模型加载。vLLM 支持 GGUF 量化权重使用repo_id:quant_type格式直接从 HuggingFace 加载python examples/basic/offline_inference/generate.py \ --model unsloth/Qwen3-0.6B-GGUF:Q4_K_M \ --tokenizer Qwen/Qwen3-0.6B3. CPU offload 装载超大模型。--cpu-offload-gb N可视为“虚拟扩大显存”例如单卡 24 GB 再卸载 10 GB 到 CPU可近似按 34 GB 使用从而装载 BF16 下需约 26 GB 显存的 13B 模型python examples/basic/offline_inference/generate.py \ --model meta-llama/Llama-2-13b-chat-hf \ --cpu-offload-gb 10这种方式每次 forward 都会把部分层从 CPU 内存动态搬入 GPU因此对 CPU-GPU 互连带宽要求较高见 examples/basic/offline_inference/README.md。Generative APIs补全与对话生成式模型对应的两个同步 API 是LLM.generate(prompts, sampling_params)对给定输入 prompt 生成补全LLM.chat(messages, sampling_params, ...)基于对话消息生成回复。generate的输入即上一节的basic.py形式而chat接收 OpenAI 风格的消息列表或消息列表的列表以实现对话级批处理并对每个请求应用对话模板。仓库的 chat.py 展示了完整用法from vllm import LLM, EngineArgs llm LLM(modelmeta-llama/Llama-3.2-1B-Instruct) sampling_params llm.get_default_sampling_params() conversation [ {role: system, content: You are a helpful assistant}, {role: user, content: Hello}, {role: assistant, content: Hello! How can I assist you today?}, {role: user, content: Write an essay about the importance of higher education.}, ] # 单段对话 outputs llm.chat(conversation, sampling_params, use_tqdmFalse) # 对话级批处理把同一对话复制 10 份一起跑 conversations [conversation for _ in range(10)] outputs llm.chat(conversations, sampling_params, use_tqdmTrue)从 chat.py 源码可看到llm.chat的关键行为不显式传chat_template时使用模型自带的默认对话模板也可通过文件内容显式覆盖use_tqdm打开时能看到批处理进度条示例中正是用它验证确实执行了 10 路对话推理更底层的模板拼接、add_generation_prompt、continue_final_message、工具调用tools等由 vllm/entrypoints/offline_utils.py 中的_preprocess_chat完成。Asynchronous Queue APIs先入队、后取结果与同步generate/chat不同异步队列 API 把“提交请求”与“等待结果”解耦适合需要精细控制任务编排的场景LLM.enqueue(prompts, sampling_params)把 prompt 加入队列不阻塞等待立即返回请求 ID 列表LLM.enqueue_chat(messages, sampling_params)等价于chat的入队版本LLM.wait_for_completion()阻塞等待所有已入队请求完成并返回结果。典型编排模式如下from vllm import LLM, SamplingParams llm LLM(modelQwen/Qwen2.5-7B-Instruct) params SamplingParams(max_tokens128) # 先把一批请求全部入队不阻塞 request_ids llm.enqueue( [The future of AI is, The capital of France is], sampling_paramsparams, ) print(request_ids) # 例如 [request-0, request-1] # 需要结果时再统一等待 outputs llm.wait_for_completion(use_tqdmTrue) for output in outputs: print(output.prompt, -, output.outputs[0].text)Pooling APIs分类 / 嵌入 / 打分池化式模型不生成文本而是把输入映射为向量、类别分数或两两相关度主要服务分类与检索RAG任务。对应方法按模型类型划分详见 池化模型文档方法适用范围典型任务LLM.classify()仅适用于分类模型文本分类、情感分析LLM.embed()仅适用于 embedding 模型向量化检索、相似度召回LLM.score()score 模型cross-encoder、bi-encoder、late-interaction相关性打分、重排LLM.encode()所有池化模型通用统一入口按模型类型自动处理仓库 examples/basic/offline_inference 下分别提供了 classify.py、embed.py、score.py 三个可运行示例同样支持--help查看可传参数。若不确定某个池化模型属于哪一子类用统一的encode最稳妥实现上相关逻辑封装于LLM混入的PoolingOfflineMixinvllm/entrypoints/pooling/offline.py。Profiling APIs性能剖析当需要定位推理耗时瓶颈如某个算子在 prefill/decode 阶段的开销时可通过LLM直接驱动引擎级性能剖析相关设计见 profiling 文档LLM.start_profile(profile_prefixNone)开始剖析可选自定义 trace 前缀LLM.stop_profile()停止当前剖析会话并产出结果。典型用法llm.start_profile() outputs llm.generate(prompts, sampling_params) # 被剖析的推理区间 llm.stop_profile()Sleep Mode APIs闲置时释放显存在共享 GPU 环境中长时间闲置的离线推理进程常被要求归还显存。Sleep Mode休眠模式正是为此设计机制细节见 sleep_mode.mdLLM.sleep(level1, modeabort)将引擎置入休眠态并释放显存mode可指定对未完成请求的处理方式LLM.wake_up(tagsNone)将引擎从休眠中唤醒重新加载模型与 KV cache 相关资源。在 llm.py 的签名中PauseMode由 vllm/v1/engine 定义实际使用时可结合 vLLM 的VLLM_PAUSE...相关环境变量见 engine_args 文档理解不同mode的语义。它通常与按需部署、GPU 时间片回收配套使用。Cache Management APIs缓存清理多模态与长上下文任务中缓存占用会随请求增长。LLM提供两个同步清理入口LLM.reset_mm_cache()重置多模态缓存LLM.reset_prefix_cache(reset_running_requestsFalse, reset_connectorFalse)重置前缀缓存Prefix Caching可用于热更新数据后强制旧前缀失效。Metrics APIs读取聚合指标离线推理同样可以观测运行指标LLM.get_metrics()返回来自 Prometheus 的聚合指标快照列表形式元素为 vllm/v1/metrics/reader.py 中定义的Metric对象。引擎侧指标体系的完整设计见 metrics 设计文档。典型用法for metric in llm.get_metrics(): print(metric.name, metric.values)Weight Transfer APIs为 RL 训练提供热更新离线推理同样支持强化学习RL训练中的权重热更新场景——权重由训练侧动态生成并写入无需重启推理引擎。相关设计见 Weight Transfer 文档LLM暴露的方法如下LLM.init_weight_transfer_engine(request)初始化权重传输引擎需传入WeightTransferInitRequest或等价 dictLLM.start_weight_update()开始新一轮权重更新周期LLM.update_weights(request)更新模型权重传入WeightTransferUpdateRequest或 dictLLM.finish_weight_update(weight_versionNone)结束当前更新周期可选提交版本号LLM.update_weight_version(new_version)仅设置权重版本号而不真正更新权重配合引擎内的权重版本协商机制LLM.get_weight_version()返回最新已提交的权重版本号。请求/响应数据结构定义于 vllm/distributed/weight_transfer/base.pyWeightTransferInitRequest/WeightTransferUpdateRequest版本管理机制与 RL 异步链路可进一步参考 RLHF 相关示例。Additional APIs跨 worker 的进阶操作面向分布式调试与自定义逻辑LLM还提供两个“直通各 worker”的底层 APILLM.collective_rpc(method, timeoutNone, args(), kwargsNone)在所有 worker 上集体执行某个方法或可调用对象返回各 worker 结果列表LLM.apply_model(func)在每个 worker 内直接对模型对象应用给定函数入参为torch.nn.Module返回结果列表。它们可用于自定义初始化、权重检查、逐层统计等无需重启引擎的诊断任务是 vLLM 分布式运行时下少数能“触达模型内部”的官方入口。API Reference 与更多阅读LLM类的完整字段、方法与类型注解以官方 API 参考为准见 Offline Inference API 文档其中vllm.LLM一节。源码层面LLM类主文件为 vllm/entrypoints/llm.py离线推理请求的预处理tokenize、模板渲染、批处理组装位于 vllm/entrypoints/offline_utils.py 与 vllm/entrypoints/generate/beam_search/offline.py池化逻辑位于 vllm/entrypoints/pooling/offline.py。可直接运行的端到端示例集中在 examples/basic/offline_inference生成/对话/分类/嵌入/打分全覆盖。Ray Data LLM API大规模数据集的分布式离线推理除LLM类外vLLM 官方文档还提供了一条面向超大规模数据集的替代路径——Ray Data LLM API。它以 vLLM 为底层引擎通过 Ray 补齐了若干“开箱即用”的大规模推理能力流式执行可处理超过集群聚合内存上限的数据集自动分片、负载均衡与自动扩缩在 Ray 集群上自动分发任务并内置容错连续批处理持续打满 vLLM 副本最大化 GPU 利用率透明支持张量并行与流水线并行方便多卡推理读写主流文件格式与云对象存储无需改代码即可横向扩展负载。使用前需ray2.44.1代码如下来自 offline_inference.mdimport ray # Requires ray2.44.1 from ray.data.llm import vLLMEngineProcessorConfig, build_llm_processor config vLLMEngineProcessorConfig(model_sourceunsloth/Llama-3.2-1B-Instruct) processor build_llm_processor( config, preprocesslambda row: { messages: [ {role: system, content: You are a bot that completes unfinished haikus.}, {role: user, content: row[item]}, ], sampling_params: {temperature: 0.3, max_tokens: 250}, }, postprocesslambda row: {answer: row[generated_text]}, ) ds ray.data.from_items([An old silent pond...]) ds processor(ds) ds.write_parquet(local:///tmp/data/)其中preprocess负责把数据行转换成对话消息与采样参数postprocess抽取generated_text作为结果字段最终可直接把处理结果落盘到本地或云存储。Ray Data LLM 的更多用法可参考 Ray 官方 Data 文档中“与 LLM 协同工作”的部分。小结如何选型离线推理方案场景推荐方案理由单机少量样本、快速验证LLM.generate/LLM.chat同步语义简单直接返回即结果需要异步编排、按批次收集enqueue/enqueue_chat/wait_for_completion提交与取结果解耦易接入任务调度分类 / Embedding / Rerankclassify/embed/score统一可用encode池化模型专用语义对标样、GPU 被占用告警sleep/wake_up闲置期释放显存可随时恢复RL 训练中在线迭代权重Weight Transfer 系列方法热更新权重而无需重启引擎海量数据 Ray 集群Ray Data LLM API流式、自动分片与故障容错开箱即用从一次LLM(model...)generate的最小闭环到enqueue异步队列、池化 API、Sleep Mode、缓存清理乃至 RL 权重热更新离线推理并不是“只能跑个简单脚本”——把本文梳理的 API 组合起来即可在纯 Python 进程内搭建起一套面向批处理、检索与训练配套的完整离线推理流水线。【免费下载链接】vllmA high-throughput and memory-efficient inference and serving engine for LLMs项目地址: https://gitcode.com/GitHub_Trending/vl/vllm创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考