Files
ssw-mpc/docs/RAY_CORE_101.md
T
rong 45bc626256 feat(ray): 对齐 Ray 1.0.1,nax 作为 driver 跑通跨架构 MPC
用户要求先用 1.0.1 对齐两端再把 nax MPC 跑通。闭环达成:

  x86_64  Ray node 73bfdc0a…  nax site=b  MPC 35
  armv7   Ray node 235afb22…  nax site=a  MPC 35

同一进程既是 Ray driver 又是 MPC 参与方;node_id 由 raylet 握手分配,
两端不同即「真的挂在两个节点上」的证据。35 = (1·4+1)+(2·5+1)+(3·6+1)。

1.0.1 shim(ray/nax_ray_shim_101.cc)与 2.59 的六个接口差异:
CoreWorkerProcess 无独立头、TaskExecutionCallback 只有 8 参数、
GcsClientOptions 位置参数、无 GetNodeToConnectForDriver/GetNextJobID、
无 ray::core 命名空间、GcsNodeInfo 无 node_manager_port。

两个必踩的坑:
- options.num_workers 必须显式设 1(1.0.1 有 RAY_CHECK(>0),默认 0 abort)
- gcs_options 要指向 Redis(6400)而非 gcs_server(6402),指错报
  Protocol error got "\x00",看着像协议问题其实是端口给错

同一版本两个架构的 string ABI 不同(关键):
x86_64 _raylet.so 是旧 ABI(0 个 cxx11),armv7 是新 ABI(423 个)。
搞错的表现是运行期 basic_string::_M_create 异常,错误信息不提 ABI。

编译补丁自动打在解出来的头上:client_call.h 的 vector<CompletionQueue> 换 deque
(grpc 1.51 删了移动构造)、影子 arrow/buffer.h、-Dgrpc_impl=grpc。
Python 符号 x86 缺 8 个 / armv7 缺 2 个,shim 零值占位(不执行 Python 代码)。

nax-cli 加可选 feature ray:设 NAX_RAY_RAYLET 即注册 driver,默认构建仍是
纯静态单二进制。rpath 放在 nax-cli 的 build.rs(link-arg-bins),放 nax-ray
里传不到依赖方的 bin。

新增 docs/RAY_CORE_101.md、ray/{nax_ray_shim_101.cc,build101.sh,
build101_armv7.sh,test101.py,test101_arm.c,verify101.sh}、ray/armv7/mpc_ray.sh;
nax-ray 重写为 1.0.1 签名;README 状态表更新。
2026-10-30 13:44:00 +08:00

