0.10.0：lookup chunk 并行（opt-in）¶

版本锚定：Scalim 0.10.0。
同一 LoadRef(keys) 被分片后，片间默认仍串行。
0.10 新增 Python opt-in：在 parallel_mode="adaptive" 下允许片间并行，重叠 RTT 等待——当时无新 YAML 并行键；分片大小 alone 不是并行开关。

架构 / 护栏：parallel-modes.md §3.6。
版本亮点总览：0.10.0 重点特性。

姊妹能力：write-precompute-0.10 · rowwise-fusion-0.10。

测量摘要日期：。

数据：assets/data/lookup-chunk-parallel-0.10.json。¶

1. 命名与公开面（相对 ≤0.9）¶

启用示例（Python）：

from scalim.dsl.yaml_dsl import DemandRunRuntimeOptions

options = DemandRunRuntimeOptions(
    parallel_mode="adaptive",
    parallelize_lookup_chunks=True,
    max_workers=8,          # 全局在途帽 W
    max_chunk_workers=None, # 可选：单步扇出再收紧
)

flowchart TD
  A[LoadRef keys + lookup_chunk_size] --> B{parallel_mode=adaptive<br/>且 parallelize_lookup_chunks?}
  B -->|否| S[串行分片 · 今日路径]
  B -->|是| P[独立 chunk 池扇出<br/>在途 ≤ W]
  P --> M[按 offset 升序 first-wins 合并]
  S --> M2[同序合并]
  M --> C[至多一次 load_ref_cache 写入]
  M2 --> C

2. 一图看懂：串行分片 vs opt-in 并行¶

flowchart LR
  subgraph serial["默认 / seq / 未 opt-in"]
    S1[chunk 0] --> S2[chunk 1] --> S3[chunk N]
  end

  subgraph parallel["adaptive + opt-in"]
    P1[chunk 0]
    P2[chunk 1]
    P3[chunk N]
  end

  serial -.->|同一合并语义 · 成功路径 calls 相等<br/>RSS 目标 ≤ +10%| parallel

读法：加速来自 RTT 重叠，不是少调 loader。片数 × RTT 主导时收益最大；外部 QPS 会被放大到约 W。

3. 实际例子：前后对拍¶

合成 sleep-RTT shape（固定 time.sleep，无真实 DB）；分进程分别跑串行 / 并行，避免同进程 ru_maxrss 高水位交叉污染。

3.1 加速比（D3）¶

约 3.3×–6.4×（Python 3.6.15 sleep 上限；真实库通常更低，取决于连接池与 QPS）。

3.2 墙钟：串行 vs 并行（D3）¶

3.3 峰值 RSS 增量（D3；虚线 = +10% 目标）¶

3.4 明细表¶

测量环境：Python 3.6.15，分进程 A/B。数据：assets/data/lookup-chunk-parallel-0.10.json。

读法

• 「更快」= 片间等待重叠，不是少算 / 少调用（成功路径 calls 相等）。
• 大键集加速比略低：物化与合并占比上升，RTT 占比下降。
• 全部 shape：values_sample 相等。大 shape 进程 RSS Δ 约 +10.3%–+11.5%（略高于目标 ≤10%；属 sleep-RTT 合成证据 / 解释器差异，不改变成功路径语义）。

复现：

# 开发环境
uv run python docs/doc/releases/repro/chunk-parallel/run_ab.py \
  --keys 20000 --chunk-size 100 --rtt-ms 5 --max-workers 8
# Python 3.6 运行时边界
PYTHONPATH=src .tmp/venvs/py36-scalim/bin/python docs/doc/releases/repro/chunk-parallel/run_ab.py \
  --keys 100000 --chunk-size 500 --rtt-ms 5 --max-workers 8 \
  --out .tmp/evidence/c30-chunk-parallel/ab_100k.json

4. 谁受益 / 谁不变¶

flowchart TD
  Start[你的 LoadRef] --> A{键集很大且已设 lookup_chunk_size?}
  A -->|否| Skip[先别开：没有片就没有重叠]
  A -->|是| B{loader 以 RTT/IO 为主?}
  B -->|否·CPU 重| Mild[收益通常有限]
  B -->|是| C{外部系统扛得住 ≈W 并发?}
  C -->|否| Cap[用 max_workers / max_chunk_workers 收紧或不开]
  C -->|是| Win[opt-in：常见数倍墙钟]
  Start --> D{需要严格主线程 loader_call?}
  D -->|是| Caution[单 ref 退化层时回调在 worker 线程]

失败路径注意：已在途 chunk MAY 仍跑完，错误路径 loader 调用次数可能 高于 串行；成功路径次数一致。半份 merged / 半份 cache 不会当成功返回。

5. GitHub Release 引用¶

## Highlights
- lookup chunk 并行（opt-in）：adaptive + parallelize_lookup_chunks，
  同 LoadRef 多片重叠 RTT；无新 YAML；lookup_chunk_size ≠ 并行开关。
  详述与对拍：docs/doc/releases/lookup-chunk-parallel-0.10.md
- write-precompute：docs/doc/releases/write-precompute-0.10.md
- row-wise fusion：docs/doc/releases/rowwise-fusion-0.10.md

6. 相关链接¶

• Spec：llmanspec/specs/execution-refloader-chunk-parallelism/
• 归档 change：llmanspec/changes/archive/2026-08-02-c30-refloader-chunk-parallelism/
• 复现脚本（已入库）：docs/doc/releases/repro/chunk-parallel/run_ab.py；输出证据（可再生成，不入库）：.tmp/evidence/c30-chunk-parallel/