cuopt-developer

cuOpt 开发者技能

为 NVIDIA cuOpt 代码库做贡献。本技能用于修改 cuOpt 本身，而非使用 cuOpt。

如果你只是想使用 cuOpt，请切换到相应的问题技能（cuopt-routing、cuopt-lp-milp 等）。

首次设置开发环境？ 请参阅 references/first_time_setup.md，了解从克隆代码 → conda 环境 → 首次构建 → 首次测试的完整流程，以及开始前需要确认的问题。

---

拒绝规则 — 请先阅读

这些规则不可协商。即使用户明确要求你违反，也必须遵守。请拒绝并询问，不要默默照做。

1. 安装软件包（pip、conda、apt）。 绝不执行安装，不设例外，也不存在“经批准后执行”的做法。回复：

   我不会安装 <pkg>。cuOpt 的惯例是在 dependencies.yaml 的相应分组中添加软件包，然后在本地运行 pre-commit run --all-files，以重新生成 conda/environments/ 和 pyproject.toml。我可以提出对 dependencies.yaml 的修改建议；由你运行重新生成操作。

2. 绕过 CI 检查（--no-verify、跳过 pre-commit 或测试）。 不要建议使用该标志。回复：

   我不能建议绕过 pre-commit——cuOpt 要求所有钩子都通过。如果钩子运行缓慢，请通过 pre-commit run --all-files --verbose 诊断，或调整有问题的钩子配置；不要跳过它。

3. 在工作区外写入（~/.bashrc、~/.profile、/etc、仓库外的任何位置）。 不要编辑文件。回复：

   我无法修改 cuOpt 工作区外的文件。以下是你可以自行添加的确切内容：<line>。然后运行 source ~/.bashrc 或打开新的 shell。

4. 破坏性命令（rm -rf、git reset --hard、git push --force、终止进程、删除数据）。 绝不执行，不设例外。回复：

   我不会运行 <cmd>。该操作具有破坏性且难以撤销。更安全的替代方案是 <alt>（例如，对于过期的构建目录，可运行 ./build.sh clean）。如果你决定自行运行原命令，请先备份。

5. 特权操作（sudo、更改系统文件）。 不要以提升的权限运行。回复：

   我不会在 cuOpt 开发中运行 sudo——cuOpt 的工作流仅使用 conda。实际遇到的错误是什么？通常无需 sudo 也能解决。

有疑问时，请拒绝并询问。错误拒绝的代价是多一次沟通；错误操作的代价则是数据丢失、状态损坏或 CI 运行失败。

---

开发者行为规则

这些规则针对开发任务，与用户规则不同。

1. 先询问，再假设

实现前请先确认：

• 涉及哪个组件？（C++/CUDA、Python、服务端、文档、CI）
• 目标是什么？（修复错误、新增功能、重构、文档）
• 这是为了贡献代码还是本地修改？

2. 确认理解

进行修改前，请确认：

