Files
ssw-mpc/docs/RAY_CORE.md
T
rong d60fcf40ca fix(docs): Ray 在 armv7 上确实能跑——更正错误结论并附实测
用户指出社区编过 ray 1.0.1 armv7l wheel。核实为真,之前的"不可能"是错的。

PyPI 侧仍是事实:135 个版本 5087 个 wheel,armv7l/armhf/armv6 共 0 个,
piwheels 全 skip(binary only),无 sdist。但社区有人编:
- PidgeyBE 1.0.1 (cp36)、PeterPirog 1.2.0 (cp38),issue #12128
- 唯一需要的改动是 setup.py 加 --linkopt=-latomic(8 字节原子要 libatomic)

实物核对(ray-1.0.1-cp36-cp36m-linux_armv7l.whl,19MB→64MB):
_raylet.so 16.4MB / raylet 13.1MB / gcs_server 10.9MB,
全部 ELF32 ARM EABI5 hard-float;_raylet.so 导出 2040 个 ray:: 符号,
CoreWorkerProcess::Initialize/GetCoreWorker/RunTaskExecutionLoop 齐全,
无 B5cxx11(同样是旧 ABI),所以 shim 那套做法在 armv7 也成立。

实测跑通完整节点(x86_64 沙箱 + qemu-arm-static 真 ELF32 执行):
redis(带 ray 模块) → gcs_server:6392 → plasma → raylet:6393,
NodeManager ID ebb89cb9…,GCS 回 IsAlive = 1。

顺带记三个非 32 位坑:redis 要手工播种 5 个键;容器 /dev/shm 64MB 要改
plasma 目录;raylet 硬性要求一个 worker_command。

代价也说清:1.0.1 是 2020-12 代码,GCS 协议与 2.x 不同,接不进现代集群;
cp36 要 python3.6;44.6MB 二进制。默认仍走 nax-orch。

新增 docs/RAY_ARMV7.md + ray/armv7/{run_node,run_gcs_only}.sh;
RAY_CORE.md §5 与状态表改正。
2026-10-30 12:07:19 +08:00

