cuopt-server-api-python-nvidia-skills

1. 基本信息

2. 功能介绍与亮点

这个技能指导 agent 把 cuOpt（NVIDIA 出品的 GPU 加速决策优化引擎）以 REST 服务的形式部署起来，并正确编写调用它的客户端代码——覆盖路径规划（VRP）、线性规划（LP）、混合整数规划（MILP）三类问题，QP 明确标注该接口不支持。

主要亮点：

• 先问清楚三件事再动手：问题类型是路由还是 LP/MILP？部署目标是本机、Docker 还是 Kubernetes/云端？调用方用什么语言？REST 接口本身跟语言无关，这一步帮 agent 选对客户端实现路径。
• 完整的请求-轮询工作流：POST /cuopt/request 拿到 reqId，轮询 /cuopt/solution/{reqId} 直到出结果，附带可直接运行的 Python 客户端示例。
• Python API 与 REST 字段名对照表：order_locations ↔ task_locations、set_order_time_windows() ↔ task_time_windows 等，专门解决“用 Python 库的思路拼 REST 请求体却报错”这个常见坑，并特别标注 travel_time_matrix_data 拼写、以及 capacities 应按维度而非按车辆分组的两个高频出错点。
• 针对 422 错误的调试指引：明确指向 OpenAPI 定义（/cuopt.yaml）核对字段名，并要求捕获失败请求的 reqId 与响应体，把“参数拼错但报错信息看不出所以然”的调试成本降下来。
• 5 组可运行资产：基础 VRP、带时间窗 VRP、取送货（PDP）、LP、MILP 各配一份可直接执行的客户端脚本，服务未启动时会打印提示并正常退出（不会因环境未就绪而报错中断）。经抽查 assets/vrp_simple/client.py，服务器地址通过环境变量 CUOPT_SERVER_URL 配置、默认 localhost，无硬编码外部地址。
• 官方发布前量化评测：NVIDIA 内部 NVSkills-Eval 框架在 Claude Code 与 Codex 上分别测了安全性、正确率、可发现性、有效性、效率五个维度，安全性两个 agent 均 100% 通过。

3. 适用场景

所属分类：工程效率与代码质量

适合需要把 cuOpt 求解能力以微服务形式接入现有系统的开发者与后端工程师——典型场景包括：用非 Python 语言（如 Node.js、Java 后端）通过 curl 或 HTTP 客户端调用 cuOpt 求解路由/LP/MILP 问题、把 cuOpt 部署进 Docker/Kubernetes 环境对外提供求解接口、以及在从 Python 原生 API 迁移到 REST 接口时排查字段名不一致导致的 422 错误。它与同仓库的 cuopt-routing-api-python（Python 原生库调用）、cuopt-numerical-optimization-api（C API）是同一引擎的三种不同接入形态，本技能专注于“部署为服务、跨语言调用”这一种。

4. 跨 Agent 兼容性

• Claude Code：原生支持，官方 skills CLI 提供 --agent claude-code 参数直接安装，装完需运行 /reload-skills 加载。
• Codex：原生支持，--agent codex 参数同样覆盖；官方发布前评测两个 agent 均通过。
• OpenClaw / Hermes Agent：未验证。官方 skills CLI 目前列出的目标客户端为 Claude Code、Codex、Cursor、Kiro、Snowflake Cortex 等，抓取到的材料未提及这两个 agent。

5. 推荐理由

REST 服务器是 cuOpt 唯一跟语言无关的接入方式，但 Python 原生 API 与 REST 请求体的字段命名并不一致——这个技能把两者的对照表和最容易出错的两个具体拼写坑直接摆出来，配合针对 422 错误的调试路径，能显著缩短“从能跑通 Python 版 demo，到把 cuOpt 部署成一个能被任意语言调用的服务”这段常见迁移路径上的调试时间。

6. 评分

安全检查清单：①涉及执行的操作限于启动本地/Docker 服务（python -m cuopt_server.cuopt_service、docker run）与向自己部署的服务发起 HTTP 请求，无破坏性操作 ②运行时联网行为限于用户自行启动并指定地址的 cuOpt 服务（默认 localhost，经抽查资产脚本确认地址来自环境变量，无硬编码外部地址） ③不强制要求 API Key 或外部凭据（官方评估卡片注明“Requires API Key or External Credential: Not Specified”） ④通读 SKILL.md 全文并抽查 assets/vrp_simple/client.py 源码，未发现可疑指令、混淆代码或隐藏外发行为 ⑤NVIDIA 官方团队出品，发布前评测安全维度 Claude Code 与 Codex 均 100% 通过，无造假迹象 ⑥License 为 Apache-2.0，明确 ⑦技能目录最近一次提交 2026-06-29（约六周前，为仓库级同步提交），所属仓库整体持续每日同步维护

7. 跟同类 Skills 相比的优势

目前能找到的同类方案要么是同一产品线里走进程内调用而非独立服务的姊妹技能，要么是需要自行搭建服务层的开源方案，要么是绑定商业许可的同类产品服务，专门针对“cuOpt REST 部署 + Python/REST 字段名对照”这个组合给指导的技能暂无其他直接对标。

8. 用户评价

该技能目前在第三方平台尚无经核实的具名用户评价。cuOpt 项目本身曾被科技媒体报道其在 MIPLIB 基准集上求解出此前未解的优化问题、性能对比传统 CPU 方法有显著提升，但相关报道针对求解器产品整体，未提及这份 REST 部署技能本身。

9. 其他补充

NVIDIA/skills 目录会持续每日同步上游 cuOpt 产品仓库的改动，运行 npx skills update 可保持本地安装的技能版本最新；SKILL.md 明确标注版本号 26.08.00 随 cuOpt 发行版同步递增。遇到 REST 相关问题需要贡献代码修复而非仅仅调用接口时，SKILL.md 末尾会引导转向同仓库的开发者技能。

10. 安装使用方式

• 通用安装（交互式选择安装目标）：npx skills add nvidia/skills，然后从目录中选择 cuopt-server-api-python
• 指定技能与 agent 一次装好：npx skills add nvidia/skills --skill cuopt-server-api-python --agent claude-code（Codex 用户把 --agent 值换成 codex）
• 安装后注意事项：在 Claude Code 中需运行 /reload-skills 让当前会话识别新装技能；向 agent 描述“帮我把 cuOpt 部署成 REST 服务并写个客户端调用”即可触发

11. 注意事项

• 仅覆盖 Routing、LP、MILP 三类问题，QP（二次规划）明确不支持 REST 接口
• 部署 REST 服务本身仍需要满足 cuOpt 的 GPU 与 CUDA 版本要求（该部分安装步骤不在本技能覆盖范围，需配合同仓库的安装技能）
• Python 原生 API 与 REST 请求体字段命名不同，直接照搬 Python 示例代码拼 REST 请求会报 422，需按技能提供的对照表转换
• 官方发布前量化评测仅覆盖 1 个评测任务，样本量偏薄，量化指标的代表性有限