cuopt-server-api-python

작성자: nvidia

cuOpt REST 서버 — 서버 시작, 엔드포인트, Python/curl 클라이언트 예제. 사용자가 REST API를 배포하거나 호출할 때 사용합니다.

npx skills add https://github.com/nvidia/skills --skill cuopt-server-api-python

cuOpt Server — Deploy and client (Python/curl)

This skill covers starting the server and client examples (curl, Python). Server has no separate C API (clients can be any language).

Problem types supported

Problem type	Supported
Routing	✓
LP	✓
MILP	✓
QP	✗

Required questions

Ask these if not already clear:

Problem type — Routing or LP/MILP? (QP not available via REST.)
Deployment — Local, Docker, Kubernetes, or cloud?
Client — Which language or tool will call the API (e.g. Python, curl, another service)?

Start server

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

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

Verify

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

Workflow

POST to /cuopt/request → get reqId
Poll /cuopt/solution/{reqId} until solution ready
Parse response

Python client (routing)

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}

Terminology: REST vs Python API

Python API	REST
order_locations	task_locations
set_order_time_windows()	task_time_windows
service_times	service_times

Use travel_time_matrix_data (not transit_time_matrix_data). Capacities: [[50, 50]] not [[50], [50]].

Debugging (422 / payload)

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.