量子实验分析助手 yaqiangsun/QubitClient

QubitClient：用于量子计算的 AI 智能体

介绍 • 功能特性 • 安装 • 快速开始 • 结果页 / DSH • 任务类型 • 文档 • 许可证

📖 介绍

QubitClient 是一个功能强大的 AI 智能体，用来高效对接 Qubit 服务。它封装了丰富的 API 接口，专为量子计算实验数据处理而设计，支持特征提取、参数拟合、实验控制等多种任务，能快速分析二维能谱、功率偏移曲线等关键实验数据，支持多种格式转换。

✨ 功能特性

- 🧠 智能数据分析：支持二维能谱分析、功率偏移曲线分析等复杂任务。
- 🔬 多种量子计算任务：涵盖 S21 峰值检测、最优 π 脉冲、Rabi 振荡、T1/T2 拟合等常见实验分析。
- 📦 灵活的数据输入：可直接传入文件路径、NumPy 数组或字典，适配不同数据源。
- ⚡ 批量处理：轻松同时处理多个数据文件，提高工作效率。
- 🔌 易于集成：简洁的 API 设计，可快速融入现有项目流程。
- 🤝 MCP 协议支持：基于 MCP 协议的实时量子测量任务控制，实现实验自动化。
- 🖥️ 结果可视化与 DSH 集成：内置 pipeline 结果 Web UI（SSE 实时刷新），并提供 DeepSeek Harness 插件把结果面板嵌进右侧栏。
- 🤖 LLM/VLM 集成：支持大语言模型和视觉语言模型，用于量子测量数据分析与决策。
- 🟢 Google Gemma 4：支持 google/gemma-4-E4B-it 模型
- 🔵 NVIDIA Ising：支持 nv-community/Ising-Calibration-1-35B-A3B 模型，专为量子校准设计
- 🎨 图像生成与编辑：支持文本生成图像、图像编辑、Chat API 图像生成等多种模式。
- 支持 DALL-E、Qwen-Image 等主流图像生成模型
- 支持多图生成、单图编辑、多图变体等丰富功能

📦 安装

推荐使用 pip 进行安装：

pip install qubitclient

如果需要绘图等额外功能，可以安装完整版：

pip install qubitclient[full]

详细安装说明请参考 安装指南。

🐳 服务部署（Docker）

初始化部署文件（拷贝 serve_templates 到当前目录） qubitclient serve init

下载模型到 model_zoo 文件夹 qubitclient serve download

启动所有服务（proxy、qubitserving、qubitscope） qubitclient serve up

查看服务状态
docker ps

🚀 快速开始

1️⃣ 配置

初始化配置文件：

qubitclient init

这会创建 qubitclient.json 和 .mcp.json 文件。然后编辑 qubitclient.json，填入你的服务器地址和 API 密钥：

{
"url": "https://your-api-server.com",
"api_key": "your-api-key"
}

2️⃣ 使用示例

🧠 NNScope 功能（SPECTRUM2D）

from qubitclient import QubitNNScopeClient, NNTaskName, CurveType
import numpy as np

初始化客户端
client = QubitNNScopeClient()

方式1：使用文件路径
file_path_list = ["data/file1.npz", "data/file2.npz"]
response = client.request(
file_list=file_path_list,
task_type=NNTaskName.SPECTRUM2D,
curve_type=CurveType.COSINE
)

方式2：使用 NumPy 数组字典
data_ndarray = np.load("data/file1.npz", allow_pickle=True)
dict_list = [data_ndarray]
response = client.request(
file_list=dict_list,
task_type=NNTaskName.SPECTRUM2D,
curve_type=CurveType.POLY
)

获取结果
results = client.get_result(response=response)

🔬 Scope 功能（OPTPIPULSE）

from qubitclient import QubitScopeClient, TaskName
import numpy as np

client = QubitScopeClient()

准备数据（示例）
dict_list = [{
"x_data": np.array([...]),
"y_data": np.array([...])
}]

response = client.request(
file_list=dict_list,
task_type=TaskName.OPTPIPULSE # 可选任务见下方列表
)

results = client.get_result(response=response)

🤖 Ctrl 功能（MCP 协议测量S21）

from qubitclient.ctrl import QubitCtrlClient, CtrlTaskName

client = QubitCtrlClient()

执行 S21 腔频测量实验
result = client.run(
task_type=CtrlTaskName.S21,
qubits=["Q0", "Q1"],
frequency_start=-40e6,
frequency_end=40e6,
frequency_sample_num=101
)

print(result)

🤖 LLM 功能（VLM 图像分析）

