# `nax-ir`:算子图与轮次规划 > 这一层是被隐语(SecretFlow)逼出来的。 > SPU 的链路是 `JAX → XLA HLO → PPHLO → MPC 运行时`,其中 PPHLO 做的正是 > 「可见性推导 + MPC 专用优化」。nax 之前没有这一层:每个协议调用都是手写的, > 写的人要同时知道「数学上算什么」和「哪几步过网络」,两件事糊在一起。 ## 1. 没有这一层时,哪里疼 三个具体的疼法,都真实发生过: 1. **轮数没人能回答。** 「纵向 LR 一步要几个往返」以前只能靠读代码数, 而且数完还是错的(`mul` 内部有两次 open)。 2. **公开值只能出现一次,这条约束没有地方表达。** `truncate` 的 `cs`、 `poly` 的 `c₀` 各栽过一次:每方都带一份 → 结果变成 n 倍,**不报错**。 以前靠 review 和测试兜。 3. **本地算子和交互算子混在一起写。** 一段纯线性的预处理(加、减、转置、 整数缩放)在代码里长得很像交互算子,读的人不知道它其实零通信。 ## 2. 三层,各管一件事 ``` Graph 构造期:形状检查、可见性、公开值进密态表达式时插 Lift ↓ Plan 编译期:base/end 推导 → 分阶段 → 同阶段 open 合并 ↓ Exec 运行期:本地算子本地算,交互算子走 nax-vault ``` ### 2.1 `Vis` 是值的属性,不是环境变量 这一点和 `nax-runtime::device` 的结论一致:域跟着数据走。 由此两条硬规则: - `Open` 之后的值是 `Public`,拿它乘公开系数是**本地运算**,不再走协议; - 公开值进入密态表达式**必须显式 `Lift`**(构造期自动插)。 ```rust let x = g.input(Shape::vec(3)); // Secret let c = g.constant(vec![100, 100, 100], Shape::vec(3))?; // Public let s = g.add(x, c)?; // 自动插 Lift assert!(g.nodes().iter().any(|n| matches!(n.op, Op::Lift { .. }))); ``` `Lift` 落成「**只有 0 号携带明文,其余方持 0**」。这是加性分片的一个合法表示 (三片加起来正好是明文),也正是 `truncate` 里 `cs` 的处理方式。 > 为什么不让每方都带一份?因为三方时和会变成 `3c`。能跑、能收敛、数是错的 —— > 这类 bug 是 nax 历史上最贵的一类。 ### 2.2 每个算子自带真实往返数 | 算子 | 往返 | 依据 | |---|---|---| | `matmul` / `mul` | 2 | `d`/`e` 合成一轮(`open_batch`),截断的 `c` 再一轮 | | `mul_raw` | 1 | 精确乘,不截断 ⇒ 只要 `d`/`e` 那一轮 | | `cmp` | 9 | 见下 | | `select` | 1 | 一次精确乘 | | `trunc` | 1 | 打开 `c = x + r` | | `open` | 1 | 广播分片 | | `scale`(小数系数) | 1 | 乘法把定点尺度翻倍,截断必须走协议 | | `scale` / `scale_int`(**整数**系数) | 0 | 尺度不变,连右移都不需要 | | `add` / `sub` / `sum` / `sum_rows` / `transpose` / `slice` / `concat` / `bit_not` / `lift` | 0 | 对加性分片透明 | | `mul_public` | 0 | 本地乘公开常量向量(尺度 +1,后面补一次 `trunc`) | 最后一行里 `transpose` 值得单独说:分片按**同一布局**切,所以「转置后取分片」 就等于「取分片后转置」,纯本地置换。`slice` 同理 —— 取第 i 行是本地复制。 `cmp` 的 9 轮不是拍脑袋:`msb_raw` 里 1 次 `open`(打开被掩盖的差值)+ `bit_lt_public` 的 Hillis–Steele 扫描(63 位 → 6 次 Beaver 乘)+ 1 次 `z = p·d` + 1 次 `msb = t ⊕ borrow`。常量 `CMP_ROUNDS` 与真跑出来的突发次数由 `tests/cmp_rounds.rs` 对齐 —— 协议改了没同步改常量,那条测试会红。 ### 2.3 定点尺度挂在值上(这一节是踩出来的) nax 的密文是定点数:一个值的编码是 `真实值 · 2^((k+1)·fxp)`,`k` 就是它的 **尺度**。基准值是 `k = 0`;乘一个 fxp 编码的**公开系数**会变成 `k = 1` (`2·fxp`),必须 `trunc` 回 0 才能和别的基准值相加。 手写协议序列时这件事全靠人记,`nax-ml` 里就有注释在提醒: > `scale_public` 把 grad 乘到 2·fxp,再和 w(fxp)相加需要对齐 漏了不是崩溃,是**结果差 2^fxp 倍**。所以 `k` 挂在 `Node` 上: ```rust let x = g.input(Shape::vec(2)); let c = g.constant_f64(18, &[0.5, 0.5], Shape::vec(2))?; let scaled = g.mul_public(x, c)?; // k = 1 g.add(x, scaled) // 构造期就拒:定点尺度不一致 ``` 两条由此得来的结论: 1. **截断可以延后。** 多项式先乘 4 个系数(都是 `k=1`)、加在一起、最后只 `trunc` 一次 —— 从 4 轮降到 1 轮。只要每一步的 `k` 对得上,延后就是安全的; 对不上,构造期就报错。 2. **整数系数和系数不是一回事。** `Scale` 走 `scale_public`(编系数再乘, 尺度 +1、必须截断);`ScaleInt` 是裸的 `wrapping_mul(k)`(尺度不变、0 轮)。 两者对整数系数的**结果**一样,代价差一轮。 > 第 2 条是这一层自己的第一个 bug:第一版让整数系数走 `Scale` 却跳过截断, > 结果差 `2^fxp` 倍 —— 而且当时没有任何测试比对过整数系数的值。 > 现在 `tests/schedule.rs` 用「`scale` 调用次数必须是 0、`scale_int` 必须是 1」 > 把它钉住。 ### 2.4 阶段与轮数 ```text base(n) = max(end(前驱)) end(n) = base(n) + cost(n) ``` 同 `base` 的交互算子互不依赖(依赖了的话 `base` 会被抬到对方的 `end`), 所以可以**一起发、一起收**。 轮数不是 `max(end)`。第一版这么写,结果在「同一阶段既有 `scale` 又有 `open`」 时少算一轮 —— 这两者串行,搭不上车。现在的数法跟执行器逐条对齐: ```text 轮数 = Σ cost(所有交互算子) − Σ (每个阶段的 open 个数 − 1) ``` 分阶段本身是 `O(n)`:`base` 的取值范围是 `0..=最大轮数`,所以按 `base` 直接 散列成桶,而不是「对每个去重后的 `base` 扫一遍全图」。后者是 `O(n·k)`, `MIN`/`MAX` 那种逐行归约会造出几千个不同 `base` 的节点,图一大就废。 ## 3. 实测 `nax plan` 把纵向 LR 的**一整次迭代**编一遍(`--rows/--features/--sigmoid-degree` 只影响形状和多项式次数,与数据无关): ``` $ nax plan --rows 8 --features 4 --lr 0.1 起始轮 | 交互算子 | 本地算子 | 交互数 -------+----------+----------------------------------------------------------------------------------------------+------- 1 | matmul | input, input, input, const, lift, concat, const, const, lift, const, const, const, transpose | 1 3 | scale | — | 1 4 | mul | mul_public, add | 1 6 | mul, mul | — | 2 10 | mul, mul | mul_public, add | 2 14 | trunc | mul_public, add, mul_public, add | 1 15 | matmul | sub | 1 17 | scale | — | 1 18 | — | sub | 0 编译结果 算子总数 | 33 交互算子 | 10 本地算子 | 23 公开值抬升 | 2 每轮迭代往返 | 17 ``` `sigmoid` 的次数决定多项式那几段 `mul` 的个数,也就决定了轮数: | `--sigmoid-degree` | 3 | 5 | 7(默认) | 9 | |---|---|---|---|---| | 每轮迭代往返 | 11 | 13 | **17** | 19 | `--l2 0.1` 恰好 **+1 轮**(多一条「乘公开系数 + 截断」),测试 `l2_costs_exactly_one_more_round` 钉住。`--lr` 不改变轮数:步长是 `lr/n`, `lr=2` 时也还是 `0.25` 这种小数,照样 `scale` + `trunc`。 > **修正**:本节早前贴的是「14 个算子 / 5 交互 / 7 轮」,`--lr 2` 时 5 轮。 > 那是 `cmd_plan` 里手搭的最小 demo 图(线性梯度步,不含 `sigmoid` 多项式)。 > `nax-ml` 迁移之后 `nax plan` 直接调 `VerticalLR::build_epoch`,报的是真迭代, > 数字随之变成 33 算子 / 17 轮。**旧数字按 demo 图理解是对的,按 `nax plan` > 的输出理解是错的。** 整数系数 `scale` 零往返那条结论本身仍然成立 > (`Op::ScaleInt`),只是真迭代里步长不是整数,碰不到它 —— 由 > `schedule.rs` 的库级测试直接钉。 > 注意第一行那几个 `const` / `lift` / `concat`:33 个算子里 23 个是纯本地的, > 包括 `transpose` 和偏置列拼接时的两次 `lift`。**图的规模不等于协议的规模**, > 这是这一层最直接的产出。 ### 3.2 密态 SQL 的 WHERE + 聚合 `nax sql-plan` 把一条掩码 WHERE + 聚合的查询编一遍(不联网、不需要数据 —— 图只依赖形状): ``` $ nax sql-plan --rows 6 --where "0<400" --aggs count,sum,avg,min,max 掩码段(谓词 → 0/1 位 → 掩码后列 → 命中数) 起始轮 | 交互算子 | 本地算子 | 交互数 -------+---------------+---------------------------------------------+------- 1 | cmp | input, const, lift | 1 10 | mul_raw, open | bit_not, scale_int, bit_not, scale_int, sum | 2 聚合段(SUM / AVG / MIN / MAX) 起始轮 | 交互算子 | 本地算子 | 交互数 -------+-----------------------+------------------------------+------- 1 | open, scale, cmp, cmp | input×3, sum×2, add, slice×12 | 4 21 | open | — | 1 22 | select, select | — | 2 24 | cmp, cmp | — | 2 ... 每归约一行 10 轮,MIN / MAX 各 5 行 ... 104 | open, open | — | 2 掩码段往返 | 11 聚合段往返 | 104 总往返 | 115 ``` 两件事一眼可见,而且以前都读不出来: 1. **`slice×12` 是零通信的。** `MIN`/`MAX` 的逐行归约在图上长成 12 个节点 (每人 2 个,`padded` 取行),但它们全是本地复制 —— 图大不等于协议大。 2. **`MIN`/`MAX` 是绝对大头**:6 行就是 `5 × (9 + 1) × 2 = 100` 轮,占 87%。 要压这个数,得换归约方式(树形不省轮数,因为串行依赖不变),或者换协议 (比较的 9 轮是 `bit_lt` 的实现决定的)。 > `cmp, cmp` 和 `select, select` 落在同一行,说明它们同一阶段。模型把它们 > **按顺序各算一遍** —— 这与执行器一致(`eval_comm` 是顺序循环),也与 > 「跨类别不共享尾部轮」那条边界一致。真要并行化,得把 Beaver 的收发摊到 > IR 层,那是另一件事。 ### 3.3 分组:相等判断换单调前缀 `GROUP BY` 的默认路径是「每组一次 `gcol == g`」,而 `bit_eq` 是两次比较 (18 轮/组),按组累加 —— `N` 个组光比较就要 `18N` 轮。 如果分组码是**整数**,同一件事可以换个问法:不问「这行是不是第 g 组」, 而问「这行码 ≤ g 吗」。这 `N+1` 个单调前缀一次建完,组内值由**累积和相减** 得到,`COUNT` 甚至不用乘掩码(前缀是位,求和就是计数),所有 `open` 合并成 一次,`SUM`/`AVG` 直接落在明文上 —— 没有第二段图。 ``` $ nax sql-plan --rows 8 --groups 8 --aggs count,sum --group-mode coded 前缀段(谓词 → 分组码搬家 → N+1 个单调前缀 → 累积和) 起始轮 | 交互算子 | 本地算子 | 交互数 -------+------------------------------------------------+---------------------------------+------- 1 | cmp × 9 | input, const, lift × 9 | 9 82 | open, mul_raw 交替 × 9 对 | sum × 9 | 18 92 | open × 9 | — | 9 掩码段往返 | 92 聚合段往返 | 0 总往返 | 92 ``` 第二行那 9 对 `open`/`mul_raw` 就是「累积计数」和「累积和」:计数只要 `sum(前缀位)`(本地),和要一次 `mul_raw(前缀位, 列)`。第三行是它们的 `open` 全部落在同一阶段 —— 9 个组的输出一起出来。 | 组数 | 逐组比较 | 整数码前缀和 | 倍数 | |---|---|---|---| | 2 | 42 | 32 | 1.3× | | 4 | 82 | 52 | 1.6× | | 8 | 162 | **92** | **1.8×** | 两处代价都写在这里,不藏: * **分组码必须是整数**。非整数码会落到它上方最近的一组(`1.5 → 2 号组`), 而不是「哪组都不算」—— `tests/coded.rs` 里有一条测试专门钉这个语义; * **不支持 `MIN`/`MAX`**。前缀和只知道「和」,不知道「谁最大」,所以请求它们 直接报错,不会静默降级。 越界码(负数、`≥ N`)被丢掉,这点与逐组比较一致:两端的边界 `−0.5` / `N−0.5` 就是为它留的。 `WHERE` 未命中的行不逐组乘 `base`,而是**把码搬到 −1000**(按 `2^fxp` 缩放的 raw 值)。这些行会出现在每一个前缀里,差分时自动抵消 —— 省掉 `2N` 轮。 第一版拿真值 `−1000` 直接当 raw 用,它比 `0.5·2^18` 还大,结果被算进了每一个 前缀:行数变成全表、`SUM` 变成全表之和,**且不报错**。这条坑写在 `secure_graph.rs` 的源码注释里。 ## 4. 谁在用这一层 到目前为止两个消费者,迁移方式一样:**手写协议序列搬上图,轮数改由编译器报**。 | | `nax-ml` 纵向 LR | `nax-sql::secure` 掩码聚合 | |---|---|---| | 迁移前的形态 | 一次迭代一串 `matmul_trunc` / `truncate` / `scale_public` | 掩码 → `bit_mask` → 各聚合逐个 `reveal` | | 图建几次 | 1 次(`build_epoch`),跑 `epochs` 遍 | 每条查询 2 段(`AVG` 的除数要执行后才知道) | | 报出来的数 | `nax plan`:**17 轮/迭代**(degree 7),degree 3 是 11 轮 | `nax sql-plan`:见上,`[COUNT,SUM,AVG,MIN,MAX]` 共 **115 轮** | | 回归判据 | 帧序列逐帧相同 + ≤64 ULP | `COUNT`/`SUM`/`MIN`/`MAX` **逐位相同**、`AVG` ≤1e-4、轮数不增 | SQL 侧还有第三条路径不在上表里,因为它是**换算法**而不是搬家: `--group-mode coded` 把逐组 `==` 换成整数码前缀和(§3.3),8 组从 162 轮降到 92 轮。它自带两条契约(码是整数、不支持 `MIN`/`MAX`),所以是显式开关, 默认仍是逐组比较。 两边的「为什么不是逐位相同」都指向同一处:`nax-vault::truncate` 是随机舍入 (`c = x + r`,`out = (c >> fxp) − (r >> fxp)`),只有 `x` 的低 `fxp` 位全 0 才 精确。所以**同一段手写代码换个 seed 结果都会变**(`nax-ml` 的 `legacy_is_seed_sensitive` 钉住这一点)。真正成立的判据是「协议形状相同 + 数值在舍入预算内」。 搬家的净收益(都是实测,不是估计): | 场景 | 迁移前 | 迁移后 | |---|---|---| | `[COUNT,SUM,AVG,MIN,MAX]`,5 行,`col < 300` | 96 轮 | 95 轮 | | `GROUP BY` 2 组,`[COUNT,SUM]` | 44 轮 | 42 轮 | | `GROUP BY` 4 组 | 88 轮 | 82 轮 | | `GROUP BY` 8 组 | 176 轮 | 162 轮 | 省下的都是 `open` 合并(`GROUP BY` 是 `2N − 2` 轮,8~9%),**不是数量级**。 分组的主导成本仍是每组的 `bit_eq`(两次比较 = 18 轮),它按组累加。 真正的量级在别处:整数分组码可以把 `gcol == g` 换成 `lt(gcol, g+0.5) − lt(gcol, g−0.5)`,`N` 组只要 `N+1` 次比较 —— 但那是语义 变更(非整数分组码会落到相邻组),不混在搬家这一次里做。 **所以搬家的价值不在提速**,在于:轮数第一次能报出来(`--rows/--features/--groups` 就能算,不必先有数据),以及「漏一次截断差 2^fxp 倍」这类错从 review 靠运气 变成建图期报错。 ## 5. 变异验证(验证测试真的在测东西) 按项目惯例,把实现改坏,确认对应测试**失败**: | 改坏的地方 | 结果 | |---|---| | `Lift` 改成每方都带明文 | 3 条失败,报错是「公开常量被加了 2 次」 | | 取消同阶段合并(每节点自成阶段) | `independent_opens_share_one_round` 失败;端到端那条以「两次 open 必须落在同一个阶段」失败 | | 执行时逐个 `open` 而非批量 | 调用日志从 `open_batch:2` 变成 `open_batch:1, open_batch:1` | | 整数系数改回走 `Scale` 却不截断 | `two_opens_are_issued_as_one_batch` 失败(`scale` 出现、`scale_int` 消失)—— 这就是当初真出的那个 bug | | `bit_not` 的常量 1 每方都加 | n 方掩码测试整体错,两方用例仍过 —— 典型的「两方看不出、三方才分叉」 | | `MIN` 补位符号取反(`+SENTINEL` → `−SENTINEL`) | `secure_where_aggregate_matches_engine` 与 `secure_cmp_col_matches_engine` 失败 | | `CMP_ROUNDS` 改成 8 | `cmp_rounds_matches_the_real_protocol` **和** `query_rounds_matches_the_measured_protocol` 一起失败 | 最后一行是关键:它说明 `nax sql-plan` 报出来的 115 轮不是「自己跟自己一致」, 而是锚在真协议的收发次数上。轮数模型和实测是两条独立的链,只有两边都改对 才同时绿。 第三条尤其说明问题:**静态分析说「合并了」不等于运行时真的合并**, 所以 `tests/schedule.rs` 用一个记录调用序的明文档执行器把这件事钉住。 ## 6. 这一层不做什么 写清楚比假装完整有用: - **不是 MLIR。** 没有通用 pass 框架、没有 shape 多态、没有多后端 lowering。 - **不做协议选择。** `mul` 永远是 Beaver,不会因为参与方数变 3 就换 ABY3 —— `nax-vault` 目前只有一套协议,编译期假装能选是骗人。 - **不做恶意安全。** 轮次合并不改变半诚实模型下的语义:合并的两个 `open` 本来就互不依赖,只是把等待叠在一起。 - **跨类别不共享尾部轮。** 同阶段的 `open` 合成一轮;`mul`/`matmul` 的 2 轮 不与 `open` 交叉共享 —— 那要求把 Beaver 拆到 IR 层自己持有三元组, 代价是 IR 要懂协议细节。现在的估计是**上界**,真跑只快不慢。 - **没有前端。** 图用 Rust 手写(`Graph::matmul(...)`),不做语言绑定。 ## 7. 与 `nax-runtime::device` 的关系 两个模块回答不同的问题,不要混: | | `nax-runtime::device` | `nax-ir` | |---|---|---| | 回答 | 「这个值现在在哪一域」 | 「这次计算要几个往返」 | | 时机 | 运行期 | 编译期 | | 粒度 | 单个值 | 整张图 | | 对非线性算子 | 显式拒绝,指向 `nax-sql::secure` | 标上代价,交给调度 | 两者都建立在同一个前提上:**域/可见性是值的属性**。所以 `Vis` 和 `DeviceKind` 语义一致,只是 `nax-ir` 多带了一份「谁依赖谁」的信息。