跳转到正文

操作 sleep / wake

本文目录

本文说明怎样休眠整个部署、部分副本或 PD 角色以释放显存,并在需要时唤醒、确认服务恢复。

适用场景:多个模型轮流使用 GPU,暂时不用的实例需要释放显存并保留容器。休眠会丢弃 KV cache 中的请求历史,不会在唤醒时恢复旧请求状态。

前置条件:

  • 部署使用 vLLM,并在创建时打开了可休眠。支持单机和普通多机副本;SGLang 不支持。
  • PD 部署的 KV 传输使用以太网时可以休眠;使用主机 RDMA 网络传 KV 时不能开启可休眠(PD_SLEEP_RDMA_UNSUPPORTED)。普通多机部署通过 RDMA 做集合通信不受此限制。
  • L1 需要主机内存容纳卸载的权重;主机可用内存扣掉余量后放不下时,平台拒绝 L1(409 SLEEP_HOST_MEMORY_INSUFFICIENT),改用 L2,并确保唤醒时原模型目录仍可读。
  • 同卡部署多个模型的完整流程见一张 GPU 跑两个模型;自定义镜像等边界见限制。

两种级别

级别休眠时唤醒时适用
L1(快速)权重挪到主机内存,KV cache 丢弃从内存恢复权重,重新分配空的 KV cache主机内存够用
L2(深度)权重直接丢弃,不落盘;KV cache 丢弃从原模型目录重新加载权重,恢复 KV cache 空间并清理前缀缓存主机内存不够,能接受重新加载权重的耗时

KV cache 保存请求历史 token 的 Key/Value;休眠会丢弃这些内容,唤醒只重新分配空的缓存空间。前缀缓存利用 KV cache 复用已计算过的公共前缀;L2 重新加载权重后会清除旧的复用记录,L1 保留主机内存中的权重,直接恢复即可。

L2 没有“占用哪个磁盘”的配置项;唤醒读取的仍是部署挂载的模型目录。NFS 不可用时,重新读取可能卡住或失败。

休眠时在途请求怎么办

休眠确认框中选择:

  • 等待完成(默认):引擎跑完正在处理的请求再睡。长请求会推迟休眠,agent 单次指令上限为 10 分钟。
  • 立即中止:正在处理的请求立即收到错误。

确认框里还有一项有请求时自动唤醒,决定这次休眠之后请求来了怎么办:

  • 勾选:网关挂起请求并唤醒部署,醒后放行。部署仍按自己的出让策略和别的部署轮流用卡:它睡着时别人可以用这些卡,有请求时再按规则要回来。
  • 不勾选:保持休眠,请求一律回 503,直到有人手动唤醒(或定时计划唤醒)。

默认值由服务端按部署的出让策略给出(部署详情的 sleep_wakes_on_request):出让策略不是不自动出让的部署默认勾选,因为它本来就同意按需让卡、按需要回;不自动出让的部署默认不勾选。副本和 PD 角色的休眠框也有这一项。

指令发出后,网关立即停止向这次选中休眠的实例转发新请求。其余可服务的清醒副本继续接收请求;没有可服务的清醒副本时,网关才返回 HTTP 503,信息为 model is asleep; wake it first (console, or POST /api/v1/deployments/<id>/wake; a schedule or a waiting wake may also wake it)。你手动下的休眠如果是保持休眠(上面没勾选有请求时自动唤醒),网关不会因为请求唤醒它;定时计划或唤醒等位可以替你唤醒。勾选了的,以及平台自己让它睡下的(按出让策略让卡),有请求时会被自动唤醒,见调度分析。保持按实例算:你只休眠一个副本,就只保持这个副本;同一部署里平台让卡睡下的其他副本,请求照样能唤醒。部署详情的休眠提示据此显示“手动休眠,请求不会唤醒”“部分副本手动休眠,请求只唤醒其余副本”或“有请求时会自动唤醒”,每个实例被保持时另有“手动休眠”标签。

已经保持休眠的部署,提示旁边有允许请求唤醒按钮:它解除全部保持,但不唤醒任何副本,部署照旧睡着,之后有请求时才被唤醒,也重新加入按出让策略的轮流用卡。部署整体的休眠命令随之撤销,之后新起的副本是醒着的。API 为 POST /api/v1/deployments/{id}/wake-on-request,返回 {"released":[实例 UUID]},没有被保持的实例时为空列表;时间线记 SLEEP_HOLD_RELEASED(带操作人)。

休眠整个部署

  1. 打开部署详情,选择 L1 或 L2 休眠。引擎不能休眠的部署(没打开可休眠,或引擎不支持休眠)不显示休眠、唤醒控件,是否显示由服务端在部署详情的 schedule_capabilities.sleep 里告知。
  2. 在确认框选择等待完成或立即中止,再确认。
  3. 等待部署读作 asleep 且 sleep_level 显示所选级别;实例仍为 running。若只完成一部分,按副本查看状态和时间线中的失败原因,不要把指令已发出当作全部休眠成功。