from qubitclient.llm import QubitLLM, LLMTaskName, ExperimentFamily

初始化客户端（自动从 qubitclient.json 读取配置）
llm = QubitLLM()

方式1：直接对话
result = llm.chat([
{"role": "system", "content": "You are a quantum physics expert."},
{"role": "user", "content": "Explain quantum entanglement"}
])
print(result)

方式2：带图像的 VLM 分析
result = llm.chat(
[{"role": "user", "content": "分析这张图像"}],
images="measurement.png"
)
print(result)

方式3：使用任务 prompt（自动构建消息和 JSON schema） QCalEval Q1: 描述图表
result = llm.run(
LLMTaskName.DESCRIBE_PLOT,
"test.png",
experiment_family=ExperimentFamily.RABI
)
print(result)

QCalEval Q2: 分类实验结果
result = llm.run(
LLMTaskName.CLASSIFY_OUTCOME,
"test.png",
experiment_family=ExperimentFamily.T1
)
print(result)

QCalEval Q3: 科学推理
result = llm.run(
LLMTaskName.SCIENTIFIC_REASONING,
"test.png",
experiment_family=ExperimentFamily.RAMSEY_T2STAR
)
print(result)

QCalEval Q4: 评估拟合可靠性
result = llm.run(
LLMTaskName.ASSESS_FIT,
"test.png",
experiment_family=ExperimentFamily.RABI
)
print(result)

QCalEval Q5: 提取参数
result = llm.run(
LLMTaskName.EXTRACT_PARAMS,
"test.png",
experiment_family=ExperimentFamily.T1
)
print(result)

QCalEval Q6: 评估实验状态
result = llm.run(
LLMTaskName.EVALUATE_STATUS,
"test.png",
experiment_family=ExperimentFamily.T1
)
print(result)

决策任务：基于评估结果给出下一步测量建议
result = llm.run(
LLMTaskName.DECIDE_NEXT_ACTION,
evaluation_result={"status": "success", "params": {...}},
available_actions=["S21", "RABI", "T1"]
)
print(result)

🎨 Generate 功能（图像生成与编辑）

from qubitclient.generate import QubitGenerate, ImageSize

初始化客户端（自动从 qubitclient.json 读取配置）
gen = QubitGenerate()

方式1：文本生成图像（使用 /v1/images/generations）
images = gen.generate(
prompt="A beautiful sunset over mountains, digital art style",
size=ImageSize.SIZE_1024x1024,
n=1
)
images[0].save("output.png")

方式2：图像编辑（使用 /v1/images/edits）
images = gen.edit(
prompt="Convert to watercolor painting style",
image="input.png",
size=ImageSize.SIZE_1024x1024,
)
images[0].save("edited_output.png")

方式3：Chat API 图像生成（支持多模态模型）
images = gen.chat(
prompt="A quantum computing circuit diagram",
image=None, # 纯文本生成
size=ImageSize.SIZE_1024x1024,
n=1
)
images[0].save("circuit.png")

方式4：Chat API 单图像编辑
images = gen.chat(
prompt="Enhance the colors",
image="input.png", # 单图编辑
size=ImageSize.SIZE_1024x1024,
)
images[0].save("enhanced.png")

🖥️ 结果页与 DSH 集成

pipeline 脚本把每次运行写进 tmp/db/result/pipeline/.json，项目自带的结果页服务会把它们实时推成一张卡片瀑布流。
既可以在浏览器里单独打开，也可以通过 DeepSeek Harness（下称 DSH）插件嵌进它的右侧栏，写代码和看结果不用来回切窗口。

启动结果页

pip install -e ".[ui]" # fastapi / uvicorn
qubitclient ui start # 默认 http://localhost:8581/ qubitclient ui start --port 9000

| 能力 | 说明 |
| 实时列表 | 每 2 秒扫 tmp/db/result/pipeline/，新增或更新的记录经 SSE 推到页面 |
| 卡片缩略图 | GET /api/plots/{run_id}/{i} 直接返回拟合图 PNG |
| 详情 | 点卡片查看参数、分析结果与原始 JSON |
| 依赖 | 单页内联 CSS/JS，无 CDN，离线可用 |

启动时工作目录要在仓库根：读取侧固定按 cwd/tmp/db/result 取数，--storage-root 目前只影响 SSE 监听目录。

DSH 插件（dsh-plugin/）

把上面这个结果页搬进 DSH 的右侧栏，并让模型能直接读到 pipeline 记录。npm 包：qubitclient-dsh-panel。

