kaiwu-cli-mcp

Kaiwu SDK CLI & MCP 双模工具 — 玻色量子 CIM 相干光量子计算机 Python SDK 的 Docker 封装工具，支持命令行（CLI）和 AI Agent（MCP）两种调用方式。

📚 Kaiwu SDK 官方文档: https://kaiwu-sdk-docs.qboson.com/zh/latest/index.html

架构概述

┌─────────────────────────────────────────────┐
│                 宿主机 (Host)                │
│                                             │
│  ┌──────────┐  ┌───────────────┐            │
│  │  CLI     │  │  MCP Server   │            │
│  │ (cli.py) │  │ (mcp_server)  │            │
│  └────┬─────┘  └───────┬───────┘            │
│       │                │                     │
│       └───────┬────────┘                     │
│               │                              │
│        ┌──────▼──────┐                       │
│        │   core.py   │  纯业务逻辑层          │
│        └──────┬──────┘                       │
│               │ docker compose               │
│               │                              │
│  ┌────────────▼──────────────┐               │
│  │    user_script/            │  脚本目录(常驻)│
│  │    ~/任意路径/xxx.py       │  自动挂载      │
│  └───────────────────────────┘               │
│               │                              │
└───────────────┼──────────────────────────────┘
                │ volume mount
┌───────────────▼──────────────────────────────┐
│           Docker 容器 (kaiwu-sdk)             │
│                                              │
│  • Python 3.10                               │
│  • Kaiwu SDK v1.3.1 (已安装)                   │
│  • /user_script/ (映射自宿主机)               │
│  • /mnt/script/  (外部脚本自动挂载)            │
│  • named volume: kaiwu-license (持久化)       │
│                                              │
│  用户脚本在此环境中运行，调用 Kaiwu SDK        │
│  访问玻色量子 CIM 相干光量子计算机             │
└──────────────────────────────────────────────┘

核心原则：一个核心逻辑层（core.py），两个薄接口层（cli.py + mcp_server.py）。CLI 给人类用，MCP 给 AI Agent 用，共享同一套业务逻辑。

前置要求

Docker & Docker Compose (v2+)
Python 3.10 (宿主机，仅用于 CLI/MCP 工具。Kaiwu SDK 仅支持 3.10)
Kaiwu SDK v1.3.1 (当前适配版本，cp310 wheel)
玻色量子平台账号：https://platform.qboson.com/

快速开始

1. 获取凭证

登录玻色量子平台，获取你的 用户ID (user_id) 和 SDK授权码 (sdk_code)。

2. 下载 SDK

访问 SDK 下载页，下载 Linux 版本的 Kaiwu SDK（下载后为 .zip 文件，内含 .whl）。

将下载的 .zip（或解压后的 .whl）放入项目 sdk/ 目录：

# 方式一：直接放 zip（Docker 构建时自动解压）
cp ~/Downloads/kaiwu-*.zip ./sdk/

# 方式二：解压后放 whl
unzip ~/Downloads/kaiwu-*.zip -d ./sdk/

Docker 构建时会自动处理：.zip 自动解压 → 找到 .whl → pip install。

3. 配置用户信息

编辑 user_config.yaml，填入你的凭证：

user_id: "your_user_id_here"
sdk_code: "your_sdk_code_here"

4. 构建 Docker 镜像

# 使用 CLI 工具
python cli.py build

# 或直接使用 docker compose
docker compose build --no-cache

5. 生成 License

# 使用 user_config.yaml 中的凭证
python cli.py license init

# 或显式指定凭证
python cli.py license init --user-id "your_id" --sdk-code "your_code"

# 检查 license 状态
python cli.py license check

License 通过 Docker named volume (kaiwu-license) 持久化，docker compose run --rm 不会丢失。

6. 运行脚本

在任意位置编写你的 Python 脚本（使用 Kaiwu SDK），CLI 会自动将其挂载到 Docker 容器中执行：

# 运行 user_script/ 下的脚本
python cli.py run example_tsp.py

# 运行宿主机任意位置的脚本
python cli.py run /home/user/projects/my_tsp_solver.py
python cli.py run ~/Desktop/experiment.py

CLI 使用指南

命令一览

