AnnealBridge

AnnealBridge

English | 繁體中文

面向 AI Agent 的组合优化中间件。 Agent 以结构化 JSON 描述要优化的内容；AnnealBridge 决定如何对其编码并求解，依据原始问题检查每个答案，并通过 MCP、命令行或纯 Python 返回经过排序和验证的解决方案。

flowchart LR
    U[Natural language] --> A[AI agent]
    A -->|OptimizationProblem JSON<br/>variables · objective · constraints| B
    subgraph B[AnnealBridge]
        direction LR
        V[validate] --> C[compile<br/>BQM / CQM] --> S[solve<br/>local or remote] --> R[re-validate against<br/>the original problem] --> K[rank]
    end
    B -->|SolveResult<br/>ranked, verified solutions| A
    A --> N[Natural-language answer]

快速开始

pip install annealbridge

一个 0/1 背包问题：四件物品，容量为 10，最大化价值。无需文件。

from annealbridge.models import OptimizationProblem
from annealbridge.orchestration import OptimizationService

problem = OptimizationProblem.model_validate({
    "version": "1.0",
    "name": "knapsack",
    "variables": [{"name": n, "type": "binary"} for n in ["a", "b", "c", "d"]],
    "objective": {"direction": "maximize", "linear_terms": [
        {"variable": "a", "coefficient": 10}, {"variable": "b", "coefficient": 8},
        {"variable": "c", "coefficient": 7}, {"variable": "d", "coefficient": 6}]},
    "constraints": [{"id": "capacity", "type": "hard", "operator": "<=", "rhs": 10, "terms": [
        {"variable": "a", "coefficient": 6}, {"variable": "b", "coefficient": 5},
        {"variable": "c", "coefficient": 4}, {"variable": "d", "coefficient": 3}]}],
})

result = OptimizationService().solve(problem)
print(result.status)                        # success
print(result.solutions[0].variables)        # {'a': 1, 'b': 0, 'c': 1, 'd': 0}
print(result.solutions[0].objective_value)  # 17.0

领域层面的失败会作为结果返回，而不会抛出异常：result.status 的值为 success、infeasible、invalid_problem、resource_limit_exceeded、backend_unavailable、configuration_error 或 solver_error。请参阅 docs/output-format.md。

可选扩展：

pip install "annealbridge[mcp]"       # + MCP server (annealbridge-mcp)
pip install "annealbridge[dwave]"     # + D-Wave cloud backends
pip install "annealbridge[all]"       # everything
pip install "annealbridge[gpu]"       # + PyTorch, for simulated_bifurcation on CUDA

[gpu] 有意不包含在 [all] 中：PyTorch 的下载体积很大，而且在 Windows 上，PyPI 提供的 wheel 是仅含 CPU 的构建版本，因此要运行 CUDA，必须先从 PyTorch 自己的索引安装 torch——请参阅 docs/backends.md。

在 AI Agent 中使用（MCP）

安装 uv 后，将服务添加到 claude_desktop_config.json（或主机的同等配置文件）中，然后重启 主机；Claude Desktop、Claude Code 和 Codex 将该配置存放在哪里，详见 docs/mcp.md。 首次运行时，会将软件包下载到 uvx 自己的缓存环境中；这次下载会包含 numpy、dimod、dwave-samplers 等内容，可能需要几十秒，久到足以让主机的启动超时机制 将服务显示为已断开连接。先在终端中预热一次缓存：

uvx --from "annealbridge[mcp]" annealbridge-mcp --version

它会解析环境并打印版本；此后主机就会从该缓存启动。

{
  "mcpServers": {
    "annealbridge": {
      "command": "uvx",
      "args": ["--from", "annealbridge[mcp]", "annealbridge-mcp"]
    }
  }
}

Claude Code 可以用一行命令注册它：

claude mcp add annealbridge -- uvx --from "annealbridge[mcp]" annealbridge-mcp

接下来就可以像普通聊天一样进行优化：

你： 我最多能搬 10 kg。物品 A 值 10，重 6；B 值 8，重 5； C 值 7，重 4；D 值 6，重 3。我该拿哪些？

