Ray任务开发手册

更新时间：2026-07-21

dbray 面向开发机用户让用户支持使用dbray 来提交ray任务，并且支持将本地Ray任务提交到百度胜算远端Ray集群，利用共享PFS存储资源执行任务。

什么是dbray

dbray是开发机上提交Ray任务到百度胜算远端Ray集群的命令行工具。相比原生ray job submit，下表将从各维度逐一对比说明两者差异：

维度	原生`ray job submit`	`dbray job submit`
集群地址	需手动输入`--address http://...:8265`	通过 `--compute-id` 自动从平台获取
鉴权	无	百度胜算统一权限校验（compute_id 无权限时请求将被直接拒绝）
working_dir	压缩后上传至 GCS 等远端对象存储，任务启动时自动下载并解压	可通过共享 PFS不打包不上传，worker直接使用本地路径
env_vars	由用户自行配置。	集中渲染并自动注入
子命令	`submit / status / logs / stop / list`	行为对齐

因此，如果您的代码已经位于开发机挂载的PFS上，推荐直接使用dbray。以下是快速使用dbray的示例：

                Bash
                
                cd /pfs/<...>/my-project           # cd 到 PFS 上你正在开发的代码目录
dbray job submit --config-file ~/.dbray/dbray.yaml -- python train.py

前提条件

开发机已挂载 PFS（一般在 /pfs/<workspace>/... 或 /mnt/pfs/<...>，前缀因部署而异）；
Ray实例与开发机挂载相同PFS实例，同时保证挂载源路径和容器内路径相同；
需持有一对BCE AK/SK（长期或 STS 临时凭证均可）；
需持有一个具有权限的compute_id（在百度胜算控制台分配的计算资源；如果没权限提交任务会被平台拒绝）；

快速开始

您只需要通过五步即可快速提交一个Ray作业，具体操作步骤如下：

步骤一：确认环境

使用下方两个命令检查开发环境是否就绪：

                Bash
                
                dbray --help                                  # 1) dbray CLI 在 PATH
python3 -c "from ray.runtime_env import RuntimeEnv; \
    RuntimeEnv(working_dir='/tmp', working_dir_shared=True)"   # 2) ray 补丁已装

步骤二：准备dbray凭证

您可以有配置文件方式、使用环境变量、显式指定变量三种方式准备凭证，本快速开始使用显式指定变量方式来准备凭证。更多的凭证方式可参考下方配置凭证的多种方式。

绿色部分配置为必填项。

                Bash
                
                mkdir -p ~/.dbray && chmod 700 ~/.dbray

创建配置文件

                Bash
                
            

                cat > ~/.dbray/dbray.yaml <<EOF
workspace_id: <your-workspace-id>   # 不配置的话默认使用开发机所在工作空间ID
user_id:      <your-user-id>        # 选填 用于生成带有标识的submission_id
compute_id:   <your-compute-id>     # ray实例ID

credentials:
  access_key:    <your-bce-ak>
  secret_key:    <your-bce-sk>
  session_token: ""    # 没有可空置
EOF
chmod 600 ~/.dbray/dbray.yaml
            

字段说明：workspace_id / compute_id 用于标识连接目标；user_id 仅作为提交记录的可读标签，不影响权限校验；credentials 中填写 AK/SK，请确保其对应账号拥有 Ray 实例及任务运行所需权限。

步骤三：代码开发

                Bash
                
            

                # 假设 /pfs/<your-workspace>/projects 是你的 PFS 工作目录
mkdir -p /pfs/<your-workspace>/projects/hello-ray
cd /pfs/<your-workspace>/projects/hello-ray

cat > demo.py <<'PY'
"""Ray 任务。"""
import math, os, socket, time
import ray


@ray.remote
def slow_sqrt(n: int) -> dict:
    time.sleep(0.5)
    return {"n": n, "sqrt": math.sqrt(n),
            "host": socket.gethostname(), "pid": os.getpid()}