| 能力 | 说明 |
| 结果面板 | 右侧栏 tab「QubitClient 结果」：原样嵌入结果页（卡片流 / SSE / 详情） |
| 状态徽标 | 输入框下方显示服务在线状态、记录总数、最近一次任务；面板已打开时按钮变「聚焦面板」 |
| 模型工具 | qubitclient_results：按任务名与条数读取运行记录（任务、状态、比特、时间、图数、错误） |

安装（三条命令，都在仓库根执行）：

pip install -e ".[ui]" # 前置：结果页依赖（一次性）
qubitclient ui start # 前置：启动结果页服务（默认 http://127.0.0.1:8581/）
dsh plugin add qubitclient-dsh-panel # 装插件；之后重启 DSH，右侧栏「新建 tab」里出现「QubitClient 结果」

也可以在 DSH「插件 → 发现」里搜索安装。

卸载：

dsh plugin remove qubitclient-dsh-panel
再从 profile 的 dsh.profile.bundles 里删掉 qubitclient-dsh-panel（或在 DSH「插件」页取消勾选），重启 DSH

配置与限制：

| 项 | 说明 |
| 服务地址 | DSH 侧默认 http://127.0.0.1:8581；换端口时改 dsh-plugin/qubitclient-panel/cordis.patch.yml 的 config.baseUrl，并在面板的离线提示里改一次浏览器侧地址 |
| 未启动服务 | 面板显示启动指引与地址编辑框，不影响 DSH 其他功能 |
| 深链 | 结果页暂不支持 ?run= 直达某次运行，详情需在面板内点卡片 |
| 主题 | 面板保持结果页自己的样式，不跟随 DSH 明暗主题 |

详见 dsh-plugin/README.md 与 结果页文档。

📋 支持的任务类型

🧠 NNScope 任务

| 任务名称 | 描述 | 文档 | 状态 |
| NNTaskName.SPECTRUM2D | 二维频谱数据曲线分割 | 文档 | ✅
| NNTaskName.POWERSHIFT | 功率偏移曲线分割 | 文档 | ⏸️
| NNTaskName.S21VSFLUX | S21 vs Flux 参数曲线分割 | 文档 | ⏸️
| NNTaskName.SPECTRUM | 频谱分析 | 文档 | ✅
| NNTaskName.S21PEAK | S21 峰值检测 | 文档 | ✅
| NNTaskName.S21PEAKMULTI | S21 峰值检测 | 文档 | ✅

🔬 Scope 任务

| 任务名称 | 描述 | 文档 | 状态 |
| TaskName.S21PEAKMULTI | 全频段扫描S21全链峰值检测 | 文档 | ✅
| TaskName.S21PEAK | S21 单个峰值优化检测 | 文档 | ✅
| TaskName.OPTPIPULSE | 最优 π 脉冲计算 | 文档 | ✅
| TaskName.RABICOS | Rabi 振荡余弦第一峰检测 | 文档 | ✅
| TaskName.RAMSEY | RAMSY 衰减震荡余弦拟合 | 文档 | ✅
| TaskName.S21VSFLUX | S21 vs Flux 分析 | 文档 | ✅
| TaskName.SINGLESHOT | 单次测量分析 | 文档 | ✅
| TaskName.SPECTRUM | 频谱分析 | 文档 | ✅
| TaskName.T1FIT | T1 时间拟合 | 文档 | ✅
| TaskName.T2FIT | T2 时间拟合 | 文档 | ✅
| TaskName.T12DFIT | 2D T1 衰减拟合 | 文档 | ✅
| TaskName.POWERSHIFT | 功率偏移曲线分析 | 文档 | ✅
| TaskName.SPECTRUM2D | 二维频谱数据曲线分割 | 文档 | ✅
| TaskName.DRAG | DRAG 免交叉点分析 | 文档 | ✅
| TaskName.DELTA | delta优化实验 | 文档 | ✅
| TaskName.RB | 保真度测试 | 文档 | ✅ |
| TaskName.SPINECHO | Spin Echo T2 拟合 | 文档 | ⏸️ |
| TaskName.TIMINGXYZ | XYZ Timing 分析 | 文档 | ⏸️ |

🤖 Ctrl 任务

