📚 课程目录第3章量子任务提交前的环境准备

3. 量子任务提交前的环境准备

在把第一个量子线路提交到云端之前，真正决定后续体验的往往不是线路写得多巧妙，而是环境是否准备到位。账户、密钥、SDK、本地解释器与网络连通性这五件事中任何一环出问题，都会表现为“提交失败”“认证错误”或“结果为空”，而错误信息常常并不直指根因。本节按“账户与密钥 → SDK 与版本 → 本地环境 → 连接测试 → 最小提交”的顺序展开，目标是让你在十分钟内搭出一个可复现、可排障的提交环境。

账户注册与 API 密钥管理

主流量子云平台（如 IBM Quantum、Amazon Braket、Azure Quantum）都采用“账户 + 凭证”的分离模型：账户标识你是谁，凭证证明你有权调用后端。以 IBM Quantum 为例，注册后进入控制台的 API keys 页面即可创建密钥，密钥是一串长字符串，通常只在创建时完整显示一次。拿到密钥后不要写进源码，而是写入本地凭证文件或环境变量。IBM 平台的惯例是写入 ~/.qiskit/qiskit-ibm.json，并用一个自定义名称（如 my-channel）保存：

{
  "my-channel": {
    "channel": "ibm_quantum",
    "token": "粘贴你的API密钥",
    "instance": "crn:v1:bluemix:public:quantum-computing:..."
  }
}

这里有两个容易踩的坑。第一，channel 字段必须与平台当前要求一致，旧教程里的 ibm_q 已废弃，写错会得到“无法识别渠道”的报错。第二，instance 是资源实例标识（CRN），免费套餐用户也需要填写，否则提交时会提示无可用实例。密钥属于敏感凭证，一旦泄露应立即在控制台吊销并重建；团队协作时用环境变量 QISKIT_IBM_TOKEN 注入，避免把凭证文件提交进 Git 仓库。

SDK 安装与版本控制

量子 SDK 迭代很快，接口在版本间可能发生破坏性变更。以 Qiskit 为例，1.x 系列把 IBMQ.load_account() 这类旧接口移除，改用 QiskitRuntimeService。因此安装时不要只写 pip install qiskit，而应锁定版本区间：

python -m venv .venv
source .venv/bin/activate        # Windows 用 .venv\Scripts\activate
pip install "qiskit>=1.0,<2.0" qiskit-ibm-runtime
pip freeze > requirements.txt

建议同时安装 qiskit-aer 用于本地模拟，这样在联网提交前可以先验证线路逻辑。版本控制的关键动作是：用虚拟环境隔离项目依赖，用 requirements.txt 固化版本，并在升级 SDK 后重跑最小提交示例确认接口未变。若团队多人协作，把 Python 版本也写进文档（如 3.10～3.12），避免因解释器差异导致二进制依赖安装失败。

本地开发环境配置

本地环境要解决三件事：解释器、依赖、凭证加载路径。推荐用 VS Code 配合 Python 扩展，把虚拟环境选为当前解释器，这样终端与编辑器使用同一套依赖。凭证加载方面，Qiskit Runtime 会按顺序查找环境变量、~/.qiskit/qiskit-ibm.json 和 ~/.qiskit/qiskitrc，因此只要文件放在默认路径，代码里就不必出现密钥。若使用 Braket，则通过 aws configure 写入 ~/.aws/credentials，并在创建 AwsQuantumTask 时指定 region 与 S3 桶。无论哪个平台，都建议在项目根目录放一个 .env.example 说明需要哪些变量，实际 .env 加入 .gitignore。

连接测试与最小提交示例

环境搭好后不要直接跑复杂线路，先用“列后端”验证认证链路。Qiskit Runtime 的写法是：

from qiskit_ibm_runtime import QiskitRuntimeService
service = QiskitRuntimeService(name="my-channel")
print([b.name for b in service.backends()])

能打印出后端名称列表，说明密钥、渠道、实例三项都正确；若报“No credentials found”，检查凭证文件路径与名称是否匹配；若报“Instance not found”，回到控制台核对 CRN。接着用本地 Aer 模拟器跑一遍线路，确认逻辑无误，再提交到真实后端。最小提交示例选单比特 Hadamard 加测量，shots=1024，预期结果约为 0 和 1 各占一半。这个示例的价值在于：线路足够简单，任何异常都只能来自环境而非算法；结果分布又能直观反映后端是否真正执行了任务。提交后通过 job.status() 观察状态从 QUEUED 到 RUNNING 再到 DONE，若长时间停在 QUEUED，应查看后端队列深度与账户配额，而不是反复重提。

把“列后端成功 + 本地模拟通过 + 最小提交返回计数”作为环境就绪的三项验收标准，任何一项不通过都先修环境，不要急着调试线路。

最后提醒一个常见误区：本地模拟通过不等于云端提交通过。模拟器不校验凭证、实例与配额，因此三项验收必须分开做。把凭证文件、requirements.txt 和最小提交脚本一起放进项目模板，下次换机器时按同样顺序复现，环境准备就从“碰运气”变成了可重复的工程动作。