Back to Details

cuopt-server-api-python

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

cuOpt Server — Deploy and client (Python/curl)

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

This skill covers starting the server and client examples (curl, Python). Server has no separate C API (clients can be any language).
本技能涵盖启动服务器和客户端示例（curl、Python）。服务器没有单独的C API（客户端可使用任意语言）。

Start server

启动服务器

bash
undefined
bash
undefined

Development

开发环境

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

Docker

Docker部署

docker run --gpus all -d -p 8000:8000 -e CUOPT_SERVER_PORT=8000
nvidia/cuopt:latest-cuda12.9-py3.13
undefined
docker run --gpus all -d -p 8000:8000 -e CUOPT_SERVER_PORT=8000
nvidia/cuopt:latest-cuda12.9-py3.13
undefined

Verify

验证服务器

bash
curl http://localhost:8000/cuopt/health
bash
curl http://localhost:8000/cuopt/health

Workflow

工作流程

  1. POST to 
    /cuopt/request
    → get 
    reqId
  2. Poll 
    /cuopt/solution/{reqId}
    until solution ready
  3. Parse response
  1. 向 
    /cuopt/request
    发送POST请求 → 获取 
    reqId
  2. 轮询 
    /cuopt/solution/{reqId}
    直到解决方案就绪
  3. 解析响应结果

Python client (routing)

Python客户端（路径规划）

python
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)
req_id = r.json()["reqId"]
python
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)
req_id = r.json()["reqId"]

Poll: GET /cuopt/solution/{req_id}

轮询：GET /cuopt/solution/{req_id}

undefined
undefined

Terminology: REST vs Python API

术语对照：REST API vs Python API

Python APIREST
order_locationstask_locations
set_order_time_windows()task_time_windows
service_timesservice_times
Use 
travel_time_matrix_data
(not transit_time_matrix_data). Capacities: 
[[50, 50]]
not 
[[50], [50]]
.
Python APIREST
order_locationstask_locations
set_order_time_windows()task_time_windows
service_timesservice_times
请使用 
travel_time_matrix_data
（而非transit_time_matrix_data）。容量格式应为 
[[50, 50]]
而非 
[[50], [50]]
。

Debugging (422 / payload)

调试（422错误 / 请求体问题）

Validation errors: Check field names against OpenAPI (
/cuopt.yaml
). Common mistakes: 
transit_time_matrix_data
→ 
travel_time_matrix_data
; capacities per dimension 
[[50, 50]]
not per vehicle 
[[50], [50]]
. Capture 
reqId
and response body for failed requests.
验证错误： 对照OpenAPI文档（
/cuopt.yaml
）检查字段名称。常见错误：将
transit_time_matrix_data
误写为
travel_time_matrix_data
；容量应按维度格式
[[50, 50]]
而非按车辆格式
[[50], [50]]
。对于失败的请求，请记录
reqId
和响应体。

Runnable assets

可运行资源

Run from each asset directory (server must be running; scripts exit 0 if server unreachable). All use Python 
requests
:
  • assets/vrp_simple/ — Basic VRP (no time windows)
  • assets/vrp_basic/ — VRP with time windows
  • assets/pdp_basic/ — Pickup and delivery
  • assets/lp_basic/ — LP via REST (CSR format)
  • assets/milp_basic/ — MILP via REST
See assets/README.md for overview.
在每个资源目录下运行（服务器必须处于运行状态；若无法连接服务器，脚本将以0状态码退出）。所有资源均使用Python 
requests
库：
  • assets/vrp_simple/ — 基础VRP（无时间窗）
  • assets/vrp_basic/ — 带时间窗的VRP
  • assets/pdp_basic/ — 取送件问题（PDP）
  • assets/lp_basic/ — 通过REST API求解LP（CSR格式）
  • assets/milp_basic/ — 通过REST API求解MILP
详见assets/README.md中的概述。

Escalate

升级处理

For contribution or build-from-source, see the developer skill.
如需贡献代码或从源码构建，请参考开发者技能文档。