124 lines
6.5 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 把 Ray 的 C++ 内核接进 nax(实测记录)
结论先说:**跑通了**。nax 的 Rust 二进制可以链接 Ray 的 C++ core(`core_worker`),
作为 driver 接入真实的 Ray 集群(GCS + raylet),拿到 raylet 分配的 node id。
但代价和边界写在前面,别当成白捡的:
| 项 | 实测 |
|---|---|
| 需要的 C++ 源码改动 | 一个 ~250 行 shim(`ray/nax_ray_shim.cc`),零改动 Ray 本体 |
| 是否需要 bazel | **否**。复用 pip wheel 里的预编译 `_raylet.so` |
| 编译耗时 | 90 秒(含生成 68 个 protobuf 头 + 2 个 flatbuffers) |
| 运行时硬依赖 | 44 MB `_raylet.so` + 40 MB `gcs_server` + 35 MB `raylet` + libpython |
| 能不能进 armv7 | **能**(社区 1.0.1/1.2.0 有 armv7l wheel,已实测跑通完整节点,见 [RAY_ARMV7.md](RAY_ARMV7.md));2.59 官方无 armv7 版 |
| 拿到的能力 | 集群成员 / 节点资源标签 / driver 身份;**不接管计算** |
结论:Ray 只当「集群目录 + 放置」用,计算仍然走 nax 自己的帧。
这也是和最初规划一致的分工——`Ray 不进计算路径`。
---
## 1. 为什么不是 bazel
Ray 官方要求用 bazel 编 C++(`//:ray_cpp`)。实测代价见 `build/measure_ray_core*.py`:
38 个 http_archive、384 MB 源码、仅依赖解析就 400–470 秒,且没有 armv7 平台定义。
真正的发现是:**pip wheel 里的 `ray/_raylet.so` 就是编好的 C++ core**,而且
- `readelf -d` 显示 NEEDED 只有 `libpthread/librt/libm/libstdc++/libgcc_s/libc`(无 libpython 的 DT_NEEDED);
- `nm -D` 导出 34 113 个符号,其中 3 638 个 `ray::` 符号是 default 可见性,
包含 `ray::core::CoreWorkerProcess::Initialize/GetCoreWorker/RunTaskExecutionLoop/Shutdown`。
也就是说:**核心 API 是可直接链接的**,不需要重新编 Ray。
## 2. 怎么跑通的
```
nax (Rust) ──C ABI──▶ libnax_ray.so (shim) ──▶ _raylet.so ──gRPC/UnixSocket──▶ raylet / GCS
```
`ray/build.sh` 干的事:
1. 下 wheel,抽出 `_raylet.so`(若本机装了 ray 就直接用 site-packages 里的);
2. 下 ray 源码里的 `src/ray/**`(只要 `.h` 和 `.proto`,12 MB);
3. `protoc` 生成 68 个 `.pb.h`,`flatc` 生成 2 个 `*_generated.h`;
4. 编 shim,链接 `_raylet.so`。
Rust 侧 `crates/nax-ray` 通过 `build.rs` 找 `libnax_ray.so`(`NAX_RAY_LIB_DIR`
或 `target/ray`),加 rpath,再显式链 libpython。
跑:
```bash
ray start --head --num-cpus 4 --include-dashboard=false
NAX_RAY_LIB_DIR=target/ray cargo run -p nax-ray --features probe --bin rayprobe -- 127.0.0.1:6379 127.0.0.1
```
实测输出(沙盒 Debian 12 / ray 2.59.0):
```
raylet_socket = /tmp/ray/session_2026-10-30_03-20-42_124221_2205/sockets/raylet
plasma_socket = /tmp/ray/session_.../sockets/plasma_store
job_id = 03000000
worker_id = 03000000ffff...
raylet_assigned_node_id = d190801cbef6346f068507bbedd6ef58d058864123748caa24a47ad4
probe 通过
结论: nax 已作为 driver 接入 Ray 集群
```
`raylet_assigned_node_id` 是 raylet 在握手时分配的,不是本地算出来的——
它出现就说明注册真的成功了。
## 3. 六个坑(每个都会让你卡半天)
| # | 现象 | 原因 | 解法 |
|---|---|---|---|
| 1 | `Required Language isn't supported: CPP`(raylet 直接 abort) | pip wheel 的 raylet 只编了 Python 的 worker pool | 注册时把 `options.language` 声明成 `PYTHON`(driver 不执行任务,任务体由 nax 自己跑) |
| 2 | 链接期 `undefined symbol ... B5cxx11 ...` | Ray 的 C++ 用**旧 ABI** 编译(`std::string` 不带 cxx11) | 全部加 `-D_GLIBCXX_USE_CXX11_ABI=0` |
| 3 | `undefined symbol: ...fmt2v9...` | Ray 自带 fmt(v11),系统是 v9 | `-DFMT_HEADER_ONLY=1` |
| 4 | `absl::nullopt` 转不成 `std::optional` | Debian 的 absl 为 ABI 稳定固定成自家实现 | 影子头 `absl/types/optional.h` 直通 std |
| 5 | 加载期 `undefined symbol: _Py_NoneStruct`(共 253 个) | `_raylet.so` 本质是 CPython 扩展 | 必须链 libpython(`--no-as-needed`),否则只能 LD_PRELOAD |
| 6 | opentelemetry / opencensus / flatbuffers / msgpack 头找不到 | Ray 的这些依赖由 bazel 拉,不在源码树里 | 影子头压掉 otel;其余用系统包或上游头 |
还有一处:`GcsNodeInfo` 的解析**没有用 protobuf**,而是手写 wire format 解析
(`wire::ParseGcsNodeInfo`)。原因和第 2 条一样——在旧 ABI 的 TU 里没法再调
cxx11 ABI 的 libprotobuf。
## 4. 为什么不进 nax 默认构建
`crates/nax-ray` 在 workspace 里,但:
- 默认不链接:`build.rs` 找不到 `.so` 只 warn 不报错,`cargo build` 照常过;
- 可执行文件 `rayprobe` 挂在 `probe` feature 后面;
- 交付的 `nax` 单二进制**不依赖 Ray**(`nax-orch` 那套编排是纯 std 的)。
要接 `nax-cli`,加一个 `ray` feature 指向 `nax-ray` 即可,但那是「Ray 在,就用 Ray
的资源标签做放置;Ray 不在,退回 `nax-orch`」的分支,不是硬依赖。
## 5. armv7 / Zynq 的结论
**先纠正一个曾经的错误结论**:Ray 在 armv7 上是能跑的。PyPI 没有,但社区编过
1.0.1 / 1.2.0 的 armv7l wheel,唯一需要的源码改动是 `--linkopt=-latomic`
(32 位 ARM 的 8 字节原子操作要显式链 libatomic)。2026-10-30 实测:用 qemu-arm
起 redis + gcs_server + plasma + raylet,节点注册进 GCS 拿到 `IsAlive = 1`。
完整记录见 [RAY_ARMV7.md](RAY_ARMV7.md)。
但「能跑」不等于「该用」,代价是三条:
1. 版本停在 2020 年底(1.0.1 / 1.2.0),GCS 协议与 2.x 不同,**接不进现代 Ray 集群**;
2. wheel 是 cp36,`_raylet.so` 是 CPython 扩展,板上要 python3.6 或链 libpython 兜符号;
3. C++ 侧 44.6 MB 二进制 + plasma 内存。ACZ7015 的 1 GB DDR3 放得下,512 MB 的板子悬。
自己编 2.59 的 armv7 版不建议:要给 bazel 写完整 armv7 crosstool,38 个第三方依赖
全部跟着过一遍,还要面对未知数量的 32 位问题——而我们只用它「放置」这一项能力。
所以最终分工:
- **Zynq / 边缘**:nax 自己的编排(`nax-orch`,661 行纯 std,已跑通 3/4 方)+ 交叉编译单二进制;
- **x86 集群**:可选接 Ray 做成员与放置;
- **确需边缘 Ray 生态时**:走 [RAY_ARMV7.md](RAY_ARMV7.md) 的 1.0.1 路线。
这也回答了最初的问题:Ray 的 C++ 内核**可以**给 Rust 集成,在 armv7 上也**可以**跑,
但它的价值在「大集群的成员管理」,不在「边缘设备的隐私计算」。