# 当前接口与迁移

1.3 版将求解入口统一为混合、启发式和 OptX 精确求解三类。模型方法与模块函数使用相同参数。旧入口及参数别名已移除，需同步调整调用、配置和结果判断。

## 调整调用方式

| 原调用 | 当前调用 |
| --- | --- |
| `solve(worker_threads=4)` | `solve(threads=4)`；基础配置直接展开 |
| `solve_ga(config=GaConfig(...))` | `solve_heuristic(...)`；时间、线程等参数直接传入，遗传参数移入 `ga=GaOptions(...)` |
| `solve_optx(config=OptxConfig(...))` | `solve_optx(config=HighsConfig(...))` |
| `solve_cpx(config=CpxConfig(...))` | `solve_optx(config=CpSatConfig(...))` |
| `solve_cpsat(config=CpSatConfig(...))` | `solve_optx(config=CpSatConfig(...))`；改用内置 CP-SAT，并检查配置参数 |
| `solve_mathopt(config=MathOptConfig(...))` | 按模型支持范围改用 `solve_optx()` 的 HiGHS 或 CP-SAT 后端，并重新配置 |

### 迁移运行参数

| 原参数 | 当前参数 |
| --- | --- |
| `solve(worker_threads=...)` | `solve(threads=...)` |
| 旧配置中的 `time_limit`，或 CP-SAT 的 `max_time_in_seconds` | `time_limit_s` |
| HiGHS 的 `mip_rel_gap` / `mip_abs_gap` | `relative_gap_limit` / `absolute_gap_limit` |
| CP-SAT 的 `num_search_workers` / `num_workers` | `threads` |
| HiGHS 的 `output_flag` / `log_to_console`，或 CP-SAT 的 `log_search_progress` | `log_level="off"`、`"on"` 或 `"debug"` |

例如，原先 `OptxConfig(time_limit=10, mip_rel_gap=0.01)` 改为
`HighsConfig(time_limit_s=10, relative_gap_limit=0.01)`。旧参数不能作为原生选项继续透传。

独立 GA 的通用参数和遗传参数按下面的方式分开设置：

```python
from optagent import GaOptions

solution = model.solve_heuristic(
    time_limit_s=10.0,
    threads=4,
    ga=GaOptions(population_size=64),
)
```

## 选择精确后端

```python
from optagent import CpSatConfig, HighsConfig, solve_optx

solution = solve_optx(model)  # 默认 HiGHS，30 秒
solution = solve_optx(model, config=HighsConfig(time_limit_s=30.0, threads=4))
solution = model.solve_optx(config=CpSatConfig(time_limit_s=30.0, threads=4))
```

`config` 接收一个 `HighsConfig` 或 `CpSatConfig` 对象，由类型选择后端。
`time_limit_s` 以秒为单位，覆盖序列化、转换、求解、核验和交付；线程数统一使用 `threads`。
原生调优参数直接作为对应配置类的命名参数传入，例如 `HighsConfig(presolve="on")`。
HiGHS 和 OR-Tools CP-SAT 均已内置，无须为这些入口安装 Python `highspy` 或 `ortools`。
集成的 OR-Tools 能力是 CP-SAT，原 MathOpt 的其他求解器选项不能直接迁入。
各后端的支持范围见[求解路径与限制](solvers.md)。

## 读取结果与处理异常

三个入口均返回 `Solution`，先检查 `solution.feasible` 再读取 `.value`。
`solver_name` 分别为 `hybrid`、`heuristic` 和 `optx`；精确求解的实际后端由
`diagnostics["backend"]` 标明，值为 `highs` 或 `cp_sat`。
原先按 `search`、`ga`、`highs` 或 `cpx` 判断一次性求解入口的代码，也需按此调整。
精确转换不支持模型时统一抛出 `OptxUnsupportedError`，可读取 `.issues` 及其中的 `backend` 查看原因。
未知结果不证明模型无解；修改模型后需要重新求解才能读取当前值。
完整说明见[结果与诊断](results.md)及[求解与配置](../api/solve.md)。

[从当前示例开始 →](../start/quickstart.md)