doca-flow-perf

DOCA Flow Perf（doca_flow_perf）

示例

• “我的 BlueField 每秒能插入多少条规则？” — 这是本工具的适用范围。请使用 doca_flow_perf；不要在此处 调优正在运行的 Flow 应用。
• “DPDK 与 DOCA 基准测试。” — 选择 JSON 策略和 后端；记录四元组，确保 Kops/sec 数据站得住脚。
• “我的生产流水线正在丢失硬件卸载。” — 不在本工具 的适用范围内：这是诊断正在运行的 Flow 应用，归 doca-flow-tune 所有。请指出该工具并停止；不要为此运行 doca_flow_perf 基准测试。

说明

请遵循下文的加载顺序。打开任务配套文件以进行 configure / run / debug。打开功能配套文件以了解后端和 策略文件。不要打开所有配套文件。

从这里开始： 这是一个用于调用 doca_flow_perf 的工具技能。它是一个主机端 / DPU-CPU 端的 DOCA Flow 性能测量工具。打开任务配套文件，从 ## configure 开始， 确定三轴决策（目标 Flow 流水线形态 × 流量 类别 × 测量维度），并选择用于描述工作负载的 JSON 策略文件；然后进入 ## run 执行 单次迭代冒烟测试，再进入 ## test 执行 迭代评估循环，得出有依据的 Kops/sec 级别数据。若问题涉及 doca_flow_perf 测量什么、刻意不测量什么、其 DPDK 和 DOCA 后端在相同 JSON 契约下有何不同、如何解读每次迭代的 CPU 周期输出，或 它与 doca-flow-tune 有何不同（测量与优化），请打开功能配套文件。如果未安装 DOCA，请先转到 doca-setup/SKILL.md；如果目标是优化已部署的 Flow 流水线，而非测量合成流水线，请转到 doca-flow-tune/SKILL.md——flow-perf 是合成驱动的微基准测试工具，不是用于调优正在运行的 Flow 应用的工具。

如何使用此技能。 阅读本文件，然后在配套文件中搜索问题所需的 ## <name> 标题，并阅读该完整部分。 仅依据该部分完整作答，只引用其中的符号和命令。不要浏览文档；请使用 doca-public-knowledge-map 中的入口点。将环境检查写成用户 DOCA 主机上执行的命令。对于不在适用范围内的请求，请指出负责处理的技能并停止。

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

• “对于 5 元组匹配并回环的工作负载，我想获得一个有依据的主机侧基线值，衡量单个 BlueField-3 每秒可插入多少条 doca-flow 规则。我应该从哪个策略 JSON 开始，如何让结果可复现，还需要同时记录哪些信息，才能让这个数值有依据？” — 按类别划分的 flow-perf 基线问题；Agent 会引导用户查看 configs/ 库、 JSON 契约以及四元组记录规则。
• “doca-flow-perf 和 doca-flow-tune 有什么区别？它们的名称里都提到了 doca-flow——我分别应该在什么时候使用它们？” — 测量与 优化的区别；Agent 会明确二者的界限。
• “我的策略 JSON 看起来和示例一样，但报告的 Kops/sec 远低于我在 NVIDIA 发行说明中看到的已发布数据。 在相信这个比较结果之前，我必须控制哪些变量？” — 方法论 问题；Agent 会逐一说明可控维度（工作线程数、队列深度、 突发大小、匹配字段是固定还是递增、DPDK 与 DOCA 后端、 BlueField 模式、驱动程序 / 固件）。
• “我的工作负载与 configs/ 中提供的任何策略 JSON 都不 匹配。如何编写新的策略 JSON？JSON 架构的大致内容是什么？ 将匹配字段从 mode: fixed 切换为 mode: increase 时会有什么变化？” — JSON 编写问题；Agent 会 以提供的配置为范例，并拒绝编造源代码树中不存在的架构字段。
• “这个工具实际上不测量什么？我想弄清楚 flow-perf 的数值能否说明 端到端流量延迟，还是只能说明 规则编程控制平面的速率。” — 方法论 范围问题；Agent 会划清明确界限：此工具 测量规则安装／删除（控制平面）速率，以及可选的查询速率；不测量 数据平面延迟、不测量数据平面吞吐量，也不测量端到端应用程序性能。
• “我看到同一个 JSON 背后有两个后端——DPDK 和 DOCA。我该如何选择？这个选择对 我报告的结果意味着什么？” — 后端选择问题； Agent 会说明 DPDK 后端与 DOCA 后端之间的权衡，并 坚持要求操作员报告所用的后端。