命令	说明
`python cli.py build`	构建 Kaiwu SDK Docker 镜像
`python cli.py license init`	生成 SDK License
`python cli.py license check`	检查 License 状态
`python cli.py run <script>`	运行 Python 脚本（支持宿主机任意路径）
`python cli.py solve --qubo '<json>'`	直接求解 QUBO 矩阵
`python cli.py solve --ising '<json>'`	直接求解 Ising 矩阵
`python cli.py solve --tsp '<distances>'`	自动编译 TSP → QUBO → 求解 (via qubify)
`python cli.py solve --maxcut '<adjacency>'`	自动编译 Max-Cut → QUBO → 求解 (via qubify)
`python cli.py solve --knapsack '<json>'`	自动编译 Knapsack → QUBO → 求解 (via qubify)
`python cli.py solve --dsl '<json>'`	自动编译自定义问题 → QUBO → 求解 (via qubify)
`python cli.py compile --preset tsp --data '<json>'`	编译问题 → QUBO 矩阵（不求解）
`python cli.py convert qubo-to-ising '<json>'`	QUBO 矩阵 → Ising 矩阵
`python cli.py convert ising-to-qubo '<json>'`	Ising 矩阵 → QUBO 矩阵
`python cli.py status`	查看容器状态

求解器参数

solve 命令支持细粒度的求解器参数调整：

SA (模拟退火) 参数

参数	说明	默认值
`--sa-temp`	初始温度	100
`--sa-alpha`	降温系数	0.99
`--sa-cutoff`	截止温度	0.001
`--sa-iters`	每温度迭代次数	10
`--sa-size`	输出解的个数	100
`--sa-procs`	并行进程数 (-1 为全部核心)	1

CIM (量子真机) 参数

参数	说明	默认值
`--cim-interval`	轮询间隔（分钟）	1
`--cim-project`	项目编号	—
`--cim-task-mode`	计算模式 (quota/sample)	quota
`--cim-samples`	采样次数 (sample 模式)	10

示例

# 构建镜像
python cli.py build

# 生成 license（使用 user_config.yaml）
python cli.py license init

# 运行自定义脚本（任意路径）
python cli.py run my_optimization.py
python cli.py run ~/projects/quantum/experiment.py

# 直接求解 QUBO（自动转为 Ising + 精度调整）
python cli.py solve --qubo '[[0.89, 0.22, 0.198], [0.22, 0.23, 0.197], [0.198, 0.197, 0.198]]'

# 使用 CIM 真机求解
python cli.py solve --ising '[[1, -1], [-1, 1]]' --cim --task-name "my-experiment"

# 带参数的 SA 求解
python cli.py solve --qubo '[[1, 2], [0, 3]]' --sa-temp 1000 --sa-alpha 0.995 --sa-size 50

# 使用 CIM sample 模式
python cli.py solve --qubo '[[1, 0], [0, 1]]' --cim --cim-task-mode sample --cim-samples 100

# 自动编译并求解 (via qubify)
python cli.py solve --tsp '[[0,10,15,20],[10,0,35,25],[15,35,0,30],[20,25,30,0]]'
python cli.py solve --maxcut '[[0,1,0],[1,0,1],[0,1,0]]'
python cli.py solve --knapsack '{"values":[60,100,120],"weights":[10,20,30],"capacity":50}'

# 编译自定义问题（qubify DSL）并求解
python cli.py solve --dsl '{"variables":{"x":("binary",(3,))},"objective":[{"coeff":1,"vars":[0,1]}],"constraints":[{"type":"one_hot","vars":[0,1,2]}]}'

# 只编译不求解（输出 QUBO 矩阵 JSON）
python cli.py compile --preset maxcut --data '[[0,1,0],[1,0,1],[0,1,0]]'

# QUBO ↔ Ising 矩阵转换
python cli.py convert qubo-to-ising '[[1, 2], [0, 3]]'
python cli.py convert ising-to-qubo '[[0, 1], [1, 0]]'

自动编译求解 (via qubify)

kaiwu-cli-mcp 集成了 qubify — 一个约束→QUBO 编译器。

这意味着你不再需要手推 QUBO 矩阵。 只需要给出业务数据：

你的业务数据 → qubify 编译器 → QUBO 矩阵 → Kaiwu SDK → 解

支持的预设问题类型：

Preset	输入	示例
`tsp`	距离矩阵 `[[d00,d01,...], ...]`	旅行商问题
`maxcut`	邻接矩阵 `[[w00,w01,...], ...]`	最大割问题
`knapsack`	`{"values":[], "weights":[], "capacity":N}`	0/1 背包问题

也可以使用 qubify DSL 描述任意自定义约束问题：

{
  "variables": {"x": ("binary", (5,))},
  "objective": [{"coeff": -1.0, "vars": [0]}],
  "constraints": [
    {"type": "one_hot", "vars": [0, 1, 2]},
    {"type": "cardinality", "vars": [3, 4], "rhs": 1}
  ]
}