208 lines
8.7 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 1.0.1 × nax:跨架构集群 + 跨架构 MPC
这是 `docs/RAY_CORE.md` 的 1.0.1 姊妹篇。那篇讲的是怎么把 Ray **2.59** 的 C++ core
接进 Rust;这篇讲的是**为什么最终用 1.0.1**,以及接进去之后 nax 的 MPC 真的跑起来了。
结论先放这里:
```
x86_64 侧 Ray node 73bfdc0a… nax site=b MPC 结果 35 ✅
armv7 侧 Ray node 235afb22… nax site=a MPC 结果 35 ✅
(同一进程既是 Ray driver,又是 MPC 参与方;Ray 只提供成员目录,不进计算路径)
```
---
## 1. 为什么是 1.0.1
| | 2.59 | 1.0.1 |
|---|---|---|
| x86_64 wheel | 有 | 有 |
| aarch64 wheel | 有(2.2.0 起) | 无 |
| **armv7 wheel** | **无** | **社区编过**(1.0.1 cp36 / 1.2.0 cp38) |
| GCS 后端 | gRPC | Redis |
| 与另一版本互通 | ✗ | ✗ |
Zynq-7015 是 Cortex-A9(ARMv7-A,32 位),只有 1.0.1/1.2.0 有可用二进制。
而 1.0.1 与 2.59 **双向不通**(实测:1.0.1 raylet 连 2.59 的 6379 报
`Protocol error, got "\x00"`,因为 2.0 起 6379 从 RESP 换成了 gRPC/HTTP2)。
所以要么整集群 2.x(armv7 进不来),要么整集群 1.0.1。选了后者。
---
## 2. 和 2.59 版的六个接口差异
`ray/nax_ray_shim_101.cc` 是 1.0.1 版,对比 2.59 版(`ray/nax_ray_shim.cc`):
| 项 | 2.59 | 1.0.1 |
|---|---|---|
| `CoreWorkerProcess` 头文件 | `core_worker/core_worker_process.h` | 就在 `core_worker/core_worker.h` 里 |
| `TaskExecutionCallback` | 22 个参数 | **8 个参数** |
| `GcsClientOptions` | `(ip, port, ClusterID, allow_nil, fetch)` | `(ip, port, password, is_test)` 位置参数 |
| 取 raylet socket | `GlobalStateAccessor::GetNodeToConnectForDriver()` | **没有**,必须调用方给(Python 侧也是在 `_raylet.pyx` 里算好传进来的) |
| 取 job id | `GetNextJobID()` | **没有**,`JobID::FromInt(n)` 自己给 |
| 命名空间 | `ray::core::CoreWorker` | `ray::CoreWorker`(没有 `core` 这一层) |
| `GcsNodeInfo` 字段 | 1..5 含 node_manager_port | 1..4 + `state=7`,**无 port** |
两个直接踩到的坑:
1. **`options.num_workers = 1` 必须显式设**。1.0.1 的 `CoreWorker` 构造函数里有
`RAY_CHECK(options_.num_workers > 0)`,默认 0 会直接 abort。
2. **`gcs_options` 要指向 Redis,不是 gcs_server 的 gRPC 端口**。1.0.1 的
CoreWorker 内部建的是 `ServiceBasedGcsClient`,但它同时要连 Redis 拿表。
指向 6402 会得到 `redis_client.cc:114 Check failed: Protocol error, got "\x00"`。
正确值是 Redis 主节点(本仓库的混合集群是 6400)。
---
## 3. 两个 ABI 事实(最容易翻车的地方)
同一个 ray 1.0.1,两个架构的 wheel 用了**不同的 std::string ABI**:
```
x86_64 ray-1.0.1-...-manylinux1_x86_64.whl → nm -D | grep -c cxx11 = 0 (旧 ABI)
armv7 ray-1.0.1-...-linux_armv7l.whl → nm -D | grep -c cxx11 = 423 (新 ABI)
```
所以 shim 必须分别编译:
```bash
# x86_64
g++ ... -D_GLIBCXX_USE_CXX11_ABI=0 ray/build101.sh
# armv7
arm-linux-gnueabihf-g++ ... ray/build101_armv7.sh # 不加那个宏
```
搞错的表现不是链接错误,而是**运行期 `basic_string::_M_create` 异常**——
`CoreWorkerOptions.gcs_options.server_ip_` 传过去后长度字段错位,`std::string`
认为长度是个天文数字。这个错误信息完全不提 ABI,很容易往内存越界上查。
---
## 4. Python 符号:8 个 stub + 一份 libpython
`_raylet.so` 本质是 CPython 扩展。x86 版引用 203 个 `Py*` 未定义符号,
armv7 版 201 个。解法是链上 libpython(`--no-as-needed`,否则被 as-needed 丢掉),
剩下的差集由 shim 自己定义占位:
| 符号 | 为什么缺 |
|---|---|
| `_Py_CheckRecursionLimit` | 3.12 移除的内部变量 |
| `_Py_tracemalloc_config` | 同上 |
| `_PyTraceMalloc_NewReference` | 同上 |
| `PyCode_New` | 3.12 换成 `PyCode_NewWithPosOnlyArgs` |
| `PyUnicode_AsUnicode` / `PyUnicode_FromUnicode` | 3.3 起弃用,3.12 删除 |
| `_PyUnicode_Ready` | 同上 |
| `_PyGen_Send` | 3.11 起不再导出 |
armv7 侧只要前两个(`_PyGen_Send` 和 `_Py_CheckRecursionLimit`),
因为 armhf 的 libpython3.11 把其余的都提供了。
**安全性**:这些符号只在「真的执行 Python 代码」时才被调用,而 nax 只把 Ray
当成员目录,从不调用 Ray 的 Python 路径,所以零值占位不会被执行。
---
## 5. 编译
依赖(Debian 12,apt 源换 USTC 后可用):
```bash
apt install g++ protobuf-compiler libprotobuf-dev libgrpc++-dev \
protobuf-compiler-grpc libabsl-dev libboost-dev libssl-dev \
libflatbuffers-dev flatbuffers-compiler
# armv7 交叉
apt install g++-arm-linux-gnueabihf libatomic1:armhf libpython3.11:armhf
```
```bash
# 1) x86_64 shim(链 manylinux1_x86_64 wheel 里的 _raylet.so)
RAYSO=/path/r17x/ray-1.0.1.data/purelib/ray/_raylet.so bash ray/build101.sh
# 2) armv7 shim(链 armv7l wheel 里的 _raylet.so)
bash ray/build101_armv7.sh
# 3) nax 带 Ray(可选 feature,默认构建仍是纯静态单二进制)
cargo build --release -p nax-cli --features ray # x86
CARGO_TARGET_ARMV7_UNKNOWN_LINUX_GNUEABIHF_LINKER=arm-linux-gnueabihf-gcc \
NAX_RAY_LIB_NAME=nax_ray_armv7 \
NAX_RAY_LIBPYTHON=/usr/lib/arm-linux-gnueabihf/libpython3.11.so.1.0 \
cargo build --release -p nax-cli --features ray \
--target armv7-unknown-linux-gnueabihf
```
`build101.sh` 会自动打两个补丁(都打在解出来的头文件上,不动 ray 源码):
- `rpc/client_call.h`:`std::vector<grpc::CompletionQueue>` → `std::deque`。
grpc 1.51 删掉了 CompletionQueue 的移动构造,`reserve` + `emplace_back` 编不过。
- 影子头 `arrow/buffer.h`:1.0.1 只有 `PlasmaBuffer` 用 `shared_ptr<arrow::Buffer>`,
nax 不实例化它,给个最小声明即可(省掉整个 Arrow 依赖)。
- 宏 `-Dgrpc_impl=grpc`:1.0.1 用的是旧 grpc 命名空间,1.51 已并入 `grpc`。
---
## 6. 运行:nax 自己接入 Ray
不需要额外进程。`nax node` 看到 `NAX_RAY_RAYLET` 就会先注册成 Ray driver:
```bash
export NAX_RAY_GCS=127.0.0.1:6400 # Redis 主节点,不是 gcs_server
export NAX_RAY_RAYLET=/tmp/raylet_a.sock
export NAX_RAY_PLASMA=/tmp/plasma_a.sock
export NAX_RAY_NM_PORT=6413
nax node --site a --sites a,b --connect 127.0.0.1:9103 --data 1,2,3
```
输出(armv7 侧,qemu 承载):
```
接入 Ray 集群: gcs=127.0.0.1:6400 raylet=/tmp/raylet_a.sock nm_port=6413
Ray 节点已确认: node_id=235afb22db57c7249f4862ce9de95f92cffdd16c(由 raylet 分配)
Ray worker_id=01000000ffffffffffffffffffffffffffffffff
连接对端...
nax node · site=a · 2 方 · 3 个元素 · fxp=18
分片交换完成(2 方)
密文乘法完成(1 次)
还原完成: [9175040]
会话结果: 35
```
那个 node_id 是 raylet 在握手时分配的(`CoreWorker::GetRpcAddress().raylet_id()`),
两端拿到的是**不同**的值——这正是「两个进程真的挂在两个不同节点上」的证据。
`(1·4+1)+(2·5+1)+(3·6+1) = 35`,与 `nax-node::run_session` 的语义
`z = (x₁·x₂·…·xₙ + 1).sum()` 一致。
---
## 7. 已知限制
| 限制 | 说明 |
|---|---|
| 拿不到节点列表 | 1.0.1 的 `_raylet.so` 只导出了 `GlobalStateAccessor` 的 3 个方法(`GetActorInfo` / `GetActorCheckpointId` / `GetObjectInfo`),**没有 `GetAllNodeInfo`**。要列节点用 `ray/armv7/decode_gcs.py` 直读 Redis 分片,或改走 gRPC 直连 gcs_server。 |
| 成员变更只能看日志 | driver 内部订阅了节点表(日志里 `Received notification for node id = …, IsAlive = 1`),但没暴露回调给 C ABI。要结构化输出得改 shim 另开一条通道。 |
| 二进制不再自包含 | 开 `--features ray` 后动态依赖 `libnax_ray.so` + `libpython`。**默认构建不受影响**,仍是 700KB 级静态单二进制。 |
| 两端 worker_id 相同 | 两个进程都声明 `job_id=1`,driver worker id 由 job 派生,所以都是 `01000000ffff…`。要区分就设 `NAX_RAY_JOB`。 |
---
## 8. 复现
```bash
# 起 x86_64 原生 + armv7(qemu) 混合 1.0.1 集群(redis/gcs/plasma/raylet ×2)
bash ray/armv7/mixed_cluster.sh
# 闭环:两端各自注册成 Ray driver,然后跑跨架构 MPC
bash ray/armv7/mpc_ray.sh
```
`mixed_cluster.sh` 会清理上一轮的全套进程(redis 和 gcs_server 会占着 6400/6402,
只杀 raylet 会导致「新进程起不来但端口探测仍通过」的假成功)。
## 9. 与 2.59 的关系
`ray/build.sh` + `ray/nax_ray_shim.cc` 那一套仍然可用,用来在纯 x86 集群上验证
「nax 能接 Ray 的 C++ core」。但**边缘目标只能用 1.0.1**,而两版本不能混布,
所以生产形态是:整集群 1.0.1。2.59 那条线留作对照与未来 2.x 支持 32 位 ARM 时的参考。