Skip to content

README_zh.md

Latest commit

 

History

History
294 lines (226 loc) · 9.46 KB

README_zh.md

File metadata and controls

294 lines (226 loc) · 9.46 KB

QPanda3 Runtime MCP 服务器

Python 3.10+ FastMCP License Documentation

一个模型上下文协议 (MCP) 服务器，使 AI 助手能够通过 QPanda3 Runtime 与本源量子计算服务进行交互。

功能特性

  • 账户管理：配置和管理本源量子云平台账户认证
  • 设备管理：列出和查询可用的 QPU 设备
  • 量子计算任务：执行采样和估计任务
  • 批量操作：高效运行多个量子线路
  • 多目标决策：CircuitObservableBinding 用于复杂优化
  • 任务管理：查询任务状态、获取结果、取消任务
  • 示例线路：提供常用量子线路示例资源

文档

文档 说明
English Docs 英文文档站
中文文档 中文文档站
快速入门 完整的初学者指南 - 从这里开始
安装指南 详细的安装说明
快速开始 面向有经验用户的快速设置
配置说明 环境和客户端配置
用户指南 详细功能文档
API 参考 自动生成的 API 文档

安装

一键配置（推荐）

项目提供了自动化安装配置脚本，可以一键完成全部设置：

Linux / macOS：

git clone https://github.com/OriginQ/qpanda3-runtime-mcp-server.git
cd qpanda3-runtime-mcp-server
chmod +x scripts/setup_configure.sh
./scripts/setup_configure.sh

Windows (PowerShell)：

git clone https://github.com/OriginQ/qpanda3-runtime-mcp-server.git
cd qpanda3-runtime-mcp-server
.\scripts\setup_configure.ps1

脚本会自动完成：依赖安装、API 密钥配置和 MCP 客户端设置。

手动安装选项请参阅 安装指南。

快速开始

# 1. 配置 API 密钥
cp .env.example .env
# 编辑 .env，设置 QPANDA3_API_KEY=your_api_key_here

# 2. 启动服务器
.venv/bin/python -m qpanda3_runtime_mcp_server       # Linux/macOS
# .venv\Scripts\python.exe -m qpanda3_runtime_mcp_server  # Windows

MCP 客户端配置和高级选项请参阅 配置说明。

MCP 工具

账户管理

工具 说明
setup_origin_quantum_account_tool 配置本源量子云平台账户认证
list_saved_accounts_tool 列出已保存的账户信息（基于会话）
active_account_info_tool 获取当前活跃账户信息

设备管理

工具 说明
list_qpu_devices_tool 列出所有可用的 QPU（量子处理单元）设备
get_qpu_properties_tool 获取特定 QPU 设备的详细属性

量子计算任务

工具 说明
sample_tool 在 QPU 设备上执行量子线路采样任务
estimate_tool 执行量子线路的期望值估计任务
batch_sample_tool 批量执行多个量子线路采样任务
batch_estimate_tool 对多个线路使用一个可观测量批量执行估计任务

多目标决策 (CircuitObservableBinding)

工具 说明
create_circuit_observable_binding_tool 创建多个线路和可观测量的绑定
add_product_rule_tool 添加笛卡尔积组合规则（所有组合）
add_zip_rule_tool 添加一对一组合规则（配对组合）
estimate_with_binding_tool 使用创建的绑定执行估计
list_bindings_tool 列出所有存储的 CircuitObservableBinding 对象
delete_binding_tool 删除一个存储的 CircuitObservableBinding 对象

任务管理

工具 说明
get_task_status_tool 获取任务的执行状态（PENDING/RUNNING/DONE/FAILED/CANCELLED）
get_task_results_tool 获取已完成任务的计算结果
cancel_task_tool 取消正在运行或等待中的任务
list_my_tasks_tool 列出用户最近的量子计算任务

MCP 资源

资源 URI 说明
qpanda://status 服务状态
circuits://bell-state 贝尔态线路示例
circuits://ghz-state GHZ 态线路示例
circuits://random 随机数生成器线路
circuits://superposition 叠加态线路示例

使用示例

配置账户

