跳转到正文

部署启动配置的语义

本文目录

部署页里能看到的每个参数、环境变量、挂载和命令,最后都落成一份启动配置,实例启动只读这一份。本文解释这份配置怎么来、“没填”和“清除”和“冲突”各是什么意思、命令模式有哪三档,以及存量部署如何解释这些配置。操作步骤见部署模型与解释调度结果。

一套参数字典,一次物化

是什么

启动配置有一个单一事实源:服务端的参数字典。字典一行一个参数,持有 key、类型、控件、默认值、别名,以及每个引擎对应的 flag。前端的参数表由服务端下发,不硬编码。

同一份配置在请求里可以有三种写法:类型化的字段(表单控件)、自由文本的 extra_args、模板(目录 spec)的 args。请求进入服务端时经同一个物化步骤合并成一份类型化配置,之后系统内部不再有第二种表示。

估算、调度、命令预览和实例启动读的都是这一份,所以屏幕上看到的值、显存估算用的值和引擎拿到的值一致(设计动机见 ADR 0020)。

合并优先级与默认值

同一个参数被多处陈述时,优先级是:显式字段 > extra_args > 模板 args > 字典默认值。

字典默认值由服务端在物化时统一应用:空表单与默认载荷产生同一条命令行,所以未改动的控件不再上报默认值。物化时默认值只是兜底,不会压过任何一处显式陈述;下列情况默认值不会补上:

  • 该参数被清除(见下)。
  • 当前启动入口不接受它——表单会隐藏这个控件,它的默认值就不算用户确认过的内容。
  • 它依赖的另一个参数没有开启(例如 KV 分层的伴随参数在对应层关闭时不启用)。

字典内外的 flag

  • 字典外的 flag 可以填进「自定义参数」(extra_args),原样进入命令行。
  • 字典内的 flag 如果写在 extra_args 里,物化时会被搬入对应的类型化字段,并在评估响应里以 moved 回显;页面会提示哪些键被搬走,extra_args 文本里只剩字典不认识的部分。

未设置与清除

状态含义对命令行的影响
未设置没有任何一处陈述过这个键不发射任何 flag,由引擎自己的默认行为决定
显式关闭布尔参数明确给了关闭值参数字典为该参数定义了关闭形式的 flag 时发射它
清除请求里的 quick_params_unset 列出该键该键从所有层移除(含模板 args),模板的值不会回填

要点:

  • 未设置就是“用户没有选择,引擎默认生效”。服务端不替引擎发明值;只有字典默认值这一层会在新请求里补足,见上文。
  • 显式“未设置”与关闭、空字符串是不同的状态:未设置的键不会发射到引擎,由引擎决定默认行为。日志级别控件里的「未设置」就是这种语义(详见 SGLang 日志注入)。
  • 清除标记用于“清空一个模板提供的参数”,例如清空模板带来的解析器。清除后模板的值不会回填,直到用户重新填写。quick_params_unset 里出现未知的键会被拒绝。

冲突怎么处理

同一个键被两处陈述时,只有“说了不同的值”才算冲突;同一个值说了两次只是重复,不报错。

错误码什么时候出现怎么改
LAUNCH_CONFIG_CONFLICT同一个键在字段与 extra_args 里出现不同的值。响应带 key、flag 以及两处的值只保留冲突的一处
LAUNCH_CONFIG_UNSET_CONFLICT请求既把某个键列入清除(quick_params_unset),又在 quick_params 或 extra_args 里给了它删除那个值,或取消清除。拒绝这种歧义,是为了不让被关闭的层悄悄吞掉手写的值

另外,本次请求显式陈述的值超出字典给的上下限时也会被拒绝。只检查本次请求陈述的值:模板 args 是受控的目录内容,存量部署早于这些规则,二者都不会因此被拒。

交给引擎决定的参数