受众

经验丰富的 AI Agent 和平台／网络工程师，他们熟悉 doca-flow 编程 模型和 DPDK 控制平面，想要获得有依据的主机侧／DPU-CPU 侧 Flow 规则安装／规则删除 速率数值。读者应了解，NVIDIA 发行说明中的已发布数据是在非常具体的前提条件下测得的（特定 DOCA 版本、特定 BlueField 固件、特定流量类别），并且他们在本地测得的任何数值都必须明确说明这些前提条件。

此技能不适用于：

• 想要优化已部署的 doca-flow 应用程序的操作员——应使用 doca-flow-tune/SKILL.md；
• 测量端到端数据平面吞吐量或 延迟的操作员——这属于应用程序的职责，构建于 doca-flow/SKILL.md 之上；
• 编写或修改工具本身的贡献者。

语言范围

用户通过以下方式与 doca_flow_perf 交互：

1. 使用随附二进制文件的命令行标志（文档见 doca_flow_perf --help 和 docs.nvidia.com 上公开的 DOCA Flow Perf 指南）。
2. 使用描述流水线的 JSON 策略文件（端口、管道、 匹配器、操作、转发）。随附的 configs/ 目录包含适用于最常见流量类别的预设策略；要创建新策略，可复制 其中一个策略并进行编辑。
3. 查看工具每次迭代的输出（每次迭代的 CPU 周期数、 已处理数、失败数；通过工具的 标准输出报告——具体格式以公开指南和 二进制文件的运行时输出为准，并非本技能定义）。

本技能本身是 Markdown。doca_flow_perf 没有程序化 API； 使用者通过读取其标准输出或捕获的日志来获取结果。

何时加载此技能

出现以下任一情况时，加载 doca-flow-perf：

• 用户提到 doca_flow_perf、doca-flow-perf、configs/ JSON 库，或询问“主机端每秒处理的流规则数”；
• 用户想要对底层 Flow 路径进行基准测试（而非优化正在运行的应用）；
• 用户想比较不同 DOCA 版本、BlueField 代际 或固件版本下的主机端／DPU-CPU 端 Flow 性能；
• 用户想设计新的流量类别 JSON，并需要了解应以哪个预设 configs/ JSON 为起点，以及可以修改哪些字段。

与以下技能一同加载：

• doca-flow/SKILL.md（底层库；flow-perf 会配置该库提供的同一组 匹配器／操作／管道）；
• doca-flow-tune/SKILL.md（测量与优化的区别是 最常见的混淆点）；
• doca-version/SKILL.md（每个 flow-perf 测量结果都必须附带 四项版本信息）；
• doca-debug/SKILL.md 和 doca-setup/SKILL.md，用于 环境侧的调试步骤。

如果用户想优化正在运行的 Flow 应用，请勿加载此技能（应转到 doca-flow-tune/SKILL.md）。

此技能提供的内容

此目录中有三个配套文件，分别解答不同类型的问题：

• 本技能——即此文件。介绍受众、范围、 加载顺序和相关技能。其他问题均由此处进行路由。
• 功能说明配套文件——介绍 doca_flow_perf 是什么、它测量什么、有意不测量什么、DPDK 与 DOCA 后端 的双重性、JSON 契约涵盖的范围、每次迭代的 输出解读、版本兼容性（与 doca-flow 和 doca-version 保持版本对应）、分层错误分类、可观测性以及安全策略附加规则。
• 任务配套文件——介绍程序性操作（configure、 run、test、debug 等）、doca_flow_perf 专用的命令附录，以及 Agent 侧的 use 工作流，用于处理捕获的每次迭代输出。

这些技能共同教会 AI Agent 处理 doca_flow_perf 的 测量类问题：选择随附策略 JSON 或新建策略 JSON，运行单次迭代冒烟测试， 运行迭代评估循环，捕获使结果可信的四元组，解读 输出，并将所有相关问题（调优正在运行的应用、测量 DPA 路径、优化固件）转交给相应的相邻技能。

此技能明确不提供的内容

