vLLM-Omni Diffusion 模块家族深度解析:运行时架构、执行模式与源码级实践指南
2026/9/17 6:22:50 网站建设 项目流程

vLLM-Omni Diffusion 模块家族深度解析:运行时架构、执行模式与源码级实践指南

【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni

本篇技术指南以仓库内 diffusion.md 为骨架,结合 docs/design/module/diffusion/ 下的五份子模块设计文档(Diffusion Runtime、Model Integration、Continuous Batching、Parallelism、Offloader)与 vllm_omni/diffusion/ 源码实现,系统讲解 vLLM-Omni 扩散模型推理子系统的分层架构、请求生命周期、两种执行模式、分布式执行后端与 offload 内存管理机制。读完本文,你将掌握该模块家族的核心设计约束与不变量(invariants)、请求从准入到清理的完整状态机、uni/mp执行后端的取舍,以及各子模块对应的源码与测试路径,可直接用于代码评审、二次开发与故障定位。

一、Diffusion 模块家族总览:从顶层索引到五条主线

vLLM-Omni 将扩散(diffusion)相关能力组织为一个模块家族(module family),其权威索引位于 docs/design/module/diffusion/index.md,而面向代码评审的入口摘要则是 .claude/skills/review-pr/references/modules/diffusion.md。

该模块家族涵盖运行时(runtime)、模型集成(model integration)、批量调度(continuous batching)、分布式执行(parallelism)与内存管理(offloader)五个子系统,对应五份子模块文档:

子模块关注的信号设计文档
Runtime准入、调度、执行、进度、输出、取消、钩子、清理diffusion_runtime.md
Model Integration流水线、注册表、加载器、适配器、共享层、模型特定处理diffusion_model_integration.md
Continuous Batching兼容性、请求/步骤批次、逐请求进度、容量continuous_batching.md
Parallelism秩拓扑、进程组、分片、集合通信、分布式执行parallelism.md
Offloader驻留、迁移、内存记账、预取、销毁offloader.md

