创建计算集群、数据实验室或作业（按需拉起集群）时，页面底部提供高级配置区域。您可以通过键值对形式设置 Ray 运行时的扩展参数，用于满足调度控制、网络暴露、生命周期管理和弹性伸缩等场景的定制需求。
概述
AI DLC 的 Ray 计算实例基于开源 KubeRay 构建。每个计算集群和数据实验室对应一个
RayCluster 资源，每个按需拉起集群的作业对应一个 RayJob 资源。您在高级配置中填写的每一条参数，将按参数路径合并到最终提交的资源定义中。注意：
高级配置直接作用于底层运行时，参数填写错误可能导致实例创建失败或运行异常。建议在具备 Kubernetes 与 KubeRay 基础知识后使用，并先在测试环境验证。
适用范围
实例类型 | 对应资源 | 参数路径规则 |
计算集群 | RayCluster | spec.{group}.xxx |
数据实验室 | RayCluster | spec.{group}.xxx |
作业（按需拉起集群） | RayJob | 作业级字段为 spec.xxx，集群级字段为 spec.rayClusterSpec.{group}.xxx |
其中
{group} 为节点组，取值为 headGroupSpec 或 workerGroupSpecs。若实例包含多个工作节点组，请先在高级配置面板中选择目标节点组，再填写该节点组的参数，参数路径中无需填写数组下标。说明：
提交到指定集群或提交到集群组的作业不单独提供高级配置，其高级参数继承所选计算集群的配置。
平台管理的参数
以下配置由平台统一管理，不支持通过高级参数覆盖。填写后不生效，请通过控制台对应的配置项设置。
参数类别 | 具体范围 | 应改用的配置项 |
计算资源 | CPU 核数、内存大小、GPU 卡数、对象存储内存、自定义逻辑资源 | 创建页的资源配置或计算环境 |
节点组标识 | 工作节点组名称 | 创建页的节点组配置 |
实例数量 | 工作节点组的实例数、最小实例数、最大实例数 | 创建页的节点组实例数 |
容器配置 | 运行镜像、启动命令、启动参数、环境变量、资源声明 | 创建页的镜像配置与计算环境 |
节点组标签 | 节点组的标签配置 | 计算环境的节点标签 |
高可用配置 | 头节点高可用开关及其关联参数 | 创建页的启用高可用 |
运行时版本 | Ray 版本 | 不支持修改 |
注意：
通过高级参数指定特定工作节点组时，所填写的节点组名称必须与已配置的工作节点组名称一致，否则创建将失败。
填写方法
1. 在创建或编辑页面展开高级配置。
2. 单击添加参数，或从预置参数下拉列表中选择常用参数。
3. 在 Key 中填写完整参数路径。路径区分大小写，层级之间使用英文句点分隔。
4. 在 Value 中按字段类型填写取值：
字段类型 | 填写方式 |
String、Boolean、Integer | 直接填写取值，例如 true、600。 |
JSON 对象、JSON 数组 | 填写合法的 JSON 字符串，格式错误将导致提交校验失败。 |
5. 单击配置面板右上角的切换按钮，可通过 JSON 或 YAML 方式批量编辑多条参数。
示例：为头节点组添加调度容忍配置。
项目 | 填写内容 |
Key | 计算集群与数据实验室填写 spec.headGroupSpec.template.spec.tolerations；作业填写 spec.rayClusterSpec.headGroupSpec.template.spec.tolerations。 |
Value | [{"key":"dedicated","operator":"Equal","value":"ray","effect":"NoSchedule"}] |
注意：
系统仅校验取值的 JSON 格式是否合法，不校验字段语义。例如系统不会检查
nodeSelector 引用的节点标签是否存在。语义错误将在实例创建阶段被底层拒绝，导致实例进入异常状态或容器长时间处于 Pending 状态。参数说明
作业生命周期
以下参数仅适用于作业，路径前缀为
spec.，计算集群与数据实验室不支持。参数 | 类型 | 示例值 | 说明 |
spec.suspend | Boolean | false | 是否挂起作业。取值为 true 时不创建底层集群，作业不消耗计算资源但保留配置。 |
spec.submissionMode | Enum | K8sJobMode | 作业提交模式。取值为 K8sJobMode、HTTPMode、InteractiveMode 或 SidecarMode，默认为 K8sJobMode。 |
spec.shutdownAfterJobFinishes | Boolean | true | 作业结束后是否自动删除本次按需拉起的集群。 |
spec.ttlSecondsAfterFinished | Integer | 600 | 作业结束后延迟清理集群的等待时长，单位为秒。需在 shutdownAfterJobFinishes 取值为 true 时生效。 |
spec.activeDeadlineSeconds | Integer | 7200 | 作业的最长运行时长，单位为秒。超时后系统终止作业并标记为失败。 |
spec.deletionPolicy | Enum | DeleteCluster | 作业结束后的资源清理方式。取值为 DeleteCluster（删除集群及全部容器）、DeleteWorkers（仅删除工作节点，保留头节点用于查看日志）、DeleteSelf（仅删除作业记录）或 DeleteNone（不清理）。 |
spec.submitterConfig.backoffLimit | Integer | 2 | 提交器任务的失败重试次数上限。 |
节点组网络
作业参数路径 | 集群与实验室参数路径 | 类型 | 示例值 | 说明 |
spec.rayClusterSpec.{group}.serviceType | spec.{group}.serviceType | Enum | ClusterIP | 节点组服务类型。取值为 ClusterIP、NodePort 或 LoadBalancer。 |
spec.rayClusterSpec.{group}.enableIngress | spec.{group}.enableIngress | Boolean | false | 是否为该节点组的服务创建 Ingress。 |
spec.rayClusterSpec.workerGroupSpecs.idleTimeoutSeconds | spec.workerGroupSpecs.idleTimeoutSeconds | Integer | 300 | 工作节点空闲多长时间后被回收，单位为秒。仅工作节点组支持。 |
Ray 进程启动参数
以下参数对应
ray start 命令行参数，需以 JSON 对象形式整体填写。作业参数路径 | 集群与实验室参数路径 | 示例值 | 说明 |
spec.rayClusterSpec.headGroupSpec.rayStartParams | spec.headGroupSpec.rayStartParams | {"dashboard-host":"0.0.0.0"} | 头节点的 Ray 进程启动参数。 |
spec.rayClusterSpec.workerGroupSpecs.rayStartParams | spec.workerGroupSpecs.rayStartParams | {"block":"true"} | 工作节点的 Ray 进程启动参数。 |
容器元数据
作业参数路径 | 集群与实验室参数路径 | 示例值 | 说明 |
spec.rayClusterSpec.{group}.template.metadata.annotations | spec.{group}.template.metadata.annotations | {"prometheus.io/scrape":"true","prometheus.io/port":"8080"} | 为节点组容器注入注解，常用于监控采集配置。 |
spec.submitterPodTemplate.metadata.annotations | 不支持 | {"sidecar.istio.io/inject":"false"} | 为提交器容器注入注解。 |
spec.submitterPodTemplate.metadata.labels | 不支持 | {"app":"ray-submitter"} | 为提交器容器注入标签。 |
容器调度与运行属性
以下参数的路径前缀为
spec.rayClusterSpec.{group}.template.spec.（作业）或 spec.{group}.template.spec.（计算集群与数据实验室）。字段 | 类型 | 示例值 | 说明 |
nodeSelector | JSON 对象 | {"kubernetes.io/os":"linux"} | 按节点标签匹配调度。 |
nodeName | String | node-1 | 将容器调度到指定节点。留空表示由调度器自动选择。 |
schedulerName | String | default-scheduler | 指定使用的调度器名称。 |
priorityClassName | String | system-cluster-critical | 容器优先级类别，影响资源紧张时的抢占顺序。 |
serviceAccountName | String | ray-sa | 容器使用的服务账号。 |
automountServiceAccountToken | Boolean | false | 是否自动挂载服务账号令牌。建议在非必要时关闭。 |
dnsPolicy | Enum | ClusterFirst | 容器的 DNS 解析策略。 |
restartPolicy | Enum | Never | 容器退出后的重启策略。Ray 容器通常固定为 Never，由系统接管重建。 |
subdomain | String | ray-head | 容器子域名，用于生成稳定的 DNS 记录。 |
terminationGracePeriodSeconds | Integer | 30 | 容器收到终止信号后的优雅退出等待时长，单位为秒。 |
activeDeadlineSeconds | Integer | 3600 | 单个容器的最长存活时长，单位为秒。 |
shareProcessNamespace | Boolean | true | 同一容器组内的多个容器是否共享进程命名空间。 |
runtimeClassName | String | runc | 指定容器运行时类别。 |
hostNetwork | Boolean | false | 是否使用宿主机网络命名空间。 |
hostPID | Boolean | false | 是否共享宿主机进程命名空间。 |
hostIPC | Boolean | false | 是否共享宿主机进程间通信命名空间。 |
警告：
hostNetwork、hostPID 和 hostIPC 会降低容器隔离性。请仅在明确需要访问宿主机资源时开启，其余场景建议保持默认值 false。容器组附加资源
以下参数同样位于
template.spec. 路径下，取值均为 JSON 数组。字段 | 示例值 | 说明 |
tolerations | [{"key":"dedicated","operator":"Equal","value":"ray","effect":"NoSchedule"}] | 容忍指定污点的节点，用于配合专属节点池使用。 |
volumes | [{"name":"workspace","emptyDir":{}}] | 定义容器组级存储卷，供容器挂载使用。 |
imagePullSecrets | [{"name":"my-registry-secret"}] | 拉取私有镜像仓库所需的凭证。 |
initContainers | [{"name":"init-check","image":"busybox","command":["sh","-c","echo ready"]}] | 初始化容器，在主容器启动前执行。 |
hostAliases | [{"ip":"10.0.0.10","hostnames":["local.ray"]}] | 向容器内的 hosts 文件追加自定义域名解析。 |
topologySpreadConstraints | [{"maxSkew":1,"topologyKey":"kubernetes.io/hostname","whenUnsatisfiable":"DoNotSchedule","labelSelector":{"matchLabels":{"app":"ray-head"}}}] | 拓扑分布约束，控制同组容器在节点或可用区之间的分布，提升容灾能力。 |
容器级配置
以下参数的路径前缀为
template.spec.containers.，默认作用于 Ray 主容器。字段 | 类型 | 示例值 | 说明 |
workingDir | String | /home/ray | 容器进程的工作目录。 |
ports | JSON 数组 | [{"name":"custom-port","containerPort":18080,"protocol":"TCP"}] | 额外声明容器监听端口。 |
volumeMounts | JSON 数组 | [{"name":"workspace","mountPath":"/workspace"}] | 将已声明的存储卷挂载到容器内路径。 |
volumeDevices | JSON 数组 | [{"name":"raw-block","devicePath":"/dev/xvda"}] | 挂载块设备卷，用于需要绕过文件系统的高性能场景。 |
envFrom | JSON 数组 | [{"configMapRef":{"name":"ray-extra-env"}}] | 从配置项或密钥批量导入环境变量。 |
terminationMessagePath | String | /dev/termination-log | 容器异常退出时错误信息的写入路径。 |
terminationMessagePolicy | Enum | File | 终止信息的获取策略。取值为 File 或 FallbackToLogsOnError。 |
生命周期钩子
生命周期钩子用于在 Ray 进程启动或停止的不同阶段执行自定义脚本，路径前缀为
{group}.lifecycleHooks.，取值均为 JSON 数组。钩子 | 执行时机 | 示例值 |
preInit | 容器初始化之前，早于 Ray 进程与业务代码。 | [{"name":"pre-init","inlineScript":"echo pre-init","timeoutSeconds":30,"ignoreFailure":false}] |
preRayStart | Ray 进程启动之前，常用于环境自检和依赖预热。 | [{"name":"pre-start","inlineScript":"echo pre-start","timeoutSeconds":30,"ignoreFailure":false}] |
postRayStartBackground | Ray 进程启动之后异步执行，不阻塞节点上线。 | [{"name":"post-bg","inlineScript":"sleep 5","timeoutSeconds":60,"ignoreFailure":true}] |
preRayStop | 节点停止或缩容之前执行，常用于优雅下线和状态上报。 | [{"name":"pre-stop","inlineScript":"echo stopping","timeoutSeconds":15,"ignoreFailure":true}] |
每个钩子对象包含以下字段：
字段 | 类型 | 说明 |
name | String | 钩子名称，用于日志记录与问题定位。 |
inlineScript | String | 内联脚本内容。 |
timeoutSeconds | Integer | 脚本执行超时时长，超时按失败处理。 |
ignoreFailure | Boolean | 是否忽略执行失败。取值为 true 时，失败不影响节点继续启动或停止。 |
说明：
建议将
preInit 与 preRayStart 的 ignoreFailure 设为 false，避免环境未就绪时节点启动；将 postRayStartBackground 与 preRayStop 设为 true，避免辅助脚本失败影响主流程。生命周期钩子不支持提交器容器。弹性伸缩配置
以下参数在工作节点组配置了实例数区间（最小值小于最大值）时生效，路径前缀为
spec.rayClusterSpec.autoscalerOptions.（作业）或 spec.autoscalerOptions.（计算集群与数据实验室）。字段 | 类型 | 示例值 | 说明 |
version | Enum | v2 | 弹性伸缩组件版本。取值为 v1 或 v2，推荐使用 v2。 |
upscalingMode | Enum | Default | 扩容速率策略。取值为 Conservative（逐步扩容）、Default 或 Aggressive（快速扩容至目标规模）。 |
idleTimeoutSeconds | Integer | 300 | 全局默认的空闲缩容等待时长，单位为秒。可被节点组级的同名参数覆盖。 |
imagePullPolicy | Enum | IfNotPresent | 弹性伸缩组件容器的镜像拉取策略，与业务容器独立配置。 |
env | JSON 数组 | [{"name":"HTTP_PROXY","value":"http://proxy.example.com:8080"}] | 为弹性伸缩组件容器注入环境变量。 |
envFrom | JSON 数组 | [{"configMapRef":{"name":"autoscaler-config"}}] | 为弹性伸缩组件容器批量导入环境变量。 |
volumeMounts | JSON 数组 | [{"name":"certs","mountPath":"/etc/certs","readOnly":true}] | 为弹性伸缩组件容器挂载存储卷。 |
提交器容器
作业的
submissionMode 取值为 K8sJobMode 时，系统创建一个独立的提交器容器执行作业提交命令。提交器容器的字段规则与节点组容器一致，仅路径前缀不同，为 spec.submitterPodTemplate.spec.。类别 | 参数路径示例 | 说明 |
调度与运行属性 | spec.submitterPodTemplate.spec.serviceAccountName | 建议为提交器容器配置独立的服务账号，与节点组权限隔离。 |
附加资源 | spec.submitterPodTemplate.spec.tolerations | 用法与容器组附加资源一致。 |
容器级配置 | spec.submitterPodTemplate.spec.containers.workingDir | 用法与容器级配置一致。 |
元数据 | spec.submitterPodTemplate.metadata.labels | 用法与容器元数据一致。 |
配置示例
示例1：作业按需拉起集群的生产配置
以下配置设置作业超时时长、结束后自动清理资源，并为头节点配置优先级与调度容忍。
{"spec.shutdownAfterJobFinishes": "true","spec.ttlSecondsAfterFinished": "600","spec.activeDeadlineSeconds": "7200","spec.deletionPolicy": "DeleteCluster","spec.rayClusterSpec.headGroupSpec.template.spec.priorityClassName": "system-cluster-critical","spec.rayClusterSpec.headGroupSpec.template.spec.tolerations": "[{\\"key\\":\\"dedicated\\",\\"operator\\":\\"Equal\\",\\"value\\":\\"ray\\",\\"effect\\":\\"NoSchedule\\"}]","spec.rayClusterSpec.workerGroupSpecs.rayStartParams": "{\\"block\\":\\"true\\"}","spec.rayClusterSpec.autoscalerOptions.upscalingMode": "Conservative"}
示例2：计算集群开启监控采集与指定节点调度
以下配置为头节点开启监控采集，将工作节点调度到指定节点池，并缩短空闲缩容等待时长。
{"spec.headGroupSpec.template.metadata.annotations": "{\\"prometheus.io/scrape\\":\\"true\\",\\"prometheus.io/port\\":\\"8080\\"}","spec.workerGroupSpecs.template.spec.nodeSelector": "{\\"node-pool\\":\\"cpu-pool\\"}","spec.autoscalerOptions.idleTimeoutSeconds": "120"}
常见问题
作业与计算集群的参数路径有什么区别？
两者使用同一套字段，区别仅在路径前缀：
作业对应
RayJob 资源，集群相关字段需增加 rayClusterSpec. 层级，例如 spec.rayClusterSpec.headGroupSpec.serviceType。计算集群与数据实验室对应
RayCluster 资源，无需该层级，例如 spec.headGroupSpec.serviceType。作业生命周期字段（例如
suspend、submissionMode、deletionPolicy）仅作业支持，计算集群与数据实验室无对应配置。参数填写错误会有什么影响？
系统仅校验取值的 JSON 格式。格式错误在提交时被拦截并提示；语义错误（例如引用不存在的节点标签、填写非法的枚举值）在提交后由底层拒绝，实例进入异常状态。您可以在实例详情页的操作与事件日志页签中查看具体报错信息。
填写的参数为什么没有生效？
请确认所填参数不在平台管理范围内。计算资源、实例数量、运行镜像、启动命令、环境变量、节点组名称与运行时版本均由平台统一管理，需通过控制台对应配置项设置，详情请参见本文的平台管理的参数。
参数中出现了两个 activeDeadlineSeconds，有什么区别？
两者层级不同：
spec.activeDeadlineSeconds 为作业级，限制整个作业的最长运行时长。spec.rayClusterSpec.{group}.template.spec.activeDeadlineSeconds（作业）或 spec.{group}.template.spec.activeDeadlineSeconds（计算集群与数据实验室）为容器级，限制单个头节点或工作节点容器的最长存活时长。什么情况下需要配置弹性伸缩参数？
仅当工作节点组配置了实例数区间（最小值小于最大值）时，弹性伸缩参数才会生效。若所有工作节点组的最小值与最大值相同（固定资源），该类参数不产生实际影响。
生命周期钩子有哪些典型使用场景？
常见场景如下：
preInit：下载模型文件或校验 GPU 驱动版本，失败时阻止容器继续启动。preRayStart：设置环境变量或生成配置文件后再启动 Ray 进程。postRayStartBackground：启动独立的监控或日志采集进程，不增加节点上线耗时。preRayStop：工作节点缩容前将本地缓存回写到远程存储，避免数据丢失。
