---
tags:
  - install
---

# 安装指南

本页说明当前公开发行的 OptAgent wheel 安装包。当前正式版本为 **1.2.0**，只发布 **CPython 3.12**，安装流程按“准备环境 -> 安装 wheel -> 获取并安装许可证 -> 验证导入 -> 按需安装求解器依赖”组织。

## 支持范围

| 项目 | 当前公开范围 |
| --- | --- |
| Python | CPython 3.12，wheel 标签为 `cp312-cp312` |
| Linux | `x86_64` manylinux wheel |
| macOS | Apple Silicon `arm64` wheel |
| Windows | 仅使用正式发布并通过验证的 `win_amd64` wheel |
| 安装工具 | `pip` 或 `uv` |

## 获取 wheel

OptAgent 当前通过 wheel 文件发布。请从项目经理处获取当前版本、当前平台和 `cp312-cp312` 标签匹配的 `.whl` 文件，例如：

```text
optagent-1.2.0-cp312-cp312-manylinux2014_x86_64.whl
```

不要在不同操作系统、CPU 架构或 Python 版本之间复用 wheel。文件名中的平台标签必须与目标环境匹配。

## 使用 pip 安装

```bash
python3.12 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install /path/to/optagent-1.2.0-cp312-cp312-<platform-tag>.whl
```

Windows PowerShell 使用：

```powershell
py -3.12 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install C:\path\to\optagent-1.2.0-cp312-cp312-<platform-tag>.whl
```

## 使用 uv 安装

```bash
uv venv --python 3.12
source .venv/bin/activate
uv pip install /path/to/optagent-1.2.0-cp312-cp312-<platform-tag>.whl
```

## 安装第三方 CP-SAT 支持

默认安装包含 OptAgent 内部 strategy 路径和 OptX/HiGHS MP 路径。需要使用 Google OR-Tools CP-SAT 时，安装 `[ortools]` extra：

```bash
python -m pip install '/path/to/optagent-1.2.0-cp312-cp312-<platform-tag>.whl[ortools]'
```

该 extra 提供 `ortools >= 9.15`，对应公开入口 `solve_cpsat()`。如需明确选择 CP-SAT，
请参考[求解与策略](../api/solve-reference.md)；公开调度示例统一使用 `solve(...)`，无需安装此 extra。

## 安装后验证

先确认 Python 版本和包路径：

```bash
python -c "import sys; print(sys.version)"
python -c "import optagent; print(optagent.__file__)"
```

再运行 [快速入门](quickstart.md) 中的三个最小模型，确认当前环境可以完成建模、求解和结果读取。

## 获取并安装许可证

OptAgent 的正式 wheel 需要有效的机器许可证才能执行求解。许可证不是通过 pip 自动获取的；安装 wheel 后，先在目标机器上生成机器申请：

```bash
python -m optagent.license request
```

将生成的 `optagent-license-request.json` 提交给项目经理或合同联系人，由项目方签发与该机器绑定的 `optagent.license` 文件。收到文件后，在安装 wheel 的同一环境中执行：

```bash
python -m optagent.license install /path/to/optagent.license
python -m optagent.license status
```

`status` 显示许可证有效后，再运行求解。许可证文件应妥善保管，不要复制到其他机器；续期或更换机器时，请联系项目方重新签发。

## 常见问题

### Wheel 架构不匹配

安装时报 `is not a supported wheel on this platform` 时，检查三个标签：

- Python 必须是 CPython 3.12，标签为 `cp312-cp312`。
- Apple Silicon 使用 `macosx_*_arm64` wheel。
- Linux 和 Windows 不能互换 wheel；`manylinux` 与 `win_amd64` 也不能互换。

### C++ 内核加载失败

`import optagent` 成功但 `solve()` 报内核不可用时，确认当前 wheel 与操作系统匹配，并检查 Linux 的 glibc 和 C++ 运行库是否满足 wheel 标签要求。

### OR-Tools 与 protobuf 冲突

OptAgent 需要 `protobuf >= 6.33, < 7.0`。使用 `[ortools]` extra 时，OR-Tools 版本应为 `>= 9.15`；如果环境还安装了其他 protobuf 使用者，建议为 OptAgent 创建独立虚拟环境。

### 当前不发布其他 Python 版本

当前公开安装说明只覆盖 CPython 3.12。其他 Python 版本即使能满足项目元数据，也没有对应的公开 wheel 发布承诺。