文档首页/ 智能数据湖 AI DataLake/ API参考/ Ray相关API/ RayJob管理/ 运行作业 - RunRayJob

更新时间：2026-10-29 GMT+08:00

运行作业 - RunRayJob

功能介绍

运行Ray作业。本接口为异步接口，当前运行作业请求下发成功后会返回job_id，此时运行作业并没有立即完成，需要通过调用查看Ray作业详情查询Job状态，当状态为SUCCEEDED时代表运行作业成功。

调用方法

URI

POST /v2/workspaces/{workspace_id}/ray-jobs

表1 路径参数
参数	是否必选	参数类型	描述
workspace_id	是	String	参数解释：工作空间ID。获取方法，请参见获取工作空间ID。约束限制：不涉及。取值范围：长度为1~36的英文字符、数字和中划线的组合。默认取值：不涉及。

请求参数

表2 请求Header参数
参数	是否必选	参数类型	描述
X-Auth-Token	是	String	参数解释：用户Token，通过调用获取IAM用户Token接口获取。约束限制：不涉及。取值范围：长度不超过65534个字符。默认取值：不涉及。
X-Client-Token	否	String	参数解释：作业事务 ID，防止重复提交。约束限制：不涉及。取值范围：长度不超过65534个字符。默认取值：不涉及。

表3 请求Body参数
参数	是否必选	参数类型	描述
name	是	String	参数解释：Job名称。约束限制：不涉及。取值范围：长度为1~47的英文字母、数字、中划线。默认取值：不涉及。
endpoint_name	是	String	参数解释：端点名称。约束限制：不涉及。取值范围：长度为1~63个字符。包含小写字母、数字、中划线的组合。字母开头、字母或数字结尾。默认取值：不涉及。
config	是	RayJobConfig object	参数解释：Ray作业类型的配置信息。key为配置项名称，value为配置项值。约束限制：不涉及。
description	否	String	参数解释：描述信息。约束限制：不涉及。取值范围：长度为0~1024的中文、英文字母、数字、下划线、中划线、点号、空格的组合。默认取值：不涉及。

表4 RayJobConfig
参数	是否必选	参数类型	描述
entrypoint	是	String	参数解释：运行作业主脚本。运行作业时会自动解压作业脚本的.zip文件。如果解压后的第一层只有一个文件夹，该文件夹会被自动去掉，因此此处直接写脚本文件名即可，无需包含父目录。约束限制：不涉及。取值范围：长度为1~102400个字符。默认取值：不涉及。
runtime_env	否	RuntimeEnv object	参数解释：作业的运行时环境配置。约束限制：不涉及。默认取值：不涉及。
image	否	V2ImageBriefInfo object	参数解释：镜像信息。约束限制：仅提交作业到RayJob端点时配置。
resource_config	否	RayResourceConfig object	参数解释：Ray节点资源配置。约束限制：仅提交作业到RayJob端点时配置。
rayjob_strategy	否	RayJobStrategy object	参数解释：Ray Job提交策略。约束限制：不涉及。
metadata	否	Map<String,String>	参数解释：用户自定义作业元数据（键值对）。约束限制：键值对数量为0~255个。key和value的值不能为空，长度不超过255个字符。

表5 RuntimeEnv
参数	是否必选	参数类型	描述
working_dir	否	String	参数解释：代码将在其中运行的工作目录。约束限制：必须是远程URI，如OBS路径。取值范围：最小长度1，最大长度2048。默认取值：不涉及。
pip	否	Array of strings	参数解释：要安装的pip软件包列表。约束限制：最小个数0，最大个数1023。
env_vars	否	Map<String,String>	参数解释：要设置的环境变量。key为环境变量名称，value为环境变量值，均为String类型。约束限制：不涉及。
config	否	Map<String,Object>	参数解释：运行环境的配置。key为配置项名称，value为配置项值。约束限制：不涉及。

表6 V2ImageBriefInfo
参数	是否必选	参数类型	描述
image_id	是	String	参数解释：镜像ID。获取方式请参见查看镜像列表。约束限制：不涉及。取值范围：长度为32~36的英文、数字、中划线的组合。默认取值：不涉及。
image_version_id	是	String	参数解释：镜像版本ID。获取方式请参见查询镜像详情。约束限制：不涉及。取值范围：长度为32~36的英文、数字、中划线的组合。默认取值：不涉及。

表7 RayResourceConfig
参数	是否必选	参数类型	描述
head_resource_spec	是	RayHeadResourceSpec object	参数解释：head资源配置。约束限制：仅提交作业到RayJob端点时配置。
worker_resource_spec	是	Array of RayWorkerResourceSpec objects	参数解释：worker资源配置。约束限制：仅提交作业到RayJob端点时配置。

