Qiskit Gym MCP Server

Qiskit Gym MCP 服务

基于 Model Context Protocol（MCP）的服务，使用 qiskit-gym 提供基于强化学习的量子电路合成能力。

功能

• 训练 RL 模型：训练强化学习 Agent，以合成最优量子电路
• 后台训练：在后台线程中运行长时间训练，并支持轮询
• 三种合成类型：
  • 置换：以最少的 SWAP 门进行量子比特路由
  • 线性函数：为线性布尔函数合成 CNOT
  • Clifford：使用自定义门集合成最优 Clifford 电路
• 硬件支持：提供 IBM Heron、Nighthawk 以及常见网格／线性拓扑的预设
• 精确的 IBM 拓扑：访问 IBM Quantum fake 后端的精确耦合映射（离线使用，无需凭据）
• 子拓扑提取：从硬件耦合映射中提取连通子图，用于针对性训练
• 模型持久化：保存、加载和管理训练好的模型
• TensorBoard 集成：使用 TensorBoard 监控训练进度

安装

pip install qiskit-gym-mcp-server

或从源代码安装：

git clone https://github.com/Qiskit/mcp-servers
cd mcp-servers/qiskit-gym-mcp-server
pip install -e .

快速开始

Claude Desktop 配置

添加到 Claude Desktop 配置文件（~/Library/Application Support/Claude/claude_desktop_config.json）：

{
  "mcpServers": {
    "qiskit-gym": {
      "command": "qiskit-gym-mcp-server"
    }
  }
}

示例工作流

User: "Train a model to synthesize Clifford circuits on a 3x3 grid topology"

AI Agent:
1. create_clifford_env_tool(num_qubits=9, preset="grid_3x3")  # -> env_id
2. start_training_tool(env_id, algorithm="ppo", num_iterations=200)  # -> session_id, model_id
3. save_model_tool(session_id, model_name="clifford_3x3_v1")  # -> saved to disk

User: "Train on all 6-qubit subtopologies from IBM Nighthawk"

AI Agent:
1. extract_subtopologies_tool(preset="ibm_nighthawk", num_qubits=6)  # -> list of subtopologies
2. For each subtopology:
   - create_clifford_env_tool(num_qubits=6, coupling_map=subtopology["edges"])
   - start_training_tool(env_id, algorithm="ppo", num_iterations=100)
   - save_model_tool(session_id, model_name=f"nighthawk_6q_{i}")

User: "Train a model using the exact topology of IBM Fez backend"

AI Agent:
1. get_fake_backend_coupling_map_tool(backend_name="fake_fez")  # -> exact 156-qubit Heron topology
2. extract_subtopologies_tool(edges=coupling_map["edges"], num_qubits=5)  # -> 5-qubit subtopologies
3. For each subtopology:
   - create_permutation_env_tool(num_qubits=5, coupling_map=subtopology["edges"])
   - start_training_tool(env_id, algorithm="ppo", num_iterations=100)

User: "Train a model in the background so I can do other things"

AI Agent:
1. create_clifford_env_tool(num_qubits=6, preset="grid_2x3")  # -> env_id
2. start_training_tool(env_id, algorithm="ppo", num_iterations=500, background=True)  # -> session_id (returns immediately)
3. (User can now ask other questions or the agent can do other work)
4. get_training_status_tool(session_id)  # -> check progress
5. wait_for_training_tool(session_id, timeout=600)  # -> blocks until complete, returns model_id
6. save_model_tool(session_id, model_name="clifford_6q_v1")

工具参考

环境管理

工具	说明
create_permutation_env_tool	创建用于 SWAP 路由的 PermutationGym
create_linear_function_env_tool	创建用于 CNOT 合成的 LinearFunctionGym
create_clifford_env_tool	创建使用自定义门集的 CliffordGym
list_environments_tool	列出活动环境
get_environment_info_tool	获取环境详情
delete_environment_tool	移除环境