有的参数平台判断这次启动可能不认(入口跑的程序或镜像里的引擎版本不接受这个 flag),这时平台不替用户填默认值,把它交给引擎决定;但这个判断可能误判,所以参数照样显示、照样可以打开或关闭,用户显式陈述的值照常发射,不会被拒绝。

表单上这类参数显示为「自动」:开关是「自动 / 开启 / 关闭」三态,滑块多一个「自动 / 指定」,选「自动」就不传参数,和命令一一对应。评估响应与模板详情的 engine_decides_param_keys 列出这些 key。

判断由引擎适配按最终启动参数与镜像里的引擎版本做(版本取镜像目录的记录,没有时读镜像 tag;请求没指定镜像时,按目标节点或目标厂商从镜像目录挑出的镜像):

  • SGLang sglang serve --model-type diffusion 跑的是 diffusion server,它只接受与 LLM server 共有的少数参数,其余一律报 unrecognized arguments 退出。gpu_memory_utilization(--mem-fraction-static)等 LLM 参数交给引擎;enable_cache_report 从 0.5.18、enable_metrics 从 0.5.21 起才套默认值,版本未知时交给引擎。log_level、quantization、trust_remote_code、data_parallel_size 照常。
  • sglang serve 不写 --model-type 时,SGLang 按模型目录(model_index.json 或 diffusion 注册表)自己选 server,平台无从判断,所以只套两个 server 都接受的默认值。
  • 入口不是平台认识的 SGLang 程序时,enable_metrics 交给引擎。
  • vLLM 的 enable_request_metrics(--enable-per-request-metrics)只在镜像表明为 vLLM 0.25.0 及以上、且参数里没有 --disable-log-stats 时默认打开。
  • 带 --omni 的 vLLM 启动不套 gpu_memory_utilization 默认值:vllm-omni 的 deploy 配置给每个 stage 各分一份显存(如 Fish S2-Pro 是 0.6 + 0.1),命令行的一个值会覆盖所有 stage。准入仍按字典默认值记账。

存量部署不受默认值影响。

带 --omni 的 vLLM 启动做拓扑校验时,GPU 数按 TP × PP × Ulysses(--usp)× Ring(--ring)× CFG 并行(--cfg-parallel-size)计算。

命令模式的三档

命令模式是一次部署对启动命令解释方式的选择。默认是 engine;image-entry 和 manual 必须是这次部署的显式选择。更换镜像或切换表单视图不会改变已选的模式(见 ADR 0022;三档的由来见 ADR 0013)。

模式谁拼命令适合
engine(引擎接管,默认)平台按引擎适配生成完整命令,忽略镜像 entrypoint系统镜像和目录里的方案
image-entry保留镜像 entrypoint,平台只把引擎参数追加为 cmd把 entrypoint 当启动器的社区镜像
manual用户的命令文本就是真源,引擎参数不再注入命令写死的专用镜像,或需要完全自己控制的专家

manual 是唯一接管完整命令的通道

manual 是唯一绕过参数字典的通道,边界要分清:

  • 命令文本是真源,参数表不再控制手工命令;估算不适用,页面会明示。所以不能把表单里的容量推导当成手工命令的实际容量。
  • 资源放置仍可编辑:节点、GPU、张量并行与 dGPU 显存限额仍由表单决定。
  • 平台仍会把命令里已有的 --port 改写为本次部署实际分配的端口;配置了引擎别名时,同样改写 --served-model-name。
  • 手工脚本可以选择是否包含准备步骤,见SGLang 日志注入 · 怎么自己接管。

engine 与 image-entry 不是例外:它们的引擎参数全部来自那一份启动配置。

多机与 PD 的手工命令