在回复背后，Agent 会将请求写成问题 JSON 并调用 solve_optimization。每个解都会根据 原始约束重新验证；使用穷举 exact 后端时，会带有 optimality_proven: true；如果服务拒绝某个文档，它会以 invalid_problem 返回，并列出所有错误以及每个错误的修复方法，Agent 会应用这些修复后 再次发送。使用远程后端求解或处理大型问题前，它会先调用 validate_optimization_problem，因此出错也不会产生任何代价；需要查看后端列表或完整架构时， 它会调用 get_optimization_capabilities。

Agent： 拿 A 和 C：价值为 17，重量正好 10 kg。次优组合是 A 和 D（价值 16，重 9 kg）以及 B 和 C（价值 15，重 9 kg）。这是已证明的最优解。

回复措辞由 Agent 决定；数值来自工具。另一个工具 recommend_backend 会为问题中的后端排名，但仅提供建议； 如果你没有指定后端，且有多个本地后端适用，服务指令会要求 Agent 显示排名靠前的选项并询问你要运行哪一个，而不是替你做决定。

如果主机在输入菜单中列出提示词，其中三个——pick_subset、 assign 和 schedule_shifts——会引导 Agent 将你的一句话转换为符合相应日常场景的问题文档，然后由它进行求解。服务还提供资源：annealbridge://examples/ 下的七个 示例文档，以及 annealbridge://schema 上的完整问题架构，这样 Agent 可以读取完整示例或架构本身，而不必猜测。

不适用的场景。 AnnealBridge 不支持连续 （实数）变量、非线性目标函数或非线性约束。 只有 exact 能证明答案是最优解或不存在可行解，并且默认最多处理 24 个编译后变量（包括松弛位）；其他本地后端（simulated_annealing、tabu、 simulated_bifurcation）都是启发式方法，返回的最佳答案可能并非 最优解。请参阅下方的 后端表格和 docs/limitations.md。

任何支持 stdio 的 MCP 主机都能以相同方式工作；此外还有 streamable-http 传输方式，也可以用 pipx 或通过绝对路径调用的 pip 安装服务来替代 uvx。uvx 会复用首次运行时解析的环境，因此要让新版本更新到现有安装中，必须先运行 uv cache clean annealbridge，再重启主机；详见 docs/mcp.md。

从命令行使用

将下方的问题 JSON保存为 knapsack.json，然后：

annealbridge solve knapsack.json

Problem:   knapsack
Backend:   exact
Status:    success
Attempts:  1
Elapsed:   2.7 ms

Best solution (rank 1)
  objective (maximize):  17
  soft violation score:  0
  item_a = 1
  item_b = 0
  item_c = 1
  item_d = 0

Hard constraints: 1 / 1 satisfied
Soft constraints: 0 violations
Optimality proven: yes

Elapsed 是服务自身的墙上时钟时间，每次运行都会有所不同。添加 --json 可获取完整的 SolveResult，添加 --backend simulated_annealing 可 覆盖后端，也可以试试 validate、recommend、capabilities、 example 和 export-schema。请参阅 docs/cli.md。

问题 JSON

上方 MCP 和 CLI 示例所用文档的简化形式，参见 examples/knapsack.json：

{
  "version": "1.0",
  "name": "knapsack",
  "variables": [
    {"name": "item_a", "type": "binary"},
    {"name": "item_b", "type": "binary"},
    {"name": "item_c", "type": "binary"},
    {"name": "item_d", "type": "binary"}
  ],
  "objective": {
    "direction": "maximize",
    "linear_terms": [
      {"variable": "item_a", "coefficient": 10},
      {"variable": "item_b", "coefficient": 8},
      {"variable": "item_c", "coefficient": 7},
      {"variable": "item_d", "coefficient": 6}
    ]
  },
  "constraints": [
    {
      "id": "capacity",
      "type": "hard",
      "terms": [
        {"variable": "item_a", "coefficient": 6},
        {"variable": "item_b", "coefficient": 5},
        {"variable": "item_c", "coefficient": 4},
        {"variable": "item_d", "coefficient": 3}
      ],
      "operator": "<=",
      "rhs": 10
    }
  ],
  "solver": {"backend": "exact"}
}