def main():
    user = os.environ.get("task_user_id", "<unknown>")
    print(f"hello from dbray, user={user}, cwd={os.getcwd()}")

    N = 8
    print(f"[driver] dispatching {N} tasks...")
    t0 = time.time()
    results = ray.get([slow_sqrt.remote(i) for i in range(1, N + 1)])
    print(f"[driver] done in {time.time() - t0:.2f}s")

    for r in results:
        print(f"  n={r['n']:>2} sqrt={r['sqrt']:.4f}  on {r['host']} pid={r['pid']}")
    print(f"[driver] sum = {sum(r['sqrt'] for r in results):.4f}")


if __name__ == "__main__":
    main()
PY
            

步骤四：提交执行任务

                Bash
                
                cd /pfs/<your-workspace>/projects/hello-ray
dbray job submit --config-file ~/.dbray/dbray.yaml -- python demo.py

将输出任务执行日志：

Plain Text

1Submitted: dbray-<your-user>-20260627T...-xxxxxx
2Dashboard: http://<ray-dashboard-host>:8265
3Logs:      dbray job logs dbray-<...>-xxxxxx -f
4Stop:      dbray job stop dbray-<...>-xxxxxx
5
6...job stdout streamed in real-time...
7hello from dbray, user=<your-user-id>, cwd=/pfs/<your-workspace>/projects/hello-ray
8[driver] dispatching 8 tasks...
9[driver] done in 0.78s
10  n= 1 sqrt=1.0000  on ray-cluster-...-head-xxxxx pid=12345
11  ...
12  n= 8 sqrt=2.8284  on ray-cluster-...-head-xxxxx pid=12351
13[driver] sum = 15.6066
14
15Final status: SUCCEEDED

步骤五：查看历史作业

Bash

1dbray job list --config-file ~/.dbray/dbray.yaml

进阶使用

在创建过程中或创建完成后，您可对Ray任务执行以下常用进阶操作。

配置凭证多种方式

以下提供三种配置方法，具体操作步如下：

dbray的连接参数：workspace_id / compute_id / access_key / secret_key（外加可选的 user_id / session_token）。

三种渠道，按下列优先级解析，也就是同一个参数被多处定义时，最左边的胜出：

Plain Text

1CLI flag  >  环境变量  >  --config-file

1.配置文件方式

配置文件方式将数据写入固定的配置文件，一次写好，推荐日常使用。

每次 submit/status/logs/stop/list 都只需 --config-file <path>。

使用--config-file <path>指定该写入的配置文件以提交任务：

Bash

1dbray job submit --config-file ~/.dbray/dbray.yaml -- python demo.py
2dbray job logs   <sid> --config-file ~/.dbray/dbray.yaml -f
3dbray job list         --config-file ~/.dbray/dbray.yaml

1.1 YAML 嵌套写法

～/.dbray/dbray.yaml:

YAML

1workspace_id: workspace_9862_xxxxxxxxxxxx
2compute_id:   compute_a7b2_xxxxxxxxxxxx
3user_id:      alice
4
5credentials:
6  access_key:    ALTAKxxxxxxxxxxxxxxxxxx
7  secret_key:    xxxxxxxxxxxxxxxxxxxxxxxxxxx
8  session_token: ""

1.2 YAML 顶层平铺写法：

~/.dbray/dbray-flat.yaml，credentials 字段不嵌套:

YAML

1workspace_id: workspace_9862_xxxxxxxxxxxx
2compute_id:   compute_a7b2_xxxxxxxxxxxx
3user_id:      alice
4access_key:   ALTAKxxxxxxxxxxxxxxxxxx
5secret_key:   xxxxxxxxxxxxxxxxxxxxxxxxxxx

1.3 JSON 写法：

~/.dbray/dbray.json:

                JSON
                
            

                {
  "workspace_id": "workspace_9862_xxxxxxxxxxxx",
  "compute_id":   "compute_a7b2_xxxxxxxxxxxx",
  "user_id":      "alice",
  "credentials": {
    "access_key":    "ALTAKxxxxxxxxxxxxxxxxxx",
    "secret_key":    "xxxxxxxxxxxxxxxxxxxxxxxxxxx",
    "session_token": ""
  }
}
            

