cuopt-developer

cuOpt 开发者技能

为 NVIDIA cuOpt 代码库作出贡献。此技能用于修改 cuOpt 本身，而不是使用 cuOpt。

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

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

---

拒绝规则——请先阅读

有一条不可妥协的规则，即使用户明确要求也必须遵守——拒绝并询问，不要默默照做：

特权／系统级操作——sudo、以 root 身份运行、编辑系统文件（/etc）、更改驱动或内核设置、添加系统级软件包仓库或密钥。不要执行这些操作。请回复：

我不会运行 sudo，也不会更改 cuOpt 的系统级状态。开发工作流基于 conda，完全在用户空间运行——具体是什么错误？通常无需 root 就能解决。

除此之外，设置和使用开发环境所需的一切操作都允许。 在干净的机器上，可以直接构建可用的 cuopt 环境——以下指南是为了采用可复现的方式，而不是让你拒绝操作：

• 允许设置环境。 你可以根据仓库中的 conda/environments/all_cuda-*.yaml 创建并激活 conda 环境，在用户空间环境中运行 pip／conda／mamba 安装，也可以在用户主目录中引导安装 conda／miniforge——包括其添加到 ~/.bashrc 中的 conda init 命令。引导安装 conda 不得需要 sudo；应将其安装到 $HOME，而不是系统路径。
• 新增的永久项目依赖不同于一次性安装。 项目始终应包含的软件包应添加到 dependencies.yaml 中的相应分组；然后运行 pre-commit run --all-files，重新生成 conda/environments/ 和 pyproject.toml，以便其他贡献者也能获得该依赖。为解决你自己的构建问题而临时安装软件包，无需经过这套流程。
• 不要绕过 CI 检查（--no-verify、跳过 pre-commit 或测试）。如果钩子运行缓慢，请使用 pre-commit run --all-files --verbose 诊断，或调整有问题的钩子——不要跳过检查。
• 谨慎使用破坏性命令（rm -rf、git reset --hard、git push --force、终止进程、删除数据）。执行前确认意图，并优先选择更安全的替代方案（例如，对陈旧的构建目录使用 ./build.sh clean）。

---

开发者行为规则

这些规则专用于开发任务，与用户规则不同。

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 操作）
• 环境设置：根据 conda/environments/*.yaml 创建／激活 conda 环境，并在该环境中使用 pip／conda／mamba 安装

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

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

仍需事先询问：

• git commit、git push（写入操作）
• 任何破坏性或不可逆操作

5. 禁止特权操作

sudo／系统级更改是唯一不可妥协的拒绝事项；允许在用户空间安装软件和设置 conda 环境。请参阅拒绝规则——请先阅读。

---

开始前：必答问题

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

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	路由
C API	✓	✓	✓	✗
C++ API	（内部）	（内部）	（内部）	（内部）
Python	✓	✓	✓	✓
服务端	✓	✓	✗	✓

安全规则（不可妥协）

最小化差异

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

不得凭空设计 API

• 未经讨论，不要设计新 API
• 遵循 docs/cuopt/source/ 中的现有模式
• 服务端 schema 必须与 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 环境——这是允许且预期的操作（参见拒绝规则——请先阅读）。按照 CONTRIBUTING.md 使用本地前缀环境（./.cuopt_env），并使用第 1 步中选定的环境文件（如果有 mamba，请将 conda 替换为 mamba）：

   conda env create -p ./.cuopt_env --file conda/environments/all_cuda-<ver>_arch-$(uname -m).yaml
   conda activate ./.cuopt_env
   

   测试会链接该环境中编译的库；如果在新的 shell 中没有运行 conda activate ./.cuopt_env，就会遇到难以理解的链接器错误。
3. 如果 RAM 受限，请设置 PARALLEL_LEVEL——参阅 references/build_and_test.md。默认值 $(nproc) 可能导致构建中途出现 OOM，因为 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 及各自使用的编译器）、include 顺序、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 执行、安装、conda 环境和 sudo 策略，请参阅本技能顶部的 Refusal Rules — Read First。

VRP 维度内部机制（路由引擎）

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

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

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

非路由求解器内部机制中的数值问题

当错误表现为看似合理但实际错误的求解器输出（无效下界、异常大的对偶值、小幅更改后迭代次数暴增 10 倍），而非崩溃时，请阅读：

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

在修补之前，请遵循其中所述的先插桩，再在确切位置添加保护工作流——对此类症状进行臆测式修复通常会找错方向。