整数变量（"type": "integer" 并设置边界，"version": "1.1"）、 基数约束——一组二进制变量中恰好、至多或至少有 k 个满足条件；可编译为 无需松弛变量的硬性至多一个约束（"cardinality_constraints"、 "version": "1.2"）——模板可在索引集上一次编写大型规则模型，并由服务展开 （"index_sets"、"parameters"、"variable_families" 和 *_templates 列表，"version": "1.3"）、二次目标项、带权重的软约束，以及按后端设置的 求解器偏好，详见 docs/problem-format.md。 annealbridge export-schema 会输出 Agent 可用于结构化输出的 JSON Schema。

仓库中有七个开箱即用的示例 — 背包问题、 指派问题、 TSP、 整数背包问题、 轮班排程、 考试排程 （基数约束），以及 带模板的 TSP （在索引集上一次编写 TSP；annealbridge expand 会输出展开后的内容）。 已安装的软件包也包含相同文件：annealbridge example 会列出这些文件， annealbridge example knapsack > knapsack.json 会保存一个示例（也可以直接 通过管道传入：annealbridge example knapsack | annealbridge solve -）；MCP 服务 也会将相同的七份文档作为资源提供，路径为 annealbridge://examples/。

工作原理

Agent 会生成一个 OptimizationProblem：其中包含二元或有界整数变量、线性或二次目标，以及硬性或软性的线性约束和基数约束。仅此而已。随后，AnnealBridge 会按确定性的流程：

1. 验证问题，并在将模板展开为明确条目后，一次性收集所有错误；
2. 编译为 BQM 或 CQM，并自行计算惩罚项、松弛变量和整数编码；
3. 在本地或远程后端上求解；
4. 根据原始 JSON 重新验证每个候选解，从不信任求解器的能量值；
5. 排序可行解，并返回前 K 个解及各约束的评估结果。

选择启用的 solver.postprocess 步骤还可以在排序前，针对原始变量修复并局部改进最佳样本；其生成的结果会像其他候选解一样经过重新验证，并由每个解的 source 标记。可选的 solver.wall_clock_limit_seconds 会限制本地启发式后端的求解时长：时间用尽时，结果会保留已完成的部分，仍经过重新验证和排序，并注明这一情况（wall_clock_limit_reached）。MCP 客户端取消求解时，求解会立即停止，而不会继续运行。

Agent 从不编写 QUBO 矩阵、惩罚权重、松弛变量或整数编码；每个步骤都可以在没有 AI、网络或供应商账户的情况下进行测试。

后端

八种后端遵循同一协议。

后端	类型	路径	说明
exact	本地	BQM	枚举所有赋值；默认最多 24 个编译后变量
simulated_annealing	本地	BQM	启发式；通用型选择，在小规模或硬约束问题上的表现优于另外两种；支持 num_reads、num_sweeps、seed
tabu	本地	BQM	启发式多起点禁忌搜索，适用于稠密 QUBO；稠密问题规模较大时的首选；支持 num_reads、seed
simulated_bifurcation	本地	BQM	启发式稠密矩阵动力学（Goto 等，2021），适用于大型稠密无约束 QUBO；对于硬约束被编译为惩罚项的问题，表现较弱；支持 num_reads、num_sweeps、seed；可通过 [gpu] 选用 CUDA
dwave_qpu	远程	BQM	通过 EmbeddingComposite 使用 D-Wave 量子退火器
leap_hybrid_bqm	远程	BQM	D-Wave Leap 混合 BQM 求解器
leap_hybrid_cqm	远程	CQM	D-Wave Leap 混合 CQM 求解器；支持原生约束
fujitsu_da	远程	BQM	Fujitsu Digital Annealer，通过 HTTPS 使用 QUBO API V4，无需 SDK