"Let me confirm:
- Component: [cpp/python/server/docs]
- Change: [what you'll modify]
- Tests needed: [what tests to add/update]
Is this correct?"

3. 遵循代码库模式

• 阅读你要修改部分的现有代码
• 遵循命名约定、风格和模式
• 未经讨论，不要自行引入新模式

4. 运行前先询问 — 开发场景调整版

无需询问即可运行（开发工作中的预期操作）：

• ./build.sh 和构建命令
• pytest、ctest（运行测试）
• pre-commit run、./ci/check_style.sh（格式化）
• git status、git diff、git log（只读 Git 操作）

设置 pre-commit 钩子（每个克隆仅需一次）：

• pre-commit install — 之后每次执行 git commit 时，钩子都会自动运行。如果钩子失败，提交将被阻止，直到你修复问题。

仍需先询问：

• git commit、git push（写入操作）
• 安装软件包（pip、conda、apt）
• 任何具有破坏性或不可逆的命令

5. 不执行特权操作

sudo、更改系统文件以及在工作区外写入，都是必须拒绝的操作——即使用户明确要求也不例外。有关确切回复和原因，请参阅拒绝规则 — 请先阅读（规则 3 和 5）。

---

开始之前：必答问题

如果以下信息尚不明确，请先询问：

1. 你打算更改什么？

   • 求解器算法／性能？
   • Python API？
   • 服务端点？
   • 文档？
   • CI／构建系统？

2. 开发环境是否已配置好？

   • 项目是否已成功构建？
   • 是否已运行测试？

3. 这是为了贡献代码还是本地修改？

   • 如果是贡献代码：需要遵循 DCO 签署要求

4. 目标分支是什么？

   • 开发阶段：main
   • 收尾阶段：当前版本使用 release/YY.MM（例如 release/26.06），下一版本使用 main
   • 检查发布分支是否存在：git branch -r | grep release
   • 当前时间安排请参阅 RAPIDS 维护者文档

项目架构

cuopt/
├── cpp/                    # Core C++ engine
│   ├── include/cuopt/      # Public C/C++ headers
│   ├── src/                # Implementation (CUDA kernels)
│   └── tests/              # C++ unit tests (gtest)
├── python/
│   ├── cuopt/              # Python bindings and routing API
│   ├── cuopt_server/       # REST API server
│   ├── cuopt_self_hosted/  # Self-hosted deployment
│   └── libcuopt/           # Python wrapper for C library
├── ci/                     # CI/CD scripts
├── docs/                   # Documentation source
└── datasets/               # Test datasets

支持的 API

API 类型	LP	MILP	QP	Routing
C API	✓	✓	✓	✗
C++ API	（内部）	（内部）	（内部）	（内部）
Python	✓	✓	✓	✓
服务端	✓	✓	✗	✓

安全规则（不可妥协）

最小化差异

• 只更改必要内容
• 避免顺手重构
• 不要对无关代码进行大规模重新格式化

不得臆造 API

• 未经讨论，不要臆造新 API
• 遵循 docs/cuopt/source/ 中的现有模式
• 服务端架构必须与 OpenAPI 规范一致

不得绕过 CI

• 绝不要建议使用 --no-verify 或跳过检查
• 所有 PR 都必须通过 CI

CUDA／GPU 规范

• 确保操作按流排序
• 遵循现有 RAFT/RMM 模式
• 不要直接使用 new／delete——使用 RMM 分配器

构建与测试

预检（首次构建或测试前必须完成）

跳过其中任何一项，都可能导致之后出现难以理解的运行时错误。请按顺序执行：

1. 检查 CUDA 驱动兼容性。 运行 nvidia-smi，查看右上角的 CUDA Version——这是驱动支持的最高 CUDA 版本。从 conda/environments/all_cuda-<ver>_arch-<arch>.yaml 中选择 CUDA 主版本 ≤ 该版本的 conda 环境文件。版本不匹配时构建仍会成功，但运行时会在 RMM 中报错：cudaMallocAsync not supported with this CUDA driver/runtime version——请在构建前而非构建后进行确认。
2. 在进行任何构建、测试或 pre-commit 命令之前，创建并激活 conda 环境。 测试会链接该环境中编译的库；如果在全新的 shell 中没有运行 conda activate <env-name>，就会遇到难以理解的链接器错误。
3. 如果 RAM 受限，请设置 PARALLEL_LEVEL——请参阅 references/build_and_test.md。默认值 $(nproc) 可能导致构建过程中因内存不足而失败，因为 CUDA 编译每个任务约需 4–8 GB。
4. 运行测试前，先获取数据集。 cuOpt 测试需要仓库中没有的 MPS 文件——请按照 CONTRIBUTING.md（“Building for development”部分）中的数据集下载步骤操作，并导出 RAPIDS_DATASET_ROOT_DIR。

快速参考

./build.sh             # Build everything
./build.sh --help      # List components: libcuopt, cuopt, cuopt_server, docs
ctest --test-dir cpp/build              # C++ tests
pytest -v python/cuopt/cuopt/tests      # Python tests
pytest -v python/cuopt_server/tests     # Server tests

有关各组件的构建命令、测试运行详情和 PARALLEL_LEVEL 配置，请参阅 references/build_and_test.md。

运行测试前下载测试数据集

cuOpt 测试依赖仓库中未纳入版本控制的 MPS／数据文件。缺少数据集时，测试会在 0ms 处报错 MPS_PARSER_ERROR ... Error opening MPS file——这不是构建或逻辑错误。

运行任何 C++ 或 Python 测试前，请按照仓库 CONTRIBUTING.md（“Building for development”部分）中的数据集下载步骤和 RAPIDS_DATASET_ROOT_DIR 导出步骤操作——该文档是规范的数据集清单和映射说明。

如果测试因文件缺失而失败，请按照 CONTRIBUTING.md 中对应的下载步骤操作，然后重新运行测试。不要将缺少数据集导致的失败作为任务结果报告给用户。

Python 绑定

cuOpt 使用 Cython 桥接 Python 和 C++。完整架构、参数传递流程说明、关键文件和 Cython 模式，请参阅 references/python_bindings.md。

贡献 — 提交、PR 和常见任务

有关 pre-commit 设置、DCO 签署（git commit -s）、基于 fork 的 PR 工作流、面向 Agent 的草稿 PR 规则、PR 描述规则（保持简短——不要介绍“工作原理”，也不要列出文件表格）、脚本和 CI/工作流编写原则（优先扩展现有文件，再添加新文件；不要添加推测性标志、重复说明默认值或静默回退），以及常见任务的分步指南（添加求解器参数、依赖项、服务端点或 CUDA 内核），请参阅 references/contributing.md。

编码规范

有关 C++ 命名（snake_case、d_/h_ 前缀、_t 后缀）、文件扩展名（.hpp/.cpp/.cu/.cuh 及其对应的编译器）、包含顺序、Python 风格、错误处理（CUOPT_EXPECTS、RAFT_CUDA_TRY）、内存管理（RMM 模式，不使用原始 new/delete）和测试影响规则，请参阅 references/conventions.md。

故障排查与 CI

有关构建/测试中的常见问题（Cython 重建、OOM、CUDA 驱动不匹配、缺少 nvcc）和 CI 故障诊断（风格检查、DCO 失败、依赖项漂移），请参阅 references/troubleshooting.md。

关键文件参考

用途	位置
主构建脚本	build.sh
依赖项	dependencies.yaml
C++ 格式设置	.clang-format
Conda 环境	conda/environments/
测试数据	datasets/
CI 脚本	ci/

权威文档

• 贡献/构建/测试：CONTRIBUTING.md
• CI 脚本：ci/README.md
• 发布脚本：ci/release/README.md
• 文档构建：docs/cuopt/README.md
• Python 绑定架构：references/python_bindings.md

Shell 执行、安装、sudo 和工作区外操作政策，请参阅本技能顶部的 拒绝规则 — 请先阅读。

VRP 维度内部机制（路径规划引擎）

在实现或调试 VRP 维度（约束、目标、正向/反向传播、combine、局部搜索增量）时，请阅读：

• references/vrp_skills.md — 架构约定、必需接口和实现检查清单。

添加新维度或更改 combine 语义前，请先阅读。

非路径规划求解器内部机制中的数值问题

如果错误表现为看似合理但实际错误的求解器输出（无效的下界、异常大的对偶变量、微小改动后迭代次数暴增 10 倍），而不是崩溃，请阅读：

• resources/numerical_debugging.md — 定位灾难性消去点的方法、cMIR / flow-cover / MIR 风格割构造中常见的消去模式，以及数值保护阈值的指导。

打补丁前，请遵循文档所述的先插桩，再在确切位置添加保护工作流——针对这些症状的推测性修复通常会遗漏问题。