表8 RayHeadResourceSpec
参数	是否必选	参数类型	描述
cpu	是	Integer	参数解释：CPU核数量，单位为毫核。约束限制：不涉及。取值范围：最小值为1000。默认取值：不涉及。
memory	是	Integer	参数解释：单个head内存大小，单位MB。约束限制：不涉及。取值范围：最小值为1024。默认取值：不涉及。
gpu	否	Double	参数解释：节点的GPU数量。约束限制：不支持小于1的值或带小数部分的值（如0.5, 1.5）。取值范围：需配置为大于等于1.0，且必须为整数值（如1.0, 2.0, 3.0, ...）。默认取值：不涉及。
npu	否	Double	参数解释：节点的NPU数量。约束限制：不支持小于1的值或带小数部分的值（如0.5, 1.5）。取值范围：需配置为大于等于1.0，且必须为整数值（如1.0, 2.0, 3.0, ...）。默认取值：不涉及。

表9 RayWorkerResourceSpec
参数	是否必选	参数类型	描述
cpu	是	Integer	参数解释：CPU核数量，单位为毫核。约束限制：不涉及。取值范围：最小值为1000。默认取值：不涉及。
memory	是	Integer	参数解释：内存大小，单位MB。约束限制：不涉及。取值范围：最小值为1024。默认取值：不涉及。
gpu	否	Double	参数解释：节点的GPU数量。约束限制：不支持小于1的值或带小数部分的值（如0.5, 1.5）。取值范围：需配置为大于等于1.0，且必须为整数值（如1.0, 2.0, 3.0, ...）。默认取值：不涉及。
npu	否	Double	参数解释：节点的NPU数量。约束限制：不支持小于1的值或带小数部分的值（如0.5, 1.5）。取值范围：需配置为大于等于1.0，且必须为整数值（如1.0, 2.0, 3.0, ...）。默认取值：不涉及。
worker_replicas	否	Integer	参数解释：Worker副本数量。约束限制：不涉及。取值范围：1~64。默认取值：不涉及。
enable_autoscaling	是	Boolean	参数解释：是否开启worker节点的弹性伸缩。约束限制：不涉及。取值范围：可选值有： true：开启弹性伸缩。取该值时worker_min_replicas和worker_max_replicas必须设置。 false：不开启弹性伸缩。取该值时worker_replicas必须设置。默认取值：false。
worker_min_replicas	否	Integer	参数解释：Worker最小副本数量。约束限制：不涉及。取值范围：0~64。默认取值：不涉及。
worker_max_replicas	否	Integer	参数解释：Worker最大副本数量。约束限制：不涉及。取值范围：1~64。默认取值：不涉及。

**表10** RayJobStrategy
参数	是否必选	参数类型	描述
queued_timeout	否	Integer	参数解释：作业提交超时时间，如果超过此时间作业仍未运行，则作业失败。单位为分钟。约束限制：不涉及。取值范围：10~1440。默认取值：180（即3小时）。
running_timeout	否	Integer	参数解释：作业运行超时时间，如果超过此时间作业还未运行结束，则作业会取消运行，并标记失败。单位为分钟。约束限制：不涉及。取值范围：-1~10080（-1表示不配置超时）。默认取值：-1。

响应参数

状态码：202

**表11** 响应Body参数
参数	参数类型	描述
job_id	String	参数解释：作业ID。可通过查询Ray作业列表获取。取值范围：长度为1~36的英文字符、数字和中划线的组合。

状态码：400

**表12** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码。取值范围：长度为8~36个字符。
error_msg	String	参数解释：错误描述。取值范围：长度为2~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：401

**表13** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码。取值范围：长度为8~36个字符。
error_msg	String	参数解释：错误描述。取值范围：长度为2~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：403

**表14** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码。取值范围：长度为8~36个字符。
error_msg	String	参数解释：错误描述。取值范围：长度为2~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：404

**表15** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码。取值范围：长度为8~36个字符。
error_msg	String	参数解释：错误描述。取值范围：长度为2~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：408

**表16** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码。取值范围：长度为8~36个字符。
error_msg	String	参数解释：错误描述。取值范围：长度为2~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

状态码：500

**表17** 响应Body参数
参数	参数类型	描述
error_code	String	参数解释：错误码。取值范围：长度为8~36个字符。
error_msg	String	参数解释：错误描述。取值范围：长度为2~512个字符。
solution_msg	String	参数解释：解决方案描述。取值范围：长度为0~4096个字符。

请求示例

运行Ray作业。

POST /v2/workspaces/{workspace_id}/ray-jobs

{
  "name" : "rayjob0615-4",
  "description" : "run Ray Job",
  "endpoint_name" : "ray-test",
  "config" : {
    "entrypoint" : "python3 create_csv.py",
    "runtime_env" : {
      "working_dir" : "obs://ray-shared-csc/ray-zy/create_csv.zip",
      "pip" : [ "numpy==1.16.1" ],
      "env_vars" : {
        "APP_PORT" : "8848",
        "NODE_ENV" : "production"
      }
    },
    "image" : {
      "image_id" : "dd877a59-5cbd-44c5-b8a7-dc464cca****",
      "image_version_id" : "01ae8ee6-af8a-48a8-895b-8d4a70bf****"
    }
  }
}

响应示例