doca-bench

DOCA Bench（doca_bench）

示例

• “这个设备上的 DOCA 库实际能达到什么性能？” — 这是本技能的适用范围。使用 doca_bench；不要编写自定义 微基准测试。
• “在这套安装中，doca_bench 能驱动哪些 DOCA 库？” — 先探测内置查询；枚举结果为空表示缺少库，而不是基准测试失败。

说明

遵循下方的加载顺序。打开任务配套文件，了解配置 / 运行 / 调试。打开功能配套文件，了解模式和测量可靠性。不要打开所有配套文件。

从这里开始： 这是一个用于调用 doca_bench（跨库微基准测试工具）的技能。打开 任务配套文件，从 ## configure 开始，进行三轴决策 （目标库 × 工作负载形态 × 测量轴），然后转到 ## run，按照先冒烟测试、再批量测试的流程执行。当问题涉及 doca_bench 能测量什么、它能驱动哪些 DOCA 库，或 如何解读吞吐量 / 延迟 / 操作速率输出，避免被预热或稳态数据误导时， 请打开功能配套文件。如果尚未安装 DOCA，先转到 doca-setup/SKILL.md；如果安装版本低于 2.7.0，主机上 不会附带 doca_bench。

此技能擅长回答的示例问题

此技能旨在回答的 doca_bench 问题类别，每类配有一个实际示例。类别是关键所在； 实际示例只是其中一种情况。

• “这个设备上的 DOCA 库实际能达到什么性能？” — 实际示例：“我的 BlueField-3 上 DOCA Compress 的吞吐量”。 可通过功能配套文件中的三轴配置
  • 任务配套文件中的先冒烟测试、再批量测试流程来回答。相同的 形态也适用于回答 “DOCA RDMA 的发送端吞吐量” — doca_bench 支持跨库，而非仅支持单个库。
• “在这套安装中，doca_bench 实际能驱动哪些 DOCA 库？” — 实际示例：“在精简构建的安装中，能否枚举 doca_sha”。 可通过功能配套文件中介绍的内置查询系统
  • 任务配套文件的第 2 步 （先探测，再进行基准测试）来回答。枚举结果为空 = 未安装该库， 而非基准测试失败。
• “这个数值可靠吗？还是我漏掉了预热？” — 实际示例：“为什么我第一秒的数值与稳态数值不同”。可通过 功能配套文件中的测量可靠性 第 5 层 + 任务配套文件来回答（评估循环 会将预热 / 稳态 / 异常值视为需要重新迭代的触发条件， 而不是一次性结论）。
• “基准测试报告吞吐量为零 / 启动时卡住 / 与公开文档不符。” — 实际示例：“doca_bench 显示 AES-GCM 的操作数为零，但 doca_caps 说设备支持 它”。可通过功能配套文件中的分层错误分类 （配置语法 → 设备绑定 → 库前置条件 → 工作负载前置条件 → 测量可靠性 → 版本 → 跨领域问题）+ 任务配套文件来回答。
• “如何采集基线，以便日后进行回归测试？” — 实际示例：“在固件更新前，记录这台 BlueField + 当前 DOCA 版本的解压吞吐量快照”。 可通过任务配套文件中的 CSV 输出 + 版本叠加规则来回答（在记录 数值时，同时保留命令行 + 版本 + 设备 + 已部署环境；缺少这四项 信息的数值会导致跨版本回归排查失败）。
• “doca_bench 对库 X 没有返回任何内容——这意味着什么？” — 实际示例：“DOCA SHA 没有输出”。 可通过任务配套文件
  • 功能配套文件中的空输出解读规则来回答。 先转到 doca-caps/SKILL.md，确认每台设备支持的各库的粗略 能力基准，然后在确认该能力存在后，再返回 基准测试流程。

适用对象

此技能面向外部运维人员、开发者和 AI Agent，他们需要一种可复现且受供应商支持的方法，在用户实际安装的环境和设备上测量 DOCA 库的性能。具体包括：

