cuopt-server-api-python

cuOpt サーバー — デプロイとクライアント（Python/curl）

このスキルでは、サーバーの起動とクライアントの使用例（curl、Python）を扱います。サーバーに個別の C API はありません（クライアントには任意の言語を使用できます）。

目的

cuOpt REST サーバーをデプロイする場合、またはそのサーバーを利用するクライアントを作成する場合に、このスキルを使用してください。デプロイ先の選定、問題を HTTP エンドポイントに対応付ける方法、Python API と REST のフィールド名の対応付け、拒否されたペイロードのデバッグなどを扱います。

前提条件

• CUDA ドライバーが正常に動作する NVIDIA 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

ドライバーの CUDA メジャーバージョンに合わせて latest-cu12 または latest-cu13 を使用してください（UBI10 ベースの場合は latest-cu13-ubi10）。

本番環境では、タグを固定し、変動するタグは使用しないでください。latest-* タグは変更可能なため、気付かないうちに別のイメージに切り替わることがあります。完全なリリースタグ（nvidia/cuopt:<release>-cu<cuda-major>）または不変のダイジェスト（nvidia/cuopt@sha256:<digest>）を使用してください。利用可能なタグは nvidia/cuopt レジストリで確認してください。

動作確認

ローカルポート（例：http://localhost:8000/cuopt/health）で GET /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

transit_time_matrix_data ではなく travel_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]] ではなく、容量の次元ごとに内側のリストを 1 つ持つ [[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 とレスポンス本文全体を取得してください。サーバー側での拒否を診断するには、両方が必要です。

制限事項

• QP は REST 経由では公開されていません。 二次目的関数には Python または C API を使用してください。
• サーバーには認証機能も TLS もありません。 ポートに接続できるものは誰でもジョブを送信できます。ゲートウェイの背後に配置し、--server／ベース URL は信頼できるネットワークのエンドポイントとしてのみ扱ってください。
• 解はポーリングして取得します。プッシュ／Webhook による配信はありません。
• サーバープロセスごとに同時に解くリクエストは 1 つです。同時実行には複数のレプリカが必要です。

実行可能なアセット

各アセットのディレクトリから実行してください（サーバーが起動している必要があります。サーバーに接続できない場合、スクリプトは終了コード 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 を参照してください。

エスカレーション

貢献またはソースからのビルドについては、開発者向けスキルを参照してください。