API 为 POST /api/v1/deployments/{id}/sleep?level=1|2&mode=wait|abort&wake_on_request=true|false,wake_on_request 不填时取部署的默认值(sleep_wakes_on_request),其他取值返回 400 SLEEP_INVALID_WAKE_ON_REQUEST;应答带 wake_on_request,时间线的 SLEEP_ORDERED 也记下它。勾选时平台按副本逐个下令,部署整体不处在休眠命令下;只有保持休眠才把整个部署置于休眠命令下(之后新起的副本同样睡着、同样保持)。

怎么确认部署睡着了

部署详情和部署列表的每一行都带三个回答「睡没睡」的字段,不必逐个实例去数:

字段含义
state这一行唯一该显示的状态:整体睡着为 asleep;指令已被接受、网关已经不派发但还有引擎没睡下去为 sleeping;删除中为 deleting,优先于其他一切
asleep_replicas因睡眠不被网关派发的副本数。指令刚发出、引擎还在换出显存的时候就已经计入,因为这个副本确实已经不接收请求了
sleep_level引擎上报的级别(1 或 2);还没睡下去时没有值,缺省不能当成「没睡」

runtime_state 在这些时候一直是 running:睡着的引擎进程还在跑,只是网关不向它派发。判断睡眠看 state,不要看 runtime_state。

只睡了一部分副本(或只睡了一个 PD 角色)时部署仍能服务:state 保持 running,asleep_replicas 给出睡着的副本数,列表里对应的读数就是部分休眠 · k/N 个副本。 asleep_replicas 与 ready_replicas 是同一组副本的两种计数,两者相加是网关够得到的副本数;因其他原因挂掉的副本(停止、失败、节点失联、多机缺 rank)两个都不计,也不会被算成睡着。

一个可服务的副本都不剩时(实例已停止或已失败)不算睡着:没有东西可唤醒,state 给出失败或停止本身的状态,asleep_replicas 为 0。

字段定义、优先级与 PD 各角色的计数见 API 参考:部署的睡眠状态。

只睡一部分:副本与 PD 角色

多副本部署可以只让一部分休眠,其他副本继续服务:

操作范围入口与条件
单个副本在副本 leader 的实例面板点击休眠副本(L1)或唤醒副本。只有一个副本时使用部署级按钮。多机按整个副本一起睡醒,不能单独操作 follower
PD 的一个角色在部署详情点击休眠 Prefill(L1)。只提供该 PD 模式允许为空的角色;vLLM NIXL 下为 prefill,全部休眠后由 decode 完成 prefill,不计降级。decode 只能随整个部署休眠,最后一个清醒的 decode 也不能单独休眠(SLEEP_ROLE_CANNOT_EMPTY)

单副本 API 为 POST /api/v1/instances/{uuid}/sleep?level=&mode= 与 POST /api/v1/instances/{uuid}/wake;角色休眠为 POST /api/v1/deployments/{id}/sleep?role=prefill。

确认后检查选中范围的状态。部署这一行的读数见上一节:只睡了一部分副本时 state 仍是 running, asleep_replicas 数出睡着的副本,列表里显示部分休眠 · k/N 个副本;只有全部所需副本都睡着、网关不再接受任何请求时,state 才变成 asleep/sleeping。

重建后的睡眠状态取决于休眠范围:

  • 整个部署休眠:新建或失败后重建的实例也按该级别启动。
  • 单副本或单角色休眠:它们被重建后是清醒的。

L1 休眠前的主机内存检查

L1 把权重挪到主机内存。休眠前,平台按本节点上将要休眠的实例估算要搬的权重大小(多机副本每个 rank 按分摊份额),与节点最近一次上报的可用内存比较:需要量超过“可用内存减去余量”时拒绝,余量取主机总内存的 5% 与 4 GiB 中较大的一个。拒绝返回 409 SLEEP_HOST_MEMORY_INSUFFICIENT,参数含 node、need_gib、available_gib,改用 L2 即可。节点没有最近的主机内存观测时不判断,由你决定。

已经做过一次 L1 休眠的引擎不再计入。vLLM 第一次 L1 休眠时把权重拷进锁页的主机内存,之后醒着也一直占着、不还给系统;平台在每个可休眠实例启动后都会做一次 L1 预热,所以这块内存从启动起就已经占着,节点上报的可用内存里也已经扣掉了。再按权重大小算一遍,等于同一块内存算两次,会把不需要新内存的休眠拒掉。agent 在预热或某次 L1 休眠成功后上报这一点,实例换了新进程(重建、重启)就重新计入,直到它自己的预热完成。agent 版本较旧、不上报时,仍按权重计入。

