跳转至

09 Driver API

目的

本章定义统一的后端 Driver 接口。

Driver 的角色

Driver API 是面向后端执行的契约层。它消费 canonical bundle 与 program 信息，并把这些信息转换为 backend-specific 的计划、编译、执行与诊断。

在参考草案中，driver 层被定位为 canonical UQCI 工件下降到 backend-native 执行链之前的最后边界。本仓库保留这一定位。

必需职责

后端接入应暴露稳定的能力入口，用于：

  • validation
  • resource allocation
  • scheduling
  • compilation
  • execution
  • diagnostics

仓库中的后端扩展指南还建议暴露 get_device_spec 与 fetch_results 等能力入口。具体方法粒度可以不同，但生命周期职责应保持可见。

生命周期解释

由参考草案与仓库设计共同隐含的后端流程是：

  1. 根据能力边界验证 canonical 程序
  2. 分配资源并解决冲突
  3. 在时序与约束规则下完成调度或排序
  4. 编译为 backend-facing 执行形式
  5. 运行已编译计划
  6. 返回结果与诊断

这一流程具有强实现导向，但仍然保留 canonical 语义在其上游的位置。

最小契约

在仓库层面，最小契约为：

  • validate(bundle) -> ValidationReport
  • plan(bundle) -> ExecutionPlan
  • run(bundle) -> RunResult

具体实现可以在内部细分为 validate_ir、allocate_resources、schedule、compile 等步骤。

输入与规范性依赖

Driver 应消费 canonical 程序以及执行所需的规范性 sidecar 工件。就当前仓库而言，典型输入包括：

  • UQCIProgram
  • Manifest
  • DeviceSpec
  • 在需要校准上下文时提供的 CalSet
  • 可选补充工件，如 pulseir

这使 Driver API 对 Schema 友好，但不会把 Schema 文件本身误当作语义真源。

架构规则

Driver 必须把 UQCI IR 与规范性 sidecar 作为权威输入面。OpenQASM 可以作为兼容导出或调试视图，但不能变成后端唯一输入真相。

这一规则防止后端边界悄悄颠倒架构归属关系。

扩展规则

后端可以扩展诊断与 capability metadata，但仍必须返回标准化的结果与验证抽象，以保证仓库层面的互操作与可测试性。

稳定性规则

Driver API 应当稳定到足以支持：

  • 新后端家族在不改写 canonical core 的前提下加入
  • mock backend 与未来真实 backend 共享顶层契约
  • 测试对 bundle 到 result 的主链路进行一致验证