Files
ssw-mpc/docs/IR.md
T
rong 903f14efb2 feat(sql): GROUP BY 走整数码前缀和,8 组 162 → 92 轮
影响:`secure_group_by` 新增 `GroupMode::IntegerCode` 路径,每组相等判断
(`bit_eq` = 两次 `bit_lt`,18 轮/组、串行累加)换成 `N+1` 个单调前缀
「码 ≤ g」,`COUNT` 取前缀位之和、`SUM` 取 `mul_raw(前缀位, 列)`,所有 `open`
落在同一阶段合成一次,**组内值在明文侧差分**,没有第二段图。默认仍是
`GroupMode::Exact`,语义不变。

实测(`nax sql-plan --rows 8 --aggs count,sum`):2 组 42→32、4 组 82→52、
8 组 162→92;每组建图成本约 20 → 11 轮。带 WHERE 的增量是「一次比较 + 一次
搬家乘」10~11 轮。

新增:

- `secure_graph::build_prefix_stage` —— 谓词 → 码搬家 → N+1 个前缀 → 累积和
- `secure_group_by_coded` / `secure_group_by_pred_coded`,`query_rounds` 收
  `GroupMode`,`nax sql-plan --group-mode coded`、`nax sql --group-mode coded`
- `crates/nax-sql/tests/coded.rs` 12 条:与 Exact 对拍(`COUNT`/`SUM` 逐位、
  `AVG` 相对 1e-4)、复合谓词、越界/非整数码契约、空组、k-匿名、单组、轮数钉值

三条契约(写进 `docs/IR.md` §3.3,不隐藏代价):分组码必须是整数(非整数落
到上方最近一组);不支持 MIN/MAX(前缀和还原不出极值,直接报错不降级);
越界码丢弃(与逐组比较一致,两端边界 `−0.5` / `N−0.5` 就是为它留的)。

WHERE 未命中行不逐组乘 `base`(`2N` 轮),而是把码搬到 `−1000·2^fxp` 让它在
差分中自动抵消。**第一版把 `−1000` 当 raw 用**:分组码列是 fxp 编码,
`0.5` 编出来是 `131072`,于是 `−1000` 比每个边界都小,全部行被算进每个前缀
(行数变全表、SUM 变全表之和且不报错)。改为按 `2^fxp` 缩放,`fxp > 40` 拒绝。

变异验证 4 条全部按预期变红后还原:停放值不缩放(2 红)、边界少 `−0.5`
(只有非整数码契约那条红,整数码下 `<g` 与 `<g+0.5` 等价)、累积和忘记差分
(7 红)。

全量 462 用例通过 / 0 失败,`-Dwarnings` 零告警,`nax-core` no_std 守线过。
2026-11-01 19:49:16 +08:00

353 lines
19 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.
# `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` 多带了一份「谁依赖谁」的信息。