操作指南
部署模型与解释调度结果
本文目录
本文说明怎样把模型部署成可调用的推理服务,检查放置结果,并在部署后调整节点范围。
前置条件:
- 至少一个在线节点,见接入节点。
- 模型有目标节点可读取的完整副本(下载完成或已登记),或可下载、复制到目标节点,见下载、缓存和节点间同步模型。
- 需要的运行镜像可在目标节点获取;离线环境见离线环境部署。
步骤
选择模型和运行方案
在部署页选择已登记的模型,或搜索内置目录中的具体模型,再选运行方案。模型与方案分别检索,同名方案以来源和名称区分。目录中没有所需组合时,可以使用自己的镜像和配置。
模板列表的芯片筛选会同时核对厂商、型号、适用的计算能力和架构 ID,并遵守目录中的不支持规则;匹配更具体的配方优先。缺少或不一致的架构 ID 不会因为 GPU 同名而通过筛选。模板详情的兼容性警告和默认引擎使用同一套规则,命令预览由平台评估选择节点。
部署页的芯片匹配推荐限定在所选节点;未固定节点时,限定在目标厂商的在线节点范围。它只表示该范围内有匹配的芯片,不保证手动指定的 GPU、内存或其他部署条件可用。修改节点或目标厂商后,等待新范围的结果;最后仍以当前草稿的部署评估为准。
如果表单提示这个部署不会暴露任何推理接口,先到模型页设置所需接口。模型和所选模板配方都没有声明接口时,部署不会出现在试验场,也不能开启健康检查;模板配方声明的接口会补给接口为空的模型,包括接口列表为 []、登记时未识别出任务或后来被清空接口的模型;已有接口的模型保持原样。
选择部署形态和节点
-
选择放置方式,三种形状使用同一个控件:
方式 怎样选择节点 自动 单机:每次启动副本都从候选节点中选一台放得下的;可在限定节点中进一步列出范围。多机与 PD:创建时由平台按空闲卡为请求没写的 rank 或单元挑节点(每个副本、每个 PD 部署只在一张计算网络、一种 GPU 架构内选),挑中的节点写进部署,单元启动时再按当前空闲卡试算,放不下才换节点。页面显示候选数量及当前首个副本的节点、GPU 试算结果 手动 单机:固定到一台节点,可指定 GPU 序号。多机与 PD:每个 rank、每个 P / D 单元的节点(PD 还可以钉卡)都由你指定并按此钉死;只有节点失联时仍按节点失联重调度处理 -
按需填写节点标签及硬件与网络条件,包括 GPU 型号、架构、计算网络、存储同步网络和服务网络。同类多选满足其一,不同条件必须同时满足;手动选择也不能绕过条件。按需设置并行度、dGPU 显存上限和副本数。
放置选项决定同一种候选里谁优先:单机默认分散副本,优先选择本部署副本较少的节点;也可选集中,优先填满剩余资源较少的节点,见调度与显存估算。多机与 PD 部署没写放置策略时默认集中(binpack,自动与手动都是):它们一次要一整组卡,集中放能给下一个部署留下完整的空节点;自动放置的 PD 在集中时,只要一台节点放得下它全部的单元,就都放在这一台,选分散则尽量让 prefill 与 decode 在不同的节点。节点条件会在每次启动副本前重新检查,标签、换卡或网络变化不会自动迁移运行中的实例。
确认启动配置、镜像和权重
- 在快捷部署中填写常用参数,需要全部参数时切换到专家部署。两种视图共用草稿,切换不会重置环境变量、挂载或手工命令。未改控件使用默认值,字典外的 flag 填入自定义参数;未设置与清除的区别及冲突处理见部署启动配置的语义。
- 确认运行镜像。可直接填私有或专用镜像地址,无需先登记到镜像目录;更换镜像会保留本次参数与启动方式。启动方式默认由引擎生成命令,也可显式选择镜像入口或手工命令,区别见命令模式。镜像兼容性未知时会提示,已知的资源和放置冲突仍需处理。
- 确认权重来源(Hugging Face 或 ModelScope)和保存到的存储。模型、镜像的实际下载地址及节点复制按拉取设置决定。自动调度尚未选出节点时提示调度后获取;指定节点后查看逐节点获取预估。存储限制见部署时选存储。
- 按需设置开启健康检查和超时阈值。支持对话、文本补全、向量或 System One 决策接口的新部署默认开启,默认阈值 60 秒,可设 1–600 秒。
健康检查每分钟经网关发送最小请求:对话或补全输入“1”、只生成 1 个 token,向量接口输入“1”,决策接口对状态“1”问一个是/否问题。它不会重启或摘除副本,也不计入网关请求数、token 和延迟统计,引擎自身指标仍可能包含这些请求。
检查结果的含义:
- 正常:在阈值内回复。
- 超时:超过阈值。
- 失败:返回错误或连不上副本。
- 无可用副本:没有可用的清醒副本,此时不发请求。
推理服务列表与详情并排显示的三类信息用途不同:
- 状态描述部署运行情况。
- 健康是最近一次最小请求的结果。
- 副本显示运行中 / 期望数,不能用一个健康结果代替全部副本的就绪情况。
评估并部署
-
等待当前草稿的评估完成。处理字段旁或页面级的错误,查看显存拆分、token 容量和调度解释。
-
核对命令、配置环境、准备脚本、挂载和容器参数。多机命令按 rank 展示与复制,不能把多个 rank 的脚本拼成一条;修改配置后等待新的评估结果再提交。
命令预览中的配置环境仅包含本次配置产生的变量,不等于容器最终进程环境。镜像目录不保存启动配置,部署按模板与本次输入启动;配置环境与镜像内置环境的关系见配置环境与镜像环境。
-
点击部署,打开详情观察模型准备、镜像获取及实例启动状态。等待节点时查看等待原因、最接近的节点,或点击查看候选节点逐台检查限制。
-
实例就绪后,用详情中的调用示例或试验场发起一次请求,确认获得预期响应。启动失败时保留的实例和日志可用于检查镜像、模型文件、端口与运行时,再改参数重试,见查看指标与检索日志。
参数来源与 SGLang 自动生成的日志环境、准备脚本分别见部署启动参数来源和 SGLang 日志说明。
表单中的开放分词接口默认开启,网关将 /v1/tokenize、/v1/detokenize 转给该部署的引擎,不计入请求统计。详情里可以随时开关,无需重启,见分词接口。
表单中的请求优先级默认开启:引擎按请求的优先级排队,优先级只由网关决定。引擎、加速卡或启动参数不支持时,开关旁写明原因;推理模板的调度参数冲突时可一键改用兼容的参数,见请求优先级。
部署后调整
在部署详情的服务概览中,直接修改单节点部署的期望副本数后点击应用。启用健康检查后,可直接修改阈值(1 至 600 秒),点击保存生效。修改期间可取消。
-
编辑部署:在部署详情点击编辑,部署页带着当前配置打开(地址为
/deploy?edit=<id>),表单、显存评估与命令预览与创建时相同,评估不计入该部署自身实例占用的显存。模型、模板、引擎、厂商、名称与对外模型名不能编辑,需要修改时点击克隆并修改,以当前配置新建部署。点击检查变更后确认框列出每个字段的旧值、新值与生效方式:- 副本数、路由、健康检查、分词、启动超时、节点条件等立即生效,不重启实例。
- 启动参数、额外参数、镜像、容器参数、并行度、请求优先级等需要重建副本,可选滚动替换(多副本且有副本在服务时默认)、全部立即重建(单副本、启动中或失败时默认,服务中断),或仅保存、下次重启时生效。已停止的部署只保存,可勾选保存后启动;休眠中的部署可选唤醒并按新配置重建。开启或关闭 dGPU、更换分区后端时只能全部重建,确认框会提示服务将中断。
- 启动失败的部署在失败提示旁点击修改参数并重试,改正参数后全部重建,重试次数重新计算。
编辑从部署保存的配置出发:没改的参数保持原值,模板在部署之后的修改不会被带进来。他人在你打开之后改过部署时,保存会提示重新载入。详见编辑部署。
-
单机部署的节点范围:在详情的节点条件旁点击编辑,修改节点、标签或分散/集中策略。保存只影响以后启动的副本;需要重新放置已有副本时,重启该副本。新条件下没有节点能容纳部署会被拒绝,原条件不变;镜像决定的厂商不能在此修改。多机与 PD 用调整副本修改 rank 节点;自动放置的多机与 PD 部署也可以在这里切换放置方式,见下。
-
增加单机副本时指定节点:在调整副本里选首次放置节点,或在
PUT /api/v1/deployments/{id}/replicas加place_on。它只决定新副本第一次在哪里启动,之后与其他副本一样,详见节点失联重调度。 -
切换多机与 PD 的放置方式:
PUT /api/v1/deployments/{id}/placement-mode、请求{"mode": "auto"}或{"mode": "manual"},在自动与手动之间切换,不重启实例,单元继续用现在的节点,之后单元启动时按新的方式处理。切到自动会同时去掉 PD 单元钉住的卡(启动时由调度器现挑)。单机部署返回 400PLACEMENT_MODE_SHAPE,它的放置写在节点条件里。部署详情的placement_mode给出当前方式。 -
节点失联重调度的等待时间:节点离线超过它(默认 10 分钟,0 为从不),副本自动换到别的节点,见节点失联重调度。
-
定时计划与出让策略:可休眠部署可以按周几和时刻自动休眠、唤醒或调整单机副本数,也可以用出让策略(不自动出让、闲置自动出让、按时自动出让、随时出让)与共卡的部署轮流用卡,见使用调度分析。
-
健康检查:详情中可开关或修改阈值,无需重启;API 为
PUT /api/v1/deployments/{id}/health-check。升级前已有部署默认不开启。 -
多副本路由:默认
least_request,可用PUT /api/v1/deployments/{id}/routing、请求{"routing_policy": "..."}改为prefix_affinity或failover。路由策略不属于引擎启动参数,修改不会重启实例。
同一个模型名的多个部署
一个部署的所有副本形状相同:张量并行、每副本卡数和启动参数对所有副本一致(编辑部署会把它们一起换成新配置),扩容时每台节点都按同一套配置试算,不会因为节点的卡更大而改成更小的 TP,也不会把单机副本拆到两台机器上。要让同一个模型在不同硬件上用不同配置(例如 RTX 2080 Ti 上 tp=2、RTX 8000 上 tp=1,或 NVIDIA 与昇腾同时提供服务),按硬件各建一个部署。
对外模型名(served_name)在部署之间唯一:已有部署(运行中或已停止)占用的名字,新建或克隆时返回 409 SERVED_NAME_IN_USE,参数里给出占用它的部署;正在删除的部署不再占用名字,可以立刻用原名重建。部署表单预填的对外模型名是模型名加 - 和 4 位随机小写字母或数字(如 Qwen3-0.6B-x7k2),可以手动改成别的名字;不填时服务端用模型名,被占用同样返回 409。克隆的副本也在原名后加同样形状的随机后缀。
这条规则之前建的、已经同名的部署保持原样,网关不在它们之间分流:请求交给最新创建的、当前能应答的那个部署,旧部署只在所有更新的部署都无法应答(全部休眠、失败或仍在启动)时接手。部署内各副本之间的分流仍按该部署的路由策略。
要让几套硬件一起承担同一个模型名的流量,给每个部署取不同的模型名,在网关前放一层按模型名聚合多个后端的路由,例如 LiteLLM:
model_list:
- model_name: qwen3-8b # 对客户端暴露的名字
litellm_params:
model: openai/qwen3-8b-2080 # gpuworks 部署的 served_name
api_base: http://<server>/v1
api_key: <gpuworks API key>
- model_name: qwen3-8b
litellm_params:
model: openai/qwen3-8b-rtx8000
api_base: http://<server>/v1
api_key: <gpuworks API key>这种组合下,各部署仍分别计量、分别休眠与扩缩;分流策略、权重与重试以所用路由的文档为准。
常见问题
提交失败时,错误会显示在页面上,同时带着下面这些稳定的错误码。更多排查见故障排查。
| 错误码 | 含义与处理 |
|---|---|
UNIT_PLACEMENT_NONE | 自动放置的多机或 PD 请求现在没有一组节点放得下(HTTP 409)。参数给出节点总数,以及各项检查各排除了多少台(unmet 不满足节点条件、cordoned 已停止调度、offline 离线、busy 空闲卡不够、no_network 没有可用的计算网络),largest 是同一计算网络、同一架构里最大的一组有几台可用节点(少于 rank 数,所以凑不成一个副本)。按数字最大的一项补齐条件,或改手动指定节点 |
AUTO_PLACEMENT_TP_REQUIRED | 自动放置的多机请求没写 placement.tp,平台不知道每台节点要多少张卡;填上 TP(和 PP) |
AUTO_PLACEMENT_PD_MULTI_NODE | 自动放置的 PD 单元必须一台节点放得下;某个角色的单元带了 followers(跨节点),给它写明节点,或不要用自动 |
AUTOMATIC_PLACEMENT_STALE | 评估之后资源被占走(比如其它部署占满了显存),或所选节点不再满足节点条件,自动放置的结果失效了。服务端不会悄悄换节点,回到部署页重新评估再提交 |
ACQUISITION_CANDIDATE_STALE | 请求指定的保存存储已不存在,或所选权重来源(Hugging Face / ModelScope)已不在模板里。重新评估后再提交,服务端不会替换 |
LAUNCH_CONFIG_CONFLICT | 同一个参数在表单字段和额外参数(extra_args)里给了不同的值。错误里会写出两处的值,只保留其中一处 |
LAUNCH_CONFIG_UNSET_CONFLICT | 某个参数在表单里被关闭(清除),但额外参数里还写着它。删掉那个值,或重新启用该参数 |
NODE_REQUIREMENTS_NOT_EDITABLE | 多机与 PD 部署按 rank 列节点,没有可编辑的节点条件;用“调整副本”改它们的节点 |
NODE_REQUIREMENTS_UNMET | 所选节点不满足部署的节点条件(标签、厂商等)。改选满足条件的节点,或调整条件 |
这篇文档有帮助吗?