三种格式 dbray 都识别。chmod 600：里面有你的 AK/SK，不要让别人读到。

2.使用环境变量

                Bash
                
                export DATABUILDER_WORKSPACE_ID=workspace_9862_xxxxxxxxxxxx
export DBRAY_COMPUTE_ID=compute_a7b2_xxxxxxxxxxxx
export DATABUILDER_ACCESS_KEY_ID=ALTAKxxxxxxxxxxxxxxxxxx
export DATABUILDER_SECRET_ACCESS_KEY=xxxxxxxxxxxxxxxxxxxxxxxxxxx
# export DATABUILDER_SESSION_TOKEN=...   # 可选

dbray job submit -- python demo.py        # 连接参数从 env 自动取

变量名映射：

字段	环境变量名
workspace_id	`DATABUILDER_WORKSPACE_ID` 或 `DBRAY_WORKSPACE_ID`
compute_id	`DBRAY_COMPUTE_ID`
access_key	`DATABUILDER_ACCESS_KEY_ID`
secret_key	`DATABUILDER_SECRET_ACCESS_KEY`
session_token	`DATABUILDER_SESSION_TOKEN`
user_id	`DBRAY_USER_ID`

开发机镜像通常已预置 DATABUILDER_WORKSPACE_ID，仅需额外配置 AK/SK 与 compute_id 即可。

3.显式指定变量

一次性 / 调试用:

                Bash
                
            

                dbray job submit \
  --workspace-id workspace_9862_xxxxxxxxxxxx \  # 可选 默认用开发机所在工作空间ID
  --compute-id   compute_a7b2_xxxxxxxxxxxx \
  --access-key   ALTAKxxxxxxxxxxxxxxxxxx \
  --secret-key   xxxxxxxxxxxxxxxxxxxxxxxxxxx \
  -- python demo.py
            

三种方式的混合

dbray 允许混用，按优先级合并。最常见的两种组合：

                Bash
                
            

                # 1) AK/SK 写文件，compute_id 命令行现场指定
dbray job submit \
  --config-file ~/.dbray/dbray.yaml \
  --compute-id  compute_OTHER_xxx \
  -- python demo.py

# 2) 整套从 env 拿，但临时换 compute_id
DBRAY_COMPUTE_ID=compute_xxxx \
  dbray job submit -- python demo.py
            

常用指令列表

dbray job 下有 5 个子命令，全部需要配置连接参数（按照配置方式三选一）。

submit 提交作业

                Bash
                
                dbray job submit [连接参数] [可选项] -- <entrypoint> [args...]

-- 之后的内容会原样交给 Ray 作为作业 entrypoint，最常见就是 python xxx.py [...]。

可选项：

选项	默认	说明
`--working-dir <abs path>`	`$PWD`	worker 端 cwd（必须在 PFS 共享路径上）
`--runtime-env <file.yaml>`	—	用户自己的 runtime_env 文件（pip / py_modules / env_vars 等）
`--runtime-env-json '<json>'`	—	用户自己的 runtime_env 内联 JSON；与 `--runtime-env` 同时给时叠加在文件之上（同 key 内联值胜出）
`--no-wait`	false	立即返回，不阻塞等日志

默认行为：submit 后阻塞，把 worker stdout/stderr 实时 tail 到本地终端，作业终态时打印 Final status: SUCCEEDED/FAILED/STOPPED。Ctrl-C 中断 tail 不会停止远端作业。

提交作业默认为阻塞模式，如需修改模式，可参考提交作业的多种方式。

stdout 格式：

Plain Text

1Submitted: dbray-<user>-<UTC-timestamp>-<6-hex-random>
2Dashboard: http://<ray-dashboard>:8265
3Logs:      dbray job logs <sid> -f
4Stop:      dbray job stop <sid>
5
6<job stdout streamed>
7...
8Final status: SUCCEEDED

