架构说明
部署启动配置的语义
本文目录
部署页里能看到的每个参数、环境变量、挂载和命令,最后都落成一份启动配置,实例启动只读这一份。本文解释这份配置怎么来、“没填”和“清除”和“冲突”各是什么意思、命令模式有哪三档,以及存量部署如何解释这些配置。操作步骤见部署模型与解释调度结果。
一套参数字典,一次物化
是什么
启动配置有一个单一事实源:服务端的参数字典。字典一行一个参数,持有 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)会被拒绝,而不是悄悄覆盖。 - 每一项从哪一层来、谁覆盖谁,见部署启动参数来源。
这篇文档有帮助吗?