cuopt-server-api-python

cuOpt 服务端 — 部署与客户端（Python/curl）

本指南涵盖启动服务端和客户端示例（curl、Python）。服务端没有单独的 C API（客户端可以使用任何语言）。

用途

在用户部署 cuOpt REST 服务端或为其编写客户端时使用本指南，包括选择部署目标、将问题映射到 HTTP 端点、在 Python API 与 REST 字段名称之间进行转换，或排查被拒绝的请求负载。

先决条件

• 一块装有可正常工作的 CUDA 驱动的 NVIDIA GPU（服务端需要 GPU；Docker 使用 --gpus all）。
• 已安装 cuopt-server，或已安装 NVIDIA Container Toolkit 的 Docker。请参阅安装指南。
• Python 客户端需要 requests。服务端本身不需要 API 密钥或身份验证令牌。

支持的问题类型

问题类型	是否支持
路由	✓
LP	✓
MILP	✓
QP	✗

必要问题

如果尚不明确，请询问以下问题：

1. 问题类型 — 路由还是 LP/MILP？（REST 不支持 QP。）
2. 部署方式 — 本地、Docker、Kubernetes 还是云端？
3. 客户端 — 将使用哪种语言或工具调用 API（例如 Python、curl 或其他服务）？

启动服务端

# Development
python -m cuopt_server.cuopt_service --ip 0.0.0.0 --port 8000

# Docker — pick the tag matching your CUDA major version
docker run --gpus all -d -p 8000:8000 -e CUOPT_SERVER_PORT=8000 \
  nvidia/cuopt:latest-cu13

使用 latest-cu12 或 latest-cu13，以匹配驱动的 CUDA 主版本（使用 UBI10 基础镜像时选择 latest-cu13-ubi10）。

用于生产时，请固定版本，而不要使用浮动标签：latest-* 标签会变动，可能在不知情的情况下切换到其他镜像。请使用完整发布标签（nvidia/cuopt:<release>-cu<cuda-major>）或不可变摘要（nvidia/cuopt@sha256:<digest>）。请在 nvidia/cuopt 注册表中查看可用标签。

验证

向本地端口发送 GET /cuopt/health 请求（例如 http://localhost:8000/cuopt/health），确认服务端已启动；健康的服务端会返回 HTTP 200。

操作说明

1. 向 /cuopt/request 发送 POST 请求 → 获取 reqId
2. 轮询 /cuopt/solution/{reqId}，直到解已就绪
3. 解析响应

将 reqId 视为不可信输入：在将其插入轮询 URL 之前先进行验证（例如 re.fullmatch(r"[A-Za-z0-9_-]{1,64}", req_id)），并为每个请求设置明确的 timeout。

示例

import requests, time
SERVER = "http://localhost:8000"
HEADERS = {"Content-Type": "application/json", "CLIENT-VERSION": "custom"}
payload = {
    "cost_matrix_data": {"data": {"0": [[0,10,15],[10,0,12],[15,12,0]]}},
    "travel_time_matrix_data": {"data": {"0": [[0,10,15],[10,0,12],[15,12,0]]}},
    "task_data": {"task_locations": [1, 2], "demand": [[10, 20]], "task_time_windows": [[0,100],[0,100]], "service_times": [5, 5]},
    "fleet_data": {"vehicle_locations": [[0, 0]], "capacities": [[50]], "vehicle_time_windows": [[0, 200]]},
    "solver_config": {"time_limit": 5}
}
r = requests.post(f"{SERVER}/cuopt/request", json=payload, headers=HEADERS, timeout=30)
req_id = r.json()["reqId"]
# Poll: GET /cuopt/solution/{req_id}

术语：REST 与 Python API

Python API	REST
order_locations	task_locations
set_order_time_windows()	task_time_windows
service_times	service_times

请使用 travel_time_matrix_data（不要使用 transit_time_matrix_data）。容量应为 [[50, 50]]，而不是 [[50], [50]]。

故障排查

错误	原因	解决方案
422 Unprocessable Content	字段名称不在架构中	对照 /cuopt.yaml 中的 OpenAPI 规范检查名称。最常见的是：transit_time_matrix_data → travel_time_matrix_data
fleet_data 返回 422	容量按车辆嵌套，而非按维度嵌套	使用 [[50, 50]]（每个容量维度对应一个内层列表），而不是 [[50], [50]]
连接被拒绝	服务端未启动，或绑定到了其他接口/端口	运行 curl http://localhost:8000/cuopt/health 检查；使用 --ip 0.0.0.0 --port 8000 启动
Docker 容器立即退出	容器无法看到 GPU	使用 --gpus all 运行，并确认已安装 NVIDIA Container Toolkit
轮询始终没有返回解	求解时间超过客户端的轮询预算	同时增大 solver_config.time_limit 和轮询循环次数

对于任何失败的请求，请记录 reqId 和完整响应正文——诊断服务端拒绝请求需要这两项信息。

限制

• REST 不提供 QP。 对于二次目标函数，请使用 Python 或 C API。
• 服务端不提供身份验证或 TLS。 任何能够访问该端口的对象都可以提交作业。请将其置于网关之后，并仅将 --server/基础 URL 视为可信网络端点。
• 解通过轮询获取；不支持推送或 webhook 交付。
• 每个服务端进程一次只求解一个请求；要实现并发处理，需要使用多个副本。

可运行资产

在各资产目录中运行（服务必须正在运行；如果无法连接服务，脚本会以 0 退出）。所有脚本都使用 Python requests，并接受 --server（默认值为 http://localhost:8000）：

• assets/vrp_simple/ — 基本 VRP（无时间窗）
• assets/vrp_basic/ — 带时间窗的 VRP
• assets/pdp_basic/ — 取货与配送
• assets/lp_basic/ — 通过 REST 执行 LP（CSR 格式）
• assets/milp_basic/ — 通过 REST 执行 MILP

概览请参阅 assets/README.md。

升级处理

有关贡献或从源代码构建的信息，请参阅开发者技能。