占着的量因模型而异,规划主机内存时按实测算:L20 上 7B/14B 约为权重的 1.9 倍;H20 上 TP8 的 DeepSeek-V4.1-Flash、GLM-5.3-Flash 分别为显存权重的 1.44 倍、1.78 倍。L2 休眠也不会把它还回去。

休眠后这张卡能做什么

休眠实例只在每张 GPU 上占它的残留(CUDA 上下文、分配器池、CUDA graph 池、多卡时的通信缓冲),卡上其余显存可以让给别的部署。残留按实例记,不再是固定常量:

  • 实测:实例独占这几张卡、卡上没有平台外进程时,agent 在休眠成功约 1 秒后读卡的已用显存,作为这个实例的残留。
  • 估算:卡与别的实例共用,或读不到时,由平台按模型估算。参数量不超过 3B、30B、200B、更大分别取 0.75、1、1.5、2.5 GiB;加 0.5 GiB 的 CUDA graph 池(按开启计);引擎跨多于 1 张卡再加 0.5 GiB,跨 8 张及以上加 1 GiB;结果限制在 0.75–4 GiB。模型大小未知时按 1.5 GiB。参数量由权重字节数和已存的精度推出。

没有实测值时用估算,不会当作 0;实测值保留到该实例下一次休眠重新测量。多机副本的 follower 随 leader 的休眠状态计账。

部署评估放不下时,可按页面的释放显存建议点击休眠并重新评估。评估中的可用显存已扣掉残留。

让出的容量是真的让出:卡被别的部署占满后,休眠实例唤醒时可能放不回,这是明示的语义(409 WAKE_INSUFFICIENT_GPU_MEMORY),不是缺陷。

为什么不继续给休眠实例保留原有分配权:那样休眠对“多个模型轮流用一张卡”没有意义,你能让出的显存也被白白锁住。代价是唤醒没有保证;需要保证唤醒的场景,请让这几个部署各占各的卡。实测读的是整卡的已用显存,偏高,方向安全;估算只是经验值,可能偏高或偏低;多个实例共卡时,休眠实例始终用估算。

唤醒

  1. 在部署详情或副本面板点击唤醒;部署级 API 为 POST /api/v1/deployments/{id}/wake。

    唤醒任一副本会撤销部署整体的睡眠命令,其余已休眠副本继续睡,各自的保持也不变:唤醒只解除被唤醒副本的保持。

  2. 如果返回 409 WAKE_INSUFFICIENT_GPU_MEMORY,按提示查看卡号、缺口 GiB 和占用者。可以先停止或休眠占用者再试,也可以让平台代劳,见下面的放不下时:等位与让位。部署级默认全部可容纳才唤醒;多个休眠副本被拒绝后,可选择唤醒放得下的副本(?partial=true)。多机按整个副本判断,任何一个 rank 放不回,整个副本继续休眠。 卡被平台外的进程占着(平台看不到它占多少)时,唤醒被拒绝,返回 409 WAKE_GPU_HELD_OUTSIDE,参数与上一条相同,refused[].held_outside 为 true。先在节点上释放该进程,再唤醒;等位和让位都不能绕开这一条。agent 也会检查平台上的实例全部在休眠的卡:休眠引擎自己的进程号已知时,才能把它们和平台外的进程区分开。

  3. 等到 state 不再是 asleep/sleeping(回到 running 或实例正在重建的状态),再重试 /v1 请求,确认服务恢复。部分唤醒时还需检查其余副本的显存差额,不能据一个请求成功认定所有副本都已清醒:部署仍可能读作 running 而 asleep_replicas 大于 0。

唤醒中的实例已按完整显存计账,避免等待 agent 回报期间重复分配同一张卡。

放不下时:等位与让位

唤醒被 WAKE_INSUFFICIENT_GPU_MEMORY 拒绝后,界面提供两个按钮,API 对应两个参数:

做法入口效果
等位等位唤醒,?wait=true放得下的先醒,其余等卡腾出来,服务端在容量释放后自动唤醒;等满 30 分钟放弃并写时间线(这个时限由服务端给出,见部署详情的 wake_wait_limit_sec)
让位让占用者休眠后唤醒,?yield=true,可加 &yield_level=1|2(默认 1)先让占着所需卡的醒着的部署休眠,再把唤醒放进等位,对方睡下后自动完成
curl --fail-with-body -sS -X POST \
  "$API_URL/api/v1/deployments/7/wake?wait=true" \
  -H "Authorization: Bearer $TOKEN"