第一行 Submitted: 后的 token 就是 submission_id；后续 logs / stop / status 都用它。

dbray job submit 支持多种使用方式，以下介绍常见的开发与调试场景，包括开发调试、批量调度、离线查看日志、终止作业、环境隔离和并发提交。

所有示例默认使用配置文件，也可根据前述配置方式自行选择。

Bash

1--config-file ~/.dbray/dbray.yaml

提交作业的多种方式

1.阻塞模式（默认，推荐开发调试）

阻塞模式是是 dbray 任务提交后的默认行为，也是开发调试的常用方式。

提交后命令会停留在当前终端，实时输出远端作业的 stdout 和 stderr，体验接近本地直接运行：

Bash

1dbray job submit --config-file ~/.dbray/dbray.yaml -- python demo.py

特点：

可以实时看到程序输出。
Python 报错时可以直接看到 traceback。
按 Ctrl-C 只会中断本地日志 tail，不会终止远端作业。
如果需要真正停止远端作业，请使用 dbray job stop <sid>

2.非阻塞模式（适合批处理和自动化）

非阻塞模式适合脚本化提交、批处理调度和后台运行。加上 --no-wait 后，命令会在提交成功后立即返回 submission id。

                Bash
                
                SID=$(dbray job submit --config-file ~/.dbray/dbray.yaml --no-wait \
  -- python demo.py | awk '/^Submitted:/ {print $2}')

提交后可以继续执行其他任务，之后再查询状态或查看日志：

                Bash
                
                sleep 60

dbray job status "$SID" --config-file ~/.dbray/dbray.yaml
dbray job logs   "$SID" --config-file ~/.dbray/dbray.yaml

适用场景：

CI/CD 或调度脚本中提交作业。
一次提交后立即返回，不阻塞当前 shell。
后续通过 status 和 logs 主动查询作业状态。

3.提交后离线观察

使用 --no-wait 提交长任务后，可以关闭本地终端。终端关闭不会影响远端任务执行。

Bash

1dbray job submit --config-file ~/.dbray/dbray.yaml --no-wait -- python long_train.py

之后可以重新打开终端，通过 submission id 查看日志：

                Bash
                
                dbray job logs <sid> --config-file ~/.dbray/dbray.yaml | less

说明：

远端作业生命周期不依赖本地终端。
logs 可用于后续追踪输出。
配合 less 可以更方便地翻页查看长日志。

status 查询作业状态

                Bash
                
                dbray job status <submission_id> [连接参数]

输出枚举之一：PENDING / RUNNING / SUCCEEDED / FAILED / STOPPED。

logs 获取作业日志

                Bash
                
                dbray job logs <submission_id> [连接参数] [-f|--follow]

不带 -f 时一次性拉到当前日志；带 -f 时实时 tail 到作业结束（Ctrl-C 中断 tail 不会停作业）。

stop 停止作业

                Bash
                
                dbray job stop <submission_id> [连接参数]

正常输出 stopped，作业转入 STOPPED 状态。已经 SUCCEEDED/FAILED 的作业 stop 是 no-op。

list 列出作业

Bash

1dbray job list [连接参数]

返回该 compute_id 下所有 ad-hoc 作业的 JSON 数组（按 ray dashboard 的 list_jobs 输出，出于安全考虑已做隐私处理：runtime_env 字段已移除，敏感元数据已替换为 "***"）。

示例：

                JSON
                
            

                [
  {
    "type": "SUBMISSION",
    "submission_id": "dbray-alice-20260627T125345-63bd06",
    "status": "SUCCEEDED",
    "entrypoint": "python demo.py",
    "message": "Job finished successfully.",
    "start_time": 1782564835594,
    "end_time": 1782564840321,
    "metadata": {},
    "driver_exit_code": 0
  },
  ...
]
            

导入自定义依赖pip

最常见的需求是：作业运行时需要安装额外的 pip 包。

dbray 支持以下几种方式配置 runtime env。