而缓存(cache)、量化(quantization)、性能剖析(profiling)与基准测试(benchmarking)则遵循各自的顶层模块文档,不属于本家族文档的范畴。从源码看,该家族的核心代码集中在vllm_omni/diffusion/**(vllm_omni/diffusion/ 目录下包含diffusion_engine.pyrequest.pydata.pysched/executor/worker/models/model_loader/offloader/distributed/等子包),相关的平台代码位于vllm_omni/platforms/**,验证测试位于 tests/diffusion/。

1.1 家族级检查清单(代码评审要点)

索引文档给出了五条全家族通用检查项,是评审任何 diffusion 相关改动时的第一道关口:

  1. 单一生命周期所有者:从准入(admission)到完成、取消、失败、清理,每个请求必须只有一个调度器(scheduler)拥有的生命周期;可选功能必须通过已定义的钩子(hooks)接入,而非另起一套生命周期。
  2. 通过注册表选择模型:模型实现必须通过 registry 与 loader 契约选择,禁止散落的model_name条件分支;真实的模型差异只允许留在各自的模型目录中(对应不变量 DIFF-MODEL-INV-002)。
  3. 追踪张量全链路:latent、conditioning、timestep、generator、shape、layout、dtype、device、batch 扩展与输出转换,必须一路追踪到实际消费者。
  4. 批量兼容性与逐请求隔离:批量兼容必须显式声明;禁止依据不稳定的 batch 位置关联输出(对应不变量 BATCH-INV-004)。
  5. 分布式边界纪律:拓扑必须从校验过的配置推导、每个分片边界必须明确、集合通信必须对称、且必须保留受支持的单秩(single-rank)路径;每个被 offload 的组件只能有一个驻留所有者,传输就绪后才能被消费,必须保留模型状态、限制保留副本数量并确定性清理。

评审时还需要为缓存、量化、并行、连续批处理或 offload 加载对应的特性设计文档,并强制要求:特性关闭(feature-off)时行为正确、代表性的推理验证、terminal-path 测试,以及针对优化的质量证据。

二、Diffusion Runtime:控制循环与组件职责

Diffusion Runtime 是整个模块家族的核心,负责 diffusion stage 内部的请求准入、调度、执行、进度、输出、取消与清理。它的设计文档是 diffusion_runtime.md,主代码路径为 diffusion_engine.py、request.py、data.py、sched/、executor/、worker/,核心验证测试在 test_diffusion_engine.py 与 test_diffusion_scheduler.py。

2.1 运行时是一个小控制循环

文档将运行时描述为一个精简的控制循环,共五步:

  1. 调度器(scheduler)选择就绪请求;
  2. 执行器(executor)将这一选择发送到 worker 层;
  3. 每个worker管理自己的设备,并把模型工作委托给runner
  4. runner调用模型流水线并返回逐请求结果;
  5. 引擎(engine)把这些结果反馈给调度器与输出流。

从源码看,DiffusionEngine定义于 diffusion_engine.py 第 218 行,其类方法make_engine(第 836 行)负责解析引擎类并构造执行器与调度器;add_request(第 903 行)负责准入;abort(第 1306 行)与close(第 1271 行)负责取消与幂等关闭。

2.2 目标与非目标

目标:让请求策略(policy)与设备执行(device execution)解耦;让请求身份(request identity)从准入到最终输出(含取消与失败)保持稳定。

非目标:本模块负责选择下一个 Omni stage、不放置 stage 副本、也不定义某个模型的去噪算法:

  • 跨 stage 路由属于 engine_orchestration.md;
  • 进程放置与副本生命周期属于 stage_runtime.md;
  • 模型特定工作属于 diffusion_model_integration.md。

2.3 运行时组件速览

Stage 拥有DiffusionEngine与一个DiffusionExecutor后端。内联 stage client(inline_stage_diffusion_client.py)把整条执行栈保留在调用进程内;而进程型 stage 则运行在StageDiffusionProc(stage_diffusion_proc.py)内部,进程间通过 ZMQ 通信。

执行器随后决定 worker 的运行方式:

  • uninum_gpus == 1时的默认值):UniProcDiffusionExecutor(uniproc_executor.py 第 43 行)在进程内构建一个 worker,没有worker 子进程、没有共享内存 RPC;
  • mpnum_gpus > 1时的默认值,或显式指定):MultiprocDiffusionExecutor(multiproc_executor.py 第 144 行)为每个设备启动一个WorkerProc

无论哪种方式,每个 worker 都拥有自己的设备、分布式状态、DiffusionWorkerDiffusionModelRunner与流水线实例。

需要特别注意的是:部署的 stage 可能已经运行在StageDiffusionProc子进程中,这与可选的mpworker 进程是两回事。使用uni时,worker 与引擎同处一个进程。

2.4 组件职责划分表

组件拥有不拥有
DiffusionEngine准入、busy loop、调度器/执行器协调、RPC 排序、输出流、warmup、abort 路由批处理策略细节、设备设置、模型计算
BaseScheduler请求状态、waiting/running 集合、容量、兼容性、终态转换IPC、worker 调用、输出格式化
RequestScheduler完整请求波(wave)与可选的准入延迟(面向请求级批处理)去噪步骤进度
StepScheduler逐请求去噪进度与逐步完成流水线张量与模型状态
DiffusionExecutor执行后端契约、worker RPC、健康、关闭准入与请求状态转换
UniProcDiffusionExecutornum_gpus == 1时的单进程内 worker;无 IPC、无异步输出泵多 GPU 执行
MultiprocDiffusionExecutorworker 进程、共享内存消息队列、结果分发、worker 监控进程内单 GPU 路径
WorkerProc单个mpworker 进程的 IPC 循环与回复规则调度策略;uni不使用
DiffusionWorker设备/分布式设置、LoRA 激活、profiling、sleep/wake、runner 委托请求准入
DiffusionModelRunner流水线加载、请求本地模型状态、cache/compile 设置、请求或步骤执行排队与跨 stage 路由

其中RequestSchedulerStepSchedulerBaseScheduler的实现分别位于 request_scheduler.py(第 59 行)、step_scheduler.py(第 30 行)、base_scheduler.py(第 46 行);DiffusionWorkerWorkerProc定义在 diffusion_worker.py(第 225 行与第 1028 行);DiffusionModelRunner定义在 diffusion_model_runner.py(第 150 行)。

2.5 策略与执行的边界:DiffusionSchedulerOutput

策略与执行的边界DiffusionSchedulerOutput对象。它包含:

  • 新准入的请求负载(payload);
  • 其 runner 状态已被缓存、无需重新初始化的请求 ID;
  • 已完成的请求 ID;
  • 可选的 KV 预取(prefetch)工作;
  • 当启用 paged Diffusion KV 时,挂在NewRequestData信封上的逐请求diffusion_kv_metadata

执行器与 worker 只消费这个输出,不自行决定接下来该运行什么。这从机制上保证了"执行必须跟随调度决策"这条不变量(DIFF-RUNTIME-INV-002)。

BaseScheduler.initialize()会用od_config.max_num_seqs(默认值为 1)设置max_num_running_reqs。引擎可以为了分布式 layerwise offload(AllGather DP 并发)而覆盖该容量。

2.6 一次调度 tick 的完整时序

异步请求共享同一个引擎 busy loop,worker 调用与控制 RPC 都经过该循环,因此不会在 executor 传输上产生竞态。一次 tick 的调用链为:

  1. Caller调用Engine.add_request(request)
  2. 引擎把请求交给Scheduler.add_request(request)并调用schedule()
  3. 调度器返回DiffusionSchedulerOutput
  4. 引擎调用Executor.execute_batch()execute_step()
  5. 执行器调用 worker 方法,worker 再委托 runner 执行完整模型或单步;
  6. runner 返回RunnerOutput(s),逐层回传为BaseRunnerOutput
  7. 引擎调用Scheduler.update_from_output(...),得到已完成的请求 ID;
  8. 引擎向调用方输出 chunk 或最终结果。

引擎会捕获请求执行错误并将其转换为逐请求错误输出。而整个 worker 组死亡是另一种情况:执行器把自己标记为失败,健康检查抛出EngineDeadError,由所属 stage client 处理 stage 级故障。

三、两种执行模式:Request Batch 与 Step Batch

引擎在启动时只解析一种模式,并绑定对应的调度器与执行器调用:

模式调度器执行器调用Runner 路径
Request batchRequestSchedulerexecute_batch()单请求execute_model(),或融合批execute_model_batch()
Step batchStepSchedulerexecute_step()execute_stepwise()

用户侧的选择方法见 execution_modes.md(对应 docs/user_guide/diffusion/ 目录下的执行模式指南);本文聚焦模式选定之后运行时内部发生的事情。

3.1 Request 模式:整条流水线前向

Request 模式为每个调度波(wave)运行一次完整的流水线前向:

  • 单请求波是保守路径(conservative path);
  • 多请求波通常使用融合的execute_model_batch(),要求流水线显式声明支持 request-batch。

3.2 DLO DP 并发:AllGather 专用分发路径

分布式 layerwise offload + AllGather(DLO DP 并发)是一条独立的 multiproc 分发路径,激活条件:

  • data_parallel_size > 1
  • 设置了enable_distributed_layerwise_offload
  • dlo_use_allgather为 true。

激活后引擎把dp_concurrent置为True,并把scheduler.max_num_running_reqs提升到dp_size,覆盖initialize()中来自max_num_seqs的默认值。调度器仍然发出多请求DiffusionSchedulerOutput;multiproc 执行器通过execute_request()而不是融合的execute_model_batch()来路由该波。

可选的准入合并(admission coalescing)可以填满一个dp_size波:当request_batch_max_wait_ms > 0时,RequestScheduler可能在一个波首次调度前短暂等待(在dp_concurrent下,稳定窗口为min(0.3s, wait/2))。默认request_batch_max_wait_ms == 0,即不等待。

分发前,MultiprocDiffusionExecutor.execute_request()会拒绝采样参数兼容性或extra_args不一致的波(AllGather 要求每个 DP 秩遵循相同的前向调度)。随后每个 worker 秩从波中取一个信封:req[dp_rank % len(req)],这样每个秩进入同一个集合通信、同时计算不同请求。

3.3 Step 模式与流式输出

Step 模式StepRequestState保存在 runner 中:

  • 新请求先运行一次prepare_encode()
  • 每个 tick 运行denoise_step()step_scheduler()
  • 完成的请求运行post_decode()

调度器只保留生命周期与进度元数据——不持有模型张量

Step 模式也是流式扩散输出的必经路径:启用streaming_output时,必要时会自动切换到 step 执行。支持 chunk 的流水线可以通过同一条请求流发出中间输出;仅支持 final-only step 的流水线仍然只输出最终结果。如果流水线没有实现 step 执行,初始化会失败。相关验证见 tests/diffusion 下的test_diffusion_streaming_output.py

四、请求状态机与身份管理

调度器是已准入请求的真相来源(source of truth),其正常状态流转为:

[*] --> WAITING: add_request WAITING --> RUNNING: schedule WAITING --> FINISHED_ABORTED: abort RUNNING --> FINISHED_ABORTED: abort RUNNING --> FINISHED_COMPLETED: successful output RUNNING --> FINISHED_ERROR: failed or missing output FINISHED_COMPLETED --> [*]: deliver and remove state FINISHED_ABORTED --> [*]: deliver and remove state FINISHED_ERROR --> [*]: deliver and remove state

PREEMPTEDBaseScheduler.preempt_request()虽然存在于调度器 API 上,但当前引擎循环并不会调用它们——只有调度器单元测试在使用。

request_id把调度器状态、runner 状态、执行器结果与输出队列串在一起。batch 位置是临时的,在把结果映射回去时绝不能用 batch 位置代替请求身份(不变量 DIFF-RUNTIME-INV-005 与 BATCH-INV-004 的双重约束)。

只有兼容的请求才能进入同一个运行波。调度器会比较一个模式相关的采样参数键,并在第一个不兼容的等待请求处停止。这是有意为之的保守策略,代价是可能产生队头阻塞(head-of-line blocking)。

五、执行后端与 IPC:uni 与 mp 的取舍

DiffusionExecutor是后端接口,通过distributed_executor_backend选择内置后端:

后端何时选择Worker 布局
uninum_gpus == 1默认,或显式指定单个进程内 worker
mpnum_gpus > 1默认,或显式指定每设备一个 worker 进程

Ray 与外部启动器(external-launcher)的扩散后端未实现。自定义DiffusionExecutor子类或 import path 也可被接受。

5.1 Uniproc 后端

UniProcDiffusionExecutor在引擎进程内构造WorkerWrapperBase并直接调用 worker 方法,从而避免第二次模型加载、MessageQueue ring、ZMQ IPC socket 与/dev/shm张量打包。RPC 超时参数仅为接口一致性而保留,不强制执行:一个挂死的 worker 会阻塞调用线程。粘性加速器故障(sticky accelerator faults)通过失败回调把执行器标记为 dead;普通请求错误仍是逐请求的。验证见 test_uniproc_executor.py。

5.2 Multiproc 后端

MultiprocDiffusionExecutor的启动流程:

  1. 创建所有 worker 共享的 broadcast 队列;
  2. 为每个配置的设备派生一个 worker 进程;
  3. 等待所有 worker 报告就绪;
  4. 以 RPC 消息发送生成与控制调用;
  5. 应用 rank-aware 回复规则,只让预期秩应答;
  6. 监控 worker 进程哨兵,若有 worker 死亡则使执行器失败。

在 request 模式下,每个异步输出产生两条以async_output_id关联的消息:

  • COMPUTE_DONE——前向结束,设备可以开始下一个请求;
  • OUTPUT_READY——后台 D2H/SHM 打包完成,最终输出就绪。

worker 在入队COMPUTE_DONE之前就把后台打包工作排入队列,但两条消息到达执行器的先后顺序不固定,因此 result pump 与execute_batch()必须同时处理两种顺序。Step 模式保持同步结果路径,不启动这些泵。更详细的时间线见特性文档 async_diffusion_output.md 与测试 test_result_pump.py、test_async_output_worker.py、test_multiproc_engine_concurrency.py。

5.3 Worker 与 Runner 边界

mp路径上,WorkerProc接收消息并通过WorkerWrapperBase调用方法;在uni路径上,执行器直接持有该 wrapper。两种情况下DiffusionWorker都处理与设备相关的部分:分布式初始化、模型 runner 构造、LoRA 激活、profiling、内存 sleep/wake,并把实际模型工作委托给DiffusionModelRunner

runner 拥有长生命周期的模型侧状态:

  • 已加载的流水线与编译(compile)设置;
  • cache 与 offload 集成;
  • 随机生成器设置;
  • 完整前向的请求批次;
  • step 执行所需的StepRequestStateInputBatch

这种切分把基础设施挡在模型流水线之外:流水线只接收请求批或 step 状态并执行模型工作,不应检查引擎队列或修改调度器状态。这也正是 DIFF-MODEL-INV-003"模型代码不负责调度请求"的落地。

六、生命周期与清理:启动、取消、关闭

6.1 启动与 Warmup

DiffusionEngine.make_engine()解析引擎类、构造执行器与调度器,然后通常运行一个小的 dummy 请求来预热(warmup)模型。

仅在以下情况跳过 warmup:启用了 DLO + AllGather(enable_distributed_layerwise_offloaddlo_use_allgather),且max(data_parallel_size, sequence_parallel_size) > 1——因为 dummy run 只发送一个请求,而 AllGather 要求每个 shard 秩进入同一个集合通信。若初始化或 warmup 失败,运行时在返回错误前会先关闭调度器状态与 worker 资源。验证见 test_diffusion_engine_dummy_run.py。

6.2 取消

abort()把请求 ID 放入 abort 队列。busy loop 将这些请求标记为FINISHED_ABORTED;终结阶段移除调度器状态,并在仍有消费者时发出 aborted 输出。runner 在收到报告该请求 ID 已结束的调度输出时,会清除缓存的 step 模式状态。

在 multiproc request 模式的异步路径上,abort 或消费者在输出物化期间断开时,应当释放关联的 async-output 记账,避免请求结束后仍保留迟到结果(文档标注为 pending #6253/#6439/#6580)。当前设计是:未被消费的OUTPUT_READY会被有意缓存,直到wait_output_ready()或执行器销毁。丢弃输出流消费者会移除该消费者的队列,但接管调度器清理的所有权。

6.3 关闭与 worker 故障

DiffusionEngine.close()幂等的:停止 busy loop、以错误唤醒挂起的流、关闭调度器状态、关闭执行器。

  • mp:执行器请求 worker 停止并等待;错过宽限期的 worker 会被终止。关闭会把未完成的 RPC 与 async-output future 标记为失败并清除。为后续wait_output_ready()缓存且已完成的 async 输出随执行器对象一起丢弃。
  • uni:执行器关闭进程内 worker、丢弃最后一个模型引用、清空加速器缓存,使后续引擎可以复用该设备。

重要警告:在致命的集合通信超时或意外 worker 退出后,不要继续使用该 worker 组——分布式状态可能不完整。multiproc 执行器刻意 fail-closed,让 stage 可以重启;uniproc 执行器在加速器上下文本身被污染时同样 fail-closed。

七、扩展边界与候选不变量(评审锚点)

7.1 扩展边界

  • 自定义引擎可设置default_diffusion_model_runner_cls;显式配置的diffusion_model_runner_cls仍然优先。
  • 测试与自定义引擎集成可以注入BaseScheduler子类;SchedulerInterface仅作为已废弃的兼容名称保留(见 base_scheduler.py 第 471 行)。
  • distributed_executor_backend可以是"uni""mp"、自定义DiffusionExecutor子类或 import path。后端必须保持调度输出、请求身份、健康与清理契约。需要进程隔离或多 GPU 时用"mp""uni"是单 GPU 默认。
  • worker 扩展通过WorkerWrapperBase进行:添加 worker 方法,但变成第二个调度器或请求生命周期。

这些是高级 Python 集成点,不是稳定的终端用户 CLI 定制面。

7.2 运行时不变量(DIFF-RUNTIME-INV 系列)

  • INV-001 单一生命周期所有者:每个已准入请求在完成、取消或失败之前,必须恰好有一个调度器拥有的生命周期。
  • INV-002 执行跟随调度输出:执行器与 worker 必须执行调度决策,不得独立准入、重排或转发请求。DLO + AllGather 是分发时的例外:调度器可调度多请求波,但每个 DP 秩只从该波执行一个信封,以保证所有秩进入同一集合通信调度。
  • INV-003 终态清理完整:每条终态路径必须释放请求状态、临时张量、钩子与运行时拥有的资源;abort 或消费前消费者丢弃时的 async-output 记账也属必需要求(pending #6253/#6439/#6580)。
  • INV-004 可选功能走运行时钩子:cache、profiling、offload 与并行特性应在已定义的钩子上集成,而不是再创建一个请求生命周期。
  • INV-005 结果保持请求身份:批量与异步结果必须按稳定请求 ID 映射,而非假定的完成顺序。

7.3 安全改动指南(回归证据映射)

改动区域最小证据
准入或状态转换test_diffusion_scheduler.py(覆盖重复 ID、兼容性、abort、缺失输出)
引擎循环或输出投递test_diffusion_engine.pytest_diffusion_engine_cleanup.pytest_diffusion_engine_rpc_routing.py
执行器或 IPCtest_multiproc_engine_concurrency.pytest_uniproc_executor.pytest_result_pump.pytest_diffusion_ipc.pytest_async_output_worker.py
Worker 或 Runnertest_diffusion_worker.pytest_diffusion_model_runner.py
Stage 边界test_stage_diffusion_proc.pytest_inline_stage_diffusion_client.py
Warmup 或流式test_diffusion_engine_dummy_run.pytest_diffusion_streaming_output.py

改动后务必覆盖:成功、取消、逐请求失败、致命 worker 失败、重复关闭、单请求、多兼容请求;step 模式改动还要测试部分进度与 runner 状态清理。

八、其余四个子模块的契约与不变量

8.1 Model Integration:注册表即选择边界

设计文档 diffusion_model_integration.md 的代码路径为vllm_omni/diffusion/models/**vllm_omni/diffusion/model_loader/**(相关:layers/**lora/**utils/**)。其职责是流水线契约、注册、checkpoint 加载、适配器、共享层与模型特定处理。

不变量:

  • DIFF-MODEL-INV-001:流水线必须声明其支持的模态、配置、输入、输出、加载路径与运行时能力;
  • DIFF-MODEL-INV-002:运行时必须通过 registry 或 loader 契约选择模型实现,而非散落的模型名条件分支;
  • DIFF-MODEL-INV-003:流水线代码不得拥有准入、批处理、取消或跨 stage 路由;
  • DIFF-MODEL-INV-004:模型目录应只包含真实的模型差异(共享行为保持共享)。

Safe-change 指南要求测试:registry 选择、checkpoint 加载、最小推理、输入输出契约,以及每个已声明的可选能力。

8.2 Continuous Batching:显式兼容与逐请求隔离

设计文档 continuous_batching.md 的代码路径为vllm_omni/diffusion/sched/**(相关:executor/**),验证在 tests/diffusion/batching/。它定义扩散请求何时兼容、如何共享执行步、以及每个请求如何独立推进。

不变量:

  • BATCH-INV-001 兼容性显式:只有当所选流水线、调度器步骤、形状、精度与执行特性所需的所有属性都兼容时,请求才可共享批次;
  • BATCH-INV-002 逐请求状态隔离:批次组装必须保留每个请求的随机生成器、进度、conditioning、输出、取消与错误;
  • BATCH-INV-003 准入有界:准入必须遵守配置容量,不得依赖无界的等待或活动请求集合;
  • BATCH-INV-004 批次顺序≠完成顺序:输出关联必须使用稳定请求身份,而非跨执行步的 batch 位置。

Safe-change 指南:测试异构请求、部分完成、取消、确定性种子、容量限制,以及 batch size 为 1 和多个的场景。

8.3 Parallelism:拓扑单一真相源

设计文档 parallelism.md 的代码路径为vllm_omni/diffusion/distributed/**vllm_omni/diffusion/attention/parallel/**(相关:vllm_omni/distributed/**vllm_omni/config/composable_parallel/**)。其职责是秩拓扑、进程组、张量与序列分片、集合通信与分布式执行。

不变量:

  • PARALLEL-INV-001 拓扑单一真相源:秩坐标、组成员与并行维度必须从校验过的配置推导;
  • PARALLEL-INV-002 分片契约显式:每个分布式边界必须定义张量形状、分片维度、放置、dtype、生产者与消费者;
  • PARALLEL-INV-003 集合通信对称:进程组成员必须以相同逻辑顺序调用兼容的集合通信;
  • PARALLEL-INV-004 单秩路径有效:分布式实现应保留一个无需分布式初始化的受支持单秩路径。

Safe-change 指南:测试拓扑校验、单秩执行、受影响的并行模式、组合模式、非法形状与有序销毁。

8.4 Offloader:驻留、就绪与有界内存

设计文档 offloader.md 的代码路径为vllm_omni/diffusion/offloader/**(相关:models/**worker/**),上游参考为torch.nn.Module.to。其职责是组件驻留、迁移调度、内存记账、预取与销毁。

不变量:

  • OFFLOAD-INV-001 驻留显式:每个被管理组件必须有一个已知驻留状态与一个负责转换的所有者;
  • OFFLOAD-INV-002 使用跟随就绪:组件迁移到目标设备完成之前,运行时不得消费它;
  • OFFLOAD-INV-003 迁移保留模型状态:offload 必须保留参数与 buffer 的身份、dtype、设备,以及所选执行模式所需的正确性;
  • OFFLOAD-INV-004 内存有界且释放:保留的主机与设备副本必须遵守配置上限,并提供确定性销毁。

此外,allocator-cache 保留必须局限于显式组件所有者、同时声明 cache 与物理空闲内存边界、在遥测不可用时保守释放,并在失败或内存压力时强制释放;它不得取代无条件的执行器关闭清理。相关配置与实现见 offloader/config.py 与 offloader/base.py。

Safe-change 指南:测试启用与禁用路径、重复执行、异步迁移、内存上限、失败、销毁与数值等价性。

九、总结:一次代码评审的完整检查路径

结合 diffusion.md 的家族级检查与五份子模块文档,评审一个 diffusion 相关改动时建议按以下路径走查:

  1. 先定子模块:改动落在 Runtime(引擎/调度/执行器/worker)、Model Integration(模型/注册/加载)、Batching(调度兼容性)、Parallelism(分布式)还是 Offloader(内存)?加载对应子模块文档与其不变量。
  2. 验证生命周期纪律:请求是否只有一个调度器所有者?可选功能是否走钩子而不是新建生命周期?(INV-001/INV-004)
  3. 验证选择边界:模型选择是否通过 registry/loader?是否引入新的model_name条件分支?(DIFF-MODEL-INV-002)
  4. 验证身份与兼容性:结果是否按request_id而非 batch 位置映射?批次兼容是否显式、逐请求状态是否隔离、准入是否有界?(BATCH-INV 系列)
  5. 验证分布式纪律:拓扑是否来自校验配置、分片契约是否显式、集合通信是否对称、单秩路径是否保留?(PARALLEL-INV 系列)
  6. 验证内存纪律:offload 组件是否有唯一驻留所有者、就绪后才被消费、状态是否保留、副本是否有界?(OFFLOAD-INV 系列)
  7. 对照测试证据:按第三节的 safe-change 映射表运行对应单元测试,并补齐成功/取消/逐请求失败/致命故障/重复关闭/单请求/多兼容请求的覆盖。

通过这套自顶向下的检查路径,可以在不改动一行代码的情况下快速定位绝大多数设计级缺陷,这也是该文档家族作为"设计索引 + 评审锚点"的核心价值所在。

【免费下载链接】vllm-omniA framework for efficient model inference with omni-modality models项目地址: https://gitcode.com/GitHub_Trending/vl/vllm-omni

创作声明:本文部分内容由AI辅助生成(AIGC),仅供参考

需要专业的网站建设服务?

联系我们获取免费的网站建设咨询和方案报价,让我们帮助您实现业务目标

立即咨询