1. Qiskit工程环境搭建

Qiskit 是 IBM 开源的量子计算 SDK，它并不是一个单一库，而是一组围绕量子电路构建、编译、执行与结果分析组织起来的 Python 包集合。工程环境搭建的目标，是让本地机器具备“写电路—编译电路—提交执行—读取结果”的完整能力，并且这套能力在本地模拟器与云端真实量子硬件之间可以平滑切换。本章围绕安装、环境配置、运行验证与版本依赖管理四件事展开，重点不是把命令敲一遍，而是理解每一步在整条工具链中的位置。

1.1 理解 Qiskit 的包结构与工具链

从 Qiskit 1.0 起，官方将原先的元包拆分为更清晰的模块，安装时最常用的是 qiskit 主包，它包含构建与编译电路的核心能力（Terra 相关功能），以及基础的原语接口。与之配套的常见组件包括：qiskit-aer 提供高性能本地模拟器；qiskit-ibm-runtime 提供访问 IBM Quantum 云端服务与真实硬件的运行时接口；qiskit-visualization 相关能力已并入主包，用于绘制电路图与结果直方图。理解这层分工，才能明白为什么“装完 qiskit 却跑不了真实硬件”——因为云端访问需要额外的 runtime 包与账号凭据。

工具链的依赖关系可以概括为：Python 解释器是底座，Qiskit 主包依赖 NumPy、SciPy、SymPy 等科学计算库，Aer 模拟器依赖编译好的本地扩展，Runtime 客户端依赖网络请求库。任何一层版本不匹配，都可能在导入或执行阶段报错。

1.2 安装与虚拟环境配置

推荐始终在虚拟环境中安装 Qiskit，这样不同项目的依赖版本互不干扰。以 Python 自带的 venv 为例，在项目目录下执行：

python -m venv qiskit-env
# Windows
qiskit-env\Scripts\activate
# macOS / Linux
source qiskit-env/bin/activate

python -m pip install --upgrade pip
pip install qiskit qiskit-aer qiskit-ibm-runtime

安装完成后，用一条命令确认版本与来源，这是排查环境问题的第一手依据：

python -c "import qiskit; print(qiskit.__version__)"
pip show qiskit qiskit-aer qiskit-ibm-runtime

如果使用 conda，可用 conda create -n qiskit-env python=3.11 创建环境，再在其中用 pip 安装。需要注意：Aer 模拟器包含本地编译扩展，某些平台若 pip 安装失败，通常与 Python 版本过新或缺少编译工具有关，此时优先选择官方已发布 wheel 的 Python 版本（如 3.10、3.11）。

1.3 本地运行验证：从电路到结果

环境是否可用，不能只看导入是否成功，而要跑通一条最小但完整的链路：构建一个含叠加与纠缠的电路，用 Aer 模拟器执行，并读取计数结果。下面这段示例构建 2 量子比特的 Bell 态，预期只在 00 与 11 两个状态上出现近似各半的计数。

from qiskit import QuantumCircuit
from qiskit_aer import AerSimulator

qc = QuantumCircuit(2, 2)
qc.h(0)          # 对 qubit 0 施加 H，产生叠加
qc.cx(0, 1)      # CNOT 纠缠
qc.measure([0, 1], [0, 1])

sim = AerSimulator()
job = sim.run(qc, shots=1024)
result = job.result()
counts = result.get_counts()
print(counts)    # 示例输出：{'00': 512, '11': 512} 附近

判断标准有三点：其一，程序无导入错误与运行异常；其二，计数只出现在 00 和 11，不应出现 01 或 10（若出现，说明纠缠逻辑或测量映射有误）；其三，两者比例接近 1:1，偏差来自有限采样次数，属于正常统计涨落。若使用 qiskit.visualization.plot_histogram(counts)，可直观看到两根等高的柱。

1.4 云端环境与凭据配置

要访问 IBM Quantum 的真实硬件，需要先在 IBM Quantum 平台注册并获取 API Token，然后保存到本地凭据文件，避免把 Token 写进代码：

from qiskit_ibm_runtime import QiskitRuntimeService

QiskitRuntimeService.save_account(
    channel="ibm_quantum",
    token="你的_API_Token",
    overwrite=True
)

service = QiskitRuntimeService()
print(service.backends())   # 列出当前账号可用的后端

保存后，后续代码只需 QiskitRuntimeService() 即可自动读取凭据。选择后端时，可用 service.least_busy(operational=True, simulator=False) 挑选当前排队最少的真实设备。提交任务会返回 Job 对象，通过 job.job_id() 记录编号，再用 job.result() 获取结果。云端任务存在排队时间，验证阶段建议先用模拟器，确认逻辑无误后再提交硬件。

1.5 版本与依赖管理

Qiskit 迭代较快，主版本之间可能存在 API 变更，例如 1.0 之后原语接口与部分模块路径有调整。工程上应固定版本，而不是每次安装最新版。推荐做法是把依赖写入 requirements.txt：

qiskit==1.2.4
qiskit-aer==0.15.1
qiskit-ibm-runtime==0.30.0

用 pip install -r requirements.txt 复现环境。若需精确锁定全部间接依赖，可用 pip freeze > requirements-lock.txt。升级前先在独立环境验证，确认 transpile、原语调用与结果接口没有破坏性变化，再更新主环境。