编译和求解在宿主机完成（qubify 不需要装在 Docker 里），只把最终矩阵传入 Docker 中调用 Kaiwu SDK。

求解流程说明

solve --qubo 和 solve --ising 的内部处理流程：

--qubo 输入 → QUBO→Ising 转换 (kw.conversion) → 精度调整 (kw.ising) → 优化器求解 → 输出
--ising 输入 → 精度调整 (kw.ising) → 优化器求解 → 输出

QUBO 矩阵会自动通过 kw.conversion.qubo_matrix_to_ising_matrix() 转为 Ising 格式，并通过 kw.ising.adjust_ising_matrix_precision() 调整精度，确保与 CIM 硬件兼容。

编写用户脚本

在任意位置创建 .py 文件，直接 import kaiwu as kw 使用 SDK。

推荐做法：脚本放在 user_script/ 目录下（该目录已映射到容器 /user_script/，执行最快）
灵活做法：脚本放在宿主机任意路径，CLI 调用时自动将该脚本所在目录以只读方式挂载到容器的 /mnt/script/，然后用容器中的 Kaiwu SDK 环境执行

参考 Kaiwu SDK 官方文档 - TSP 教程学习 QUBO/Ising 建模方法。

# user_script/my_solver.py
import numpy as np
import kaiwu as kw

# 定义 QUBO 矩阵
matrix = np.array([[0.89, 0.22], [0.22, 0.23]])

# 调整精度
adjusted = kw.qubo.adjust_qubo_matrix_precision(matrix)

# 使用模拟退火求解
opt = kw.classical.SimulatedAnnealingOptimizer()
solution = opt.solve(adjusted)
print(f"Solution: {solution}")

MCP Server 使用指南

MCP (Model Context Protocol) 模式允许 AI Agent 直接调用 Kaiwu SDK。支持以下 AI 编码工具的 MCP 配置：Hermes Agent、Claude Code、OpenAI Codex、OpenCode。

启动 MCP Server

cd /root/kaiwu-cli-mcp
pip install -r requirements.txt   # 安装 fastmcp 依赖
python mcp_server.py              # 启动 MCP Server (stdio 模式)

各工具 MCP 配置方法

Hermes Agent

编辑 ~/.hermes/config.yaml：

mcpServers:
  kaiwu-sdk-tools:
    command: python
    args: ["/root/kaiwu-cli-mcp/mcp_server.py"]

Claude Code

方法一：CLI 命令（推荐）

claude mcp add --transport stdio kaiwu-sdk-tools -- python /root/kaiwu-cli-mcp/mcp_server.py

方法二：.mcp.json 文件（项目级，可 git-track）

在项目根目录创建 .mcp.json：

{
  "mcpServers": {
    "kaiwu-sdk-tools": {
      "command": "python",
      "args": ["/root/kaiwu-cli-mcp/mcp_server.py"]
    }
  }
}

Local 作用域（仅当前项目，gitignored）：claude mcp add --scope local ...
Project 作用域（团队共享）：claude mcp add --scope project ...
User 作用域（全局所有项目，~/.claude.json）：claude mcp add --scope user ...

在 Claude Code TUI 中使用 /mcp 查看和管理所有 MCP 服务器。

OpenAI Codex

编辑 ~/.codex/config.toml：

[mcp_servers.kaiwu-sdk-tools]
command = "python"
args = ["/root/kaiwu-cli-mcp/mcp_server.py"]

详细配置参数参考：Codex 配置文档

OpenCode

在项目根目录创建 opencode.json（或 opencode.jsonc 支持注释）：

{
  "mcp": {
    "kaiwu-sdk-tools": {
      "type": "local",
      "command": ["python", "/root/kaiwu-cli-mcp/mcp_server.py"]
    }
  }
}

详细配置参数参考：OpenCode 配置文档

OpenCode TUI 中使用 /mcps 管理 MCP 服务器。

可用 MCP 工具

配置完成后，AI Agent 可自动发现以下工具：

工具名	说明
`kaiwu_build_image`	构建 Kaiwu SDK Docker 镜像
`kaiwu_init_license`	生成 SDK License（可指定 user_id/sdk_code）
`kaiwu_check_license`	检查 License 状态
`kaiwu_run_script`	运行 Python 脚本（支持宿主机任意路径，自动挂载到 Docker）
`kaiwu_solve_qubo`	求解 QUBO 矩阵（自动转 Ising + 精度调整）
`kaiwu_solve_ising`	求解 Ising 矩阵（自动精度调整）
`kaiwu_solve_preset`	自动编译+求解 (tsp/maxcut/knapsack) via qubify
`kaiwu_solve_dsl`	自动编译+求解 (自定义 DSL) via qubify
`kaiwu_compile_problem`	编译问题 → QUBO 矩阵（不求解）via qubify
`kaiwu_convert_qubo_to_ising`	QUBO 矩阵 → Ising 矩阵
`kaiwu_convert_ising_to_qubo`	Ising 矩阵 → QUBO 矩阵
`kaiwu_container_status`	查看 Docker 容器状态