全部放得下时返回 200 {"status":"waking","woken":[...],"waiting":[],"yielded":[],"yielded_held":[]};有的要等则返回 202 {"status":"waiting",...},waiting 是在等的实例,yielded 是被让位休眠的部署名,yielded_held 是其中被保持休眠的那些。单个实例用 POST /api/v1/instances/{uuid}/wake?wait=true。

让位的细节:

  • 占用者默认休眠到 L1;它所在节点的主机内存放不下 L1 时自动改 L2。可用 yield_level=2 直接指定 L2。yield_level=1 就是出让策略的 auto:先 L1、放不下退回 L2,不会因为放不下 L1 而拒绝整个让位唤醒;让卡和让位唤醒用的是同一条规则。
  • 占用者里有不可休眠的部署、PD 里最后一个醒着的角色,或卡被平台外进程占着时,整个请求被拒绝,返回 409 WAKE_YIELD_BLOCKED(occupants 列出名字),什么都不会改动。
  • 被让位休眠的部署按它自己的出让策略处理:出让策略不是不自动出让的,有请求时会被唤醒,按规则把卡要回来(和平台让卡一样,不会因为一次让位唤醒就退出轮流用卡);不自动出让的保持休眠,除非另有定时计划或有人唤醒,它不会自己醒来。时间线记 YIELDED_FOR_WAKE,参数 wake_on_request 说明是哪一种;界面的结果提示也分开列出。

等位一旦开始,等位实例的保持休眠就解除了:它们是要醒的,等位期间到达的请求由网关挂起、等这次唤醒,驻留仲裁也可以按各自的出让策略为它腾地方,而不是回 503(以前要等唤醒落地才解除)。没在这次唤醒里的实例保持不变。

保持休眠(你没勾选自动唤醒的休眠、定时计划的休眠、让位唤醒让不自动出让的占用者下的休眠)不为自己留卡:请求唤醒不了它,它的卡对任何新部署开放,所以卡可能在你唤醒它之前就被别的部署占了。之后的唤醒要么等位、要么让位,就是上面两种做法。平台自己让卡的休眠则相反,请求能唤醒它,共卡的部署睡着时会为这次唤醒留着卡,见出让策略:几个部署怎样共用一批 GPU。

部署在等位期间,详情页显示等位横幅和起点时间(部署的 wake_waiting_since)。要放弃等位,点取消等位,或调用:

curl --fail-with-body -sS -X DELETE \
  "$API_URL/api/v1/deployments/7/wake-waiting" \
  -H "Authorization: Bearer $TOKEN"

返回 200 {"items":["<实例 UUID>"],"total":1},列出被撤销的实例。等位、让位与定时计划、出让策略一起构成调度分析;调度看板上能看到谁在等位。

休眠或唤醒失败时,先查看实例时间线:

一个实例休眠失败时,仅回退它自己的意图及仍生效的部署整体命令,已休眠的其他副本不会一起唤醒。再按实际状态能否确认,选择后续处理:

结果后续处理
实际睡眠状态可确认平台保留已确认的实际休眠级别和失败原因,仅将仍对应这次失败指令的期望回退到该级别。处理原因后重新点击对应按钮;失败指令不会自动重试
状态无法确认,或 L2 唤醒已部分分配显存后失败,或引擎对休眠指令回了错误、却又自称已休眠(权重可能只卸了一半)实例标为失败,保留完整显存占用并禁止网关转发;平台移除并重建这一代实例。等待重建结果,不能按休眠残留估算其可用显存

限制

  • 只支持 vLLM;SGLang 不能休眠(创建时就会拒绝声明可休眠)。
  • 除 NVIDIA 外,昇腾 910C、PPU ZW810E、海光 K100 已真机验证;Apple 节点不支持引擎休眠。各组合所测的镜像版本与额外限制见厂商边界。
  • PD 部署的 KV 走主机 RDMA 网络时不能声明可休眠(PD_SLEEP_RDMA_UNSUPPORTED):NIXL 把 KV cache 显存注册给 RDMA 网卡, 引擎休眠释放这块显存后唤醒时申请不回来(实测报 CUDA out of memory)。KV 走以太网的 PD 部署、经 RDMA 走集合通信的普通多机部署都可以休眠。
  • 自定义镜像不做探测:以引擎能力声明为准,镜像缺 sleep 端点时休眠会在实例事件里报错。
  • 引擎的 sleep 端点由 VLLM_SERVER_DEV_MODE=1 打开,前提是引擎只监听本机、经 agent 隧道 访问;部署形态改变时要重新审视这一点。
  • 停止实例与 sleep 不同:stop 会真正停止并删除运行容器,需在部署详情里点启动(POST /api/v1/deployments/{id}/start)才能恢复。

这篇文档有帮助吗?