一个部署只存一段手工命令,多机的每个 rank、PD 的每个实例都运行它;各 rank 的差别靠平台变量表达:

  • 手工命令里写成 ${GPUWORKS_NODE_RANK} 这样带 GPUWORKS_ 前缀的名字,服务端在每个 rank 启动前把它们换成该 rank 的值,然后才交给 shell。变量词表见推理目录语法 · 变量展开。
  • 手工命令只认带前缀的名字。不带前缀的 ${MODEL_PATH}、${API_PORT} 以及脚本自己的变量都原样留给 shell,所以已有的单机手工命令逐字不变;本次启动没有给出的前缀名(单机上的 ${GPUWORKS_MASTER_ADDR})同样原样留下。
  • 多机 rank 与 PD 实例的手工启动保留系统层环境变量(VLLM_HOST_IP、参数网络网卡、PD side channel 等按 rank、按节点才知道的事实),层次与 engine 相同:系统 → 模板 → 用户;脚本里自己 export 的值最后生效。单机非 PD 的手工启动仍不含系统层。
  • 部署页在多机或 PD 时点「编辑命令文本」,编辑框从服务端生成的脚本初稿开始:每类 rank(PD 角色 × 是否 headless)一条引擎命令,放在一个按 ${GPUWORKS_PD_ROLE}/${GPUWORKS_HEADLESS}(非 PD 时只按 ${GPUWORKS_HEADLESS})分支的 case 里。初稿不含准备脚本与环境变量,准备脚本仍由平台按 rank 执行。同一类 rank 的命令有变量表达不了的差异(例如两个节点的 RDMA 设备名不同)时没有初稿,评估给出 MANUAL_DRAFT_UNAVAILABLE 提醒,命令不能从表单编辑。
  • 评估与创建拒绝看不出 rank 的手工命令:多机的命令必须引用 ${GPUWORKS_NODE_RANK} 或 ${GPUWORKS_HEADLESS},PD 的命令必须引用 ${GPUWORKS_PD_ROLE}(PD 实例跨多机时两条都要满足),否则返回 MANUAL_COMMAND_RANK_BLIND。这条规则不作用于已经存下的部署,它们照常启动。
  • 多机与 PD 部署只有手工命令能按 rank 展开。engine 或 image-entry 模式下的 Cmd 覆盖会原样交给每个 rank,评估与创建以 COMMAND_OVERRIDE_RANK_BLIND 拒绝;已经存下的部署同样不受影响。

配置环境与镜像环境

镜像是运行制品。引擎版本、框架、架构、获取地址,以及镜像里实际的 OCI ENTRYPOINT/CMD/ENV,都是镜像事实;它们与“本次配置的启动输入”是两类东西:

  • 没有节点检查过镜像时,OCI 内置环境、入口和运行中进程状态保持“未知”,不猜。
  • 部署预览里的“配置环境”只是本次配置产生的环境变量,不能冒充最终进程环境——真正的进程环境还包含镜像内置的部分。
  • SGLang 日志所需的环境和准备脚本由 SGLang 适配代码生成,页面展示的是服务端解析后的结果。

镜像目录不承载启动配置

部署的启动配置由参数字典、所选模板和本次用户输入经物化与启动方案解析确定,写进部署字段和目录选择快照。镜像目录只记录怎么拿到镜像(引用、获取地址、框架与版本),不提供任何会改写部署的默认配置,所以不会出现“评估后改了镜像目录,同一份部署重建时命令变了”的情况(ADR 0022、ADR 0031)。

  • 所有部署按同一套语义解释:命令模式默认 engine,image-entry 与 manual 只能由部署显式选择。早期快照里残留的 launch_contract 标记被忽略。
  • 部署自己的容器设置(环境变量、删除的环境变量、挂载、docker 参数、/dev/shm 大小、entrypoint 与命令)都在“容器覆盖”这一层。与平台托管项或专用字段重复的 docker 参数(如 --network、--shm-size、-e、-v、--entrypoint)会被拒绝,而不是悄悄覆盖。
  • 每一项从哪一层来、谁覆盖谁,见部署启动参数来源。

这篇文档有帮助吗?