# 通过环境变量自动配置
# 或显式调用
await setup_origin_quantum_account_tool(
    api_key="your_api_key"
)

列出设备

devices = await list_qpu_devices_tool()
print(f"Available devices: {devices['total_devices']}")

执行采样任务

# 贝尔态线路
circuit = """QINIT 2
CREG 2
H q[0]
CNOT q[0],q[1]
MEASURE q[0],c[0]
MEASURE q[1],c[1]"""

result = await sample_tool(
    circuit=circuit,
    device_id="20",
    shots=1000
)
task_id = result["task_id"]

# 检查状态并获取结果
status = await get_task_status_tool(task_id)
if status["task_status"] == "DONE":
    results = await get_task_results_tool(task_id)
    print(f"Measurement results: {results['results']}")

在 AI 编程平台中配置

自动配置： 使用 ./scripts/setup_configure.sh --mcp claude-desktop（或 --mcp cline、--mcp cursor 等）

所有客户端使用相同的配置格式（将 /path/to/... 替换为实际路径）：

{
  "mcpServers": {
    "qpanda3-runtime": {
      "command": "/path/to/qpanda3-runtime-mcp-server/.venv/bin/python",
      "args": ["-m", "qpanda3_runtime_mcp_server"],
      "cwd": "/path/to/qpanda3-runtime-mcp-server",
      "env": { "QPANDA3_API_KEY": "your_api_key_here" }
    }
  }
}
客户端 配置文件位置
Claude Code ~/.claude.json
Claude Desktop macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Cline ~/.vscode-server/data/User/globalStorage/saoudrizwan.cline/settings/cline_mcp_settings.json
Cursor .cursor/mcp.json（项目根目录）
Windsurf ~/.codeium/windsurf/mcp_config.json

更多客户端（Trae等），请参阅配置指南。

开发

安装开发依赖

uv sync --extra dev --extra test

运行测试

uv run pytest

代码检查

uv run ruff check .
uv run mypy src/

构建文档

# 安装文档依赖
uv sync --extra docs

# 构建中英文文档
./scripts/build-docs.sh

# 本地预览（实时重载，支持语言切换）
mkdocs serve

项目结构

qpanda3-runtime-mcp-server/
├── src/
│   └── qpanda3_runtime_mcp_server/
│       ├── __init__.py          # 包入口
│       ├── server.py            # MCP 服务器定义
│       ├── runtime.py           # QPanda3 Runtime 核心逻辑
│       └── utils.py             # 工具函数
├── scripts/
│   ├── setup_configure.sh       # 一键配置脚本（Linux/macOS）
│   ├── setup_configure.ps1      # 一键配置脚本（Windows PowerShell）
│   ├── setup_configure.bat      # 一键配置脚本（Windows CMD）
│   ├── build-docs.sh            # 构建所有文档
│   └── serve-docs.sh            # 预览文档（实时重载）
├── tests/
│   ├── __init__.py
│   ├── conftest.py              # pytest 配置
│   ├── test_server.py           # 服务器测试
│   └── test_runtime.py          # 运行时测试
├── docs/
│   ├── *.md                     # 英文文档（默认）
│   └── cn/                      # 中文文档
├── mkdocs.yml                   # MkDocs 配置（i18n）
├── .github/
│   └── workflows/               # GitHub Actions 工作流
├── pyproject.toml               # 项目配置
├── README.md                    # 项目文档
├── LICENSE                      # Apache 2.0 许可证
├── .env.example                 # 环境变量示例
└── .gitignore                   # Git 忽略文件

注意事项

  1. 默认服务器：服务器默认连接到 https://qpanda3-runtime.qpanda.cn。可通过设置 QPANDA3_SERVER_URL 进行覆盖。
  2. 通道：服务器默认使用 qcloud 通道
  3. 异步支持：所有工具函数均为 async 函数
  4. 错误处理：所有函数返回包含 status 字段的字典
  5. 类型提示：使用 Python 类型提示以提高代码可读性

许可证

本项目基于 Apache License 2.0 许可 - 详见 LICENSE 文件。

相关链接

贡献

详见贡献指南。

更新日志

详见更新日志获取版本历史。