kaiwu-cli-mcp

# kaiwu-cli-mcp **Kaiwu SDK CLI & MCP 双模工具** — 玻色量子 CIM 相干光量子计算机 Python SDK 的 Docker 封装工具，支持命令行（CLI）、Python Library（import）和 AI Agent（MCP）三种调用方式。 > 📚 **Kaiwu SDK 官方文档**: [https://kaiwu-sdk-docs.qboson.com/zh/latest/index.html](https://kaiwu-sdk-docs.qboson.com/zh/latest/index.html) --- ## 目录 - [架构概述](#架构概述) - [前置要求](#前置要求) - [快速开始](#快速开始) - [1. 获取凭证](#1-获取凭证) - [2. 下载 SDK](#2-下载-sdk) - [3. 配置用户信息](#3-配置用户信息) - [4. 构建 Docker 镜像](#4-构建-docker-镜像) - [5. 生成 License](#5-生成-license) - [6. 运行脚本](#6-运行脚本) - [CLI 使用指南](#cli-使用指南) - [Python Library 使用指南](#python-library-使用指南) - [MCP Server 使用指南](#mcp-server-使用指南) - [项目结构](#项目结构) - [常见问题](#常见问题) --- ## 架构概述 ``` ┌─────────────────────────────────────────────┐ │ 宿主机 (Host) │ │ │ │ ┌──────────┐ ┌───────────────┐ │ │ │ CLI │ │ Python │ │ MCP Server │ │ │ │ (cli.py) │ │ Library │ │ (mcp_server) │ │ │ └────┬─────┘ │(import) │ └───────┬───────┘ │ │ │ └─────┬─────┘ │ │ │ └──────────────┼────────────────┘ │ │ │ │ │ ┌──────▼──────┐ │ │ │ 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` + Python import + `mcp_server.py`）。CLI 给人类用，Python Library 给程序调用，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/](https://platform.qboson.com/) --- ## 快速开始 ### 1. 获取凭证 登录 [玻色量子平台](https://platform.qboson.com/)，获取你的 **用户ID (user_id)** 和 **SDK授权码 (sdk_code)**。 ### 2. 下载 SDK 访问 **[SDK 下载页](https://platform.qboson.com/sdkDownload)**，下载 **Linux 版本**的 Kaiwu SDK（下载后为 `.zip` 文件，内含 `.whl`）。 将下载的 `.zip`（或解压后的 `.whl`）放入项目 `sdk/` 目录： ```bash # 方式一：直接放 zip（Docker 构建时自动解压） cp ~/Downloads/kaiwu-*.zip ./sdk/ # 方式二：解压后放 whl unzip ~/Downloads/kaiwu-*.zip -d ./sdk/ ``` Docker 构建时会自动处理：`.zip` 自动解压 → 找到 `.whl` → `pip install`。 ### 3. 配置用户信息 编辑 `user_config.yaml`，填入你的凭证： ```yaml user_id: "your_user_id_here" sdk_code: "your_sdk_code_here" ``` ### 4. 构建 Docker 镜像 ```bash # 使用 CLI 工具 python cli.py build # 或直接使用 docker compose docker compose build --no-cache ``` ### 5. 生成 License ```bash # 使用 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 容器中执行： ```bash # 运行 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 | ### 示例 ```bash # 构建镜像 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](https://github.com/LehaoLin/kaiwu-cli-mcp) 集成了 **[qubify](https://github.com/LehaoLin/qubify)** — 一个约束→QUBO 编译器。 **这意味着你不再需要手推 QUBO 矩阵。** 只需要给出业务数据： ``` 你的业务数据 → qubify 编译器 → QUBO 矩阵 → Kaiwu SDK → 解 ``` 支持的预设问题类型： | Preset | 输入 | 示例 | |--------|------|------| | `tsp` | 距离矩阵 `[[d00,d01,...], ...]` | 旅行商问题 | | `maxcut` | 邻接矩阵 `[[w00,w01,...], ...]` | 最大割问题 | | `knapsack` | `{"values":[], "weights":[], "capacity":N}` | 0/1 背包问题 | 也可以使用 qubify DSL 描述任意自定义约束问题： ```json { "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 教程](https://kaiwu-sdk-docs.qboson.com/zh/latest/index.html) 学习 QUBO/Ising 建模方法。 ```python # 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}") ``` --- ## Python Library 使用指南 `kaiwu-cli-mcp` 支持作为 Python 库直接在代码中 import 使用。核心模块 `core.py` 的所有函数返回结构化的 dict，适合嵌入到其他程序中。 ### 安装方式 **方式一：pip install（推荐）** ```bash # 从本地源码安装（可编辑模式） cd /path/to/kaiwu-cli-mcp pip install -e . # 之后可从任意目录 import python -c "import kaiwu_cli_mcp; print(kaiwu_cli_mcp.__doc__)" ``` 安装后也可以直接使用命令行入口： ```bash kaiwu-cli build kaiwu-cli solve --qubo '[[1, 0], [0, 1]]' ``` **方式二：手动添加 path** ```bash cp -r kaiwu-cli-mcp /your/project/vendor/ ``` ```python import sys sys.path.insert(0, "/your/project/vendor/kaiwu-cli-mcp") from core import solve_qubo, compile_and_solve ``` ### 使用示例 ```python from core import build_image, init_license, check_license, run_script from core import solve_qubo, solve_ising, compile_and_solve, compile_problem from core import container_status, convert_qubo_to_ising, convert_ising_to_qubo # 构建 Docker 镜像 result = build_image() print(result) # {"success": True, "message": "Docker image built successfully", ...} # 生成 license result = init_license("your_user_id", "your_sdk_code") # 直接求解 QUBO 矩阵 result = solve_qubo('[[0.89, 0.22], [0.22, 0.23]]') if result["success"]: print(result["output"]) # 求解结果 # 使用 CIM 量子真机 result = solve_ising( '[[1, -1], [-1, 1]]', use_cim=True, task_name="my-experiment", ) # 自动编译并求解 TSP result = compile_and_solve( preset="tsp", data='[[0,10,15,20],[10,0,35,25],[15,35,0,30],[20,25,30,0]]', ) # 自动编译并求解 Knapsack result = compile_and_solve( preset="knapsack", data='{"values":[60,100,120],"weights":[10,20,30],"capacity":50}', ) # 指定 SA 求解器参数 result = solve_qubo( '[[1, 0], [0, 1]]', sa_params={"initial_temperature": 1000, "alpha": 0.995, "size_limit": 50}, ) # 编译问题（不求解），输出 QUBO 矩阵 result = compile_problem(preset="maxcut", data='[[0,1,0],[1,0,1],[0,1,0]]') if result["success"]: print(result["qubo_matrix"]) # JSON 格式的 QUBO 矩阵 print(result["var_map"]) # 变量映射 # 矩阵转换 result = convert_qubo_to_ising('[[1, 2], [0, 3]]') # result["output"] 包含 {"ising_matrix": ..., "bias": ...} # 检查容器状态 result = container_status() ``` ### 函数返回值约定 所有函数返回统一的 dict 结构： ```python # 成功 {"success": True, "message": "...", "output": "..."} # 失败 {"success": False, "message": "...", "output": "..."} ``` ### Docker 依赖说明 | 函数 | 需要 Docker | 说明 | |------|------------|------| | `build_image` | 是 | 构建 Kaiwu SDK 镜像 | | `init_license` | 是 | 需要容器内执行 Kaiwu SDK | | `check_license` | 是 | 检查容器内 license 文件 | | `run_script` | 是 | 在容器内执行用户脚本 | | `solve_qubo` | 是 | 在容器内调用 Kaiwu SDK 求解 | | `solve_ising` | 是 | 在容器内调用 Kaiwu SDK 求解 | | `compile_and_solve` | 是 | 宿主机编译 QUBO → 容器内求解 | | `compile_problem` | 否 | 纯 Python，宿主机编译 QUBO（需 `qubify`） | | `convert_qubo_to_ising` | 是 | 需要容器内 Kaiwu SDK 转换 | | `convert_ising_to_qubo` | 是 | 需要容器内 Kaiwu SDK 转换 | | `container_status` | 是 | docker compose ps | --- ## MCP Server 使用指南 MCP (Model Context Protocol) 模式允许 AI Agent 直接调用 Kaiwu SDK。 支持以下 AI 编码工具的 MCP 配置：**Hermes Agent**、**Claude Code**、**OpenAI Codex**、**OpenCode**。 ### 启动 MCP Server ```bash cd /root/kaiwu-cli-mcp pip install -r requirements.txt # 安装 fastmcp 依赖 python mcp_server.py # 启动 MCP Server (stdio 模式) ``` --- ### 各工具 MCP 配置方法 #### Hermes Agent 编辑 `~/.hermes/config.yaml`： ```yaml mcpServers: kaiwu-sdk-tools: command: python args: ["/root/kaiwu-cli-mcp/mcp_server.py"] ``` #### Claude Code **方法一：CLI 命令**（推荐） ```bash claude mcp add --transport stdio kaiwu-sdk-tools -- python /root/kaiwu-cli-mcp/mcp_server.py ``` **方法二：`.mcp.json` 文件**（项目级，可 git-track） 在项目根目录创建 `.mcp.json`： ```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`： ```toml [mcp_servers.kaiwu-sdk-tools] command = "python" args = ["/root/kaiwu-cli-mcp/mcp_server.py"] ``` > 详细配置参数参考：[Codex 配置文档](https://github.com/openai/codex/blob/main/docs/config.md) #### OpenCode 在项目根目录创建 `opencode.json`（或 `opencode.jsonc` 支持注释）： ```json { "mcp": { "kaiwu-sdk-tools": { "type": "local", "command": ["python", "/root/kaiwu-cli-mcp/mcp_server.py"] } } } ``` > 详细配置参数参考：[OpenCode 配置文档](https://opencode.ai/docs/) 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 # 纯业务逻辑层（可 import 调用） ├── config.py # 共享配置读取 ├── converters.py # qubify 转换器封装 ├── __init__.py # Python package 入口 ├── pyproject.toml # Python package 配置 ├── 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/](https://platform.qboson.com/)，在下载页面选择 Linux 版本。文件命名如 `kaiwu-1.3.1-cp310-cp310-linux_x86_64.whl`。 ### Q: 如何确认 License 是否生成成功？ ```bash python cli.py license check ``` License 通过 Docker named volume 持久化，不会因为容器重启而丢失。 ### Q: 如何直接进入 Docker 容器调试？ ```bash 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 官方文档](https://kaiwu-sdk-docs.qboson.com/zh/latest/index.html) - [玻色量子平台](https://platform.qboson.com/) - [Kaiwu SDK 模块手册](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/modules/index.html) — kaiwu.cim / kaiwu.qubo / kaiwu.license / kaiwu.conversion 等 - [Kaiwu SDK 安装说明](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/getting_started/sdk_installation_instructions.html) - [Kaiwu SDK QUBO 建模教程 (TSP)](https://kaiwu-sdk-docs.qboson.com/zh/latest/source/getting_started/tutorial_tsp.html) --- ## License 本工具为开源项目。Kaiwu SDK 版权归 [北京玻色量子科技有限公司](https://www.qboson.com/) 所有。