所有求解工具支持 sa_params 和 cim_params 参数（JSON 格式）来调整优化器行为。

项目结构

kaiwu-cli-mcp/
├── cli.py              # CLI 入口（argparse）
├── mcp_server.py       # MCP Server 入口（FastMCP）
├── core.py             # 纯业务逻辑层
├── config.py           # 共享配置读取
├── converters.py       # qubify 转换器封装
├── user_config.yaml    # 用户凭证配置 ★编辑此文件★
├── Dockerfile          # Kaiwu SDK Docker 环境
├── docker-compose.yml  # Docker 编排（映射 user_script/ + license 持久化）
├── requirements.txt    # Python 依赖
├── README.md           # 本文件
├── sdk/                # 放置 Kaiwu SDK .whl/.zip 文件
│   └── .gitkeep
└── user_script/        # 用户脚本目录 ★在此编写脚本★
    └── example_tsp.py  # TSP 示例脚本

常见问题

Q: SDK .whl 从哪里下载？

登录 https://platform.qboson.com/，在下载页面选择 Linux 版本。文件命名如 kaiwu-1.3.1-cp310-cp310-linux_x86_64.whl。

Q: 如何确认 License 是否生成成功？

python cli.py license check

License 通过 Docker named volume 持久化，不会因为容器重启而丢失。

Q: 如何直接进入 Docker 容器调试？

docker compose run --rm kaiwu bash

进入后可直接 python3 交互式使用 Kaiwu SDK。

Q: 支持哪些求解器？

SimulatedAnnealingOptimizer (kw.classical) — 经典模拟退火，无需联网
CIMOptimizer (kw.cim) — 相干光量子计算机真机，需要云平台配额

通过 CLI 参数 --sa-* 和 --cim-* 可调整求解器参数。

Q: Python 版本要求？

Kaiwu SDK v1.3.1 仅支持 Python 3.10（不区分小版本）。Docker 镜像已使用 python:3.10-slim。

Q: License 持久化怎么实现的？

通过 Docker Compose 的 named volume kaiwu-license，挂载到容器内 SDK 的 license 目录。即使 docker compose run --rm 删除了容器，license 文件仍然保留在 named volume 中。如果需要清除 license，运行 docker volume rm kaiwu-cli-mcp_kaiwu-license。

参考链接

Kaiwu SDK 官方文档
玻色量子平台
Kaiwu SDK 模块手册 — kaiwu.cim / kaiwu.qubo / kaiwu.license / kaiwu.conversion 等
Kaiwu SDK 安装说明
Kaiwu SDK QUBO 建模教程 (TSP)

License

本工具为开源项目。Kaiwu SDK 版权归北京玻色量子科技有限公司所有。

Name		Name	Last commit message	Last commit date
Latest commit History 9 Commits
sdk		sdk
user_script		user_script
.gitignore		.gitignore
Dockerfile		Dockerfile
README.md		README.md
cli.py		cli.py
config.py		config.py
converters.py		converters.py
core.py		core.py
docker-compose.yml		docker-compose.yml
mcp_server.py		mcp_server.py
requirements.txt		requirements.txt
user_config.yaml		user_config.yaml

Folders and files

Latest commit

History

Repository files navigation

kaiwu-cli-mcp

目录

架构概述

前置要求

快速开始

1. 获取凭证

2. 下载 SDK

3. 配置用户信息

4. 构建 Docker 镜像

5. 生成 License

6. 运行脚本

CLI 使用指南

命令一览

求解器参数

SA (模拟退火) 参数

CIM (量子真机) 参数

示例

自动编译求解 (via qubify)

求解流程说明

编写用户脚本

MCP Server 使用指南

启动 MCP Server

各工具 MCP 配置方法

Hermes Agent

Claude Code

OpenAI Codex

OpenCode

可用 MCP 工具

项目结构

常见问题

Q: SDK .whl 从哪里下载？

Q: 如何确认 License 是否生成成功？

Q: 如何直接进入 Docker 容器调试？

Q: 支持哪些求解器？

Q: Python 版本要求？

Q: License 持久化怎么实现的？

参考链接

License

About

Topics

Resources

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages