跳转到内容
Aira 3D

ADR-EVAL-001：Aira Evals Python 工具链与锁定策略

状态：Accepted
决策日期：2026-08-29
影响范围：packages/aira-evals、Inspect/Harbor adapter、CAD verifier 运行环境
验证依据：最小技术验证报告

Context

Section titled “Context”

aira-evals 需要同时接入 Inspect AI、Harbor 和 Python CAD 生态，但它不是 Aira 生产建模内核。工具链必须让实验可复现，同时避免把 Python 对象、CadQuery 类型或 某个 eval host 的 schema 变成 AMIR/Aira Interface 的规范真相。

Windows 本机验证还暴露了两个现实限制：项目目录中的虚拟环境可执行文件可能被 应用控制策略拦截；CadQuery 的未签名 OCP 原生扩展也可能无法加载。因此，“包能 安装”和“CAD 内核能在当前宿主执行”必须分成两个 gate。

Decision

Section titled “Decision”
  1. aira-evals 使用 CPython 3.12；package metadata 声明 >=3.12,<3.14。
  2. 使用 uv 管理 Python、虚拟环境和 uv.lock；正式 run 必须提交 lockfile，不能以 latest 作为结果 provenance。
  3. Aira canonical core 的运行依赖只保留 Pydantic；Inspect、Harbor、CadQuery 都是 optional extras，且首个 spike 固定到已验证版本：
    • Inspect AI 0.3.260；
    • Harbor 0.22.0；
    • CadQuery 2.7.0。
  4. src/aira_evals/contracts 禁止导入 Inspect、Harbor、CadQuery、OCCT 或 Manifold 类型；host/kernel 类型只能出现在 adapter、worker 或 task environment。
  5. Linux container 是不受信任 CAD 候选执行的规范环境。独立 Python process 只用于 可信 fixture 的功能验证，不能称为 security sandbox。
  6. 本地安全策略阻止普通 .venv 时，可以用 uv run --isolated 复现实验；该例外必须 写入报告，但不改变 lockfile 或正式 Linux runner 的要求。

Consequences

Section titled “Consequences”

正面：

  • 核心契约小而可迁移，Inspect/Harbor 升级不会直接修改 Aira 语义；
  • Python/CAD 的 ABI 与宿主问题会作为独立失败类型暴露；
  • 同一数据可在轻量 Inspect 和隔离 Harbor 中复用。

代价：

  • 需要维护 optional extras 和跨宿主 contract tests；
  • Windows 不能作为 CAD verifier 的唯一发布环境；
  • 更新 host/kernel 版本必须产生新 lock 和验证证据。

Rejected alternatives

Section titled “Rejected alternatives”
  • 使用系统 Python 3.14： 当前 CAD/Harbor 依赖兼容性和 wheel 可用性不足以作为 首个可复现基线。
  • 把 CadQuery 放进核心依赖： 会让纯 retrieval/schema 评测承担数百 MB 原生依赖 和不必要的 ABI 风险。
  • 只记录宽松版本范围： 无法将 scorer/kernel 行为绑定到一次可复现 run。