重试、恢复与本地历史¶
要在新的 LocalBackend 实例或 Python 进程中继续实验，创建后端时指定 store=。任务定义存入 SQLite 文件，结果保存在旁边的 <store>.artifacts 目录；读取结果时会检查校验和。
保存结果，再重新读取¶
下面先完成一次运行，再通过新的后端实例恢复同一任务。示例使用临时目录，退出时会清理数据；保存自己的实验时，请改用需要长期保留的路径。
"""用新的后端实例读取已经保存的结果。"""
from __future__ import annotations
import json
from pathlib import Path
from tempfile import TemporaryDirectory
from cascaqit import Circuit, LocalBackend, RetryPolicy
def main() -> None:
"""用新的后端实例读取已经保存的结果。"""
with TemporaryDirectory(prefix="cascaqit-resume-") as directory:
store = Path(directory) / "runs.sqlite"
backend = LocalBackend(store=store, seed=7)
job = backend.run(
Circuit(1).h(0),
shots=100,
retry=RetryPolicy(max_attempts=3),
idempotency_key="experiment-001",
)
result = job.result()
restored = LocalBackend(store=store).resume(job.job_id)
same_result = restored.result().stable_hash() == result.stable_hash()
page = backend.history(limit=20, statuses=("completed", "failed"))
if not same_result or len(page.entries) != 1:
raise RuntimeError("恢复后的结果应与保存的结果一致。")
print(
json.dumps(
{
"restored_result_matches": same_result,
"counts_total": sum(result.counts.values()),
"history_entries": len(page.entries),
"restored_status": restored.status().state,
},
sort_keys=True,
)
)
if __name__ == "__main__":
main()
python examples/learning/guides/resume_job_zh.py
{
"counts_total": 100,
"history_entries": 1,
"restored_result_matches": true,
"restored_status": "completed"
}
restored_result_matches 应为 true，历史记录应只有一条，采样总数应为100。恢复已经完成的任务会复用已保存的结果。这个例子检查结果恢复，并没有制造失败来触发重试。
完整离线示例还展示了 Hybrid 参数扫描的保存与恢复。
哪些错误会重试¶
只有带有可重试标记的 CASCAQit 异常，或 RetryPolicy 明确允许的错误码，才会触发重试。输入校验、编译、参数和存储损坏错误，以及未分类的 Python 异常，默认不会重试。增加 max_attempts 无法修正错误参数。
未配置 store= 时，任务只保存在当前进程，调用 result() 才执行计算。resume() 和 history() 都需要存储路径。
恢复时会使用哪些设置¶
恢复使用首次提交时保存的程序、绑定值、种子、采样次数、模拟选项、噪声、可观测量、重试策略和扫描顺序。新后端实例的默认设置不会替换它们。
显式传入 idempotency_key 可以防止同一定义重复提交。同一个键对应不同执行设置时会报错；不提供键的多次运行相互独立。
扫描中已完成的子任务通过校验和检查后会直接复用。等待执行或中断的子任务按保存的重试策略继续运行，最终结果按扫描索引排序。具体扫描方法见参数扫描指南。
查询和清理历史¶
history() 可以按状态、程序类型、任务类型和 UTC 创建时间过滤。分页游标只能用于原来的存储和过滤条件。每条历史记录包含标识、状态、尝试次数或参数点数量、时间，以及结果或错误的引用；查询历史不会加载完整结果文件。
任务不会自动过期，目前也没有批量清理接口。确认结果不再需要后，再同时删除 SQLite 文件和对应的 <store>.artifacts 目录。
SQLite 只协调同一主机上的执行尝试，不提供跨主机任务调度或仅执行一次的保证。尝试超时依赖执行过程配合检查，不能强制终止 NumPy、SciPy 或本地扩展中的计算。本地持久化执行不会连接硬件或云服务。
接口说明见 LocalBackend 和 RetryPolicy。