| 任务名称 | 描述 | 详细文档 | 状态 |
| CtrlTaskName.S21 | S21 腔频测量实验 | 文档 | ✅
| CtrlTaskName.DRAG | DRAG 免交叉点测量 | 文档 | ✅
| CtrlTaskName.DELTA | 频率偏移校准测量 | 文档 | ✅
| CtrlTaskName.OPTPIPULSE | 最优 π 脉冲测量 | 文档 | ✅
| CtrlTaskName.POWERSHIFT | 功率偏移曲线测量 | 文档 | ✅
| CtrlTaskName.RABI | Rabi 振荡测量 | 文档 | ✅
| CtrlTaskName.RAMSEY | Ramsey 干涉测量 | 文档 | ✅
| CtrlTaskName.S21VSFLUX | S21 vs Flux 测量 | 文档 | ✅
| CtrlTaskName.SINGLESHOT | 单次测量分析 | 文档 | ✅
| CtrlTaskName.SPECTRUM | 频谱分析测量 | 文档 | ✅
| CtrlTaskName.SPECTRUM_2D | 二维频谱测量 | 文档 | ✅
| CtrlTaskName.T1 | T1 弛豫时间测量 | 文档 | ✅
| CtrlTaskName.T2 | T2 弛豫时间测量 | 文档 | ✅
| CtrlTaskName.RB | 随机基准测试 | 文档 | ✅
| CtrlTaskName.DATA | 获取测量数据 | 文档 | ✅

🤖 LLM 任务

| 任务名称 | 描述 | 详细文档 | 状态 |
| LLMTaskName.DECIDE_NEXT_ACTION | 决策下一步测量目标及参数 | - | ⏸️
| LLMTaskName.DESCRIBE_PLOT | 描述图表类型、坐标轴、特征 | QCalEval-Q1 | ⏸️
| LLMTaskName.CLASSIFY_OUTCOME | 分类实验结果 (Expected/Suboptimal/Anomalous) | QCalEval-Q2 | ⏸️
| LLMTaskName.SCIENTIFIC_REASONING | 科学推理分析 | QCalEval-Q3 | ⏸️
| LLMTaskName.ASSESS_FIT | 评估拟合可靠性 | QCalEval-Q4 | ⏸️
| LLMTaskName.EXTRACT_PARAMS | 从图表提取参数 | QCalEval-Q5 | ⏸️
| LLMTaskName.EVALUATE_STATUS | 评估实验状态 (成功/失败及原因) | QCalEval-Q6 | ⏸️

📊 ExperimentFamily 实验家族

用 ExperimentFamily 枚举指定不同实验类型，自动获取对应的 prompt 背景和参数提取 schema：

| 枚举值 | 描述 | 状态 |
| ExperimentFamily.COUPLER_FLUX | 可调耦合器光谱 | ⏸️
| ExperimentFamily.CZ_BENCHMARKING | CZ 门基准测试 | ⏸️
| ExperimentFamily.DRAG | DRAG 校准 | ⏸️
| ExperimentFamily.GMM | 高斯混合模型 | ⏸️
| ExperimentFamily.MICROWAVE_RAMSEY | 微波 Ramsey | ⏸️
| ExperimentFamily.MOT_LOADING | MOT 加载 | ⏸️
| ExperimentFamily.PINCHOFF | Pinch-off 测量 | ⏸️
| ExperimentFamily.PINGPONG | PingPong 校准 | ⏸️
| ExperimentFamily.QUBIT_FLUX_SPECTROSCOPY | 量子比特通量光谱 | ⏸️
| ExperimentFamily.QUBIT_SPECTROSCOPY | 量子比特光谱 | ⏸️
| ExperimentFamily.QUBIT_SPECTROSCOPY_POWER_FREQUENCY | 二维功率频率光谱 | ⏸️
| ExperimentFamily.RABI | Rabi 振荡 | ⏸️
| ExperimentFamily.RABI_HW | Rabi 硬件 | ⏸️
| ExperimentFamily.RAMSEY_CHARGE_TOMOGRAPHY | Ramsey 电荷层析 | ⏸️
| ExperimentFamily.RAMSEY_FREQ_CAL | Ramsey 频率校准 | ⏸️
| ExperimentFamily.RAMSEY_T2STAR | T2 退相干 | ⏸️
| ExperimentFamily.RES_SPEC | 共振器光谱 | ⏸️
| ExperimentFamily.RYDBERG_RAMSEY | Rydberg Ramsey | ⏸️
| ExperimentFamily.RYDBERG_SPECTROSCOPY | Rydberg 光谱 | ⏸️
| ExperimentFamily.T1 | T1 弛豫 | ⏸️
| ExperimentFamily.T1_FLUCTUATIONS | T1 涨落 | ⏸️
| ExperimentFamily.TWEEZER_ARRAY | 光镊阵列 | ⏸️ |
| --- Extra 实验（非 QCalEval）--- | | |
| ExperimentFamily.S21 | 腔频校准 | ⏸️ |
| ExperimentFamily.SPECTRUM_2D | 二维频谱分析 | ⏸️
| ExperimentFamily.OPTPIPULSE | 最优π脉冲校准 | ⏸️
| ExperimentFamily.RABICOS | 功率Rabi振荡 | ⏸️
| ExperimentFamily.RAMSEY | Ramsey干涉 | ⏸️
| ExperimentFamily.S21VSFLUX | S21 vs Flux 2D | ⏸️
| ExperimentFamily.POWERSHIFT | 功率偏移 | ⏸️
| ExperimentFamily.SINGLESHOT | 单次读出 | ⏸️
| ExperimentFamily.SPECTRUM | 频谱分析 | ⏸️
| ExperimentFamily.T2 | T2退相干 | ⏸️
| ExperimentFamily.RB | 随机基准测试 | ⏸️