• 在确定应用设计前，需要在不同 DOCA 库之间做出选择的外部开发者（例如比较 COMPRESS、SHA 和 DMA 吞吐量）。
• 通过重新运行已捕获的 doca_bench 基准，对照新状态验证调优变更的平台运维人员（NUMA 绑定、驱动升级、固件烧录）。
• 需要生成一份 “设备当前的实际性能” 证明材料的 SRE / 性能工程师，供下游使用者（容量规划、回归二分定位）引用。
• 需要诚实回答 “我应该期待 DOCA 库 X 在设备 Y 上达到怎样的吞吐量 / 延迟？” 的 AI Agent——提供实测数据、生成该数据的命令行，以及限定适用范围的版本、设备和环境信息，而不是根据数据表上的醒目指标猜测。

此技能不适用于调试 doca_bench 源代码的用户，也不可替代 docs.nvidia.com 上最新的公开 DOCA Bench 指南。

doca_bench 以工具形式发布（一个独立的 CLI 二进制文件，另附一个用于远程内存 / RDMA / Eth 场景中远程端的配套应用），而非供你链接使用的库。此技能采用与套件其余部分相同的 kind: tool 三文件结构，以便 Agent 的任务动词约定（configure / build / modify / run / test / debug）在库、服务和工具间保持统一——即使对于已发布的二进制文件，某些动词会简化为路由存根。

何时加载此技能

当用户要在安装了 DOCA ≥ 2.7.0 的实际主机上（或在配备等效版本的公开 NGC DOCA 容器内）调用 doca_bench 来测量 DOCA 库性能时，或者 Agent 需要这样做时，加载此技能。具体包括：

• 为候选工作负载选择要测试的 DOCA 库（RDMA、COMPRESS、DMA 等）。
• 选择要测量的指标（吞吐量、批量延迟或精确延迟）——这是公开指南记载的三种模式；使用 --help 确认完整列表（包括任何 max-bandwidth 模式）。这些模式不可互换。
• 探查安装的细粒度构建状态，以便 Agent 能如实报告 “此安装未提供此库”，而不是编造工作负载。
• 捕获有文档记录的基准（命令行 + 版本 + 设备 + 部署时环境 + 数值），供日后排查回归问题。
• 要求工作负载负责人预先声明可接受的波动范围，并在报告稳定结果前，确认连续两次运行均在该范围内；否则升级处理波动问题。
• 诊断基准运行报告零值 / 不稳定 / 意外结果的原因（详见任务配套文档中的错误分类排查流程）。

不要为了解 DOCA 概况、库 API 开发或安装而加载此技能。这些用途请使用 doca-public-knowledge-map/SKILL.md、对应的 libs/<library> 技能或 doca-setup/SKILL.md。应用级端到端基准测试也不要加载此技能——doca_bench 测量的是 DOCA 库层，而非用户在其上构建的应用。

此技能提供的内容

这是一个轻量加载器。实质性内容位于两个配套文件中：

• 能力配套文件 — doca_bench 可以测量什么（跨库范围、三轴配置模型、文档记录的运行模式、会影响测量可靠性的预热 / 流水线 / 多核概念）、版本叠加层（在规范的 doca-version 规则基础上补充 doca-bench 专属事实）、分层错误分类（配置语法 / 设备绑定 / 库前置条件 / 工作负载前置条件 / 测量可靠性 / 版本 / 跨领域）、可观测性界面（屏幕 + CSV 输出、实时统计信息、查询系统），以及安全态势（公开指南中 “不适用于生产环境” 的警告、主机与 BlueField 执行规则、配套应用的攻击面）。
• 任务配套文件 — 涵盖范围内任务动词的分步工作流：configure（三轴决策 + 先探测再基准测试步骤）、build（引导至安装 — 已提供二进制文件，也已提供配套应用）、modify（拒绝 — 不要修补基准测试二进制文件；应修改基准测试调用方式）、run（先冒烟测试再批量运行流程）、test（评估循环 — 预热、稳定状态、异常值、跨版本）、debug（逐层排查错误分类），以及一个引导处理范围外问题的 Deferred task verbs 部分，和一个列出 doca_bench 专属调用类别的 Command appendix。

