📚 课程目录第4章量子任务描述语言与接口设计

4. 量子任务描述语言与接口设计

量子云平台要执行一个任务，首先必须把“做什么量子操作”和“在什么条件下执行”表达成机器可读的形式。这一层由量子任务描述语言承担，它决定了线路能否被正确解析、优化和映射到后端硬件。目前主流格式包括 OpenQASM、Quil 和 QIR，它们分别来自不同的生态，但都在描述同一类对象：量子比特、门操作、测量、经典寄存器以及控制流。

三种指令格式的定位与差异

OpenQASM 由 IBM 生态推动，语法接近 C 语言，以 qreg、creg、gate、measure 等关键字组织线路。它的优势是简洁、可读性强，适合手工编写和教学；局限是早期版本对复杂控制流和自定义门参数化支持有限，OpenQASM 3 才引入更完整的类型系统和时序控制。

Quil 由 Rigetti 提出，采用类似 Lisp 的指令风格，天然支持经典控制流与量子操作混合，例如 CONTROLLED、DAGGER 等修饰符可以直接作用于门。Quil 的指令粒度更接近硬件脉冲层，便于表达参数化脉冲和校准信息。

QIR（Quantum Intermediate Representation）基于 LLVM IR 扩展，是微软与 Quantinuum 等推动的中间表示。它不直接面向人类阅读，而是作为编译器前端与后端之间的桥梁，保留量子操作语义的同时复用 LLVM 的优化与类型系统。QIR 的价值在于跨平台：同一份 QIR 可以被不同后端消费，再翻译成目标硬件的原生指令。

三者的关系可以理解为：OpenQASM 和 Quil 更接近“源语言”，QIR 更接近“中间语言”。平台通常在前端接受 OpenQASM 或 Quil，在内部转换为 QIR 或自有 IR，再经过优化、映射和调度后下发到硬件。

RESTful API 的任务提交设计

RESTful API 是量子云平台最通用的提交方式，基于 HTTP 和 JSON，适合跨语言、跨网络的松耦合调用。一个典型的任务提交接口包含以下要素：

端点：如 POST /api/v1/tasks，用于创建任务；GET /api/v1/tasks/{id} 查询状态；GET /api/v1/tasks/{id}/result 获取结果。
请求体：包含线路描述、格式标识、后端名称、 shots 数、优化等级等字段。
响应体：返回任务 ID、状态、创建时间；异步任务还需提供轮询或回调地址。

下面是一个提交 OpenQASM 线路的请求示例，参数为示例值，用于说明字段结构：

POST /api/v1/tasks
Content-Type: application/json

{
  "circuit": "OPENQASM 3; include \"stdgates.inc\"; qubit[2] q; bit[2] c; h q[0]; cx q[0], q[1]; measure q -> c;",
  "format": "openqasm3",
  "backend": "superconducting_5q",
  "shots": 1024,
  "optimization_level": 2,
  "callback_url": "https://client.example.com/quantum/callback"
}

平台收到请求后，先校验线路语法与后端兼容性，再返回 202 Accepted 和任务 ID。客户端通过轮询 GET /api/v1/tasks/{id} 获取状态，状态通常包括 queued、running、completed、failed。完成后结果以计数直方图或概率分布返回。

gRPC 接口的适用场景

gRPC 基于 HTTP/2 和 Protobuf，适合高频、低延迟、强类型的场景。当平台需要批量提交大量小任务，或需要在客户端与服务端之间流式传输中间结果时，gRPC 比 REST 更有优势。其接口定义通常包含 SubmitTask、GetTaskStatus、StreamResults 等方法。Protobuf 的强类型约束减少了字段解析错误，但代价是客户端需要生成存根代码，跨语言支持不如 JSON 直接。

SDK 的封装价值

SDK 在 REST 或 gRPC 之上做了一层语言原生封装，把线路构造、序列化、提交、轮询、结果解析整合为几个函数调用。以 Python SDK 为例，用户可以用 QuantumCircuit 对象构建线路，调用 backend.run(circuit, shots=1024) 提交，再通过 result.get_counts() 获取结果。SDK 的价值在于隐藏协议细节，同时提供本地模拟器与远程后端的一致接口，降低切换成本。

选择接口方式时，可以按以下原则判断：交互式探索和跨语言集成优先 REST；高频批量提交和流式结果优先 gRPC；同一语言内的快速开发和教学演示优先 SDK。三者并非互斥，很多平台同时提供，底层共享同一套任务队列和调度器。

格式与接口的匹配要点

无论使用哪种接口，线路格式与后端能力的匹配都是关键。例如，后端只支持 cx 和 u3 门，而线路中使用了 ccx，平台需要在 IR 层将其分解为基本门序列；后端比特拓扑是线性的，而线路中有跨比特门，则需要插入 SWAP 或重新映射。这些转换发生在中间表示层，对用户透明，但会影响最终执行的保真度和线路深度。因此，提交时指定优化等级和映射策略，是控制结果质量的重要手段。

实际工程中，建议在客户端先做一次本地语法检查和后端兼容性预检，再提交到云端，避免因格式错误或门集不匹配导致任务失败。对于需要重复执行的任务，可以把线路和参数分离，通过参数化提交接口批量生成变体，减少重复传输和解析开销。