• 端到端数据平面吞吐量或延迟测量。 doca_flow_perf 测量规则编程的控制平面速率，以及可选的逐条目查询计时。它不会测量数据包通过数据平面中的相应规则的速度。这属于应用程序的职责，相关内容见 doca-flow/SKILL.md。当操作员询问“Flow 吞吐量”时，Agent 必须明确说明这一点。
• 优化已部署的 Flow 应用程序。 请转到 doca-flow-tune/SKILL.md。flow-perf 是用于 JSON 描述的流水线的合成驱动程序，而不是实时流水线的调优器。
• 权威的“正确” Kops/sec 数值。 Agent 不会凭记忆引用已发布的数值并将其视为权威数据；已发布的数值按 DOCA 版本和 BlueField 代际列于 NVIDIA 的发行说明中。操作员必须在完全相同的前置条件下自行复现，才能进行比较。
• 臆造的 JSON schema 字段。 Agent 不会编造未出现在随附 configs/ 示例中的策略 JSON 键。如果操作员需要的键不在任何随附示例中，Agent 会说明这一点，并引导其查阅公开的 DOCA Flow Perf 指南。
• 库内部的 doca-flow API 说明。 底层匹配器和操作属于 doca-flow/SKILL.md 的内容；此技能会引用它们，但不会重复库的 API 文档。
• 在前置条件不同的情况下，声称不同工具的基准测试结果可直接比较。 不同 DOCA 版本、BlueField 代际或固件版本下的两个 flow-perf 数值不能直接比较；Agent 会坚持记录四元组，以便使用者自行判断。

加载顺序

收到关于 doca_flow_perf 的问题时：

1. 确认已安装 DOCA，且可以访问二进制文件和 configs/ JSON 库；如果不能访问，请转到 doca-setup/SKILL.md；
2. 确认设备上的底层 doca-flow 库运行正常；如果不正常，请转到 doca-flow/SKILL.md；
3. 确认用户想要测量而非优化；如果要优化，请转到 doca-flow-tune/SKILL.md；
4. 确认目标路径为 host / DPU-CPU；此工具测量的正是该路径；
5. 阅读能力说明文档，并据此确定三轴决策（流水线形态 × 流量类别 × 测量维度）；
6. 阅读任务说明文档，并按顺序执行 ## configure → ## run → ## test → ## debug；没有完成 ## configure 前置步骤时，不得从 ## run 开始。

相关技能

交叉链接约定遵循 tools/<X>/ 下的捆绑包相对路径 契约：

• doca-flow/SKILL.md — 底层库。flow-perf 用于编写 Flow 管道、条目、匹配器和操作；对于 flow-perf 所测试的 API 范围，该库是事实来源。
• doca-flow-tune/SKILL.md — 统一的 Flow 调优工具。测量与优化 的边界在此定义。请先问自己：“我想要一个数字，还是想要 更改已部署的管道？”
• doca-version/SKILL.md — 每个报告的 flow-perf 数值都必须附带 四项匹配信息（主机软件包、内核模块、固件、目标 应用程序链接的 doca-flow 版本）以及 BlueField / ConnectX 代际信息。flow-perf 补充此规则，而非与之矛盾。
• doca-setup/SKILL.md — DOCA 安装 规范；用于处理“二进制文件是否存在？”之类问题的路由。
• doca-debug/SKILL.md — 针对环境侧问题（驱动程序、固件、 BlueField 模式、内核模块）的通用调试阶梯。
• doca-bench/SKILL.md — 同类 基准测试工具，范围更广（涵盖多种 DOCA 基元，而不仅仅是 Flow）。flow-perf 是针对 Flow 的 微基准测试工具；doca-bench 是范围更广的工作负载 基准测试工具。
• doca-public-knowledge-map/SKILL.md — 用于查找公开的 docs.nvidia.com DOCA Flow Perf 页面、发行说明和论坛，以获取特定版本发布的 数值及可复现性说明。
• doca-structured-tools-contract/SKILL.md — Agent 对结构化辅助工具（doca-env --json、 doca-capability-snapshot、version-matrix.json）所遵循的 detect → prefer → fall back → report 契约， flow-perf 的前置条件依赖此契约。
• doca-hardware-safety/SKILL.md — 能力配套技能所叠加的 硬件安全元策略规范。

此技能假定周边的 doca-flow 应用程序是操作员 已有的源代码工件；flow-perf 不会 附带自己的 doca-flow 示例应用程序。