方式	适用场景	示例
内联 JSON	临时添加少量依赖或环境变量	`--runtime-env-json`
runtime_env 文件	作为项目的固定运行环境配置	`--runtime-env ./my_env.yaml`
文件 + 内联 JSON	文件做基线，命令行临时覆盖部分配置	同时使用 `--runtime-env` 和 `--runtime-env-json`

env_vars 合并语义规则

env_vars 会按 key 独立合并，不是整体替换。

合并优先级从低到高如下：

优先级	来源	说明
1	DataBuilder 渲染的 `env_vars`	包括 STS / DataBuilder / Catalog 相关变量
2	dbray 默认环境变量	例如 `PYTHONDONTWRITEBYTECODE=1`
3	`--runtime-env` 文件中的 `env_vars`	项目级配置
4	`--runtime-env-json` 内联 `env_vars`	命令行临时覆盖，优先级最高

示例：

Bash

1--runtime-env-json '{"env_vars":{"X":"y"}}'

这只会设置或覆盖 X 这个 key，不会清空其他环境变量。

因此，即使用户只传了：

                JSON
                
                {"env_vars":{"X":"y"}}

dbray / DataBuilder 注入的 STS 凭证、Catalog 信息等仍然会保留。

1.内联 JSON

                Bash
                
                dbray job submit --config-file ~/.dbray/dbray.yaml \
  --runtime-env-json '{"pip": ["pandas==2.2.0", "requests"]}' \
  -- python train.py

2.runtime_env 文件

my_env.yaml：

YAML

1pip:
2  - pandas==2.2.0
3  - requests
4
5env_vars:
6  MY_DEBUG_FLAG: "1"

提交作业时使用该配置文件：

Bash

1dbray job submit --config-file ~/.dbray/dbray.yaml \
2  --runtime-env ./my_env.yaml \
3  -- python train.py

3.文件与内联 JSON 叠加

runtime_env 文件作为基础配置，命令行内联 JSON 用于临时覆盖：

                Bash
                
                dbray job submit --config-file ~/.dbray/dbray.yaml \
  --runtime-env ./my_env.yaml \
  --runtime-env-json '{"env_vars":{"MY_DEBUG_FLAG":"0"}}' \
  -- python train.py

典型错误与排查

本节介绍常见报错的含义及处理方式，帮助您在使用过程中快速定位问题。

1.access_key is required

常见提示：

access_key is required: set --access-key, DATABUILDER_ACCESS_KEY_ID, or 'access_key' in --config-file.

含义：

dbray 没有拿到 AK。
同类报错也可能是 secret_key is required。

处理方式：

按第 4 节介绍的三种渠道，至少配置一种凭证来源。
检查 --access-key、DATABUILDER_ACCESS_KEY_ID、--config-file 里的 access_key 是否真的生效。

2.403 Forbidden / AccessDenied / 暂无操作权限

常见提示：

403 Forbidden {"code":"AccessDenied","message":"暂无操作权限"}

含义：

你的 AK/SK 没有对应 compute_id 的 USE 权限。

常见原因：

compute_id 不属于你的 workspace，可能是 --compute-id 写错了。
你确实没有被授权，需要 workspace owner 处理。

处理方式：

先确认 --compute-id 是否正确。
如果确认无误，联系 DataBuilder workspace owner 给你授权。

3.working_dir_shared path /xxx is not mounted on this worker

常见现象：

在作业 dashboard 上看到这条 message。

含义：

worker 上看不到你通过 --working-dir 指定的路径。

常见原因：

你把工作目录放在了 /tmp/...、/home/... 这类非 PFS 路径。
PFS 挂载点在开发机和 worker 上不一致，例如开发机看到 /pfs/<ws>/proj，worker 看到 /mnt/pfs/<ws>/proj。

处理方式：

把代码移到正确的 PFS 路径下。
重新 cd 到该路径后再提交。
如果是挂载点路径不一致，请联系平台运维人员确认 PFS 挂载路径映射关系。

评价此篇文章

有帮助没帮助

VS Code中使用ssh服务连接开发机

PFS L2挂载使用