训练

工具	说明
start_training_tool	开始 RL 训练（PPO 或 AlphaZero），支持 background=True
wait_for_training_tool	等待后台训练完成
batch_train_environments_tool	训练多个环境
get_training_status_tool	获取训练进度和指标
stop_training_tool	停止训练会话
list_training_sessions_tool	列出所有训练会话

合成

工具	说明
synthesize_permutation_tool	生成最优 SWAP 电路
synthesize_linear_function_tool	生成最优 CNOT 电路
synthesize_clifford_tool	生成最优 Clifford 电路

模型管理

工具	说明
save_model_tool	将训练好的模型保存到磁盘
load_model_tool	从磁盘加载模型
list_saved_models_tool	列出磁盘上的模型
list_loaded_models_tool	列出内存中的模型
delete_model_tool	删除模型
get_model_info_tool	获取模型详情

耦合映射

工具	说明
create_coupling_map_tool	创建自定义耦合映射
extract_subtopologies_tool	从硬件中提取 N 量子比特子拓扑
list_subtopology_shapes_tool	列出子拓扑形状（线形、网格等）
get_fake_backend_coupling_map_tool	获取 fake IBM 后端的精确拓扑（无需凭据）
list_available_fake_backends_tool	列出所有可用于离线拓扑访问的 fake 后端

实用工具

工具	描述
generate_random_permutation_tool	生成随机置换，用于测试
generate_random_linear_function_tool	生成随机线性函数，用于测试
generate_random_clifford_tool	生成随机 Clifford 元素，用于测试
convert_qpy_to_qasm3_tool	将 QPY 电路转换为易读的 QASM3
convert_qasm3_to_qpy_tool	将 QASM3 电路转换为 QPY 格式

硬件预设

预设	量子比特	拓扑	描述
ibm_heron_r1	133	重六边形	IBM Heron r1 处理器
ibm_heron_r2	156	重六边形	IBM Heron r2 处理器
ibm_nighthawk	120	10x12 网格	IBM Nighthawk（相比 Heron，深度提升 600%）
grid_3x3	9	网格	3x3 方形网格
grid_5x5	25	网格	5x5 方形网格
linear_5	5	线形	5 量子比特线性链
linear_10	10	线形	10 量子比特线性链

资源

URI	描述
qiskit-gym://workflows	从这里开始 - 分步工作流和快速入门指南
qiskit-gym://presets/coupling-maps	可用的硬件预设
qiskit-gym://algorithms	PPO、AlphaZero 文档
qiskit-gym://policies	BasicPolicy、Conv1dPolicy 文档
qiskit-gym://environments	环境类型文档
qiskit-gym://training/sessions	活跃的训练会话
qiskit-gym://models	已加载的模型
qiskit-gym://server/config	服务配置

配置

环境变量：

# Model storage directory (default: ~/.qiskit-gym/models)
QISKIT_GYM_MODEL_DIR=~/.qiskit-gym/models

# TensorBoard logs (default: ~/.qiskit-gym/runs)
QISKIT_GYM_TENSORBOARD_DIR=~/.qiskit-gym/runs

# Training limits (0 = no limit, default)
# QISKIT_GYM_MAX_ITERATIONS=10000  # Uncomment to set a limit
QISKIT_GYM_MAX_QUBITS=15
QISKIT_GYM_MAX_SEARCHES=10000

开发

# Install with dev dependencies
pip install -e ".[all]"

# Run tests
./run_tests.sh

# Or manually
uv run pytest tests/ -v
uv run ruff check src tests
uv run mypy src

依赖项

• qiskit-gym - 用于量子电路合成的强化学习环境
• FastMCP - MCP 服务框架
• Qiskit - 量子计算框架
• qiskit-ibm-runtime - IBM Quantum 访问和模拟后端

许可证

Apache 2.0 - 详情请参阅 LICENSE。

贡献

贡献指南请参阅 CONTRIBUTING.md。