🎯 ExperimentType 实验类型

用 ExperimentType 枚举指定 QCalEval 数据集中的 87 个具体测试用例（用于评估）。详细列表见 实验类型文档。

📁 数据格式说明

不同任务对输入/输出数据格式要求不同，具体说明见对应任务的详细文档（上面链接）。

🧪 运行测试示例

项目提供了丰富的测试示例，放在 tests 目录下：

运行 NNScope 测试
python tests/test_nnscope.py

运行 Scope 测试
python tests/test_scope.py

运行 Ctrl 测试
python tests/test_ctrl_mcp.py

运行 LLM 测试
python tests/test_llm.py

运行 Generate 测试
python tests/generate/test_generate.py

⚙️ LLM/VLM 配置

在 qubitclient.json 中配置 LLM/VLM（创建或编辑此文件）：

{
"llm": {
"api_key": "your-api-key",
"base_url": "https://your-llm-endpoint.com/v1",
"model": "nvidia/Ising-Calibration-1-35B-A3B"
}
}

支持的模型

| 模型 | 描述 | 推荐用途 |
| nvidia/Ising-Calibration-1-35B-A3B | NVIDIA Ising，专门针对量子校准任务优化 | 量子测量数据分析首选 |
| google/gemma-4-E4B-it | Google Gemma 4，多模态推理能力 | 通用图表分析与推理 |
| gpt-4o | OpenAI GPT-4o | 通用对话与分析 |

支持的配置方式（优先级从低到高）：
1. 默认值（gpt-4o）
2. 用户目录 ~/qubitclient.json
3. 环境变量 OPENAI_API_KEY, OPENAI_BASE_URL, OPENAI_MODEL
4. 运行目录 ./qubitclient.json
5. 构造函数参数（最高优先级）

🔧 格式转换与工具集成

如需将数据转换为特定格式或集成其他工具，请参考 resources 目录下的实用脚本。

📝 更新日志

近期更新

- 🖥️ 新增结果页 DSH 集成：dsh-plugin/ 把 pipeline 结果页嵌入 DeepSeek Harness 右侧栏，并提供 qubitclient_results 工具供模型读取运行记录
- 🎨 新增图像生成模块：支持文本生成图像、图像编辑、Chat API 图像生成（Qwen-Image、DALL-E 等）
- 🐳 新增 Docker 服务部署：新增 qubitclient serve 命令，支持一键初始化和启动 qubitscope、qubitserving、proxy 三个服务
- 🤖 新增 VLM 模型支持：
- 🔵 NVIDIA Ising (Ising-Calibration-1-35B-A3B)：专为量子校准任务优化的 VLM
- 🟢 Google Gemma 4 (gemma-4-E4B-it)：多模态推理能力，支持图表分析
- 🤖 新增 QCalEval 基准测试：集成 NVIDIA QCalEval 数据集，支持 6 种 VLM 任务（Q1-Q6）和 87 种实验类型
- 🤖 新增实验背景模块：为 22 种实验家族提供专业物理背景描述
- 🤖 新增 LLM 决策模块：支持基于评估结果自动决策下一步测量
- 🤖 新增 LLM 模块：集成大语言模型和视觉语言模型，支持量子测量数据分析与决策
- 🎨 优化绘制功能：统一结果绘制风格
- 🤝 增加 Ctrl 功能包：基于 MCP 协议的实时测量任务
- 📈 增加 DRAG 分析功能：支持 DRAG 任务数据分析
- 🧩 增加 scope 功能包：新增多种拟合任务
- 📐 增加曲线类型：支持余弦类型曲线拟合
- 🏗️ 构建基础项目：完成基础功能与结构搭建

🤝 贡献指南

欢迎通过 Issues 提交问题或建议。如果你想贡献代码，请 Fork 本仓库并提交 Pull Request。

📄 许可证

本项目采用 GPL-3.0 许可证。详情请参阅 LICENSE 文件。