远程后端需要供应商凭据和 ANNEALBRIDGE_ALLOW_REMOTE=true；缺少任一项时，都会报告 backend_unavailable。annealbridge recommend 会为问题推荐后端，但不会实际求解，也不会更改你指定的后端。设置方法及各后端的行为说明：docs/backends.md。

设计保证

• 双向的业务级契约。 输入变量、目标和约束，输出按排名排列的解及各约束的评估结果。求解器内部细节不会泄漏到任一方向。
• 两条编译路径。 BQM（自动罚项、二进制松弛变量、编码整数）用于退火器；CQM（原生约束和整数）用于 Leap 混合 CQM 求解器。后端通过声明支持的内容来选择路径。
• 有界整数，不暴露编码。 "version": "1.1" 增加整数变量，并隐藏其编码；通过黄金测试固定 1.0 的行为。
• 明确表达计数规则。 "version": "1.2" 增加基数约束——对二进制变量设置恰好一个、至多 k 个、至少 k 个；硬性至多一个约束会编译为成对罚项，无需松弛变量；通过兼容性黄金测试固定 1.0 和 1.1 的行为。
• 大型模型只需编写一次。 "version": "1.3" 增加索引集、参数表、变量族和模板；服务会在其他处理开始前将其展开为普通变量、项和约束。错误会指向相应模板，大小上限则会拒绝整个超限展开，而不会截断。现有黄金测试固定 1.0–1.2 的行为。
• 结构化故障，不抛异常。 每个结果都是带有 status 的 SolveResult；每个故障都包含稳定的错误代码和 recommended_action。infeasible 是一种答案，而不是故障。
• 不做静默决策。 不可用的后端会被报告，而不会被替换。超出限制的参数会被拒绝，而不会被截断到上限。未声明的字段会被拒绝，而不会被忽略。每个求解结果都会附带验证器警告。
• 默认安全。 启用前，远程执行和远程重试均处于关闭状态；每项限制都通过环境变量设置，并以错误形式强制执行；供应商凭据会从结果、日志和错误消息中脱敏。streamable-http 传输没有身份验证；请将其限制在专用网络中。请参阅 docs/security.md 和 SECURITY.md。
• 架构强制执行。 导入边界、“编排层、验证层或接口层中不得出现后端名称”，以及“新后端无需触碰处理流水线即可接入”都是测试要求，而非约定。

文档

以下页面位于 docs/ 下。

页面	内容
docs/problem-format.md	输入 JSON：变量、目标函数、约束、求解器偏好
docs/output-format.md	SolveResult 及其包含的所有字段
docs/errors.md	错误目录、警告代码、原因代码、退出代码
docs/cli.md	annealbridge 命令行
docs/mcp.md	MCP 服务：工具、提示词、资源、主机配置、Inspector
docs/backends.md	八种后端、D-Wave 和 Fujitsu 设置、添加后端
docs/configuration.md	所有 ANNEALBRIDGE_* 变量及供应商凭据
docs/architecture.md	分层、软件包布局、设计原则
docs/security.md	默认设置、限制、凭据脱敏、发送给供应商的内容
docs/testing.md	测试布局、黄金测试、实时测试、CI
docs/limitations.md	已知限制和范围之外的内容

开发

git clone https://github.com/TheTsungYing/AnnealBridge.git
cd AnnealBridge
pip install -e ".[all,dev]"
pytest

pytest 会运行完整测试套件，不跳过任何测试，也不标记任何测试为预期失败，并且不会访问网络；实时供应商测试需选择启用（pytest -m remote）。如需在不检出代码的情况下安装开发版本： pip install "annealbridge[all] @ git+https://github.com/TheTsungYing/AnnealBridge.git"。 架构规则、设计原则和拉取请求检查清单见 CONTRIBUTING.md。

版本 0.4.0：问题契约（1.0 / 1.1 / 1.2 / 1.3）、八种后端、CLI 和 MCP 工具均已完成，并由测试覆盖。当前暂不支持的内容（这是有意的设计）列于 docs/limitations.md； 变更记录见 CHANGELOG.md。

许可证

MIT