此技能假设主机已安装 DOCA ≥ 2.7.0（或者正在运行等效版本的公开 NGC DOCA 容器），且操作员拥有公开指南要求的相应权限，以便 doca_bench 在其平台上绑定设备并分配资源。

此技能明确不提供的内容

此技能是面向 Agent 的指南，而非示例或脚本包。为确保边界清晰，此技能特意不包含以下内容，且拉取请求不应添加：

• 超出公开 DOCA Bench 指南文档范围的具体标志字符串或场景 / 指标 / 属性名称。 标志接口会不断变化，且因安装而异；文档记录的调用方式以及已安装版本中的 --help 才是权威答案。杜撰标志是此技能最常见的幻觉错误。
• 预先制作的示例输出或预期吞吐量数字。 基准测试输出因设备、版本、固件、NUMA 和调优而异。固定到某个平台和某个 DOCA 版本的采集数值，会误导使用其他平台 / 版本的操作员。
• 任何语言的封装器、解析器或脚本，用于处理 doca_bench 的 CSV 或标准输出。输出格式已有文档说明；如果用户想基于这些格式编写脚本，正确的答复是“阅读最新指南，并针对你已安装的版本编写解析器”。
• samples/ 或 reference/ 子目录。 这是一个用于文档所述 CLI 的轻量加载器；实质性内容位于公开页面和 --help 中。

加载顺序

1. 首先阅读此技能，确认用户的问题在范围内（用户确实想调用 doca_bench 进行测量，而不是了解 DOCA 库的一般信息）。
2. 关于 doca_bench 的测量内容、三轴模型、版本叠加层、错误分类、可观测性界面和安全态势，请参阅能力配套文件。
3. 关于文档记录的调用方式和先冒烟测试再批量运行的工作流 — configure、build、modify、run、test、debug — 请参阅任务配套文件。

相关技能

• doca-public-knowledge-map/SKILL.md — 导向 docs.nvidia.com 上的 DOCA Bench 公共页面 及其他公开 DOCA 文档。
• doca-version/SKILL.md — 规范的 版本检测链、四方匹配规则、NGC 容器语义，以及标头优先于文档的规则。本技能中的 ## Version compatibility 部分是在 doca-version 之上的轻量补充； 详细内容见该技能。
• doca-structured-tools-contract/SKILL.md — 适用于整个套件的结构化输出辅助工具契约。 满足 detect-prefer-fallback-report 循环的基准测试运行器 / 基准测试快照可执行文件将推迟到 PR2；此处提前采用该契约，以便任务配套文档中的 ## Command appendix 从 PR1 起就能考虑基础设施。
• doca-setup/SKILL.md — 环境准备、 安装验证、大页、NUMA 感知，以及使用公开 NGC DOCA 容器的我还没有安装路径。
• doca-debug/SKILL.md — 横向适用的 调试阶梯。Bench 在能力配套文档中提供自身的错误分类； 如果最终发现问题源自 DOCA 以下层级（驱动程序、固件、 NUMA），Bench 的错误分类会移交给 doca-debug。
• doca-caps/SKILL.md — 用于获取设备级、库级粗粒度能力快照的 DOCA 同类工具。 Bench 通过自身的查询系统以更细粒度探测能力；doca_caps 是成本更低的第一步，可确认 DOCA 是否能看到该设备。
• 对应的 libs/<library> 技能 — 例如 doca-comch/SKILL.md、 doca-compress/SKILL.md — 说明被测库的工作负载前置条件、能力查询规则和错误分类补充说明。Bench 驱动该库；库技能则解释对该库而言，“健康”意味着什么。