安装指南¶
本页说明当前公开发行的 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 文件，例如：
不要在不同操作系统、CPU 架构或 Python 版本之间复用 wheel。文件名中的平台标签必须与目标环境匹配。
使用 pip 安装¶
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 使用：
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 安装¶
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：
该 extra 提供 ortools >= 9.15，对应公开入口 solve_cpsat()。如需明确选择 CP-SAT，
请参考求解与策略；公开调度示例统一使用 solve(...)，无需安装此 extra。
安装后验证¶
先确认 Python 版本和包路径：
再运行 快速入门 中的三个最小模型，确认当前环境可以完成建模、求解和结果读取。
获取并安装许可证¶
OptAgent 的正式 wheel 需要有效的机器许可证才能执行求解。许可证不是通过 pip 自动获取的；安装 wheel 后，先在目标机器上生成机器申请：
将生成的 optagent-license-request.json 提交给项目经理或合同联系人，由项目方签发与该机器绑定的 optagent.license 文件。收到文件后，在安装 wheel 的同一环境中执行：
status 显示许可证有效后，再运行求解。许可证文件应妥善保管，不要复制到其他机器；续期或更换机器时，请联系项目方重新签发。
常见问题¶
Wheel 架构不匹配¶
安装时报 is not a supported wheel on this platform 时，检查三个标签：
- Python 必须是 CPython 3.12，标签为
cp312-cp312。 - Apple Silicon 使用
macosx_*_arm64wheel。 - 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 发布承诺。